PIRL.Database

## Class Update_DB

- java.lang.Object
- - PIRL.Database.Update_DB

Direct Known Subclasses:
  PVL_to_DB

    public class Update_DB
    extends Object

Update_DB updates an existing database table record or inserts a new record in a table.

Database update operations are based on references to one or more tables to be affected plus, for each table reference, a list of table field names paired with the values that they are to receive. By attaching a key (SQL conditional expression) to a table reference one or more records from the table can be selected to have the specified field values updated. Without a key the field values will be put in a new record inserted at the end of the table.

An application `main` is provided using a `command line user inteface` that will invoke the update operations of this class.

See Also:
  `PIRL.Database`, `PIRL.Configuration`

### Field Summary

Fields
`static String` `DEFAULT_CONFIGURATION_FILENAME` The default Configuration filename.
`protected boolean` `Delete` Flag for `deleting` selected records instead of updating them.
`static int` `EXIT_CONFIGURATION_PROBLEM` Application exit status when there is a Configuration file problem.
`static int` `EXIT_DATABASE_ERROR` Application exit status when there is a problem accessing the Database.
`static int` `EXIT_ILLEGAL_ARGUMENT` Application exit status when an illegal argument is encountered.
`static int` `EXIT_INVALID_COMMAND_LINE_SYNTAX` Application exit status when invalid command line syntax was encounterd.
`static int` `EXIT_IO_ERROR` Application exit status when an I/O error occured on an arguments file.
`static int` `EXIT_STATUS_LIMIT` Application exit status limit indicating the number of records affected.
`static String` `ID` The Class identification.
`protected boolean` `Ignore_Multiple_Updates` Flag for ignoring multiple updates, rather than throwing an exception, when `Update_One_Only` is enabled.
`static char` `KEY_DELIMITER` Key delimiter for table/field references.
`protected static String` `NL` System new line sequence.
`protected Database` `The_Database` The Database to be updated.
`protected boolean` `Update_One_Only` Flag for limiting updates to one record.
`static char` `VALUE_DELIMITER` Delimiter for input field assignments' values.
`protected boolean` `Verbose` Flag for verbose operation.

### Constructor Summary

Constructors
Constructor and Description
`Update_DB(Database database)` Constructs an Update_DB object from a Configuration with a connection to a database server.

### Method Summary

Methods
`Database` `Database()` Gets the Database being updated.
`boolean` `Delete()` Tests if record deletion is enabled.
`Update_DB` `Delete(boolean enable)` Enables or disables record deletion.
`boolean` `Ignore_Multiple_Updates()` Tests if multiple record updates will be ignored when only one record is allowed.
`Update_DB` `Ignore_Multiple_Updates(boolean enable)` Enables or disables ignoring multiple record updates, rather than throwing an exception, when only one record is allowed.
`static void` `main(String[] args)` Runs the Update_DB application.
`int` `Update_Database(String table_reference, String key, Vector<String> field_names, Vector<String> field_values)` Updates the database.
`int` `Update_Database(String table_reference, Vector<String> field_assignments)` Updates the database using a table reference and field assignments.
`boolean` `Update_One_Only()` Tests if the single record update rule is enabled.
`Update_DB` `Update_One_Only(boolean enable)` Enables or disables the single record update only rule.
`static void` `Usage(boolean verbose)` Command line usage syntax.
`boolean` `Verbose()` Tests if verbose mode is enabled.
`Update_DB` `Verbose(boolean enable)` Enables or disables verbose mode.

### 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

#### DEFAULT_CONFIGURATION_FILENAME

    public static final String DEFAULT_CONFIGURATION_FILENAME

The default Configuration filename.

See Also:
  Constant Field Values

#### KEY_DELIMITER

    public static final char KEY_DELIMITER

Key delimiter for table/field references.

See Also:
  Constant Field Values

#### VALUE_DELIMITER

    public static final char VALUE_DELIMITER

Delimiter for input field assignments' values.

See Also:
  Constant Field Values

#### The_Database

    protected Database The_Database

The Database to be updated.

#### Verbose

    protected boolean Verbose

Flag for verbose operation.

#### Update_One_Only

    protected boolean Update_One_Only

Flag for limiting updates to one record.

#### Ignore_Multiple_Updates

    protected boolean Ignore_Multiple_Updates

Flag for ignoring multiple updates, rather than throwing an exception, when `Update_One_Only` is enabled.

#### Delete

    protected boolean Delete

Flag for `deleting` selected records instead of updating them.

#### EXIT_INVALID_COMMAND_LINE_SYNTAX

    public static final int EXIT_INVALID_COMMAND_LINE_SYNTAX

Application exit status when invalid command line syntax was encounterd.

See Also:
  Constant Field Values

#### EXIT_CONFIGURATION_PROBLEM

    public static final int EXIT_CONFIGURATION_PROBLEM

Application exit status when there is a Configuration file problem.

See Also:
  Constant Field Values

#### EXIT_DATABASE_ERROR

    public static final int EXIT_DATABASE_ERROR

Application exit status when there is a problem accessing the Database.

See Also:
  Constant Field Values

#### EXIT_ILLEGAL_ARGUMENT

    public static final int EXIT_ILLEGAL_ARGUMENT

Application exit status when an illegal argument is encountered.

See Also:
  Constant Field Values

#### EXIT_IO_ERROR

    public static final int EXIT_IO_ERROR

Application exit status when an I/O error occured on an arguments file.

See Also:
  Constant Field Values

#### EXIT_STATUS_LIMIT

    public static final int EXIT_STATUS_LIMIT

Application exit status limit indicating the number of records affected. This is the maxium number of records that can be specified through the 8-bit exit status value.

See Also:
  Constant Field Values

#### NL

    protected static final String NL

System new line sequence.

### Constructor Detail

#### Update_DB

    public Update_DB(Database database)

Constructs an Update_DB object from a Configuration with a connection to a database server.

The Configuration object is expected to contain all the necessary information Update_DB needs to connect to the database.

Parameters:
  `database` - The Database to be updated.

### Method Detail

#### Verbose

    public Update_DB Verbose(boolean enable)

Enables or disables verbose mode.

When verbose mode is enabled all operations are logged. Verbose mode is disabled by default.

Parameters:
  `enable` - true to enable the mode, false to disable.
Returns:
  This Update_DB object.

#### Verbose

    public boolean Verbose()

Tests if verbose mode is enabled.

Returns:
  true if verbose mode is enabled, false if disabled.
See Also:
  `Verbose(boolean)`

#### Update_One_Only

    public Update_DB Update_One_Only(boolean enable)

Enables or disables the single record update only rule.

When enabled only one record will be allowed to be updated for any table reference/field assignments set. The table reference key is first used to select the records specified by the key and, if more that one record is selected, the update operation is aborted. When disabled (the default) more than one record may be updated by each update set.

N.B.: Enforcing the single record update rule by doing an initial select is not very efficient, and would be better implemented using transaction rollbacks. However, since not all databases support transaction rollbacks the select first method is guaranteed to work with all databases. The initial select is not done if the single record update rule is disabled.

Parameters:
  `enable` - true to enable the rule, false to disable.
Returns:
  This Update_DB object.
See Also:
  `Ignore_Multiple_Updates(boolean)`

#### Update_One_Only

    public boolean Update_One_Only()

Tests if the single record update rule is enabled.

Returns:
  true if the rule is enabled, false if disabled.
See Also:
  `Update_One_Only(boolean)`

#### Ignore_Multiple_Updates

    public Update_DB Ignore_Multiple_Updates(boolean enable)

Enables or disables ignoring multiple record updates, rather than throwing an exception, when only one record is allowed.

When enabled and `Update_One_Only` is also enabled if a table reference key selects more than one record the update will not be done. When disabled and Update_One_Only is enabled an IllegalArgumentException will be thrown with a message describing the situation.

Parameters:
  `enable` - If true multiple record updates will be ignored when only one record is allowed; otherwise an IllegalArgumentException will be thrown in this case.
Returns:
  This Update_DB object.
See Also:
  `Update_One_Only(boolean)`

#### Ignore_Multiple_Updates

    public boolean Ignore_Multiple_Updates()

Tests if multiple record updates will be ignored when only one record is allowed.

Returns:
  true if multiple record updates will be ignored when only one record is allowed; otherwise an IllegalArgumentException will be thrown in this case.
See Also:
  `Ignore_Multiple_Updates(boolean)`

#### Delete

    public Update_DB Delete(boolean enable)

Enables or disables record deletion.

When delete is enabled and the table reference includes a key that selects one or more records, the records will be deleted rather than updated. If `Update_One_Only` is also enabled the check for a single record selection will be applied.

If no key is provided

Parameters:
  `enable` - If true selected records will be deleted; otherwise selected records will be updated.
Returns:
  This Update_DB object.

#### Delete

    public boolean Delete()

Tests if record deletion is enabled.

Returns:
  true if record deletion is enabled; false otherwise.
See Also:
  `Delete(boolean)`

#### Database

    public Database Database()

Gets the Database being updated.

Returns:
  The Database currently being used.

#### Update_Database

    public int Update_Database(String table_reference,
                      Vector<String> field_assignments)
                        throws Database_Exception,
                               IllegalArgumentException

Updates the database using a table reference and field assignments.

A key is split off from the table_reference (on the first occurance of a ``KEY_DELIMITER` character)`, if possible. The field_assignments are split (on the first occurance of a ``VALUE_DELIMITER` character) into a list of field names and their corresponding values. Then the alternate ``Update_Database`` method is invoked.`

Parameters:
  `table_reference` - The table reference, with optional key.
  `field_assignments` - The Vector of fields with assigned values.
Returns:
  The number of records affected.
Throws:
  `IllegalArgumentException` - If the table_reference is null, or a field assignment is missing either a name or value.
  `Database_Exception`
See Also:
  `Update_Database(String, String, Vector, Vector)`

#### Update_Database

    public int Update_Database(String table_reference,
                      String key,
                      Vector<String> field_names,
                      Vector<String> field_values)
                        throws Database_Exception,
                               IllegalArgumentException

Updates the database.

The details of for the arguments is described in the command line ``Usage``..

Parameters:
  `table_reference` - A Database table reference, without any key.
  `key` - The SQL conditional to select records for an update operation; null if an insert operation is to be done.
  `field_names` - The names of the fields into which data will be placed.
  `field_values` - The values of the fields for the corresponding field_names.
Returns:
  The number of records affected.
Throws:
  `IllegalArgumentException` - If `only one` record is to be updated (not inserted) and the key selects more than one record. Also, if the table_reference is null, or a field assignment is missing either a name or value.
  `Database_Exception` - If there is a problem accessing the database.
See Also:
  `Database.Insert(String, Vector, Vector)`, `Database.Update(String, Vector, Vector, String)`

#### main

    public static void main(String[] args)

Runs the Update_DB application.

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

Exit status values:

>=0 - Success: the number of records affected (to a maximum of 250).
255 - Invalid command line syntax.
254 - Configuration problem.
253 - Database access error.
252 - An illegal argument was encountered.
251 - An I/O error occured while attempting to read an argument file.

Parameters:
  `args` - The `command line` arguments.

#### Usage

    public static void Usage(boolean verbose)

Command line usage syntax.

>     Usage: Update_DB <Switches>
>       Switches -
>         [-Configuration [<filename>]]
>         [-Database|-Server <server name>]
>         -Table|-Reference [<catalog>.]<table>[:<key>]
>         <field_name>=<value> [...]
>         [-1[+]]
>         [-+]
>         [-[No_]DElete>]
>         [-Verbose]
>         [-Quiet]
>         [-Help]

#### Configuration:

If the name of the `Configuration` file is not specified the `DEFAULT_CONFIGURATION_FILENAME` will be used. 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 server "Host" name and database "Type", "User" and "Password" access values.

Only one configuration file may be used.

#### 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 (first) Server specified in the Configuration.

Only one database server may be used.

#### Table reference:

A Table Reference specifies a <table>, and its containing <catalog>, to be updated. If the catalog is not specified the Database will attempt to use the configuration Catalog parameter for the Server group, or a default Catalog parameter. The optional <key> is an SQL conditional expression that is used to select the record(s) to be updated. N.B.: If the key specification contains spaces then it must be quoted; if it contains quotes then these must be escaped from shell interpretation (by a preceeding backslash) or the the specification is already quoted then the specication quotes must be different from the enclosing quotes (use double quotes to enclose the specification and single quotes in the specification content). If the key is not present, a new record will be inserted into the table.

#### Field value assignments:

The list of one or more <field_name>=<value> pairs specifies the name of the record fields and the values they are to receive. N.B.: There are no spaces around the '=' character, unless the entire assignment is quoted; if the value contains spaces then it must be quoted and quotes in the value specification must be escaped from the shell or be different from any enclosing quotes. If an update is occuring, only the specified fields will be modified. If a record is being inserted, any records of the field that are not specified will automatically be given their default values by the database server.

#### One (1) record update:

By default, more than one record may be updated for each table reference and field assignment list. By specifying the -1 option, only one record will be allowed to be updated for each set. In this case, if more than one record would be updated as a result of the key selection this will be prevented and processing will abort. However, if '+' is appended to this option processing will not abort though the update will not be done.

The -+ option will enable multiple record updates. This is useful when multiple update sets are specified and a previous set disabled multiple record updates but the following sets should allow it.

#### Deletion:

Instead of updating records in the table selected records may be deleted from the table. By default, or if -no_delete is specified, table records are updated. A record selection key is required when delete mode is in effect, and any field value assignments will be ignored. One record update checking applies to record deletion.

#### Update sets:

A table reference and its following field value assignments, plus any preceeding mode switches, up to the next table reference, if any, constitutes an update set. Multiple update sets may be specified on a command line. Each update set will be processed before any following command line arguments are processed. The configuration file and modes in effect at that point will apply to the update set processing. An error encountered in an update set halts all further processing of the command line.

#### Arguments files:

At any point on the command line an argument of the form "@<filename>" may be specified. The file specified will be read for command line arguments that are processed in the order they occur in the file. When the end of file has been reached processing continues with the next argument on the command line. In effect, the content of an argument file replaces the @<filename> argument on the command line. If the dash character ('-') is used for the <filename> the arguments will be read from the standard input. Any argument in an argument file may be an argument file argument. Circular references are detected and cause an error exit.

#### Verbose/Quiet:

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

#### Help:

The command line syntax usage is listed and the program exits. N.B.: If the -Help option occurs anywhere on the command line no other command line arguments will be used.

N.B.The usage is printed to stderr. 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.