Version 4.10.0

hirondelle.web4j.database
Class StoredProcedureTemplate

Object
  extended by hirondelle.web4j.database.StoredProcedureTemplate

public abstract class StoredProcedureTemplate
extends Object

Template for using CallableStatements.

The purpose of this class is to reduce code repetition related to CallableStatements : getting a connection, catching and translating exceptions, and closing statements and connections. As a second benefit, concrete implementations of this class have simpler, "straight-line" code, which is easier to both read and write.

This abstract base class is an example of the template design pattern.

The two constructors of this class correspond to whether or not this task is being performed as part of a transaction.

Use of this class requires creating a subclass. Typically, such a class would likely be nested within a Data Access Object. If an inner or local class is used, then input parameters defined in the enclosing class (the DAO) can be referenced directly. For example :

 //defined in the body of some enclosing DAO  :
 class DoPayRun extends StoredProcedureTemplate {
   DoPayRun(){ 
     super( "{call do_pay_run(?)}" );
   }
   void executeStoredProc(CallableStatement aCallableStatement) throws SQLException {
     //set param values, register out params, 
     //get results, etc.
     //fBlah is defined in the enclosing class:
     aCallableStatement.setInt(1, fBlah);
     fResult = aCallableStatement.executeUpdate();
   }
   //one way of returning a result, but there are many others :
   int getResult(){
     return fResult;
   }
   private int fResult;
 }
 ...
 //in the body of a DAO method, use a DoPayRun object
 DoPayRun doPayRun = new DoPayRun();
 doPayRun.execute();
 int result = doPayRun.getResult(); 

There are many ways to retrieve data from a call to a stored procedure, and this task is left entirely to subclasses of StoredProcedureTemplate.

In the rare cases where the default ResultSet properties are not adequate, the customizeResultSet methods may be used to alter them.

Design Note :
Although this class is still useful, it is not completely satisfactory for two reasons :


Constructor Summary
protected StoredProcedureTemplate(String aTextForCallingStoredProc)
          Constructor for case where this task is not part of a transaction.
protected StoredProcedureTemplate(String aTextForCallingStoredProc, Connection aSharedConnection)
          Constructor for case where this task is part of a transaction.
 
Method Summary
protected  void customizeResultSet(int aResultSetType, int aResultSetConcurrency)
          Change the properties of the default ResultSet, in exactly the same manner as Connection.prepareCall(java.lang.String, int, int).
protected  void customizeResultSet(int aResultSetType, int aResultSetConcurrency, int aResultSetHoldability)
          Change the properties of the default ResultSet, in exactly the same manner as Connection.prepareCall(java.lang.String, int, int, int).
 void execute()
          Template method which calls executeStoredProc(java.sql.CallableStatement).
protected abstract  void executeStoredProc(CallableStatement aCallableStatement)
          Perform the core task.
protected  void setDatabaseName(String aDatabaseName)
          Change to a non-default database.
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

StoredProcedureTemplate

protected StoredProcedureTemplate(String aTextForCallingStoredProc)
Constructor for case where this task is not part of a transaction.

Parameters:
aTextForCallingStoredProc - text such as '{call do_this(?,?)}' (for more information on valid values, see CallableStatement)

StoredProcedureTemplate

protected StoredProcedureTemplate(String aTextForCallingStoredProc,
                                  Connection aSharedConnection)
Constructor for case where this task is part of a transaction.

The task performed by executeStoredProc(java.sql.CallableStatement) will use aConnection, and will thus participate in any associated transaction being used by the caller.

Parameters:
aTextForCallingStoredProc - text such as '{call do_this(?,?)}' (for more information on valid values, see CallableStatement).
aSharedConnection - pre-existing connection created by the caller for including multiple operations in the same transaction.
Method Detail

execute

public void execute()
             throws DAOException
Template method which calls executeStoredProc(java.sql.CallableStatement).

Throws:
DAOException

executeStoredProc

protected abstract void executeStoredProc(CallableStatement aCallableStatement)
                                   throws SQLException
Perform the core task.

Implementations of this method do not fetch a connection, catch exceptions, or call close methods. Those tasks are handled by this base class.

See class description for an example.

Throws:
SQLException

setDatabaseName

protected final void setDatabaseName(String aDatabaseName)
Change to a non-default database.

Use this method to force this class to use an internal connection a non-default database. It does not make sense to call this method when using an external Connection - that is, when using StoredProcedureTemplate(String, Connection).

See ConnectionSource for more information on database names.

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

customizeResultSet

protected final void customizeResultSet(int aResultSetType,
                                        int aResultSetConcurrency)
Change the properties of the default ResultSet, in exactly the same manner as Connection.prepareCall(java.lang.String, int, int).

In the rare cases where this method is used, it must be called before execute().


customizeResultSet

protected final void customizeResultSet(int aResultSetType,
                                        int aResultSetConcurrency,
                                        int aResultSetHoldability)
Change the properties of the default ResultSet, in exactly the same manner as Connection.prepareCall(java.lang.String, int, int, int).

In the rare cases where this method is used, it must be called before execute().


Version 4.10.0

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