PIRL.Database

## Class PostgreSQL_Data_Port

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

All Implemented Interfaces:
  Data_Port

    public class PostgreSQL_Data_Port
    extends JDBC_Data_Port
    implements Data_Port

Provides access to a PostgreSQL database via a JDBC_Data_Port.

See Also:
  `JDBC_Data_Port`

### Field Summary

Fields
`static String` `ID` Class name and version identification.
`static String[]` `Optional_Parameters` Optional Configuration parameters.
`static String` `PORT` The Configuration parameter to use when specifying a specific port for connection to the database server.
`static String` `Port_Type` Data_Port Type name.
`static String[][]` `URL_Specs` Required Configuration parameters and their default values.

### Fields inherited from class PIRL.Database.JDBC_Data_Port

`Case_Sensitive_Identifiers, Component_Delimiter, Treat_Schema_As_Catalog`

### Constructor Summary

Constructors
Constructor and Description
`PostgreSQL_Data_Port()` Constructs the abstract JDBC_Data_Port finalizer class, registers the class ID and name of the Data_Port type, and sets the flag to treat schema as Database "catalogs".

### Method Summary

Methods
`void` `Open(Configuration configuration)` Implements the Data_Port `Open` method.
`Configuration` `Parameters()` Implements the Data_Port `Parameters` method.
`Vector` `Query(String SQL_query, int limit)` Specialization of the Query method to provide implementation of the limit functionality using the server specific capability.
`void` `Rename(String table, String name)` Specialization of the Rename table functionality using server specific syntax.

### Methods inherited from class PIRL.Database.JDBC_Data_Port

`Add_SQL_Listener, Case_Sensitive_Identifiers, Case_Sensitive_Identifiers, Catalog_Name, catalog_name, Catalogs, Close, composite_name, Config_Value, Configuration, Configure, Connection, Contents, Create, Create, Database_Catalog_Name, Database_Table_Name, Delete, Delete, Delete, Description, Field_Names, Field_Types, Fields, ID_Type, Insert, is_Open, Keys, List_String, Open_Data_Port, Remove_SQL_Listener, Rename, Select, Table_Name, table_name, Table_Reference_Component_Delimiter, Table_Reference, Tables, toString, Update, Update`

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

`Add_SQL_Listener, Case_Sensitive_Identifiers, Case_Sensitive_Identifiers, Catalog_Name, Catalogs, Close, Configuration, Connection, Contents, Create, Create, Database_Catalog_Name, Database_Table_Name, Delete, Delete, Delete, Description, Field_Names, Field_Types, Fields, Insert, is_Open, Keys, Remove_SQL_Listener, Rename, Select, Table_Name, Table_Reference_Component_Delimiter, Table_Reference, Tables, toString, Update, Update`

### Field Detail

#### ID

    public static final String ID

Class name and version identification.

See Also:
  Constant Field Values

#### Port_Type

    public static final String Port_Type

Data_Port Type name.

See Also:
  Constant Field Values

#### URL_Specs

    public static final String[][] URL_Specs

Required Configuration parameters and their default values.

``Database.DRIVER``
  org.postgresql.Driver
``Configuration.HOST``
  localhost
``Database.DATABASE``
  public

#### PORT

    public static final String PORT

The Configuration parameter to use when specifying a specific port for connection to the database server.

See Also:
  Constant Field Values

#### Optional_Parameters

    public static final String[] Optional_Parameters

Optional Configuration parameters.

These parameters are based on the use of the PostgreSQL JDBC driver, version 8.3.

#### Connection Parameters

`user`
  The database user on whose behalf the connection is being made. [none]
`password`
  The database user's password. [none]
`ssl`
  Connect using SSL. The driver must have been compiled with SSL support. This property does not need a value associated with it. The mere presence of it specifies a SSL connection. However, for compatibility with future versions, the value "true" is preferred. [false]
`sslfactory`
  The provided value is a class name to use as the SSLSocketFactory when establishing a SSL connection. [none]
`sslfactoryarg`
  This value is an optional argument to the constructor of the sslfactory class provided above. [none]
`compatible`
  Act like an older version of the driver to retain compatibility with older applications. At the moment this controls two driver behaviors: the handling of binary data fields, and the handling of parameters set via setString(). Older versions of the driver used this property to also control the protocol used to connect to the backend. This is now controlled by the protocolVersion property. [none]
`protocolVersion`
  The driver supports both the V2 and V3 frontend/backend protocols. The V3 protocol was introduced in 7.4 and the driver will by default try to connect using the V3 protocol, if that fails it will fall back to the V2 protocol. If the protocolVersion property is specified, the driver will try only the specified protocol (which should be either "2" or "3"). Setting protocolVersion to "2" may be used to avoid the failed attempt to use the V3 protocol when connecting to a version 7.3 or earlier server, or to force the driver to use the V2 protocol despite connecting to a 7.4 or greater server. [3]
`loglevel`
  Set the amount of logging information printed to the DriverManager's current value for LogStream or LogWriter. It currently supports values of org.postgresql.Driver.DEBUG (2) and org.postgresql.Driver.INFO (1). INFO will log very little information while DEBUG will produce significant detail. This property is only really useful if you are a developer or are having problems with the driver. [0]
`charSet`
  The character set to use for data sent to the database or recieved from the database. This property is only relevent for server versions less than or equal to 7.2. The 7.3 release was the first with multibyte support compiled by default and the driver uses its character set translation facilities instead of trying to do it itself. [none]
`allowEncodingChanges`
  When using the V3 protocol the driver monitors changes in certain server configuration parameters that should not be touched by end users. The client_encoding setting is set by the driver and should not be altered. If the driver detects a change it will abort the connection. There is one legitimate exception to this behavior though, using the COPY command on a file residing on the server's filesystem. The only means of specifying the encoding of this file is by altering the client_encoding setting. The JDBC team considers this a failing of the COPY command and hopes to provide an alternate means of specifying the encoding in the future, but for now there is this URL parameter. Enable this only if you need to override the client encoding when doing a copy. [false]
`logUnclosedConnections`
  Clients may leak Connection objects by failing to call its close() method. Eventually these objects will be garbage collected and the finalize() method will be called which will close the Connection if caller has neglected to do this himself. The usage of a finalizer is just a stopgap solution. To help developers detect and correct the source of these leaks the logUnclosedConnections URL parameter has been added. It captures a stacktrace at each Connection opening and if the finalize() method is reached without having been closed the stacktrace is printed to the log. [false]
`prepareThreshold`
  Determine the number of PreparedStatement executions required before switching over to use server side prepared statements. The default is five, meaning start using server side prepared statements on the fifth execution of the same PreparedStatement object. [5]
`loginTimeout`
  Specify how long to wait for establishment of a database connection. The timeout is specified in seconds. [Pulled timeout from DriverManager.getLoginTimeout()
`stringtype`
  Specify the type to use when binding PreparedStatement parameters set via setString(). If stringtype is set to varchar (the default), such parameters will be sent to the server as varchar parameters. If stringtype is set to unspecified, parameters will be sent to the server as untyped values, and the server will attempt to infer an appropriate type. This is useful if you have an existing application that uses setString() to set parameters that are actually some other type, such as integers, and you are unable to change the application to use an appropriate method such as setInt(). [varchar]

### Constructor Detail

#### PostgreSQL_Data_Port

    public PostgreSQL_Data_Port()

Constructs the abstract JDBC_Data_Port finalizer class, registers the class ID and name of the Data_Port type, and sets the flag to treat schema as Database "catalogs".

### Method Detail

#### Parameters

    public Configuration Parameters()
                             throws Database_Exception

Implements the Data_Port `Parameters` method.

Specified by:
  `Parameters` in interface `Data_Port`
Returns:
  A Configuration of Required and Optional Data_Port parameters.
Throws:
  `Database_Exception` - If the Data_Port could not be accessed.
See Also:
  `Data_Port.Parameters()`

#### Open

    public void Open(Configuration configuration)
              throws Database_Exception

Implements the Data_Port `Open` method.

The Configuration that is supplied is conditionally set (existing parameters of the same name are not reset) with the required `URL specifications` default values. Then the Configuration is provided to the base JDBC_Data_Port ``Configure`` method to load the JDBC driver and save the Configuration.

The URL specifying how the connection will be made to the database server has the form:

jdbc:postgresql://[HOST][:PORT]/CATALOG[?param1=value1[&param2=value2][...]]

All of the parameters will be sought in the Configuration. The paramN options are in the `optional parameters` list. Parameters with these names in the Configuration will be included in the URL, otherwise they will be omitted.

The URL specification is provided to the JDBC_Data_Port ``Open_Data_Port`` method which opens a connection to the database server.

Specified by:
  `Open` in interface `Data_Port`
Specified by:
  `Open` in class `JDBC_Data_Port`
Parameters:
  `configuration` - The Configuration for this Data_Port.
Throws:
  `Database_Exception` - If no Configuration is provided or the JDBC_Data_Port fails to load the driver or make the connection to the database server.
See Also:
  `Configuration`

#### Query

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

Specialization of the Query method to provide implementation of the limit functionality using the server specific capability.

Specified by:
  `Query` in interface `Data_Port`
Overrides:
  `Query` in class `JDBC_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.
See Also:
  `JDBC_Data_Port.Query(String, int)`

#### Rename

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

Specialization of the Rename table functionality using server specific syntax.

Specified by:
  `Rename` in interface `Data_Port`
Overrides:
  `Rename` in class `JDBC_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.
  `name` - The new name for the table. If this is null, nothing is done.
Throws:
  `Database_Exception` - If no catalog or table name is available, or the database server rejected the operation.