Version 4.10.0

hirondelle.web4j.database
Class TxTemplate

Object
  extended by hirondelle.web4j.database.TxTemplate
All Implemented Interfaces:
Tx

public abstract class TxTemplate
extends Object
implements Tx

Template for executing a local, non-distributed transaction versus a single database, using a single connection.

This abstract base class implements the template method design pattern.

The TxSimple class should be the first choice for implementing a transaction. If it is not suitable (for example, if iteration is involved), then this class can always be used. The benefits of using this class to implement transactions is that the caller avoids repeated code involving connections, commit/rollback, handling exceptions and errors, and so on.

See TxIsolationLevel for remarks on selection of correct isolation level. The DbTx class is often useful for implementors.

Do not use this class in the context of a UserTransaction.

Example Use Case

A DAO method which uses a TxTemplate called AddAllUnknowns to perform multiple INSERT operations :
public int addAll(Set<String> aUnknowns) throws DAOException {
   Tx addTx = new AddAllUnknowns(aUnknowns);
   return addTx.executeTx();
}
  
The TxTemplate class itself, defined inside the same DAO, as an inner class :
private static final class AddAllUnknowns extends TxTemplate {
    AddAllUnknowns(Set<String> aUnknowns){
      super(ConnectionSrc.TRANSLATION);
      fUnknowns = aUnknowns; 
    }
    &amp;Override public int executeMultipleSqls(Connection aConnection) throws SQLException, DAOException {
      int result = 0;
      for(String unknown: fUnknowns){
        addUnknown(unknown, aConnection);
        result = result + 1;
      }
      return result;
    }
    private Set<String> fUnknowns;
    private void addUnknown(String aUnknown, Connection aConnection) throws DAOException {
      DbTx.edit(aConnection, UnknownBaseTextEdit.ADD, aUnknown);
    }
  }
 


Field Summary
static int BUSINESS_RULE_FAILURE
          Value -1.
 
Constructor Summary
TxTemplate()
          Constructor for a transaction versus the default database, at the default isolation level.
TxTemplate(String aDatabaseName)
          Constructor for a transaction versus a non-default database, at its isolation level, as configured in web.xml.
TxTemplate(String aDatabaseName, TxIsolationLevel aTxIsolationLevel)
          Constructor for a transaction versus a non-default database, at a custom isolation level.
TxTemplate(TxIsolationLevel aTxIsolationLevel)
          Constructor for transaction versus the default database, at a custom isolation level.
 
Method Summary
abstract  int executeMultipleSqls(Connection aConnection)
          Execute multiple SQL operations in a single local transaction.
 int executeTx()
          Template method calls the abstract method executeMultipleSqls(java.sql.Connection).
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BUSINESS_RULE_FAILURE

public static final int BUSINESS_RULE_FAILURE
Value -1. Special value returned by executeMultipleSqls(Connection) to indicate that a business rule has been violated. Such a return value indicates to this class that a rollback must be performed.

See Also:
Constant Field Values
Constructor Detail

TxTemplate

public TxTemplate()
Constructor for a transaction versus the default database, at the default isolation level.

The default transaction isolation level is configured in web.xml.


TxTemplate

public TxTemplate(TxIsolationLevel aTxIsolationLevel)
Constructor for transaction versus the default database, at a custom isolation level.

The default transaction isolation level is configured in web.xml.


TxTemplate

public TxTemplate(String aDatabaseName)
Constructor for a transaction versus a non-default database, at its isolation level, as configured in web.xml.

Parameters:
aDatabaseName - one of the return values of ConnectionSource.getDatabaseNames()

TxTemplate

public TxTemplate(String aDatabaseName,
                  TxIsolationLevel aTxIsolationLevel)
Constructor for a transaction versus a non-default database, at a custom isolation level.

The default transaction isolation level is configured in web.xml.

Parameters:
aDatabaseName - one of the return values of ConnectionSource.getDatabaseNames()
Method Detail

executeTx

public final int executeTx()
                    throws DAOException
Template method calls the abstract method executeMultipleSqls(java.sql.Connection).

Returns the same value as executeMultipleSqls.

A rollback is performed if executeMultipleSqls throws a SQLException or DAOException, or if executeMultipleSqls(Connection) returns BUSINESS_RULE_FAILURE.

Specified by:
executeTx in interface Tx
Throws:
DAOException

executeMultipleSqls

public abstract int executeMultipleSqls(Connection aConnection)
                                 throws SQLException,
                                        DAOException
Execute multiple SQL operations in a single local transaction.

This method returns the number of records edited. If a business rule determines that a rollback should be performed, then it is recommended that the special value BUSINESS_RULE_FAILURE be returned by the implementation. This will signal to executeTx() that a rollback must be performed. (Another option for signalling that a rollback is desired is to throw a checked exception.)

Design Note: allowing SQLException in the throws clause simplifies the implementor significantly, since no try-catch blocks are needed. Thus, the caller has simple, "straight-line" code.

Parameters:
aConnection - must be used by all SQL statements participating in this transaction
Returns:
number of records edited by this operation. Implementations may return BUSINESS_RULE_FAILURE if there is a business rule failure.
Throws:
SQLException
DAOException

Version 4.10.0

Copyright Hirondelle Systems. Published October 19, 2013 - User Guide - All Docs.