com.prosyst.mprm.backend.dbconnection.jdbc

Interface ConnectionManager

public interface ConnectionManager

Connection manager manages a pool of connections to one database server. The connections are shared between all database services which maintains its databases in the same database server.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CHAR
static java.lang.String	FLOAT
static java.lang.String	INT
static java.lang.String	LONGVARBINARY
static java.lang.String	LONGVARCHAR
static java.lang.String	NUMERIC
static int	TABLES_INCOMPATIBLE
static int	TABLES_NOT_EXIST
static int	TABLES_OK
static java.lang.String	TIMESTAMP
static java.lang.String	VARCHAR

Method Summary

Modifier and Type	Method and Description
void	createTables(java.io.InputStream in) Creates tables in the database.
void	createTables(java.io.InputStream in, java.sql.Connection conn) The same as createTables(InputStream), except that queries are executed over the passed connection.
long	getAbsoluteTimestamp() Returns the current absolute timestamp (UTC offset) according the clock of the underlying DB server - that is, a heuristic calculation of the result of calling System.currentTimeMillis() on the DB server host.
java.sql.Timestamp	getCalendricTimestamp() Returns a java.sql.Timestamp object, representing the current calendar time of the underlying DB server.
java.sql.Connection	getConnection() Returns SQL connection for the connection pool represented by this interafce.
com.prosyst.mprm.data.system.DBCatalogueInfo	getDBCatalogEntry(java.lang.String dbName) Returns DBCatalogInfo with the specified entry from system database table.
com.prosyst.mprm.data.system.DBCatalogueInfo	getDBCatalogEntry(java.lang.String dbName, java.sql.Connection connection) See {link #getDBCatalogEntry(String)}.
DBMetaData	getMetaData() Returns object, analogous to java.sql.DatabaseMetaData, but only a limited subset of it.
java.sql.Connection	getReadOnlyConnection() Returns readOnly SQL connection.
int	validateTables(java.io.InputStream in) Checks the format of a database table.
int	validateTables(java.io.InputStream in, java.sql.Connection conn) The same as validateTables(InputStream), except that queries are executed over the passed connection.
void	writeDBCatalogEntry(java.lang.String dbName, java.lang.String version) Writes DBCatalogueInfo entry in the system database table.
void	writeDBCatalogEntry(java.lang.String dbName, java.lang.String version, java.sql.Connection connection) Writes DBCatalogueInfo entry in the system database table.

Field Detail

TABLES_OK

static final int TABLES_OK

See Also:

Constant Field Values

TABLES_NOT_EXIST

static final int TABLES_NOT_EXIST

See Also:

Constant Field Values

TABLES_INCOMPATIBLE

static final int TABLES_INCOMPATIBLE

See Also:

Constant Field Values

LONGVARBINARY

static final java.lang.String LONGVARBINARY

See Also:

Constant Field Values

INT

static final java.lang.String INT

See Also:

Constant Field Values

VARCHAR

static final java.lang.String VARCHAR

See Also:

Constant Field Values

CHAR

static final java.lang.String CHAR

See Also:

Constant Field Values

LONGVARCHAR

static final java.lang.String LONGVARCHAR

See Also:

Constant Field Values

NUMERIC

static final java.lang.String NUMERIC

See Also:

Constant Field Values

FLOAT

static final java.lang.String FLOAT

See Also:

Constant Field Values

TIMESTAMP

static final java.lang.String TIMESTAMP

See Also:

Constant Field Values

Method Detail

getConnection

java.sql.Connection getConnection()
                           throws java.sql.SQLException

Returns SQL connection for the connection pool represented by this interafce. The connection is returnd in the pool after invoking of its close method. Since the connections are usually shared between several db services, the implementation of database services must ensure invoking of close method after finishing every chunk of work with the connection.

Returns:

JDBC Connection object which provides methods for working whith the SQL RDBMS.

Throws:

java.sql.SQLException - if an error occures while connecting to the database server.

getReadOnlyConnection

java.sql.Connection getReadOnlyConnection()
                                   throws java.sql.SQLException

Returns readOnly SQL connection.

Returns:

JDBC Connection object which provides methods for working whith the SQL RDBMS.

Throws:

java.sql.SQLException - if an error occures while connecting to the database server.

getDBCatalogEntry

com.prosyst.mprm.data.system.DBCatalogueInfo getDBCatalogEntry(java.lang.String dbName)
                                                        throws java.sql.SQLException

Returns DBCatalogInfo with the specified entry from system database table. Every DBCatalogInfo contains the following fields: DBService Name, DBService Version and mPRM System Id.

Parameters:

dbName - the name of a DBService

Returns:

DBCatalogInfo entry

Throws:

java.sql.SQLException

getDBCatalogEntry

com.prosyst.mprm.data.system.DBCatalogueInfo getDBCatalogEntry(java.lang.String dbName,
                                                               java.sql.Connection connection)
                                                        throws java.sql.SQLException

See {link #getDBCatalogEntry(String)}. This method performs the database read operation over the passed connection, or creates a new connection if passed one is null.

Parameters:

connection - existing SQL connection, if null a connection is created internally

dbName - the name of a DBService

Returns:

DBCatalogInfo entry

Throws:

java.sql.SQLException

writeDBCatalogEntry

void writeDBCatalogEntry(java.lang.String dbName,
                         java.lang.String version)
                  throws java.sql.SQLException

Writes DBCatalogueInfo entry in the system database table.

Parameters:

dbName - the name of a DBService

version - the version of a DBService

Throws:

java.sql.SQLException

writeDBCatalogEntry

void writeDBCatalogEntry(java.lang.String dbName,
                         java.lang.String version,
                         java.sql.Connection connection)
                  throws java.sql.SQLException

Writes DBCatalogueInfo entry in the system database table.

Parameters:

dbName - the name of a DBService

version - the version of a DBService

connection - existing connection which will be used for writing the entry in the database

Throws:

java.sql.SQLException

createTables

void createTables(java.io.InputStream in)
           throws java.sql.SQLException

Creates tables in the database. The input stream must be a sequence of sql CREATE statements. Supported column types are "VARCHAR", "INTEGER", "LONGVARBINARY", "LONGVARCHAR", "NUMERIC", "FLOAT", and "TIMESTAMP". These are translated to the native sql types of the db server.

Parameters:

in - the sequence of CREATE statements.

Throws:

java.sql.SQLException

createTables

void createTables(java.io.InputStream in,
                  java.sql.Connection conn)
           throws java.sql.SQLException

The same as createTables(InputStream), except that queries are executed over the passed connection. Useful if a DB service has a transactional variant.

Parameters:

in - create SQL script

conn - connection to use ; if null, the method does exactly the same as createTables(InputStream)

Throws:

java.sql.SQLException

validateTables

int validateTables(java.io.InputStream in)
            throws java.sql.SQLException

Checks the format of a database table. Only the types and the names of the columns of the table are checked, and none of its constraints. At least one of the columns of the table being checked must be of type "INTEGER" or "VARCHAR" or "NUMERIC" or "FLOAT". False could be returned if a disconnection takes place or any exception is thrown by the connection.

Parameters:

in - a sequence of CREATE statements defining the structure of the tables.

Returns:

• TABLES_OK - if the table exists and its format is correct
• TABLES_NOT_EXIST - if the tables do not exist
• TABLES_INCOMPATIBLE - if the tables exist but their format differs.

Throws:

java.sql.SQLException

validateTables

int validateTables(java.io.InputStream in,
                   java.sql.Connection conn)
            throws java.sql.SQLException

The same as validateTables(InputStream), except that queries are executed over the passed connection. Useful if a DB service has a transactional variant.

Parameters:

in - create SQL script

conn - connection to use ; if null, the method does exactly the same as validateTables(InputStream)

Returns:

@see validateTables(InputStream)

Throws:

java.sql.SQLException

getCalendricTimestamp

java.sql.Timestamp getCalendricTimestamp()
                                  throws java.sql.SQLException

Returns a java.sql.Timestamp object, representing the current calendar time of the underlying DB server. The timestamp returned represents the same calendar time on all mPRM hosts, not depending on the host's time zone.

This method should be used by subsystems that treat times of different origin as calendrically equivalent (5 o'clock on site 1 is the same as 5 o'clock on site 2, even if the sites are in different time zones). The return value does not give equivalent results when treated as an absolute timestamp - its conversion to absolute format depends on the time zone of the calling host. Therefore, the results of invoking getTime() or a similar conversion on the returned object do not produce equivalent results and the return value should not be used in that way.

Returns:

the calendric timestamp of the underlying DB server, producing calendrically equivalent results on all hosts

Throws:

java.sql.SQLException

See Also:

getAbsoluteTimestamp()

getAbsoluteTimestamp

long getAbsoluteTimestamp()
                   throws java.sql.SQLException

Returns the current absolute timestamp (UTC offset) according the clock of the underlying DB server - that is, a heuristic calculation of the result of calling System.currentTimeMillis() on the DB server host. The return value is an absolute timestamp, equivalent as such on all mPRM hosts, not depending on host time zones in case daylight savings are either not taken into account or the DST offset is round hours.

This method should be used by subsystems that wish to support absolute time-keeping and want to avoid minor discrepancies in different backend host clocks. The method does not provide a solution for incorreclty set machine clocks - on the contrary, the correct results depend on the approximately correct settings of the clocks on calling backend host relative to the clock of the DB server.

The method will yield completely correct results in environments, where all interested mPRM hosts and the DB server are in the same time zone and with tolerable discrepancies in their local clock times (within half the time difference between the local time zone and the closer of its neighbours).

Returns:

current absolute timestamp (UTC offset) as measured by the clock of the underlying DB server

Throws:

java.sql.SQLException

getMetaData

DBMetaData getMetaData()

Returns object, analogous to java.sql.DatabaseMetaData, but only a limited subset of it. It also contains some ConnectionManager-specific properties, like the connection limit.

Returns:

DBMetaData object containing database properties