PIRL.Database

## Class JDBC_Data_Port

- java.lang.Object
- - PIRL.Database.JDBC_Data_Port

All Implemented Interfaces:
  Data_Port

Direct Known Subclasses:
  MySQL_Data_Port, PostgreSQL_Data_Port

    public abstract class JDBC_Data_Port
    extends Object
    implements Data_Port

A JDBC_Data_Port manages access to any JDBC database.

A JDBC_Data_Port provides a partial implementation of the Data_Port interface. Only the ``Open`` method is left to be implemented by the subclass that finalizes the Data_Port implementation for the specific type of JDBC database.

See Also:
  `Data_Port`, `Configuration`

### Field Summary

Fields
`protected boolean` `Case_Sensitive_Identifiers` Determines if database entity identifiers are case sensitive.
`protected String` `Component_Delimiter` Delimiter between catalog, table and field components when more than one component is specified in a reference.
`protected boolean` `Treat_Schema_As_Catalog` Determines if the database server schema structure is to be treated as the Database class "catalog" structure.

### Constructor Summary

Constructors
Constructor and Description
`JDBC_Data_Port()` Constructs an unopened JDBC_Data_Port.

### Method Summary

Methods
`Data_Port` `Add_SQL_Listener(SQL_Listener listener)` Adds a SQL_Listener to the list of listeners to be notified of SQL statements before they are sent to the database server.
`boolean` `Case_Sensitive_Identifiers()` Tests if identifier names are treated as case sensitive by the Data_Port.
`void` `Case_Sensitive_Identifiers(boolean case_sensitive)` Attempts to set whether identifier names are treated as case sensitive by the Data_Port.
`String` `Catalog_Name(String table_reference)` Gets the catalog part of a `table reference`.
`protected String` `catalog_name(String method, String catalog_table)` Gets a catalog name.
`Vector` `Catalogs()` Gets the list of accessible catalogs in the database.
`void` `Close()` Closes the JDBC Connection.
`protected String` `composite_name(String method, String catalog_table)` Gets a composite name.
`protected String` `Config_Value(String parameter)` Gets a Value for a Configuration Parameter.
`Configuration` `Configuration()` Gets the Configuration of the Data_Port.
`protected void` `Configure(Configuration configuration)` Used by the finalizer subclass to register its Configuration and load its database driver.
`Connection` `Connection()` Gets the JDBC Connection object for the Data_Port.
`String` `Contents(String catalog, String table)` Gets a String describing the contents of selected catalogs and tables.
`void` `Create(String catalog)` Creates a catalog in the database.
`void` `Create(String table, Vector fields, Vector types)` Creates data tables with their fields and the data types of the fields.
`String` `Database_Catalog_Name(String catalog)` Gets the name known to the database server for a catalog name.
`String` `Database_Table_Name(String table)` Gets the name known to the database server for a table name.
`void` `Delete(String catalog)` Deletes a catalog from the database.
`int` `Delete(String table, String conditions)` Deletes selected records from a table.
`void` `Delete(String table, Vector fields)` Deletes fields from a data table, or the entire table.
`String` `Description()` Provides a multi-line description of the Data_Port.
`Vector` `Field_Names(String table)` Gets the list of field names in a table on the database server.
`Vector` `Field_Types(String table)` Gets the list of field data types in a table on the database server.
`Vector` `Fields(String table, String field_info)` Obtains a list of field information for the table of a catalog.
`protected void` `ID_Type(String ID, String Type)` Used by the finalizer subclass to register its class identification and specific type name.
`int` `Insert(String table, Vector fields, Vector values)` Inserts values for selected fields into a table.
`boolean` `is_Open()` Tests if the Data_Port currently has an active Connection.
`Vector` `Keys(String table)` Gets a list of primary keys for a table.
`protected static String` `List_String(Vector list)` Produce a String representation of a Vector list.
`protected void` `Open_Data_Port(String URL)` Used by the finalizer subclass to get a JDBC Connection to the database as specified by its URL.
`abstract void` `Open(Configuration configuration)` Opens a connection to a database.
`Vector` `Query(String SQL_query, int limit)` Submit an SQL query.
`boolean` `Remove_SQL_Listener(SQL_Listener listener)` Removes a SQL_Listener from the list of listeners to be notified of SQL statements before they are sent to the database server.
`void` `Rename(String table, String name)` Renames a table.
`void` `Rename(String table, Vector fields, Vector names)` Renames fields in a table.
`Vector` `Select(Vector tables, Vector fields, String conditions, int limit)` Selects from one or more tables the data values from one or more named fields from the data records that satisfy the selection conditions.
`String` `Table_Name(String table_reference)` Gets the table part of a `table reference`.
`protected String` `table_name(String method, String catalog_table)` Gets a table name.
`String` `Table_Reference_Component_Delimiter()` Gets the table reference component delimiter.
`String` `Table_Reference(String catalog, String table)` Generates a table reference from a catalog and table name.
`Vector` `Tables(String catalog)` Obtains the list of accessible tables contained in a catalog.
`String` `toString()` Provides a String identifying the Data_Port.
`int` `Update(String SQL_update)` Submit an SQL update.
`int` `Update(String table, Vector fields, Vector values, String conditions)` Updates values for selected fields into a table.

### Methods inherited from class java.lang.Object

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

### Methods inherited from interface PIRL.Database.Data_Port

`Parameters`

### Field Detail

#### Component_Delimiter

    protected String Component_Delimiter

Delimiter between catalog, table and field components when more than one component is specified in a reference.

The component delimiter is initialzed when the Data_Port is `open`ed by the server specific subclass using the getCatalogSeparator value obtained from the database metadata.

The default is ".".

#### Case_Sensitive_Identifiers

    protected boolean Case_Sensitive_Identifiers

Determines if database entity identifiers are case sensitive.

A database server that does not use case sensitive entity identifiers will coerce the identifiers to lowercase. When these identifiers are returned from a query they will not match user specified identifiers that are in mixed case.

Because some database systems on some operating systems are not case sensitive in handling entity identifiers (the names of catalogs, tables, and field names) it may be necessary to enforce case insensitivity when matching user specified names against identifiers returned from the database server.

The case sensitivity of identifiers is initialzed when the Data_Port is `open`ed by the server specific subclass by using the `DatabaseMetaData.supportsMixedCaseIdentifiers()` value obtained from the database metadata.

The default, until the Data_Port has set the value, is to assume that database identifiers are not case sensitive.

See Also:
  `Case_Sensitive_Identifiers()`, `Database.Matches(String, String)`

#### Treat_Schema_As_Catalog

    protected boolean Treat_Schema_As_Catalog

Determines if the database server schema structure is to be treated as the Database class "catalog" structure.

The meaning of the term "catalog" to the Database class is the database server structure that contains a collection of data tables. For some database servers the term "database" is used for this structure (e.g. MySQL), but the same JDBC catalog structure applies. However, for some database servers the corresponding structure is a "schema" (e.g. PostgreSQL) and the JDBC schema structure must be used to access it rather than using its catalog structure.

This flag is expected to be set by database specific subclasses that complete the Data_Port implementation. It will be used by methods that need to make the distinction when using a JDBC method.

### Constructor Detail

#### JDBC_Data_Port

    public JDBC_Data_Port()

Constructs an unopened JDBC_Data_Port.

### Method Detail

#### is_Open

    public boolean is_Open()

Tests if the Data_Port currently has an active Connection.

Specified by:
  `is_Open` in interface `Data_Port`
Returns:
  true if the Data_Port has access to a database; false otherwise.

#### Connection

    public Connection Connection()

Gets the JDBC Connection object for the Data_Port.

Specified by:
  `Connection` in interface `Data_Port`
Returns:
  The JDBC Connection object for the Data_Port. This will be null if the Data_Port does not have an active Connection.

#### Add_SQL_Listener

    public Data_Port Add_SQL_Listener(SQL_Listener listener)

Adds a SQL_Listener to the list of listeners to be notified of SQL statements before they are sent to the database server.

Specified by:
  `Add_SQL_Listener` in interface `Data_Port`
Parameters:
  `listener` - A SQL_Listener to be added. If null, or the listener is already listed, nothing is done.
Returns:
  This Data_Port.
See Also:
  `SQL_Listener`

#### Remove_SQL_Listener

    public boolean Remove_SQL_Listener(SQL_Listener listener)

Removes a SQL_Listener from the list of listeners to be notified of SQL statements before they are sent to the database server.

Specified by:
  `Remove_SQL_Listener` in interface `Data_Port`
Parameters:
  `listener` - A SQL_Listener to be removed.
Returns:
  true if the listener was removed; false if the listener was not listed.
See Also:
  `SQL_Listener`

#### ID_Type

    protected void ID_Type(String ID,
               String Type)

Used by the finalizer subclass to register its class identification and specific type name.

Parameters:
  `ID` - The class identification string. This is recommended to be of the form "Package_name.Class_name (Version Date)".
  `Type` - The name of the specific type of Data_Port. This is expected to be the value of the ``TYPE`` parameter from the Configuration.

#### Configuration

    public Configuration Configuration()

Gets the Configuration of the Data_Port.

Specified by:
  `Configuration` in interface `Data_Port`
Returns:
  The current Configuration of the Data_Port.
See Also:
  `Configuration`

#### Open

    public abstract void Open(Configuration configuration)
                       throws Database_Exception

Opens a connection to a database.

This is a Data_Port interface method that is left to subclasses to implement. Note: This is the only abstract method.

Subclasses are expected to implement the Open method as follows:

1. Update the supplied configuration with any local parameters.

   This is typically done by using its ``Set_Conditionally (Parameters[][])``methods where Parameters[][] is an array of parameter name, value string pairs. There will a set of Required Parameters and a set of Optional Parameters. Note: The ``DRIVER``parameter is required. Its value is the classname for the JDBC driver used with the specific type of Data_Port being implemented.````

2. Call the ``Configure`` method with the configuration.

   This method will check that the Data_Port is not already open, confirm the presence of required parameters, and load the driver for the Data_Port.

3. Assemble the URL string used by the JDBC driver.

   This is driver specific and generally uses parameters from the configuration. The best way to get configuration parameter values is to use the protected ``Config_Value`` method.

4. Call the ``Open_Data_Port`` method with the URL.

   This will invoke the JDBC DriverManager to make the connection.

Specified by:
  `Open` in interface `Data_Port`
Parameters:
  `configuration` - The Data_Port Configuration.
Throws:
  `Database_Exception` - If the Data_Port could not be opened.
See Also:
  `Configuration`

#### Configure

    protected void Configure(Configuration configuration)
                      throws Database_Exception

Used by the finalizer subclass to register its Configuration and load its database driver.

The Configuration must contain a ``DRIVER`` parameter. The value of this parameter is the class name of the driver. An instance of this class will be loaded for use.

Parameters:
  `configuration` - The Configuration of the specific Data_Port. This is expected to be the Configuration passed to it via its ``Open`` method, modified as appropriate.
Throws:
  `Database_Exception` - If the Data_Port is already open, the Configuration does not contain the necessary `DRIVER` parameter, or the driver could not be loaded.

#### Open_Data_Port

    protected void Open_Data_Port(String URL)
                           throws Database_Exception

Used by the finalizer subclass to get a JDBC Connection to the database as specified by its URL.

Parameters:
  `URL` - The URL provided to the ``(String) DriverManager.getConnection`` method. The syntax of the URL is dependent on the database driver being used. It is likely to contain specifications obtained from the Data_Port Configuration.
Throws:
  `Database_Exception` - If the JDBC Connection failed.

#### Close

    public void Close()
               throws Database_Exception

Closes the JDBC Connection.

If the Connection is already closed, nothing is done.

Specified by:
  `Close` in interface `Data_Port`
Throws:
  `Database_Exception` - If there was a problem closing the JDBC Connection.

#### toString

    public String toString()

Provides a String identifying the Data_Port.

The identification includes the Data_Port Type, if known, the class ID for this JDBC_Data_Port and the class ID for the finalizer subclass.

Specified by:
  `toString` in interface `Data_Port`
Overrides:
  `toString` in class `Object`
Returns:
  The identifification for the Data_Port.

#### Description

    public String Description()

Provides a multi-line description of the Data_Port.

If the Data_Port is currently ``Open``, a description of the database connection may be included.

Specified by:
  `Description` in interface `Data_Port`
Returns:
  The multi-line description of the Data_Port and any active database connection.

#### Contents

    public String Contents(String catalog,
                  String table)

Gets a String describing the contents of selected catalogs and tables.

For each table being described each field name and its data type is listed.

Specified by:
  `Contents` in interface `Data_Port`
Parameters:
  `catalog` - The catalog to have its contents described. If it is in `table reference` format, the catalog portion of the name will be used. If null, all catalogs on the database server will be described.
  `table` - The table to have its contents described. If it is in `table reference` format, the table portion of the name will be used. If null, all tables in the catalog (or all catalogs) will be described.
Returns:
  A descriptive String.

#### Catalogs

    public Vector Catalogs()
                    throws Database_Exception

Gets the list of accessible catalogs in the database.

Specified by:
  `Catalogs` in interface `Data_Port`
Returns:
  A Vector of Strings naming all the catalogs in the database.
Throws:
  `Database_Exception` - If the Data_Port is not open, or the database rejects the operation.

#### Tables

    public Vector Tables(String catalog)
                  throws Database_Exception

Obtains the list of accessible tables contained in a catalog.

If the catalog name is null, the ``CATALOG`` from the Data_Port `Configuration` will be used. The catalog name may be in catalog.table format, in which case only the catalog portion of the name will be used.

Specified by:
  `Tables` in interface `Data_Port`
Parameters:
  `catalog` - The name of the database calolog to examine. If this is in `table reference` format only the catalog part will be used. If null or empty the ``CATALOG`` value from the `configuration`, if available, will be used.
Returns:
  A Vector of Strings naming all the tables in the catalog. If the catalog does not exist in the database, null will be returned. An empty Vector will be returned for a catalog that does not contain any tables.
Throws:
  `Database_Exception` - If the Data_Port is not open, no catalog name is available, or the database rejects the operation.

#### Field_Names

    public Vector Field_Names(String table)
                       throws Database_Exception

Gets the list of field names in a table on the database server.

Specified by:
  `Field_Names` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be examined. If null, then the ``TABLE`` from the `Configuration` will be used. If it is not in `table reference` format, the ``CATALOG`` will be used.
Returns:
  A Vector of field name Strings. If the table does not exist in the Database, a null will be returned.
Throws:
  `Database_Exception` - If the Data_Port is not open, no catalog name is available, or the operation on the database server failed.

#### Field_Types

    public Vector Field_Types(String table)
                       throws Database_Exception

Gets the list of field data types in a table on the database server.

Specified by:
  `Field_Types` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be examined. If null, then the ``TABLE`` from the `Configuration` will be used. If it is not in `table reference` format, the ``CATALOG`` will be used.
Returns:
  A Vector of field name Strings. If the table does not exist in the Database, a null will be returned.
Throws:
  `Database_Exception` - If the Data_Port is not open, no table name is available, or the operation on the database server failed.

#### Fields

    public Vector Fields(String table,
                String field_info)
                  throws Database_Exception

Obtains a list of field information for the table of a catalog.

The specified field_info must be a tag corresponding to one of the field information names obtained from the JDBC getColumns method:

TABLE_CAT (String)
  Table catalog (may be null)
TABLE_SCHEM (String)
  Table schema (may be null)
TABLE_NAME (String)
  Table name
COLUMN_NAME (String)
  Column (i.e. field) name
DATA_TYPE (short)
  SQL type from java.sql.Types
TYPE_NAME (String)
  Data source dependent type name, for a UDT the type name is fully qualified.
COLUMN_SIZE (int)
  Column size. For char or date types this is the maximum number of characters, for numeric or decimal types this is precision.
BUFFER_LENGTH (unused)
DECIMAL_DIGITS (int)
  The number of fractional digits.
NUM_PREC_RADIX (int)
  Radix (typically either 10 or 2)
NULLABLE (int)
  Is NULL allowed?
  columnNoNulls
    - might not allow NULL values
  columnNullable
    - definitely allows NULL values
  columnNullableUnknown
    - nullability unknown
REMARKS (String)
  Comment describing column (may be null)
COLUMN_DEF (String)
  Default value (may be null)
SQL_DATA_TYPE (unused)
SQL_DATETIME_SUB (unused)
CHAR_OCTET_LENGTH (int)
  For char types the maximum number of bytes in the column.
ORDINAL_POSITION (int)
  Index of the column in the table (starting at 1).
IS_NULLABLE (String)

NO
  - column definitely does not allow NULL values
YES
  - column might allow NULL values
An empty string
  - nobody knows

Specified by:
  `Fields` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be examined. If this is null then the ``TABLE`` from the `Configuration` will be used. If it is not in `table reference` format, the ``CATALOG`` will be used.
  `field_info` - The tag String for selecting field information.
Returns:
  A Vector of field information Strings, one per field. For info that is originally numeric (as indicated in the table) a String representation is returned.
Throws:
  `Database_Exception` - If no catalog or table name is available, or the database server rejected the operation.
See Also:
  `DatabaseMetaData.getColumns(String, String, String, String)`

#### Keys

    public Vector Keys(String table)
                throws Database_Exception

Gets a list of primary keys for a table.

Specified by:
  `Keys` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be examined. If this is null then the ``TABLE`` from the `Configuration` will be used. If it is not in `table reference` format, the ``CATALOG`` will be used.
Returns:
  A Vector of field name Strings.
Throws:
  `Database_Exception` - If no catalog and table name is available, or the database server rejected the operation.

#### Query

    public Vector Query(String SQL_query,
               int limit)
                 throws Database_Exception

Submit an SQL query.

The SQL_query String is an SQL statment that requests data to be extracted (not removed) from the database. The syntax, though "standardized", is likely to vary in its particulars dependent on the database server implementation.

A query always returns a table. The table is in the form of a Vector of data record Vectors. The first record contains the names (String) of each field for the data in corresponding locations of all the field value records that follow; i.e. these are the table column names. The field values in each data record are always provided in String representation regardless of the data type stored in the database. However, NULL field values remain unchanged as they are distinct from an otherwise valid field value.

Note: A field value will either be a String or null.

N.B.: All `SQL statement listeners` are notified before the SQL is sent to the database server.

Specified by:
  `Query` in interface `Data_Port`
Parameters:
  `SQL_query` - The syntax of the query string is database dependent. A typical example is an SQL "SELECT" statement.
  `limit` - The maximum number of records to return. If negative, there will be no limit to the number of records returned. If zero, no records will be returned.
Returns:
  A data table in form of a Vector of String Vectors (records). The first record is the field names for the field values in all subsequent records.
Throws:
  `Database_Exception` - If the Data_Port is not open or the operation on the database server failed.

#### Select

    public Vector Select(Vector tables,
                Vector fields,
                String conditions,
                int limit)
                  throws Database_Exception

Selects from one or more tables the data values from one or more named fields from the data records that satisfy the selection conditions.

Note: Each table name that is not in the format catalog.table will have the ``CATALOG`` from the `Configuration` prepended.

N.B.: If the limit argument is zero the SQL assmebled for the database query will be returned instead of submitting the query.

Specified by:
  `Select` in interface `Data_Port`
Parameters:
  `tables` - The Vector of database tables from which to select records. If this is null, the tables (one or more) specified by the ``TABLE`` parameter will be used.
  `fields` - A Vector of field name Strings specifying the data fields (columns) to be extracted. If this is null or empty, all data fields will be extracted.
  `conditions` - A String in SQL WHERE clause syntax (without the keyword "WHERE") specifying the conditions for selection of a data record from the database. The specific syntax of the conditions string is database dependent. If this is null, no conditions will be applied; all data records will be used.
  `limit` - The maximum number of records to return. If negative, there will be no limit to the number of records returned. N.B.: If zero, the returned vector will contain a single string that is the SQL statement that would have been submitted to the Query method.
Returns:
  A Vector of String Vectors data table,as provided by the ``Query`` method.
Throws:
  `Database_Exception` - If the Data_Port is not open, no table name is available, or the operation on the database server failed.

#### Update

    public int Update(String SQL_update)
               throws Database_Exception

Submit an SQL update.

The syntax of the SQL_update String is database dependent. These operations modify the database and return a count of the number of modifications, which may be 0 in some cases (e.g. when a catalog or table is created). Typical examples are SQL "UPDATE", "INSERT", and "ALTER" statements.

N.B.: All `SQL statement listeners` are notified before the SQL is sent to the database server.

Specified by:
  `Update` in interface `Data_Port`
Parameters:
  `SQL_update` - The SQL_update statement.
Returns:
  A count of the number of modifications.
Throws:
  `Database_Exception` - If the Data_Port is not open or the operation on the database server failed.

#### Create

    public void Create(String catalog)
                throws Database_Exception

Creates a catalog in the database.

Specified by:
  `Create` in interface `Data_Port`
Parameters:
  `catalog` - The name of the catalog to create. If it is in `table reference` format, the catalog part will be used. A null catalog name, or a name of a catalog already in the database, is ignored.
Throws:
  `Database_Exception` - If the database rejected the operation.

#### Delete

    public void Delete(String catalog)
                throws Database_Exception

Deletes a catalog from the database.

Specified by:
  `Delete` in interface `Data_Port`
Parameters:
  `catalog` - The name of the catalog to delete. A null catalog name, or a name that is not a catalog in the database, is ignored.
Throws:
  `Database_Exception` - If the database rejected the operation.

#### Create

    public void Create(String table,
              Vector fields,
              Vector types)
                throws Database_Exception

Creates data tables with their fields and the data types of the fields.

If the table does not exist, a new one is created. For each name String in the fields Vector, if the field does not exist, it is created with the data type from the corresponding entry in the types Vector. If the field is already present in the table, its data type is changed if needed.

A table name that is not in the format catalog.table will have the ``CATALOG`` from the `Configuration` prepended. If the catalog does not exist in the database, it is created.

Specified by:
  `Create` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be affected. If null, the ``TABLE`` from the `Configuration`, if any, will be used. If it is not in `table reference` format, the ``CATALOG`` will be used.
  `fields` - The Vector of field names to be used. If null, nothing is done.
  `types` - The Vector of data type names to be applied to the corresponding fields. If null, nothing is done.
Throws:
  `Database_Exception` - If the Data_Port is not open, the number of fields and types are not the same, no table name is available, or the operation on the database server failed.
See Also:
  `Data_Port.Configuration()`

#### Delete

    public void Delete(String table,
              Vector fields)
                throws Database_Exception

Deletes fields from a data table, or the entire table.

Each field in the fields list is deleted from the table. If the field is not present in the table, it is ignored. If the fields list is null, the entire table is deleted from the catalog. Note: A table is not deleted even if all of its fields are deleted. If the table does not exist in the database, nothing is done.

Specified by:
  `Delete` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be affected. If this is null then the ``TABLE`` from the `Configuration` will be used. If it is not in `table reference` format, the ``CATALOG`` will be used.
  `fields` - The Vector of field names to be used.
Throws:
  `Database_Exception` - If the Data_Port is not open, no table name is available, or the operation on the database server failed.
See Also:
  `Data_Port.Configuration()`

#### Rename

    public void Rename(String table,
              String name)
                throws Database_Exception

Renames a table.

Specified by:
  `Rename` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be affected. If this is null then the ``TABLE`` from the `Configuration` will be used. If it is not in `table reference` format, the ``CATALOG`` will be used.
  `name` - The new name for the table. If this is null, or matches the table name, nothing is done.
Throws:
  `Database_Exception` - If no catalog or table name is available, or the database server rejected the operation.

#### Rename

    public void Rename(String table,
              Vector fields,
              Vector names)
                throws Database_Exception

Renames fields in a table.

Each field name in the fields Vector that exists in the table is renamed to the corresponding name in the names Vector. Field names that do not exist in the table are ignored.

N.B.: The existing type for the field, obtained from the ``Field_Types`` method, is re-applied to the field (due to requirements of the SQL syntax). This could alter other characteristics of the field.

Specified by:
  `Rename` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be affected. If this is null then the ``TABLE`` from the `Configuration` will be used. If it is not in `table reference` format, the ``CATALOG`` will be used.
  `fields` - The Vector of field names to be renamed. If null, nothing is done.
  `names` - The Vector of new field names. If null, nothing is done.
Throws:
  `Database_Exception` - If the Data_Port is not open, the number of fields and types are not the same, no table name is available, or the operation on the database server failed.

#### Insert

    public int Insert(String table,
             Vector fields,
             Vector values)
               throws Database_Exception

Inserts values for selected fields into a table.

A new data record is created in the table. The fields Vector lists the names of the fields to be assigned a data value from the corresponding entry in the values Vector. The Vector of data values does not necessarily have to contain Strings, as long as each object's toString method produces a valid representation of the field value (or the object is null). Though the fields and values Vectors must be the same size, not all fields in the table need to be included; the database is expected to provide a default value for missing fields.

Specified by:
  `Insert` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be affected. If null, the ``TABLE`` from the `Configuration` will be used. If it is not in `table reference` format, the ``CATALOG`` will be used.
  `fields` - The Vector of field names for the data values. If null, nothing is done.
  `values` - The Vector of data values corresponding the Vector of field names. If null, nothing is done.
Returns:
  The number of records inserted; 1 if successful; 0 otherwise.
Throws:
  `Database_Exception` - If the Data_Port is not open, the number of fields and values are not the same, no table name is available, a specified field is not in the table, or the operation on the database server failed.

#### Update

    public int Update(String table,
             Vector fields,
             Vector values,
             String conditions)
               throws Database_Exception

Updates values for selected fields into a table.

The fields Vector lists the names of the fields to be assigned a new data value from the corresponding entry in the values Vector. The Vector of data values does not necessarily have to contain Strings, as long as each object's toString method produces a valid representation of the field value (or the object is null). The records to have their field values updated will be selected by the conditions expression. This is an SQL WHERE expression (without the "WHERE" keyword). If no conditions are provided, then all records will be updated.

Specified by:
  `Update` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be affected. If this is null then the ``TABLE`` from the `Configuration` will be used. If it is not in `table reference` format, the ``CATALOG`` will be used.
  `fields` - The Vector of field names for the data values.
  `values` - The Vector of data values corresponding the Vector of field names.
  `conditions` - A String in SQL WHERE clause syntax (without the keyword "WHERE") specifying the conditions for selection of a data record from the database. The specific syntax of the conditions string is database dependent. If this is null, no conditions will be applied; all data records will be used.
Returns:
  The number of records that were modified.
Throws:
  `Database_Exception` - If the Data_Port is not open, the number of fields and values are not the same, no table name is available, or the operation on the database server failed.

#### Delete

    public int Delete(String table,
             String conditions)
               throws Database_Exception

Deletes selected records from a table.

The records to be deleted will be selected by the conditions expression. This is an SQL WHERE expression (without the "WHERE" keyword).

Warning: If no conditions are provided, then all records will be deleted leaving an empty table.

Specified by:
  `Delete` in interface `Data_Port`
Parameters:
  `table` - The name of the table to be affected. If this is null then the ``TABLE`` from the `Configuration` will be used. If it is not in `table reference` format, the ``CATALOG`` will be used.
  `conditions` - A String in SQL WHERE clause syntax (without the keyword "WHERE") specifying the conditions for selection of a data record from the database. The specific syntax of the conditions string is database dependent. If this is null, no conditions will be applied and all data records will be deleted.
Returns:
  The number of records that were deleted.
Throws:
  `Database_Exception` - If the Data_Port is not open, no table name is available, or the operation on the database server failed.

#### Table_Reference

    public String Table_Reference(String catalog,
                         String table)
                           throws Database_Exception

Generates a table reference from a catalog and table name.

A table reference in a Data_Port method is a composite name combining a catalog name and a table name in the format:

catalog`delimiter`table

If a non-null, non-empty catalog name is specified the catalog portion of the name (which may itself be a table reference) will override any catalog name portion that might be in a table name that is already in table reference format. For null or empty table or catalog names the value of the ``CATALOG`` and/or ``TABLE`` Configuration parameters will be used.

Specified by:
  `Table_Reference` in interface `Data_Port`
Parameters:
  `catalog` - The catalog name portion for the table reference. If it is in table reference format, the catalog portion will be used. If null or empty, the ``CATALOG`` value from the `configuration`, if available, will be used.
  `table` - The table name portion for the table reference. If it is in table reference format, the table portion will be used. If null, the ``TABLE`` value from the `configuration`, if available, will be used.
Returns:
  A table reference suitable for use as a `table` argument of a JDBC_Data_Port method.
Throws:
  `Database_Exception` - If a table reference can not be formed.

#### Catalog_Name

    public String Catalog_Name(String table_reference)

Gets the catalog part of a `table reference`.

Specified by:
  `Catalog_Name` in interface `Data_Port`
Parameters:
  `table_reference` - A String that may be a composite name combining a catalog name and a table name. May be null.
Returns:
  The catalog name portion of the table reference. If the table_reference is null or does not contain a `Component_Delimiter` character, the empty String is returned.
See Also:
  `Table_Reference(String, String)`

#### Database_Catalog_Name

    public String Database_Catalog_Name(String catalog)
                                 throws Database_Exception

Gets the name known to the database server for a catalog name.

Only accessible catalogs can be identified. If the database server determines that the connection does not have permission to access the specified catalog then it can not be identified.

N.B.: Identifying the catalog from the list of accessible catalogs is done using the `case sensitivity` of the Data_Port implementation. Therefore, if case sensitive matching is used this method can only return the specified catalog name or null; in this case this method is only useful for determining if a catalog is accessible or not.

Specified by:
  `Database_Catalog_Name` in interface `Data_Port`
Parameters:
  `catalog` - The name of the database calolog to examine. If this is a `table reference` only the catalog part will be used. If null or empty the ``CATALOG`` value from the `configuration`, if available, will be used.
Returns:
  The name of the catalog as it is known in the database. This will be null if a non-null, non-empty catalog name could not be identified in the database.
Throws:
  `Database_Exception` - If the Data_Port is not open, a catalog name was not provided, or the database rejects the operation.

#### Table_Name

    public String Table_Name(String table_reference)

Gets the table part of a `table reference`.

Specified by:
  `Table_Name` in interface `Data_Port`
Parameters:
  `table_reference` - A String that may be a composite name combining a catalog name and a table name. May be null.
Returns:
  The table name portion of the table reference. If the table_reference does not contain a `Component_Delimiter` character, the entire String is returned. If it is null the empty String is returned.
See Also:
  `Table_Reference(String, String)`

#### Database_Table_Name

    public String Database_Table_Name(String table)
                               throws Database_Exception

Gets the name known to the database server for a table name.

Only accessible catalogs can be identified. If the database server determines that the connection does not have permission to access the specified catalog then it can not be identified.

N.B.: Identifying the catalog from the list of accessible catalogs is done using the `case sensitivity` of the Data_Port implementation. Therefore, if case sensitive matching is used this method can only return the specified catalog name or null; in this case this method is only useful for determining if a catalog is accessible or not.

Specified by:
  `Database_Table_Name` in interface `Data_Port`
Parameters:
  `table` - The name of the table to identify in the database. If null, then the ``TABLE`` value from the `Configuration`, if present, will be used. If it is not in catalog.table format, the ``CATALOG`` value, if present, will be used.
Returns:
  The name of the catalog as it is known in the database. This will be null if a catalog name could not be identified in the database.
Throws:
  `Database_Exception` - If the Data_Port is not open, catalog and table names were not provided, or the database rejects the operation.

#### Table_Reference_Component_Delimiter

    public String Table_Reference_Component_Delimiter()

Gets the table reference component delimiter.

Specified by:
  `Table_Reference_Component_Delimiter` in interface `Data_Port`
Returns:
  The portion of a table reference that delimits the catalog component from the table component.
See Also:
  `Table_Reference(String, String)`

#### Case_Sensitive_Identifiers

    public boolean Case_Sensitive_Identifiers()

Description copied from interface: `Data_Port`
Tests if identifier names are treated as case sensitive by the Data_Port.

Because some database servers on some operating systems are not case sensitive in handling identifiers (the names of catalogs, tables, and field names) it is necessary to enforce case insensitivity when matching user specified names against identifiers returned from the database server. This method indicates how the Data_Port expects identifier names to be treated.

N.B.: The identifier case sensitivity that is reported by the Data_Port does not necessarily reflect the identifier case sensitivity of the database server under all circumstances. Some identifiers may be case sensitive and others not, a given identifier may be case sensitive on some systems but not on others, an identifier may be case sensitive if double quoted but otherwise not (PostgreSQL); the rules are database implementation specific.

What the Case_Sensitive_Identifiers flag indicates is how indentifiers provided the by the user will be matched against identifiers provided by the database server.

Specified by:
  `Case_Sensitive_Identifiers` in interface `Data_Port`
Returns:
  true if identifiers will be matched with case sensitive comparisons; false if matching will ignore case.
See Also:
  `Data_Port.Case_Sensitive_Identifiers()`

#### Case_Sensitive_Identifiers

    public void Case_Sensitive_Identifiers(boolean case_sensitive)

Description copied from interface: `Data_Port`
Attempts to set whether identifier names are treated as case sensitive by the Data_Port.

N.B.: This setting does not itself determine the case sensitivity of the identifiers by the database server. The value is used to inform the Database software if case sensitive matches should be done. Setting the value to true when the database server uses case insensitive identifiers (mixed case identifiers provided by the user to the database server being always read back as all lowercase) will ultimately result in unexpected mismatches. Only set the value to true when it is known that the database server accessed by the Data_Port is capable of using case sensitive identifiers.

N.B.: A Data_Port implementation is free to ignore this setting, and may even through an exception if it thinks that the value would cause problems. In general, it is best to leave the case sensitive identifiers setting up to the Data_Port. Only when the application is aware of particular circumstances when using a particular database server that would call for a change of the Data_Port setting should the value be changed.

Specified by:
  `Case_Sensitive_Identifiers` in interface `Data_Port`
Parameters:
  `case_sensitive` - true if identifiers are to be matched with case sensitive comparisons; false if matching is to ignore case.
See Also:
  `Data_Port.Case_Sensitive_Identifiers(boolean)`

#### Config_Value

    protected String Config_Value(String parameter)

Gets a Value for a Configuration Parameter.

Only one Value is obtained; this will be the first Value when the Parameter is associated with an Array.

Parameters:
  `parameter` - The pathname to the Parameter.
Returns:
  The String representation of the Parameter Value. If the named Parameter can not be found an empty String will be returned.

#### catalog_name

    protected String catalog_name(String method,
                      String catalog_table)
                           throws Database_Exception

Gets a catalog name.

If the catalog_table String contains a Catalog_Name, that is returned. Otherwise the Database.CATALOG parameter from the Configuration, if present, is returned. If no catalog name can be found a Database_Exception is thrown.

Parameters:
  `method` - The name of the method that needs a catalog name. This name will be used in the Database_Exception message.
  `catalog_table` - A String to be provided to Catalog_Name in an attempt to extract a catalog name portion.
Returns:
  The name of a catalog.
Throws:
  `Database_Exception` - If no catalog name can be found.

#### table_name

    protected String table_name(String method,
                    String catalog_table)
                         throws Database_Exception

Gets a table name.

If the catalog_table String contains a Table_Name, that is returned. Otherwise the Database.TABLE parameter from the Configuration, if present, is returned. If no table name can be found a Database_Exception is thrown.

Parameters:
  `method` - The name of the method that needs a table name. This name will be used in the Database_Exception message.
  `catalog_table` - A String to be provided to Table_Name in an attempt to extract a table name portion.
Returns:
  The name of a table.
Throws:
  `Database_Exception` - If no table name can be found.

#### composite_name

    protected String composite_name(String method,
                        String catalog_table)
                             throws Database_Exception

Gets a composite name.

A composite name is the `catalog_name(String, String)` plus the `table_name(String, String)` separated by the `Component_Delimiter`. This is effectively the same as a `Table_Reference(String, String)` but derived from a single catalog_table reference name.

Parameters:
  `method` - The name of the method that needs a composite name. This name will be used in the Database_Exception message.
  `catalog_table` - A String to be provided to catalog_name and table_name in an attempt to obtain catalog and table names.
Returns:
  A table reference string with both catalog an table name parts.
Throws:
  `Database_Exception` - If no catalog or table name can be found.

#### List_String

    protected static String List_String(Vector list)

Produce a String representation of a Vector list.

Each list element, which must be a String of non-zero length (zero length String elements are ignored), are concatenated with the ", " delimiter between them. This produces a list representation suitable for use in SQL syntax.

Parameters:
  `list` - A Vector of Strings.
Returns:
  A String containing all the non-zero length elements of the list, in the order they occur in the list, separated by the ", " delimiter.