com.triactive.jdo.jdbc
Class InitializedConnectionFactory

java.lang.Object
  extended bycom.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.


Copyright 2001-2007 The TJDO Project All Rights Reserved.