com.unboundid.directory.sdk.sync.types

Class TransactionContext

java.lang.Object

com.unboundid.directory.sdk.sync.types.TransactionContext

public final class TransactionContext
extends java.lang.Object

This class wraps an open JDBC Connection and provides controlled access to it via a handful of delegating methods. The underlying connection is always part of a new transaction. The Data Sync Server will always automatically commit or rollback the transaction after a method is finished with it, depending on if the method returned successfully or threw an exception.

There are also facilities for setting a timeout, after which the TransactionContext will automatically become invalidated, and subsequent operations on it will throw a RuntimeException.

Constructor Summary

Constructors

Constructor and Description
TransactionContext(java.sql.Connection connection) Constructor.

Method Summary

Modifier and Type	Method and Description
void	close() Releases the internal connection back the pool and invalidates this context object.
void	commit() Commits the internal Connection if the transaction has not timed out and is still valid.
java.sql.Statement	createStatement() Creates a Statement object for sending SQL statements to the database.
int	getTransactionIsolation() Retrieves the current transaction isolation level for the underlying Connection.
boolean	isClosed() Checks whether this TransactionContext is closed.
boolean	isTimedOut() Checks whether this TransactionContext has timed out.
java.sql.CallableStatement	prepareCall(java.lang.String sql) Creates a CallableStatement object for calling database stored procedures.
java.sql.PreparedStatement	prepareStatement(java.lang.String sql) Creates a PreparedStatement object for sending parameterized SQL statements to the database.
void	rollBack() Rolls back the internal Connection if the transaction has not timed out and is still valid.
Entry	searchToRawEntry(java.sql.PreparedStatement statement, java.lang.String rdnColumn) Executes the given PreparedStatement and converts the results into a raw LDAP Entry, where the attribute names are the raw column names from the result of the query.
Entry	searchToRawEntry(java.lang.String sql, java.lang.String rdnColumn) Executes the given SQL query and converts the results into a raw LDAP Entry, where the attribute names are the raw column names from the result of the query.
void	setTimeout(long timeOutMillis) Sets a timeout for this TransactionContext.
void	setTransactionIsolation(int level) Attempts to change the transaction isolation level for the underlying Connection object to the one given.

Methods inherited from class java.lang.Object

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

Constructor Detail

TransactionContext

public TransactionContext(java.sql.Connection connection)

Constructor. The connection instance may not be null.

Parameters:

connection - a fresh JDBC Connection from the pool

Method Detail

searchToRawEntry

public Entry searchToRawEntry(java.lang.String sql,
                              java.lang.String rdnColumn)
                       throws java.sql.SQLException

Executes the given SQL query and converts the results into a raw LDAP Entry, where the attribute names are the raw column names from the result of the query. The rdnColumn parameter is the column name to use as the RDN attribute for the entry. For example if the rdnColumn is "accountID", then the DN of the returned Entry will be "accountID={accountID}".

Parameters:

sql - the SQL query to execute

rdnColumn - the column name in the result set which is to be used for the DN of the returned Entry

Returns:

the resulting LDAP Entry

Throws:

java.sql.SQLException - if a database access error occurs or the query matches more than one row

searchToRawEntry

public Entry searchToRawEntry(java.sql.PreparedStatement statement,
                              java.lang.String rdnColumn)
                       throws java.sql.SQLException

Executes the given PreparedStatement and converts the results into a raw LDAP Entry, where the attribute names are the raw column names from the result of the query. The rdnColumn parameter is the column name to use as the RDN attribute for the entry. For example if the rdnColumn is "accountID", then the DN of the returned Entry will be "accountID={accountID}".

Parameters:

statement - the PreparedStatement to execute

rdnColumn - the column name in the result set which is to be used for the DN of the returned Entry

Returns:

the resulting LDAP Entry

Throws:

java.sql.SQLException - if a database access error occurs or the query matches more than one row

createStatement

public java.sql.Statement createStatement()
                                   throws java.sql.SQLException

Creates a Statement object for sending SQL statements to the database. SQL statements without parameters are normally executed using Statement objects. If the same SQL statement is executed many times, it may be more efficient to use a PreparedStatement object.

Result sets created using the returned Statement object will by default be type TYPE_FORWARD_ONLY and have a concurrency level of CONCUR_READ_ONLY. The holdability of the created result sets can be determined by calling Connection.getHoldability().

Returns:

a new default Statement object

Throws:

java.sql.SQLException - if a database access error occurs or this method is called on a closed connection

prepareStatement

public java.sql.PreparedStatement prepareStatement(java.lang.String sql)
                                            throws java.sql.SQLException

Creates a PreparedStatement object for sending parameterized SQL statements to the database.

A SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times.

Note: This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation, the method prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement object is executed. This has no direct effect on users; however, it does affect which methods throw certain SQLException objects.

Result sets created using the returned PreparedStatement object will by default be type TYPE_FORWARD_ONLY and have a concurrency level of CONCUR_READ_ONLY. The holdability of the created result sets can be determined by calling Connection.getHoldability().

Parameters:

sql - an SQL statement that may contain one or more '?' IN parameter placeholders

Returns:

a new default PreparedStatement object containing the pre-compiled SQL statement

Throws:

java.sql.SQLException - if a database access error occurs or this method is called on a closed connection

prepareCall

public java.sql.CallableStatement prepareCall(java.lang.String sql)
                                       throws java.sql.SQLException

Creates a CallableStatement object for calling database stored procedures. The CallableStatement object provides methods for setting up its IN and OUT parameters, and methods for executing the call to a stored procedure.

Note: This method is optimized for handling stored procedure call statements. Some drivers may send the call statement to the database when the method prepareCall is done; others may wait until the CallableStatement object is executed. This has no direct effect on users; however, it does affect which method throws certain SQLExceptions.

Result sets created using the returned CallableStatement object will by default be type TYPE_FORWARD_ONLY and have a concurrency level of CONCUR_READ_ONLY. The holdability of the created result sets can be determined by calling Connection.getHoldability().

Parameters:

sql - an SQL statement that may contain one or more '?' parameter placeholders. Typically this statement is specified using JDBC call escape syntax.

Returns:

a new default CallableStatement object containing the pre-compiled SQL statement

Throws:

java.sql.SQLException - if a database access error occurs or this method is called on a closed connection

getTransactionIsolation

public int getTransactionIsolation()
                            throws java.sql.SQLException

Retrieves the current transaction isolation level for the underlying Connection.

Returns:

the current transaction isolation level, which will be one of the following constants: Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ, Connection.TRANSACTION_SERIALIZABLE, or Connection.TRANSACTION_NONE.

Throws:

java.sql.SQLException - if a database access error occurs or this method is called on a closed connection

setTransactionIsolation

public void setTransactionIsolation(int level)
                             throws java.sql.SQLException

Attempts to change the transaction isolation level for the underlying Connection object to the one given. The constants defined in the interface Connection are the possible transaction isolation levels.

Note: If this method is called during a transaction, the result is implementation-defined.

Parameters:

level - one of the following Connection constants: Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ, or Connection.TRANSACTION_SERIALIZABLE. (Note that Connection.TRANSACTION_NONE cannot be used because it specifies that transactions are not supported.)

Throws:

java.sql.SQLException - if a database access error occurs, this method is called on a closed connection or the given parameter is not one of the Connection constants

commit

public void commit()
            throws java.sql.SQLException

Commits the internal Connection if the transaction has not timed out and is still valid.

Throws:

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

rollBack

public void rollBack()
              throws java.sql.SQLException

Rolls back the internal Connection if the transaction has not timed out and is still valid.

Throws:

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

close

public void close()

Releases the internal connection back the pool and invalidates this context object.

setTimeout

public void setTimeout(long timeOutMillis)

Sets a timeout for this TransactionContext. The count begins immediately when this method is called. This method may be called multiple times if the timeout needs to be reset, provided that a previous timeout hasn't already expired. A value of zero indicates that there should be no timeout. Negative values are not allowed.

After the timeout has expired, all methods except isTimedOut and isClosed will throw a IllegalStateException.

Parameters:

timeOutMillis - the delay in milliseconds after which this TransactionContext will time out

isTimedOut

public boolean isTimedOut()

Checks whether this TransactionContext has timed out.

After the timeout has expired, all methods except isTimedOut, isClosed, and log[Error|Info|Debug|Exception] will throw an IllegalStateException.

Returns:

true if the timeout has expired, false if not.

isClosed

public boolean isClosed()

Checks whether this TransactionContext is closed.

Returns:

true if the context is closed and no longer usable, false if not.