oracle.ifs.server

Class LibraryConnection

java.lang.Object

oracle.ifs.server.LibraryConnection

Direct Known Subclasses:

TieLibraryConnection

public class LibraryConnection
extends Object

A LibraryConnection encapsulates a database connection.

Version:

2.0

Author:

Dave Long, David Pitfield

(Unpublished)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	LibraryConnection.TransactionStateListener TransactionStateListener is an abstract inner class used to provide a way of alerting custom listeners to the changes in Transaction state.

Field Summary

Fields

Modifier and Type	Field and Description
protected Connection	m_Connection The database connection.
protected String	m_ConnectionPoolName The name of this ConnectionPool to which this LibraryConnection belongs.
protected long	m_Id An identifer, accessible using getId.
protected int	m_LibraryQueryStatementCount The number of LibraryQueryStatements current in the m_LibraryQueryStatements map (not the same as the map's size)
protected HashMap	m_LibraryQueryStatements LibraryQueryStatements previously prepared in this LibraryConnection, hashed by statement name.
protected HashMap	m_PreparedStatements PreparedStatements previously prepared in this LibraryConnection, hashed by statement name.
protected S_LibraryService	m_Service The S_LibraryService that contains this LibraryConnection.
protected String	m_SessionLanguage The current Connection's language
protected long	m_StatementAccessSequence The sequence number marking the last time a cached statement has been used.
protected long	m_StatementAccessSequenceAtPreviousPurge The sequence number the last time a purge was attempted.
protected int	m_StatementCacheSizeTrigger The number of statements that need to be cached before a purge is triggered.
protected int	m_StatementCacheTarget The target maximum number of statements we wish to keep cached.
protected int	m_StatementResetLimit Access limit at which the saved statements will be closed and re-opened.
protected boolean	m_StatementResetRequested An indication that a reset of all cached statements has been requested.
protected long	m_StatementValidityRsn The resolution sequence number at which the validity of the cached PreparedStatements and LibraryQueryStatements was last confirmed.
protected oracle.ifs.server.LibraryConnection.TransactionStateManager	m_TransactionStateManager The internal TransactionStateManager.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	LibraryConnection(long id, S_LibraryService service, String connectionPoolName, DataSource dataSource, PrintStream jdbcLogStream, int defaultRowPrefetch, int statementResetLimit, int stmtCacheTarget, int stmtCacheTrigger) Constructs a LibraryConnection.

Method Summary

Modifier and Type	Method and Description
LibraryQueryStatement	acquireLibraryQueryStatement(String key) Acquires an instance of the specified LibraryQueryStatement from the LibraryQueryStatement cache.
void	addPreparedStatement(String key, PreparedStatement stmt) Caches the specified PreparedStatement.
void	addTransactionStateListener(LibraryConnection.TransactionStateListener listener) Adds a TransactionStateListener.
protected void	alterSessionLanguage(String language) alterSessionLanguage
protected void	alterSessionSqlTrace(boolean enabled) alter the SQL_TRACE parameter for the database session
protected int	closeLibraryQueryStatements(int closeCount, int sizeest, long seqTarget) Close least recently used LibraryQueryStatements.
protected int	closePreparedStatements(int closeCount, int sizeest, long seqTarget) Close least recently used PreparedStatements.
protected void	commit() Commits the database Connection represented by this LibraryConnection.
protected void	dispose() Shuts down this LibraryConnection.
protected void	disposeCachedStatements() Close all cached statements, and clear the caches.
protected String	fetchSessionLanguage() fetchSessionLanguage
protected void	finalize() Finalizes this LibraryConnection.
PreparedStatement	findPreparedStatement(String key) Finds the specified PreparedStatement in the PreparedStatement cache.
Connection	getConnection() Gets the database Connection represented by this LibraryConnection.
String	getConnectionPoolName() Gets the name of the ConnectionPool to which this LibraryConnection belongs.
protected long	getId() Gets the identifier of this LibraryConnection.
protected S_LibraryService	getService() Gets the S_LibraryService to which this LibraryConnection belongs.
String	getSessionLanguage() get current language of the database session
protected long	getStatementValidityRsn() Gets the current StatementValidity resolution sequence number (RSN) of this LibraryConnection.
protected int	handleResetOfCachedStatements() Dispose of any cached statements if a reset has been indicated.
protected boolean	isDisposed() Return true if this LibraryConnection has been disposed.
protected boolean	isValid() Detects whether the connection is still valid, by checking the encapsulated database connection.
protected int	purge() Purges statement caches if needed.
void	releaseLibraryQueryStatement(LibraryQueryStatement lstmt) Places the specified LibraryQueryStatement in the LibraryQueryStatement cache.
protected void	resetCachedStatements() Prevent any statements currently cached from being re-used.
protected void	rollback() Rolls-back the database Connection represented by this LibraryConnection.
protected void	rollback(String savepoint) Rolls-back the database Connection represented by this LibraryConnection to the specified savepoint.
protected void	rollbackOrDispose() Rolls-back the database Connection represented by this LibraryConnection.
protected void	rollbackOrDispose(String savepoint) Rolls-back the database Connection represented by this LibraryConnection to the specified savepoint.
protected void	setSavepoint(String savepoint) Sets a savepoint in the database Connection represented by this LibraryConnection.
String	setSessionLanguage(String language) set current language of the database session if different from the current setting.
protected void	verifyConnectionValidity() Verify validity of database connection by trying simple query.
protected void	verifyNotDisposed() Verify that this LibraryConnection is still valid (i.e. is not disposed).

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

m_Id

protected long m_Id

An identifer, accessible using getId.

(Unpublished)

m_Connection

protected Connection m_Connection

The database connection.

(Unpublished)

m_SessionLanguage

protected String m_SessionLanguage

The current Connection's language

(Unpublished)

m_Service

protected S_LibraryService m_Service

The S_LibraryService that contains this LibraryConnection.

(Unpublished)

m_ConnectionPoolName

protected String m_ConnectionPoolName

The name of this ConnectionPool to which this LibraryConnection belongs.

(Unpublished)

m_PreparedStatements

protected HashMap m_PreparedStatements

PreparedStatements previously prepared in this LibraryConnection, hashed by statement name.

(Unpublished)

m_LibraryQueryStatements

protected HashMap m_LibraryQueryStatements

LibraryQueryStatements previously prepared in this LibraryConnection, hashed by statement name.

(Unpublished)

m_LibraryQueryStatementCount

protected int m_LibraryQueryStatementCount

The number of LibraryQueryStatements current in the m_LibraryQueryStatements map (not the same as the map's size)

(Unpublished)

m_StatementResetLimit

protected int m_StatementResetLimit

Access limit at which the saved statements will be closed and re-opened.

(Unpublished)

m_StatementResetRequested

protected boolean m_StatementResetRequested

An indication that a reset of all cached statements has been requested.

(Unpublished)

m_StatementValidityRsn

protected long m_StatementValidityRsn

The resolution sequence number at which the validity of the cached PreparedStatements and LibraryQueryStatements was last confirmed. Initially has the value 0. Used as a timestamp proxy.

(Unpublished)

m_StatementAccessSequence

protected long m_StatementAccessSequence

The sequence number marking the last time a cached statement has been used. Used as a timestamp proxy.

(Unpublished)

m_StatementAccessSequenceAtPreviousPurge

protected long m_StatementAccessSequenceAtPreviousPurge

The sequence number the last time a purge was attempted.

m_StatementCacheTarget

protected int m_StatementCacheTarget

The target maximum number of statements we wish to keep cached.

m_StatementCacheSizeTrigger

protected int m_StatementCacheSizeTrigger

The number of statements that need to be cached before a purge is triggered.

m_TransactionStateManager

protected oracle.ifs.server.LibraryConnection.TransactionStateManager m_TransactionStateManager

The internal TransactionStateManager.

Constructor Detail

LibraryConnection

protected LibraryConnection(long id,
                            S_LibraryService service,
                            String connectionPoolName,
                            DataSource dataSource,
                            PrintStream jdbcLogStream,
                            int defaultRowPrefetch,
                            int statementResetLimit,
                            int stmtCacheTarget,
                            int stmtCacheTrigger)
                     throws IfsException

Constructs a LibraryConnection.

Parameters:

id - an identifier

service - the S_LibraryService creating the LibraryConnection

connectionPoolName - the name of the ConnectionPool to which this LibraryConnection belongs

dataSource - data source for database connections

jdbcLogStream - a PrintStream to which the JDBC log will be sent, or null to disable logging

defaultRowPrefetch - the default number of prefetched rows; ignored if 0 or if driverName does not create an OracleConnection

stmtCacheTarget - the desired number of cached statements

stmtCacheTrigger - the number of caches statements before triggering a purge

Throws:

IfsException - (IFS-10600) if the operation fails

(Unpublished)

Method Detail

getId

protected final long getId()
                    throws IfsException

Gets the identifier of this LibraryConnection.

Returns:

the identifier

Throws:

IfsException - if the operation fails

(Unpublished)

getStatementValidityRsn

protected final long getStatementValidityRsn()

Gets the current StatementValidity resolution sequence number (RSN) of this LibraryConnection.

Returns:

the RSN

addTransactionStateListener

public void addTransactionStateListener(LibraryConnection.TransactionStateListener listener)

Adds a TransactionStateListener.

Parameters:

listener - the TransactionStateListener to add

(Unpublished)

getConnection

public final Connection getConnection()
                               throws IfsException

Gets the database Connection represented by this LibraryConnection.

Returns:

the connection

Throws:

IfsException - (IFS-10602) if the operation fails

(Published)

getService

protected final S_LibraryService getService()
                                     throws IfsException

Gets the S_LibraryService to which this LibraryConnection belongs.

Returns:

the service

Throws:

IfsException - if the operation fails

(Unpublished)

getConnectionPoolName

public final String getConnectionPoolName()
                                   throws IfsException

Gets the name of the ConnectionPool to which this LibraryConnection belongs.

Returns:

the ConnectionPool name

Throws:

IfsException - if the operation fails

(Unpublished)

getSessionLanguage

public final String getSessionLanguage()
                                throws IfsException

get current language of the database session

Returns:

the current language name

Throws:

IfsException - if the operation fails

(Unpublished)

setSessionLanguage

public final String setSessionLanguage(String language)
                                throws IfsException

set current language of the database session if different from the current setting.

Parameters:

language - the desired language name

Returns:

the previous language name

Throws:

IfsException - if the operation fails

(Unpublished)

addPreparedStatement

public final void addPreparedStatement(String key,
                                       PreparedStatement stmt)

Caches the specified PreparedStatement.

Parameters:

key - the key by which the PreparedStatement is to be identified

stmt - the PreparedStatement

(Unpublished)

findPreparedStatement

public final PreparedStatement findPreparedStatement(String key)

Finds the specified PreparedStatement in the PreparedStatement cache.

Parameters:

key - the PreparedStatement key

Returns:

the statement, or null if there is no cached PreparedStatement with the specified key

(Unpublished)

acquireLibraryQueryStatement

public final LibraryQueryStatement acquireLibraryQueryStatement(String key)

Acquires an instance of the specified LibraryQueryStatement from the LibraryQueryStatement cache.

Unlike the PreparedStatement cache, whose statements can only be used transiently by a session, statements in the LibraryQueryStatement cache can be acquired by a session and used for as long as necessary, even after the session releases this LibraryConnection. This can be used, for example, to provide cursor support. For a given statement key, this cache may contain multiple (identical) LibraryQueryStatements, allowing several sessions to concurrently acquire identical statements.

This method acquires a LibraryQueryStatement. To release it for use by other sessions, invoke releaseLibraryQueryStatement.

Parameters:

key - the LibraryQueryStatement key

Returns:

the statement, or null if there is no cached LibraryQueryStatement with the specified key

(Unpublished)

releaseLibraryQueryStatement

public final void releaseLibraryQueryStatement(LibraryQueryStatement lstmt)

Places the specified LibraryQueryStatement in the LibraryQueryStatement cache.

This method is used both to release a previously acquired statement for use by other sessions, and to add new statement to the cache. For each statement key, the cache may contain more than one LibraryQueryStatement instance (all identical). The maximum number of copies is set by the LibraryQueryStatement constructor.

Parameters:

lstmt - the LibraryQueryStatement

(Unpublished)

fetchSessionLanguage

protected final String fetchSessionLanguage()
                                     throws IfsException

fetchSessionLanguage

Returns:

the database session's language setting.

Throws:

IfsException

alterSessionLanguage

protected final void alterSessionLanguage(String language)
                                   throws IfsException

alterSessionLanguage

Parameters:

language - the new language setting for the database session.

Throws:

IfsException - (IFS-10609) if the operation fails

(Unpublished)

alterSessionSqlTrace

protected final void alterSessionSqlTrace(boolean enabled)
                                   throws IfsException

alter the SQL_TRACE parameter for the database session

Parameters:

enabled - true if SQL tracing is to be enabled; false if it is to be disabled

Throws:

IfsException - (IFS-10612) if the operation fails

(Unpublished)

setSavepoint

protected final void setSavepoint(String savepoint)
                           throws IfsException

Sets a savepoint in the database Connection represented by this LibraryConnection.

Parameters:

savepoint - the savepoint name

Throws:

IfsException - (IFS-10603) if the operation fails

(Unpublished)

commit

protected final void commit()
                     throws IfsException

Commits the database Connection represented by this LibraryConnection.

Throws:

IfsException - (IFS-10604) if the operation fails

(Unpublished)

rollback

protected final void rollback()
                       throws IfsException

Rolls-back the database Connection represented by this LibraryConnection.

Throws:

IfsException - (IFS-10605) if the operation fails

(Unpublished)

rollback

protected final void rollback(String savepoint)
                       throws IfsException

Rolls-back the database Connection represented by this LibraryConnection to the specified savepoint.

Throws:

IfsException - (IFS-10606) if the operation fails

(Unpublished)

rollbackOrDispose

protected final void rollbackOrDispose()
                                throws IfsException

Rolls-back the database Connection represented by this LibraryConnection. If unable to do so, and if the database connection is determined to be invalid, then this LibraryConnection instance is disposed.

Throws:

IfsException - (IFS-10605) if the operation fails

(Unpublished)

rollbackOrDispose

protected final void rollbackOrDispose(String savepoint)
                                throws IfsException

Rolls-back the database Connection represented by this LibraryConnection to the specified savepoint. If unable to do so, and if the database connection is determined to be invalid, then this LibraryConnection instance is disposed.

Throws:

IfsException - (IFS-10606) if the operation fails

(Unpublished)

isValid

protected final boolean isValid()
                         throws IfsException

Detects whether the connection is still valid, by checking the encapsulated database connection.

Returns:

false if connection is no longer valid; true otherwise

Throws:

IfsException - (IFS-10601) if the operation fails

(Unpublished)

verifyConnectionValidity

protected void verifyConnectionValidity()
                                 throws SQLException,
                                        IfsException

Verify validity of database connection by trying simple query. If a SQLException is thrown, the caller knows that the connection is not valid.

Throws:

SQLException - if the operation fails

IfsException - if the operation fails

(Unpublished)

isDisposed

protected final boolean isDisposed()

Return true if this LibraryConnection has been disposed.

Returns:

true if this LibraryConnection has been disposed.

(Unpublished)

verifyNotDisposed

protected void verifyNotDisposed()
                          throws IfsException

Verify that this LibraryConnection is still valid (i.e. is not disposed).

Throws:

IfsException - if the operation fails

(Unpublished)

dispose

protected final void dispose()
                      throws IfsException

Shuts down this LibraryConnection.

Throws:

IfsException - (IFS-10601) if the operation fails

(Unpublished)

resetCachedStatements

protected void resetCachedStatements()

Prevent any statements currently cached from being re-used. This is called in response to any event that could render prepared statements invalid, such as adding or removing attributes from existing ClassObjects. The actual task of removing the cached statements is deferred to two separate operations:

• When the LibraryConnection is allocated, all cached statements are closed. This catches all cached statements for connections that were unallocated at the time resetCachedStatements() is called.
• When a cached statement is obtained, and the statement's RSN is older than the current RSN value of the connection. This handles all statements that are cached for a connection that was already allocated at the time resetCachedStatements() is called.

(Unpublished)

handleResetOfCachedStatements

protected int handleResetOfCachedStatements()

Dispose of any cached statements if a reset has been indicated. This is called whenever a LibraryConnection is allocated from the pool.

Returns:

the number of statements purged

purge

protected int purge()

Purges statement caches if needed.

This will attempt to close enough of the least recently used statements such that the number of cached statements does not exceed that maximum set when the connection was established.

Returns:

the number of statements closed

closePreparedStatements

protected int closePreparedStatements(int closeCount,
                                      int sizeest,
                                      long seqTarget)

Close least recently used PreparedStatements.

Parameters:

closeCount - the number of statements closed so far

sizeest - the number of statements that we want to close

seqTarget - the sequence that represents LRU

Returns:

the updated number of statements closed so far

closeLibraryQueryStatements

protected int closeLibraryQueryStatements(int closeCount,
                                          int sizeest,
                                          long seqTarget)

Close least recently used LibraryQueryStatements.

Parameters:

closeCount - the number of statements closed so far

sizeest - the number of statements that we want to close

seqTarget - the sequence that represents LRU

Returns:

the updated number of statements closed so far

disposeCachedStatements

protected void disposeCachedStatements()

Close all cached statements, and clear the caches.

(Unpublished)

finalize

protected void finalize()
                 throws Throwable

Finalizes this LibraryConnection.

Overrides:

finalize in class Object

Throws:

Throwable - if the operation fails

(Unpublished)