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.

Version:

3.27

Author:

Bradford Castalia, Christian Schaller - UA/PIRL

See Also:

PIRL.Database, PIRL.Configuration

Field Summary

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

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

Method Summary

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.