net.sourceforge.orbroker
Class Transaction

java.lang.Object
  net.sourceforge.orbroker.BrokerConnection
      net.sourceforge.orbroker.QueryableConnection
          net.sourceforge.orbroker.ExecutableConnection
              net.sourceforge.orbroker.Transaction

public final class Transaction

extends net.sourceforge.orbroker.ExecutableConnection

Any database modifications (INSERT, UPDATE, DELETE) must be done through the Transaction object. It wraps a Connection object, and like a Query instance, close() must be called after use (in a finally block), to avoid connection pool leaks. A transaction using an isolation level of Connection.TRANSACTION_NONE is considered non-transactional and will have auto-commit enabled. This makes it illegal to call either commit() or rollback(). All other isolation levels require a call to commit() method for the transaction to commit.

Author:

Nils Kilden-Pedersen

See Also:

Broker.startTransaction(), Broker.startTransaction(int)

Method Summary

void	addStatement(String id, String sql) Add temporary statement.
void	addStatement(String id, String sql, String resultObjectId) Add temporary statement.
void	close() Close transaction.
void	closeIterator(Iterator iterator) Close iterator.
void	commit() Commit the transaction.
int	execute(String statementID) Execute statement.
int	executeBatch(String statementID, String batchParameterName, Collection batchParameters) Execute a collection of parameters as a batch.
int[]	executeBatch(String statementID, String batchParameterName, Object[] batchParameters) Execute an array of parameters as a batch.
Object	getParameter(String name) Get parameter.
Iterator	iterate(String statementID, int fetchSize) Return a live iterator.
Executable	obtainExecutable() Obtain an Executable that uses this Transaction's connection.
void	releaseSavepoint(Savepoint savepoint) Release savepoint.
void	rollback() Roll back the transaction.
void	rollback(Savepoint savepoint) Roll back to savepoint.
List	selectMany(String statementID) Return a list of 0..n objects.
int	selectMany(String statementID, Collection resultCollection) Fill Collection with 0..n objects.
int	selectMany(String statementID, Collection resultCollection, int startRow, int rowCount) Fill Collection with 0..n objects.
List	selectMany(String statementID, int startRow, int rowCount) Return a list of 0..n objects.
Object	selectOne(String statementID) Return a single result object.
boolean	selectOne(String statementID, Object resultObject) Use supplied result object to apply values to.
Object	selectOneFromMany(String statementID, int fromRow) Return one result object from a query containing many.
void	setParameter(String name, Object value) Set named parameter.
Savepoint	setSavepoint() Set savepoint.
Savepoint	setSavepoint(String name) Set named savepoint.
void	setTextReplacement(String key, String value) Set a text replacement value.
void	setTextReplacements(Properties textReplacements) Set text replacement values.

Methods inherited from class java.lang.Object

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

Method Detail

close

public void close()

Close transaction. If Transaction has not been explicity committed or rolled back, it will automatically be rolled back on close. This can simplify code by automatically rolling back on close:

Transaction txn = broker.startTransaction();
 try {
    txn.setParameter("account", account);
    txn.execute("updateAccount");
    txn.commit();
 ] finally {
    txn.close();
 }

There is no need to issue a rollback. If commit() is not called due to an exception, rollback is done automatically. This is assuming that the transaction is in isolation level other than Connection.TRANSACTION_NONE.

commit

public void commit()
            throws BrokerException,
                   ConstraintException,
                   DeadlockException

Commit the transaction.

This method cannot be called if isolation level is Connection.TRANSACTION_NONE.

Throws:

BrokerException

ConstraintException

DeadlockException

See Also:

rollback()

obtainExecutable

public Executable obtainExecutable()

Obtain an Executable that uses this Transaction's connection. This class provides safe semantics for other methods that need to take part in the transaction, without exposing commit or rollback capabilities. The Executable will be automatically released and invalidated when Transaction is closed.

Returns:

Executable

See Also:

close(), Broker.obtainExecutable(Connection)

rollback

public void rollback()
              throws BrokerException

Roll back the transaction. If rollback() is not called on an exception, it will be done automatically on close() (provided that close() method is called in a finally block as it always should).

This method cannot be called if isolation level is Connection.TRANSACTION_NONE.

Throws:

BrokerException

See Also:

commit()

execute

public int execute(String statementID)
            throws BrokerException,
                   ConstraintException,
                   DeadlockException

Execute statement. This is used for statements such as

• UPDATE
• DELETE
• INSERT
• CALL

Parameters:

statementID - Statement id

Returns:

number of records affected.

Throws:

BrokerException

ConstraintException

DeadlockException

executeBatch

public int executeBatch(String statementID,
                        String batchParameterName,
                        Collection batchParameters)
                 throws BrokerException,
                        ConstraintException,
                        DeadlockException

Execute a collection of parameters as a batch.

Parameters:

statementID - Statement id

batchParameterName - The parameter name that will be repeated

batchParameters - The collection of batch parameter objects

Returns:

Total records affected, or a negative number if unknown

Throws:

BrokerException

ConstraintException

DeadlockException

executeBatch

public int[] executeBatch(String statementID,
                          String batchParameterName,
                          Object[] batchParameters)
                   throws BrokerException,
                          ConstraintException,
                          DeadlockException

Execute an array of parameters as a batch.

Parameters:

statementID - Statement id

batchParameterName - The parameter name that will be repeated

batchParameters - The array of batch objects

Returns:

Total records affected per parameter, or a negative number if unknown

Throws:

BrokerException

ConstraintException

DeadlockException

releaseSavepoint

public void releaseSavepoint(Savepoint savepoint)

Release savepoint.

Parameters:

savepoint - Savepoint

See Also:

Connection.releaseSavepoint(java.sql.Savepoint)

rollback

public void rollback(Savepoint savepoint)

Roll back to savepoint.

Parameters:

savepoint - Savepoint

See Also:

Connection.rollback(java.sql.Savepoint)

setSavepoint

public Savepoint setSavepoint()

Set savepoint.

Returns:

savepoint

See Also:

Connection.setSavepoint()

setSavepoint

public Savepoint setSavepoint(String name)

Set named savepoint.

Parameters:

name - Savepoint name

Returns:

savepoint

See Also:

Connection.setSavepoint(String)

selectMany

public final List selectMany(String statementID)
                      throws BrokerException

Return a list of 0..n objects. An empty List will be returned if result set is empty.

Parameters:

statementID - Statement id

Returns:

List of result objects

Throws:

BrokerException

selectMany

public final int selectMany(String statementID,
                            Collection resultCollection)
                     throws BrokerException

Fill Collection with 0..n objects. The supplied Collection does not have to be empty. Objects are added to Collection.

Parameters:

statementID - Statement id

resultCollection - The collection where the result will be added.

Returns:

Number of objects added to collection.

Throws:

BrokerException

iterate

public Iterator iterate(String statementID,
                        int fetchSize)

Return a live iterator. Very useful for large rows that, for memory concerns, need to be built a few at a time, controlled by the fetch size. The Iterator must be iterated with the source object active, i.e. a Query or Transaction must be open.

Parameters:

statementID - Statement id

fetchSize - Row buffer size

Returns:

Streamed Iterator of result objects.

closeIterator

public final void closeIterator(Iterator iterator)

Close iterator. Use this to close a live iterator returned by QueryableConnection.iterate(String, int). Only necessary if iterator has not been exhausted by hasNext() returning false

Parameters:

iterator - The not fully iterated iterator.

See Also:

QueryableConnection.iterate(String, int)

selectMany

public final int selectMany(String statementID,
                            Collection resultCollection,
                            int startRow,
                            int rowCount)
                     throws BrokerException

Fill Collection with 0..n objects. The supplied Collection does not have to be empty. Objects are added to Collection.

Parameters:

statementID - Statement id

resultCollection - The collection where the result will be added.

startRow - The start row to return. First row is 1.

rowCount - The number of rows to return

Returns:

Number of objects added to collection.

Throws:

BrokerException

selectMany

public final List selectMany(String statementID,
                             int startRow,
                             int rowCount)
                      throws BrokerException

Return a list of 0..n objects. An empty List will be returned if result set is empty or if startRow is greater than the result set size.

Parameters:

statementID - Statement id

startRow - The start row to return. First row is 1.

rowCount - The number of rows to return

Returns:

List of result objects

Throws:

BrokerException

selectOne

public final Object selectOne(String statementID)
                       throws BrokerException,
                              MoreThanOneRowException

Return a single result object.

Parameters:

statementID - Statement id

Returns:

the result object, or null if query returned 0 records.

Throws:

BrokerException

MoreThanOneRowException

selectOne

public final boolean selectOne(String statementID,
                               Object resultObject)
                        throws BrokerException,
                               MoreThanOneRowException

Use supplied result object to apply values to. Any constructor or factory method defined for mapping will be ignored.

Parameters:

statementID - Statement id

resultObject - result object to map to

Returns:

false if query didn't return a record.

Throws:

BrokerException

MoreThanOneRowException

selectOneFromMany

public Object selectOneFromMany(String statementID,
                                int fromRow)
                         throws BrokerException

Return one result object from a query containing many. Returns null if query is empty or returnRow is out of range.

Parameters:

statementID - Statement id

fromRow - Row to return. First row is 1.

Returns:

result object from row

Throws:

BrokerException

addStatement

public final void addStatement(String id,
                               String sql)
                        throws BrokerException,
                               ConfigurationException

Add temporary statement.

Parameters:

id - The statement id.

sql - The SQL statement

Throws:

BrokerException

ConfigurationException

addStatement

public final void addStatement(String id,
                               String sql,
                               String resultObjectId)
                        throws BrokerException,
                               ConfigurationException

Add temporary statement.

Parameters:

id - The statement id.

sql - The SQL statement

resultObjectId - The result-object id as defined in the XML configuration file.

Throws:

BrokerException

ConfigurationException

getParameter

public final Object getParameter(String name)

Get parameter. Used to retrieve OUT/INOUT parameters from stored procedures. Both input and output parameters are stored in the same context, so any parameter set using BrokerConnection.setParameter(String, Object) will be available with this method. Also if a stored procedure has an output parameter that needs to be used as input in another SQL statements, it's immediately available, i.e. there's no need to code like this: txn.setParameter("parm", txn.getParameter("parm"));

Parameters:

name - parameter name

Returns:

parameter value

setParameter

public final void setParameter(String name,
                               Object value)

Set named parameter.

Parameters:

name - parameter name

value - parameter value

setTextReplacement

public final void setTextReplacement(String key,
                                     String value)

Set a text replacement value. This will replace a {{key}} string with the value. This will override any value set on Broker.

Parameters:

key - Text replacement key

value - Text replacement value

See Also:

BrokerConnection.setTextReplacements(Properties)

setTextReplacements

public final void setTextReplacements(Properties textReplacements)

Set text replacement values. This will replace all {{key}} type properties in an sql-statement with the values. This will override any value set on Broker.

Parameters:

textReplacements - The replacement values to set.

See Also:

BrokerConnection.setTextReplacement(String, String)