net.sourceforge.orbroker
Class Transaction

java.lang.Object
  extended bynet.sourceforge.orbroker.BrokerConnection
      extended bynet.sourceforge.orbroker.QueryableConnection
          extended bynet.sourceforge.orbroker.ExecutableConnection
              extended bynet.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

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)