com.atlassian.sal.api.rdbms

Interface TransactionalExecutor

@PublicApi
public interface TransactionalExecutor

Interface allowing the user to execute a callback with a Connection, in the context of a transaction.

Note that participation in an existing transaction i.e. requiresNew is merely a hint to the host application and not binding. Best effort will be attempted.

The following example will query an application's table using JDBC:

 final TransactionalExecutor transactionalExecutor = transactionalExecutorFactory
         .createExecutor()
         .readOnly()
         .newTransaction();

 final String summary = transactionalExecutor.execute(new ConnectionCallback<String>()
 {
     public String execute(final Connection connection)
     {
         try
         {
             final String schemaPrefix = transactionalExecutor.getSchemaName().map(s -> s + '.').getOrElse("");

             final PreparedStatement preparedStatement = connection.prepareStatement(""
                     + "select summary\n"
                     + "from " + schemaPrefix + "jiraissue\n"
                     + "order by id desc");

             final ResultSet resultSet = preparedStatement.executeQuery();

             return resultSet.next() ? resultSet.getString("summary") : "no issues";
         }
         catch (SQLException e)
         {
             throw new RuntimeException("oh noes!", e);
         }
     }
 });
 
 

Since:

3.0

See Also:

TransactionalExecutorFactory

Method Summary

Methods

Modifier and Type	Method and Description
<A> A	execute(ConnectionCallback<A> callback) Execute a callback which is supplied a Connection, within a transaction.
TransactionalExecutor	existingTransaction() Alter this executor so that the connection executes within an existing transaction or creates a new one if one is not present
com.atlassian.fugue.Option<String>	getSchemaName() Returns the configured schema name (if any), for connections provided during execute(ConnectionCallback).
TransactionalExecutor	newTransaction() Alter this executor so that it executes in a new transaction, regardless of any existing
TransactionalExecutor	readOnly() Alter this executor so that the connection is read-only
TransactionalExecutor	readWrite() Alter this executor so that the connection is read-write

Method Detail

execute

<A> A execute(@Nonnull
            ConnectionCallback<A> callback)

Execute a callback which is supplied a Connection, within a transaction.

After successful execution, the transaction will be committed. If the transaction is within the scope of a larger transaction i.e. requiresNew has been set, it will be scheduled for commit, pending successful completion of the target transaction.

If any exception is thrown by callback, the transaction will be immediately rolled back.

Do not attempt to retain or reuse the Connection outside of the scope of callback or within a different thread. Connection is usually not considered thread safe.

Exceptions thrown from the callback are passed through without wrapping. SQLException occuring in the Executor will be wrapped in RdbmsException.

A UnsupportedOperationException will be thrown on invoking any of the following:

• Connection.setAutoCommit(boolean)
• Connection.commit()
• Connection.close()
• Connection.rollback()
• Connection.setReadOnly(boolean)
• Connection.setReadOnly(boolean)
• Connection.abort(java.util.concurrent.Executor)
• Connection.setCatalog(String)
• Connection.setSchema(String)
• Connection.setTransactionIsolation(int)
• Connection.setNetworkTimeout(java.util.concurrent.Executor, int)

Parameters:

callback - mandatory, may return Void

Returns:

return value of callback

getSchemaName

@Nonnull
com.atlassian.fugue.Option<String> getSchemaName()

Returns the configured schema name (if any), for connections provided during execute(ConnectionCallback).

Returns:

schema name, if there is one

readOnly

@Nonnull
TransactionalExecutor readOnly()

Alter this executor so that the connection is read-only

Returns:

this executor

readWrite

@Nonnull
TransactionalExecutor readWrite()

Alter this executor so that the connection is read-write

Returns:

this executor

newTransaction

@Nonnull
TransactionalExecutor newTransaction()

Alter this executor so that it executes in a new transaction, regardless of any existing

Returns:

this executor

existingTransaction

@Nonnull
TransactionalExecutor existingTransaction()

Alter this executor so that the connection executes within an existing transaction or creates a new one if one is not present

Returns:

this executor