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.

Version:

1.5

Author:

Bradford Castalia, UA/PIRL

See Also:

JDBC_Data_Port

Field Summary

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

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

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.