com.triactive.jdo.jdbc
Class InitializedConnectionFactory

java.lang.Object
  com.triactive.jdo.jdbc.InitializedConnectionFactory

public class InitializedConnectionFactory

extends java.lang.Object

A factory for JDBC connections that performs some initialization on each returned connection.

Initialization consists of setting the auto-commit and transaction isolation level according to the requested isolationLevel on each call to getConnection(int). If forced initialization is enabled, setAutoCommit() and setTransactionIsolationLevel() are called every time. Otherwise, they're called only if the requested setting differs from the connection's default setting. This minimizes the number of Connection.set...() calls by eliminating those believed to be redundant. (Oftentimes setTransactionIsolationLevel() involves the execution of a SQL statement so the savings are non-trivial.)

The default settings are determined from an initial connection sampled from the underlying data source when the factory is created. The factory thus assumes that every connection obtained from the data source will be in the same state. It also assumes that, if connections are being pooled, the underlying pooler is responsible for restoring the default state. If forced initialization is disabled a mild test is performed to assert these assumptions.

Author:

Mike Martin

Nested Class Summary

static class

InitializedConnectionFactory.InconsistentConnectionStateException

Constructor Summary

InitializedConnectionFactory(javax.sql.DataSource ds, java.lang.String userName, java.lang.String password, boolean forceInitialization, java.lang.String traceOptions)
Constructs a new initialized connection factory.

Method Summary

boolean	equals(java.lang.Object obj) Indicates whether some object is "equal to" this one.
java.sql.Connection	getConnection(int isolationLevel) Acquires a connection from the underlying data source and initializes it, if necessary.
boolean	getForcedInitialization() When true, every returned connection is forcibly initialized with setAutoCommit() and setTransactionIsolation().
java.lang.String	getTraceOptions() Returns the JDBC trace options.
int	hashCode() Returns a hash code value for this object.
void	setForcedInitialization(boolean forceInitialization) When true, every returned connection is forcibly initialized with setAutoCommit() and setTransactionIsolation().
void	setTraceOptions(java.lang.String traceOptions) Sets the JDBC trace options.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InitializedConnectionFactory

public InitializedConnectionFactory(javax.sql.DataSource ds,
                                    java.lang.String userName,
                                    java.lang.String password,
                                    boolean forceInitialization,
                                    java.lang.String traceOptions)
                             throws java.sql.SQLException

Constructs a new initialized connection factory.

Parameters:

ds - the underlying data source from which to obtain connections

userName - the database user name to use

password - the database password to use

forceInitialization - true to forcibly call setAutoCommit() and setTransactionIsolation() for every returned connection, false to call them only if needed.

traceOptions - comma-separated list of JDBC tracing options, or null to specify no tracing. See Trace.

Method Detail

getForcedInitialization

public boolean getForcedInitialization()

When true, every returned connection is forcibly initialized with setAutoCommit() and setTransactionIsolation(). false causes initialization only if the requested settings differ from the connection's expected default state.

setForcedInitialization

public void setForcedInitialization(boolean forceInitialization)
                             throws java.sql.SQLException

When true, every returned connection is forcibly initialized with setAutoCommit() and setTransactionIsolation(). false causes initialization only if the requested settings differ from the connection's expected default state.

Throws:

java.sql.SQLException

getTraceOptions

public java.lang.String getTraceOptions()

Returns the JDBC trace options.

Returns:

a comma-separated string indicating which tracing options are enabled, or null if tracing is disabled.

See Also:

Trace

setTraceOptions

public void setTraceOptions(java.lang.String traceOptions)

Sets the JDBC trace options.

Parameters:

traceOptions - a comma-separated string indicating which tracing options are to be enabled, or null (or the empty string) to disable tracing.

See Also:

Trace

getConnection

public java.sql.Connection getConnection(int isolationLevel)
                                  throws java.sql.SQLException

Acquires a connection from the underlying data source and initializes it, if necessary.

The isolationLevel argument specifies both auto-commit and isolation level status. Connection.TRANSACTION_NONE is used as a special indicator requesting auto-commit = true at an unspecified isolation level (in effect, the default level of the underlying data source). Otherwise it requests auto-commit = false and isolationLevel must be one of the other JDBC isolation level constants.

Parameters:

isolationLevel - the desired transaction isolation level.

Returns:

an initialized connection to the data source

Throws:

java.sql.SQLException - if a database access error occurs

hashCode

public int hashCode()

Returns a hash code value for this object.

equals

public boolean equals(java.lang.Object obj)

Indicates whether some object is "equal to" this one. Two InitializedConnectionFactory objects are considered equal if their DataSources, user credentials, and options are all equal.

Parameters:

obj - the reference object with which to compare

Returns:

true if this object is equal to the obj argument; false otherwise.