PIRL.PVL
Class PVL_to_DB

java.lang.Object
  PIRL.Database.Update_DB
      PIRL.PVL.PVL_to_DB

public class PVL_to_DB
extends Update_DB

PVL_to_DB maps a source of parameter values to database table field values.

A Map is used to define the assignment of PVL Parameter Values, or constant values, to Database fields. The map is defined using PVL Parameters. The Map defines the assignment from the value of a resolved source parameter reference to a resolved database field reference where the value is deposited. PVL_to_DB binds a PVL source of Parameter Values and a Database target to the Map. In addition, a set of configuration parameters may be specified that will supplement every PVL source mapped to the Database; these may be thought of as default parameters.

The name of each Assignment Parameter in the map specifies a database reference to a single database field. The database reference may specify either an update of an existing record or an insert of a new record. A database reference may be flagged to try an update and, if this fails, to fallback to an insert. Field reference Assignment Parameters may be contained in an Aggregate Parameter for a single update or insert operation on the Database of the collected assignments.

The value of each Parameter in the map specifies a parameter source reference. This is resolved against the PVL source, unless it is a constant value. A constant value may be a quoted string or the result of a mathematical expression that evaluates to a constant.

Both database references and parameter source references may contain nested references of either type, which themselves may contain nested references.

The map is processed in the order in which the parameters occur. The map may be processed in a loop until either no source references are resolved or a specified number of passes have been accomplished.

Version:

1.39

Author:

Bradford Castalia, Christian Schaller - UA/PIRL

See Also:

Parameter, Value, Database, Reference_Resolver

Field Summary

static char	ALTERNATIVE_MARKER Alternative source parameter reference token character.
static String	CWD_PARAMETER The name of the Parameter in the PVL_to_DB group that has the current working directory pathname: "CWD".
static String	DEFAULT_SOURCE_PARAMETERS_NAME The name given to the Source_Parameters when the Aggregate is based on an Assignment Parameter: "Source".
static int	EXIT_INVALILD_SYNTAX Exit status: Invalid syntax was found in the map.
static int	EXIT_PVL_ERROR Exit status: PVL processing problem.
static int	EXIT_SUCCESS Exit status: Success.
static int	EXIT_UNRESOLVED_REFERENCE Exit status: An unresolved reference was encountered.
static String	HOSTNAME_PARAMETER The name of the Parameter in the PVL_to_DB group that has the system hostname: "Hostname".
static String	ID The Class identification.
static String	LOOP_COUNTER_PARAMETER The name of the Parameter in the PVL_to_DB group that has the current mapping loop counter: "Loop_Counter".
int	Loop_Limit The Loop limit: 256.
static String	MAP_NAME The Group name of the map parameters: "PVL_to_DB_Map".
static char	NO_MATH_MARKER Non-math expression source parameter reference token character.
static String	PVL_to_DB_GROUP The Parameter Group for this class: "PVL_to_DB".
static String	RESOLVER_DEFAULT_VALUE Default value if a reference can not be resolved.
boolean	Retry_Group_with_Source Whether to retry failed resolving of Group name nested references with both configuration and source parameters.
static String	SOURCE_DIRECTORY_PARAMETER The name of the Parameter in the PVL_to_DB group that has the directory pathname of the current PVL_Source name: SOURCE_DIRECTORY_PARAMETER.
static String	SOURCE_FILENAME_EXTENSION_PARAMETER The name of the Parameter in the PVL_to_DB group that has the portion of the SOURCE_FILENAME_PARAMETER value following the last period ('.') character: SOURCE_FILENAME_PARAMETER.
static String	SOURCE_FILENAME_PARAMETER The name of the Parameter in the PVL_to_DB group that has the filename of the current PVL_Source name: SOURCE_FILENAME_PARAMETER.
static String	SOURCE_FILENAME_ROOT_PARAMETER The name of the Parameter in the PVL_to_DB group that has the portion of the SOURCE_FILENAME_PARAMETER value without the extension (the portion preceding the last period character): SOURCE_FILENAME_ROOT_PARAMETER.
static String	SOURCE_NAME_PARAMETER The name of the Parameter in the PVL_to_DB group that has the name of the current Source_Parameters: "Source_Name".
static String	SOURCE_PATHNAME_PARAMETER The name of the Parameter in the PVL_to_DB group that has the absolute pathname of the current PVL_Source name: SOURCE_PATHNAME_PARAMETER.
static String	UNRESOLVED_SOURCE_REFERENCE_PARAMETER The Configuration parameter which, if enabled, will cause any unresolved source parameter reference to throw an Invalid_Map_Syntax exception.
static boolean	UNRESOLVED_SOURCE_REFERENCE_THROWS Whether an unresolved source parameter reference will throw an Invalid_Map_Syntax exception by default.
static char	UPDATE_OR_INSERT_MARKER Update-or-insert database reference marker character.

Fields inherited from class PIRL.Database.Update_DB

DEFAULT_CONFIGURATION_FILENAME, Delete, EXIT_CONFIGURATION_PROBLEM, EXIT_DATABASE_ERROR, EXIT_ILLEGAL_ARGUMENT, EXIT_INVALID_COMMAND_LINE_SYNTAX, EXIT_IO_ERROR, EXIT_STATUS_LIMIT, Ignore_Multiple_Updates, KEY_DELIMITER, NL, The_Database, Update_One_Only, VALUE_DELIMITER, Verbose

Constructor Summary

PVL_to_DB(Database database, Parameter map)
Constructs from a Database and a Parameter map Aggregate.

PVL_to_DB(Database database, String map_source)
Constructs from a Database and a map source.

Method Summary

boolean	Default_Parameter(String name, Object value) Adds a new parameter to the default PVL_to_DB Group.
Parameter	Default_Parameters() Gets the default PVL_to_DB Group of parameters.
PVL_to_DB	Default_Parameters(Parameter parameter) Adds new parameters to the default PVL_to_DB Group.
String	Default_Value() Gets the default that will be used when a nested configuration parameter reference can not be resolved.
PVL_to_DB	Default_Value(String default_value) Sets the default value for unresolved nested references.
int	Loop_Count() Gets the value of the loop counter.
boolean	Loop() Tests if map looping is enabled.
PVL_to_DB	Loop(boolean enable) Enables or disables map looping.
static void	main(String[] arguments) Runs a PVL_to_DB application.
Parameter	Map() Gets the map Parameters.
PVL_to_DB	Map(Parameter map) Sets the map parameters.
PVL_to_DB	Map(String source) Assembles a map of PVL source parameter references assigned to Database field references.
int	Match_Mode() Gets the parameter match mode.
PVL_to_DB	Match_Mode(int match_mode) Sets the match mode used to resolve both nested configuration parameter references and Map parameter source references from the PVL source.
boolean	No_Op() Tests if no-op mode is enabled.
PVL_to_DB	No_Op(boolean enable) Enables or disables database update operations.
int	PVL_Source() The current source of PVL parameters is mapped into the Database.
int	PVL_Source(Parameter source) Supplies a source of PVL Parameters which is mapped into the Database.
int	PVL_Source(String source) Names a source of PVL Parameters which is mapped into the Database.
static Parameter	PVL_to_DB_Group(Parameter parameters) Finds a PVL_to_DB Group in a Parameter list.
static Parameter	Remove_PVL_to_DB_Group(Parameter parameters) Removes all PVL_to_DB Groups in a Parameter list.
String	Resolve_Source_References(String source_reference) Resolves a Source reference to its value.
Reference_Resolver	Resolver() Gets the Reference_Resolver being used to resolve all references.
Parameter	Source_Parameters() Gets the current set of source parameters.
PVL_to_DB	Source_Parameters(Parameter source) Sets the source parameter(s) to be mapped.
PVL_to_DB	Source_Parameters(String source) Sets the source parameter(s) to be mapped.
boolean	Unresolved_Source_Reference_Throws() Test whether an unresolved source reference will throw an Unresolved_Reference exception.
PVL_to_DB	Unresolved_Source_Reference_Throws(boolean enabled) Force an unresolved source reference to throw an Unresolved_Reference exception.
static void	Usage(boolean verbose) Prints the command-line usage syntax.

Methods inherited from class PIRL.Database.Update_DB

Database, Delete, Delete, Ignore_Multiple_Updates, Ignore_Multiple_Updates, Update_Database, Update_Database, Update_One_Only, Update_One_Only, Verbose, Verbose

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ID

public static final String ID

The Class identification.

See Also:

Constant Field Values

PVL_to_DB_GROUP

public static final String PVL_to_DB_GROUP

The Parameter Group for this class: "PVL_to_DB".

This group will be extracted from the Configuration parameters, or an empty group of this name will be created if it is not present in the Configuration. Then a set of common parameters are added. It is appended to the PVL source parameters.

See Also:

Constant Field Values

DEFAULT_SOURCE_PARAMETERS_NAME

public static final String DEFAULT_SOURCE_PARAMETERS_NAME

The name given to the Source_Parameters when the Aggregate is based on an Assignment Parameter: "Source".

See Also:

Constant Field Values

HOSTNAME_PARAMETER

public static final String HOSTNAME_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the system hostname: "Hostname".

See Also:

Constant Field Values

CWD_PARAMETER

public static final String CWD_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the current working directory pathname: "CWD".

See Also:

Constant Field Values

SOURCE_NAME_PARAMETER

public static final String SOURCE_NAME_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the name of the current Source_Parameters: "Source_Name".

See Also:

Constant Field Values

SOURCE_PATHNAME_PARAMETER

public static final String SOURCE_PATHNAME_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the absolute pathname of the current PVL_Source name: SOURCE_PATHNAME_PARAMETER.

See Also:

Constant Field Values

SOURCE_DIRECTORY_PARAMETER

public static final String SOURCE_DIRECTORY_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the directory pathname of the current PVL_Source name: SOURCE_DIRECTORY_PARAMETER.

See Also:

Constant Field Values

SOURCE_FILENAME_PARAMETER

public static final String SOURCE_FILENAME_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the filename of the current PVL_Source name: SOURCE_FILENAME_PARAMETER.

See Also:

Constant Field Values

SOURCE_FILENAME_ROOT_PARAMETER

public static final String SOURCE_FILENAME_ROOT_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the portion of the SOURCE_FILENAME_PARAMETER value without the extension (the portion preceding the last period character): SOURCE_FILENAME_ROOT_PARAMETER.

See Also:

Constant Field Values

SOURCE_FILENAME_EXTENSION_PARAMETER

public static final String SOURCE_FILENAME_EXTENSION_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the portion of the SOURCE_FILENAME_PARAMETER value following the last period ('.') character: SOURCE_FILENAME_PARAMETER.

See Also:

Constant Field Values

LOOP_COUNTER_PARAMETER

public static final String LOOP_COUNTER_PARAMETER

The name of the Parameter in the PVL_to_DB group that has the current mapping loop counter: "Loop_Counter".

The value of this parameter is incremented for each mapping Loop through the Source PVL parameters. It is initialized to 0.

See Also:

Constant Field Values

Loop_Limit

public int Loop_Limit

The Loop limit: 256.

The maximum number of times that a mapping loop is allowed to occur.

MAP_NAME

public static final String MAP_NAME

The Group name of the map parameters: "PVL_to_DB_Map".

See Also:

Constant Field Values

RESOLVER_DEFAULT_VALUE

public static String RESOLVER_DEFAULT_VALUE

Default value if a reference can not be resolved.

Retry_Group_with_Source

public boolean Retry_Group_with_Source

Whether to retry failed resolving of Group name nested references with both configuration and source parameters.

ALTERNATIVE_MARKER

public static final char ALTERNATIVE_MARKER

Alternative source parameter reference token character.

See Also:

Constant Field Values

NO_MATH_MARKER

public static final char NO_MATH_MARKER

Non-math expression source parameter reference token character.

See Also:

Constant Field Values

UPDATE_OR_INSERT_MARKER

public static final char UPDATE_OR_INSERT_MARKER

Update-or-insert database reference marker character.

A database reference prefixed with this marker will be used for an insert operation if the initial update operation fails. If the database reference does not include a record key specification the marker will simply be ignored. N.B.: The marker is not part of the database reference; it is removed before the database reference is used.

See Also:

Constant Field Values

UNRESOLVED_SOURCE_REFERENCE_THROWS

public static boolean UNRESOLVED_SOURCE_REFERENCE_THROWS

Whether an unresolved source parameter reference will throw an Invalid_Map_Syntax exception by default.

UNRESOLVED_SOURCE_REFERENCE_PARAMETER

public static final String UNRESOLVED_SOURCE_REFERENCE_PARAMETER

The Configuration parameter which, if enabled, will cause any unresolved source parameter reference to throw an Invalid_Map_Syntax exception.

If this parameter is not found, the UNRESOLVED_SOURCE_REFERENCE_THROWS value will be used by default.

See Also:

Constant Field Values

EXIT_SUCCESS

public static final int EXIT_SUCCESS

Exit status: Success.

See Also:

Constant Field Values

EXIT_PVL_ERROR

public static final int EXIT_PVL_ERROR

Exit status: PVL processing problem.

See Also:

Constant Field Values

EXIT_INVALILD_SYNTAX

public static final int EXIT_INVALILD_SYNTAX

Exit status: Invalid syntax was found in the map.

See Also:

Constant Field Values

EXIT_UNRESOLVED_REFERENCE

public static final int EXIT_UNRESOLVED_REFERENCE

Exit status: An unresolved reference was encountered.

See Also:

Constant Field Values

Constructor Detail

PVL_to_DB

public PVL_to_DB(Database database,
                 String map_source)
          throws Configuration_Exception,
                 PVL_Exception

Constructs from a Database and a map source.

Parameters:

database - The Database to be target.

map_source - The source of the database map. May be a URL refering to an appropriate database map.

Throws:

Configuration_Exception - If there is a problem with the configuration file.

Database_Exception - If there is a problem connecting with the database.

PVL_Exception - If there is a problem parsing the PVL from the database map file.

PVL_to_DB

public PVL_to_DB(Database database,
                 Parameter map)
          throws Configuration_Exception

Constructs from a Database and a Parameter map Aggregate.

The update mode is set to only allow one record per update operation.

Parameters:

database - The Database to be updated.

map - The Parameter map aggregate.

Throws:

Configuration_Exception - If there is a problem with the Database configuration.

Method Detail

No_Op

public PVL_to_DB No_Op(boolean enable)

Enables or disables database update operations.

As an aid in debugging complex references in map parameter syntax final database update operations may be disabled so that the results of resolving map parameter references may be viewed without affecting the database contents. This mode is implicitly verbose.

Note: No-op mode is disabled by default.

Parameters:

enable - true if no-op mode is to be enabled (database update operations are disabled); false otherwise.

Returns:

This PVL_to_DB object.

No_Op

public boolean No_Op()

Tests if no-op mode is enabled.

Returns:

true if no-op mode is enabled; false otherwise.

See Also:

No_Op(boolean)

Loop

public PVL_to_DB Loop(boolean enable)

Enables or disables map looping.

When enabled a (@link #PVL_Source() PVL_Source} is repeatedly mapped until references are exhausted or the Loop_Limit is reached.

Map looping is used in conjuction with the LOOP_COUNTER_PARAMETER in the default PVL_to_DB_GROUP parameters. The value of the loop counter parameter is initialized to 0 when PVL_Source mapping begins, and then incremented at the end of each mapping loop. By using the LOOP_COUNTER_PARAMETER in the Map a sequence of parameters from the PVL source can be mapped to the Database. For example, the Map entry:

        Group = catalog.table
          field_1 = parameter@${PVL_to_DB/Loop_Counter}
          field_2 = array[${PVL_to_DB/Loop_Counter}]
          ...
        End_Group
        

will insert a record in catalog.table with field_1 set to the value of the Nth parameter of that name and field_2 set to the Nth value of the array parameter, where N is the current value of the loop counter (starting with 0).

Note: Map looping is disabled by default.

Parameters:

enable - true if map looping is to be enabled; false otherwise.

Returns:

This PVL_to_DB object.

Loop

public boolean Loop()

Tests if map looping is enabled.

Returns:

true if map looping is enabled; false otherwise.

See Also:

Loop(boolean)

Match_Mode

public PVL_to_DB Match_Mode(int match_mode)
                     throws IllegalArgumentException

Sets the match mode used to resolve both nested configuration parameter references and Map parameter source references from the PVL source.

Parameters:

match_mode - One of the Reference_Resolver.CASE_SENSITIVE, Reference_Resolver.CASE_INSENSITIVE, or Reference_Resolver.PATTERN_MATCH values.

Returns:

This PVL_to_DB object.

Throws:

IllegalArgumentException - If the match mode is not a valid value.

Match_Mode

public int Match_Mode()

Gets the parameter match mode.

Returns:

The current parameter match mode code.

See Also:

Match_Mode(int)

Default_Value

public PVL_to_DB Default_Value(String default_value)

Sets the default value for unresolved nested references.

Note: The default value may be set by using an Unresolved_Reference parameter in the Configuration of the Database provided when the PVL_to_DB object is constructed. If the value of this parameter starts with "THROW" (case insensitive) then unresolved nested references will throw an Unresolved_Reference exception.

N.B.: The default value only applies to unresolved nested configuration parameter references. Source parameter (non-nested) references never have a default value.

Parameters:

default_value - The default String value for unresolved nested references. If null, unresolved references will throw an Unresolved_Reference expception.

Returns:

This PVL_to_DB object.

See Also:

Reference_Resolver.Default_Value(String)

Default_Value

public String Default_Value()

Gets the default that will be used when a nested configuration parameter reference can not be resolved.

Returns:

The String to use as the default. This is null if Unresolved_Reference will be thrown when a reference can not be resolved.

See Also:

Default_Value(String)

Unresolved_Source_Reference_Throws

public PVL_to_DB Unresolved_Source_Reference_Throws(boolean enabled)

Force an unresolved source reference to throw an Unresolved_Reference exception.

Unless the configuration UNRESOLVED_SOURCE_REFERENCE_PARAMETER or the UNRESOLVED_SOURCE_REFERENCE_THROWS default value is true, a source reference that is not resolved will result in the corresponding database field being ignored. Otherwise an unresolved source reference will result in an Unresolved_Reference exception being thrown.

N.B.: If no-op mode is enabled an exception will not be thrown in any case.

Parameters:

enabled - If true an unresolved source reference will result in an Unresolved_Reference exception being thrown. If false an unresolved source reference will result in the mapped database field being ignored.

Returns:

This PVL_to_DB object.

Unresolved_Source_Reference_Throws

public boolean Unresolved_Source_Reference_Throws()

Test whether an unresolved source reference will throw an Unresolved_Reference exception.

Returns:

true if an unresolved source reference will result in an Unresolved_Reference exception being thrown. false if an unresolved source reference will result in the mapped database field being ignored.

See Also:

Unresolved_Source_Reference_Throws(boolean)

Resolver

public Reference_Resolver Resolver()

Gets the Reference_Resolver being used to resolve all references.

Warning: Modifying the Reference_Resolver could produce unexpected source mapping results.

Returns:

The Reference_Resolver being used.

Source_Parameters

public Parameter Source_Parameters()

Gets the current set of source parameters.

Returns:

The Aggregate Parameter containing the parameters for resolving source parameter references. N.B.: After source mapping the source parameters include the default parameters in a PVL_to_DB_GROUP Aggregate.

See Also:

Source_Parameters(Parameter)

Source_Parameters

public PVL_to_DB Source_Parameters(Parameter source)
                            throws Configuration_Exception

Sets the source parameter(s) to be mapped.

If the source is an Assignment a new Aggregate named DEFAULT_SOURCE_PARAMETERS_NAME is created to contain it.

The default parameters are updated: SOURCE_NAME_PARAMETER is set to the name of the source Aggregate and SOURCE_PATHNAME_PARAMETER, SOURCE_DIRECTORY_PARAMETER, SOURCE_FILENAME_PARAMETER, SOURCE_FILENAME_ROOT_PARAMETER, and SOURCE_FILENAME_EXTENSION_PARAMETER are set to the corresponding components of the source name taken to be a file pathname. If, however, the name does not refer to an existing file, then these parameters will all be given the empty string as their value.

Parameters:

source - The Parameter source. If null, the current source is unchanged.

Returns:

This PVL_to_DB object.

Throws:

Configuration_Exception - If there was a problem updating the default parameters from the source name.

See Also:

Default_Parameters(), Reference_Resolver.Parameters(Parameter)

Source_Parameters

public PVL_to_DB Source_Parameters(String source)
                            throws PVL_Exception,
                                   Configuration_Exception

Sets the source parameter(s) to be mapped.

Parameters:

source - A PVL source String. This may be a URL, local pathname, or a system resource. If null, nothing is done.

Throws:

PVL_Exception - If there was a problem reading from or parsing the source stream.

Configuration_Exception - If there was a problem updating the default parameters from the source name.

See Also:

Streams.Get_Stream(String), Source_Parameters(Parameter)

PVL_to_DB_Group

public static Parameter PVL_to_DB_Group(Parameter parameters)

Finds a PVL_to_DB Group in a Parameter list.

Parameters:

parameters - The Aggregate Parameter to search.

Returns:

The top level PVL_to_DB_GROUP Aggregate, or null if not found. The first group found is returned.

Remove_PVL_to_DB_Group

public static Parameter Remove_PVL_to_DB_Group(Parameter parameters)

Removes all PVL_to_DB Groups in a Parameter list.

Parameters:

parameters - The Aggregate Parameter to search.

Returns:

The last top level PVL_to_DB_GROUP Aggregate that was removed; null otherwise.

Default_Parameters

public PVL_to_DB Default_Parameters(Parameter parameter)
                             throws Configuration_Exception

Adds new parameters to the default PVL_to_DB Group.

The PVL_to_DB Group of parameters is used as defaults when resolving source parameter references in the map that are not resolved by the Source Parameters. Just before the source mapping operation begins the default parameters are appended to the source parameters which ensures that the default parameters will be present for source parameter resolution, but the default parameters will not override any source parameters having the same name.

If the parameter is an Assignment it is added to the PVL_to_DB Group of default parameters. If the Parameter is an Aggregate and it contains a PVL_to_DB Group, the parameters in that group are added to the PVL_to_DB Group; otherwise all the Parameters of the Aggregate are added to the PVL_to_DB Group. The PVL_to_DB Group is Coalesced with its duplicate parameter action set so that newly added duplicate parameter names will take precedence.

If the Parameter is null the PVL_to_DB Group is reset with the default parameters, which are always included:

HOSTNAME_PARAMETER

The name of the host system.

CWD_PARAMETER

The pathname to the current working directory.

SOURCE_NAME_PARAMETER

The current PVL_Source name.

SOURCE_PATHNAME_PARAMETER

The absolute pathname of the current PVL_Source. This will be empty if the file does not exist.

SOURCE_DIRECTORY_PARAMETER

The directory pathname of the SOURCE_FILENAME_PARAMETER. This will be empty if the file does not exist.

SOURCE_FILENAME_PARAMETER

The filename portion of the SOURCE_PATHNAME_PARAMETER. This will be empty if the file does not exist.

SOURCE_FILENAME_ROOT_PARAMETER

The SOURCE_FILENAME_PARAMETER value with the extension removed. This will be empty if the file does not exist.

SOURCE_FILENAME_EXTENSION_PARAMETER

The extension portion of the SOURCE_FILENAME_PARAMETER. This will be empty if the filename has no extension following a period ('.') character, or if the file does not exist.

LOOP_COUNTER_PARAMETER

The Loop counter; initialized to 0.

Parameters:

parameter - The parameter(s) to be added to the PVL_to_DB default source parameters group.

Returns:

This PVL_to_DB object.

Throws:

Configuration_Exception - If there is a problem adding a new parameter.

See Also:

Default_Parameter(String, Object)

Default_Parameters

public Parameter Default_Parameters()

Gets the default PVL_to_DB Group of parameters.

Returns:

The PVL_to_DB Aggregate Parameter.

Default_Parameter

public boolean Default_Parameter(String name,
                                 Object value)
                          throws Configuration_Exception

Adds a new parameter to the default PVL_to_DB Group.

Parameters:

name - The name of the parameter to be set.

value - An Object to use for the parameter's value.

Returns:

true if an existing parameter by the same name was replaced; false if the parameter is being set for the first time.

Throws:

Configuration_Exception - If there is a problem adding a new parameter.

See Also:

Default_Parameters(Parameter)

Loop_Count

public int Loop_Count()

Gets the value of the loop counter.

This will be the number of times the last PVL_Source was successfully mapped to the Database.

Map

public PVL_to_DB Map(String source)
              throws PVL_Exception

Assembles a map of PVL source parameter references assigned to Database field references.

A PVL_to_DB map is used to assign Parameter (or constant) values to Database fields. It provides the mapping from resolved source reference values to resolved database field references where the values are deposited. Note: No map Parameter Value may be an Array; there must be only one Parameter Value for each Database field reference. However, this Value may contain multiple source references that are combined to produce a single field value.

Syntactically, the map is a Aggregate of PVL Parameters in which the name of each Assignment Parameter is a Database field reference and the Value is a source reference:

Database_field_reference = Source_reference

Nested references -

Any reference may contain nested references. All nested references are recursively resolved before the reference that contains them. A nested reference may be either a configuration parameter reference or a database field reference. All nested references are enclosed in curly braces ('{' and '}'), with configuration parameter references being distinguished from database field references by the former having a leading dollar sign ('$') before the opening curly brace. All nested references will either be resolved to a value or the Default_Value will be used (if the default value is null an Unresolved_Reference exception will be thrown).

N.B.: Nested parameter references are resolved against the configuration parameters, not the source parameters. Only nested references are enclosed in curly braces. The final database field and parameter source references used to accomplish the value assignment must not be enclosed.

Database field reference -

Catalog.Table.Field:Key

The components preceding the colon form a fully qualified field name, and the component following the colon is a match (SQL WHERE) criteria used to identify a specific record from the database.

Insert parameters

Map parameters that have a database reference without a key will insert a new record in the field of the table specified by the reference.

Update parameters

Map parameters that have a database reference with a key are used to specify existing database fields to be updated with a new value. The key is the criteria that identifies the specific record of the table that is to be updated. The key is required to uniquely identify a single record.

Update or Insert

A database reference may be flagged with an UPDATE_OR_INSERT_MARKER prefix character that will cause an update to be tried if the reference includes a key. If the update fails then an insert will be performed. If the reference does not include a key then only the insert is done. The special prefix marker is, of course, removed from the database reference before it is used.

Source reference -

A source reference is the Value of a map's Assignment Parameter. It is the expression that must be resolved to a value that is assigned to the database field. Ultimately each source reference must resolve to a single string value, which may be the text representation of a numeric value. However, a source reference is evaluated as a sequence of tokens that are individually resolved to string values that are concatenated to form the final source reference resolution. See the description of source references resolving for the details of the source reference expression syntax.

Parameter source reference -

The basic source reference names a parameter in the source file which has an assignment value that is used to satisfy the reference. The syntax of a parameter source reference is the sames as the syntax for a nested parameter reference, but without the enclosing "${" and "}" characters:

Pathname@Sequence[Index]...

The Pathname is a simple, relative or absolute Parameter pathname used to Find the parameter in the PVL source. How the pathname matching is done - whether case sensitive or using a regular expression pattern - is controlled by by the match mode. The Sequence, with its preceeding "at" ('@') delimiter , is optional; if present it indicates which of a multiple sequence parameters that match the Pathname to select (the first parameter is 0, which is the default). The Index, with its enclosing square bracket ('[' and ']') characters, is also optional; if present it indicates which element of an Array Value to select (the first element is 0, which is the default). Multiple Array Value element specifiers may be provided to select from multidimensional Array Values. Both the Sequence and Index specifiers may contain nested references. They may also be mathematical expressions that evaluate to any numeric value, which is truncated to an integer for selecting Array Value elements. The typical parameter source reference is simply a name of a source parameter.

N.B.: Source parameter references are resolved against the source parameters, not the configuration parameters.

Groups

Map parameters that are contained within an Aggregate (Group) Parameter define the field values for a single record in the Database. The name of the Group is a Database table reference (in Catalog.Table notation) that specifies the table where the record will located; that is it is a database field reference without the Field portion. Each parameter within the Group specifies a field name and its source reference value, therefore its database reference can contain just the field name without the catalog and table name portions (if these are present, however, they must be the same as the table reference in the Group name); the table reference portion is implicitly the name of the Group.

N.B.: As a special case, if the Group name contains nested references that can not be resolved against the configuration parameters an attempt will be made to resolve against both the configuration parameters and the current source parameters, in that order. This is a deprecated feature that could result in confusion of the correct parameter to resolve a nested reference. Retry can be disabled by setting Retry_Group_with_Source to false.

The field names and values of a Group are all collected together to produce a single operation on the Database. Groups, therefore, are particularly useful for specifying all the fields of a single new record to be inserted into a table; the alternative is to insert a single field of a new record and then apply updates to this new record to provide additional field values. If the database reference of the Group name includes a key, then a single Database update operation will be done. N.B.: Depending on the particular database server, this could result in only some of the updates being completed if there is an error in one of the map references within the Group.

Quotes and Escapes

Because source references may be complex expressions and are likely to contain special PVL syntax characters (e.g. '{', '}', '=', quotes and spaces), the entire Value portion of a Map Parameter should be quoted (with either single or double quote characters) to prevent the misinterpretation of the special characters. This is a common source of syntax errors.

When characters that would otherwise be interpreted as nested reference enclosure characters, or other special parse control characters (such as quotes and parentheses), need to be passed through as the value of the reference preceed these characters with a backslash ('\') which will escape the usual interpretation of the following character and remove the backslash. The backslash character itself may be escaped in this way.

Parameters:

source - The name of the PVL source (URL or pathname) containing the PVL that defines the map.

Returns:

A PVL Parameter Aggregate containing the mapping structure.

Throws:

PVL_Exception - If there is a problem parsing the PVL.

Map

public PVL_to_DB Map(Parameter map)
              throws IllegalArgumentException

Sets the map parameters.

Parameters:

map - The map Parameter Aggregate.

Returns:

This PVL_to_DB object.

Throws:

IllegalArgumentException - If the map is not an Aggregate Parameter.

Map

public Parameter Map()

Gets the map Parameters.

Returns:

The map Parameter Aggregate.

See Also:

Map(Parameter)

PVL_Source

public int PVL_Source()
               throws ParseException,
                      Database_Exception,
                      Invalid_Map_Syntax,
                      Unresolved_Reference

The current source of PVL parameters is mapped into the Database.

The loop counter is first reset to zero.

If there are no source parameters or map, then nothing is done.

Any top level PVL_to_DB_GROUP Aggregates are removed (as would occur if a source were reprocessed for any reason). Then the default parameters are appended to the source parameters.

The map processing loop is entered. The loop counter is incremented at the successful completion of this loop, but the loop number (the first loop is number 1) is reported in verbose mode. In verbose mode all mapping operations - insert or update - and their values - both before and after reference resolution - will be reported. At the end of each map processing loop the number of updates effected on the database and records that were affected is listed, and after map processing completes the totals of these values will be listed. If map looping has been enabled the map processing loop will be run until the loop counter reaches the Loop_Limit or no source parameters can be resolved during a processing loop. The map will be processed only once if looping is disabled.

Each map parameter is processed in the order it occurs in the map. A database reference is obtained from each parameter name and resolved of all nested references. From this a table reference and key is identified. Each database reference must contain a table reference, but the key is only present for update (not insert) operations. For Assignments the parameter value is resolved to a source reference (the details are provided in the description of the map syntax). For Aggregates all of the Assignment parameters it contains have their the database field references and resolved parameter references collected together before a database operation will be performed. If a source parameter reference can not be resolved the parameter is ignored. N.B.: Nested parameter references may be resolved by a default value or throw an Unresolved_Reference exception if no default has been specified, but this only applies to nested references; after resolving nested references the result is still treated as a parameter reference but without a default (or exception). If at least one source parameter reference has been resolved, and no-op mode has not been enabled, then the Database is updated.

Returns:

The total number of database record updates/inserts.

Throws:

ParseException - If a reference could not be resolved due to invalid syntax.

Database_Exception - If there is a problem accessing the database.

Invalid_Map_Syntax - If the map parameters contain a invalid syntax; such as the lack of a valid table reference, an assignment parameter without a field name, an aggregate contained inside another aggregate, or an aggregate parameter entry with a table reference that does not match it's conataining aggregate.

Unresolved_Reference - If a nested reference could not be resolved and there was no Default_Value.

See Also:

Update_DB.Update_Database(String, String, Vector, Vector)

PVL_Source

public int PVL_Source(String source)
               throws PVL_Exception,
                      Configuration_Exception,
                      ParseException,
                      Database_Exception,
                      Invalid_Map_Syntax,
                      Unresolved_Reference

Names a source of PVL Parameters which is mapped into the Database.

Parameters:

source - The name of the PVL source (a local pathname or URL). If null, the previous PVL source is used. If there is no previous PVL source, nothing is done.

Returns:

The total number of database record updates/inserts.

Throws:

PVL_Exception - If there is a problem parsing the PVL from the input file.

Configuration_Exception - If there was a problem updating the default parameters from the source name.

ParseException - If a reference could not be resolved due to invalid syntax.

Database_Exception - If there is a problem accessing the database.

Invalid_Map_Syntax - If the map parameters contain a invalid syntax; such as the lack of a valid table reference, an assignment parameter without a field name, an aggregate contained inside another aggregate, or an aggregate parameter entry with a table reference that does not match it's conataining aggregate.

Unresolved_Reference - If a nested reference could not be resolved and there was no Default_Value.

See Also:

Source_Parameters(String), PVL_Source()

PVL_Source

public int PVL_Source(Parameter source)
               throws Configuration_Exception,
                      ParseException,
                      Database_Exception,
                      Invalid_Map_Syntax,
                      Unresolved_Reference

Supplies a source of PVL Parameters which is mapped into the Database.

Returns:

The total number of database record updates/inserts.

Throws:

Configuration_Exception - If there was a problem updating the default parameters from the source name.

ParseException - If a reference could not be resolved due to invalid syntax.

Database_Exception - If there is a problem accessing the database.

Invalid_Map_Syntax - If the map parameters contain a invalid syntax; such as the lack of a valid table reference, an assignment parameter without a field name, an aggregate contained inside another aggregate, or an aggregate parameter entry with a table reference that does not match it's conataining aggregate.

Unresolved_Reference - If a nested reference could not be resolved and there was no Default_Value.

See Also:

Source_Parameters(Parameter), PVL_Source()

Resolve_Source_References

public String Resolve_Source_References(String source_reference)
                                 throws ParseException,
                                        Database_Exception,
                                        Unresolved_Reference,
                                        Invalid_Map_Syntax

Resolves a Source reference to its value.

A PVL source reference, as occurs in Map Parameter Values, is resolved to a value. The steps taken to achieve a resolved value are:

The source reference is first resolved of all nested references. If there are no syntax errors or an exception due to an unresolved reference the result is evaluated for individual reference tokens.

The source reference expression is searched for individual reference tokens. Each identified individual reference is resolved to a string value. The resolved values are concatenated in the left-to-right order they occur in the source reference to produce its resolved value. N.B.: Unquoted whitespace characters (any of " \t\r\n") are compressed out of the expression during the process of resolution value accumulation.

Individual references are identified and resolved as follows, in the order in which they are listed:

A logically empty string.

The source reference is trimmed of leading and trailing whitespace characters. If the result is an empty string the resolved value is an empty string.

A mathematical expression.

An attempt is made to evaluate the source reference as a mathematical expression. If this succeeds the result, as a string representation, is the resolved value.

The expression parser accepts both simple and complex syntax with numeric constants plus the symbolic constants pi and e, the usual mathematical operators (unary and binary + and -, * and /) plus exponentiation (either ^ or **) and a full complement of standard math functions (sin, cos, tan, cot, sec, csc, arcsin, arccos, arctan, exp, ln, log2, log10, sqrt, cubert, abs, round, floor, ceiling and trunc). Also, logical operators (&, |, ~, =, <, >, <>, <= and >=; the words "and", "or", and "not" can be used in place of &, | and ~) may be used in a conditional expression (with ? and :) as long as the result of the expression evaluation is a single numeric value. The evaluation will use double precision arithmetic and the result will be provided in its string representation form.

N.B.: If the results of resolving a mathematical expression are equivalent to an integer, despite being returned as a double type, then the resolved value will be represented as an integer without a ".0" suffix.

N.B.: Mathematical expression evaluation of an individual reference can be suppressed by preceding the reference with the NO_MATH_MARKER character. In this case the marker is stripped off an no attempt is made to evaluate the reference or its resolved value as a mathematical expression.

A quoted string.

All characters within unescaped single or double quotes are taken verbatim. The quotation marks are stripped off and the resulting string is the resolved value. N.B.: Quoted strings do not need to be surrounded by whitespace; they may be embedded anywhere in a source reference. Conversely, to include whitespace characters in the resolved value of a source reference they must be quoted.

A quotation mark without a closing unescaped matching quotation mark in the same source reference results in an Invalid_Map_Syntax exception being thrown that identifies the unclosed quoted string as the unresolved reference.

A parenthesized expression.

The characters within unescaped parentheses are recursively processed as a source reference to produce a resolved value. The enclosing parentheses are stripped off. Nested parentheses are included and, unless escaped, will be recognized during the recursive procssing of the new source reference. N.B.: Parenthetical expressions do not need to be surrounded by whitespace; they may be embedded anywhere in a source reference.

An opening parenthesis without a closing unescaped matching closing parenthesis, ignoring nested parentheses, in the same source reference results in an Invalid_Map_Syntax exception being thrown that identifies the unclosed parenthetical string as the unresolved reference.

An alternative marker.

The occurance of an ALTERNATIVE_MARKER character causes all further accumulation of resolved references in the current source reference to stop if, and only if, the immediately preceeding source reference (if any) was successfully resolved. That is, if the immediately preceeding reference fails to resolve then the occurance of an alternative marker causes the failed reference to be ignored.

N.B.: An alternative marker may be followed by any source reference other than an alternative marker, including an empty string. If another alternative marker follows in the current source reference then an Invalid_Map_Syntax exception is thrown that identifies the current source reference.

A source parameter reference.

A contiguous sequence of non-whitespace characters that are not quoted or parenthesized and is not an alternative marker is evaluated as a source parameter reference. A source parameter reference is resolved against the current source parameters, with the default parameters appended, to produce a resolved value.

If the source parameter reference is unresolved and the next reference in the current source reference is an alternative marker the unresolved reference is ignored and parsing continues with the next token. Note that if an alternative marker occurs at the end of a source reference it will never fail to resolve to at least the empty string value. However, if an alternative marker does not follow a source parameter reference that fails to resolve to a value then further parsing of the source reference stops and the enclosing source reference, if any, is signaled that an unresolved source reference occured; this source reference may be followed by an alternative marker. This enables any parenthesized expression to be provided with an alternative in case the entire parenthesized expression fails to resolve.

After each individual source reference has been successfully resolved another attempt is made to evaluate the results as a mathematical expression, unless this has been suppressed by the use of the NO_MATH_MARKER character in front of the reference. If this succeeds, the results are used as the resolved value; otherwise the original resolved value is used. N.B.: To include parameter source references in post-resolution mathematical expressions all parts of the expression that are not to be otherwise treated as resolvable references must be quoted. This is an admittedly awkward requirement, but otherwise all parameter source references would need special syntax identification which would be even more awkward.

Parameters:

source_reference - The reference String to be resolved to a Parameter source value.

Returns:

The resolved String value.

Throws:

ParseException - If the evaluation of a mathematical expression in a nested reference encounters a syntax error.

Database_Exception - If a nested database reference can not be resolved.

Unresolved_Reference - If a nested reference can not be resolved and there is no default reference value.

Invalid_Map_Syntax - If a parameter source reference can not be resolved, or a source parameter reference alternative is the quoted string constant "THROW" (case insensitive).

main

public static void main(String[] arguments)

Runs a PVL_to_DB application.

N.B.: If a Database connection is establshed it is always Disconnected before the application exits for any reason.

Exit status values:

EXIT_SUCCESS

Success

Update_DB.EXIT_INVALID_COMMAND_LINE_SYNTAX

Invalid command line syntax

Update_DB.EXIT_CONFIGURATION_PROBLEM

Configuration problem

Update_DB.EXIT_DATABASE_ERROR

Database access error

EXIT_PVL_ERROR

PVL processing problem

EXIT_INVALILD_SYNTAX

Invalid syntax was found in the map

EXIT_UNRESOLVED_REFERENCE

An unresolved reference was encountered

Parameters:

arguments - The command line arguments.

Usage

public static void Usage(boolean verbose)

Prints the command-line usage syntax.

Usage: PVL_to_DB <Options> -Map <source> <PVL source> [...]
  Options -
    -Database|-SERVER <server name>
    -Configuration [<source>] (default: Database.conf)
    -Set <parameter definition>
    -Loop [<count>] (default: 0, no looping)
    -Pattern Case_sensitive | Ignore_case | Regex (default: Case_sensitive)
    -Verbose (default: false)
    -Quiet (default: true)
    -No-op (default: false)

PVL source:

The pathname or URL of a file containing PVL to be used as the source of parameter values to be mapped into database field values.

Map:

The pathname or URL of a file containing a map of PVL parameters to database fields.

Database server name:

The Configuration file may contain connection information for more than one database. The information for each database is organized by server name, which may be specified. If no server name is provided, the Database will attempt to use the default server specified in the Configuration.

Configuration:

If the pathname or URL of the Configuration file is not specified the filename "Database.conf" will be used by default. If the configuration file is not in the current working directory, it will be looked for in the user's home directory. The configuration file must contain the necessary information needed to identify and connect with the database server (as required by the Database constructor and its Connect method). These are typically the database server "Type", "Host", "User" and "Password" access values.

The configuration parameters are used to resolve "nested" parameter references (see the discussion of map parameters for the distinction between nested configuration parameter referenes and source parameter references). In addition, if the configuration file contains a PVL_to_DB Parameter group, then these parameters will be included in the defaults list to be used when resolving source parameter references.

Set:

Parameters defined on the command line supplement or override existing configuration file parameters. Parameters are specified using the usual PVL syntax. N.B.: Spaces, quotes and other special characters that are part of the parameter definition must be protected from interpretation by the command shell. Parameters may have simple - typically single word - names or absolute pathnames including groups that exist in the configuration file or new groups to be created. This option may be used repeatedly to define multiple paramters.

Loop:

Normally only one mapping pass is made through the PVL source parameters. If a loop count greater than 1 is specified then each PVL source parameters set will be mapped repeatedly up to the loop count or until no database updates occur. This allows sets of parameters having the same names to be collected and sequentially inserted into the database using the LOOP_COUNTER_PARAMETER in the corresponding parameter reference.

Pattern:

PVL source parameter names are matched with map parameter references by using case sensitive comparison, ignoring case in the comparision, or treating the map parameter reference as a regular expression. Case sensitive matching is used by default.

Verbose/Quiet:

The verbose option provides a log of operations, as they occur, to the standard output. The quiet option disables the verbose mode. By default quiet mode is in effect.

Unresolved_source_reference_throws:

Any unresolved source reference will result in an exception being thrown rather than the mapped database field being ignored.

No-op:

As an aid in debugging complex references in map parameter syntax final database update operations will be disabled so that the results of resolving map parameter references may be viewed without affecting the database contents. This mode is implicitly verbose.

Help:

List a command line summary description and immediately exit.

N.B.This method always results in a System.exit with a status of EXIT_INVALID_COMMAND_LINE_SYNTAX.

Parameters:

verbose - If true the usage is printed, otherwise silence.