Package com.unboundid.directory.sdk.sync.types

Class 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 Description
      TransactionContext​(java.sql.Connection connection)
      Constructor.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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.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.
      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.
      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.