com.interface21.jdbc.object
Class RdbmsOperation

java.lang.Object
  |
  +--com.interface21.jdbc.object.RdbmsOperation
All Implemented Interfaces:
InitializingBean
Direct Known Subclasses:
SqlOperation, StoredProcedure

public abstract class RdbmsOperation
extends java.lang.Object
implements InitializingBean

Root of the JDBC object hierarchy, as described in Chapter 9 of Expert One-On-One J2EE Design and Development by Rod Johnson (Wrox, 2002).
An "RDBMS operation" is a multithreaded, reusable object representing a query, update or stored procedure.
An RDBMS operation is not a command, as a command isn't be reusable. However, execute methods may take commands as arguments.
Subclasses should be Java beans, allowing easy configuration.
This class and subclasses throw runtime exceptions, defined in the com.interface21.dao package (and as thrown by the com.interface21.jdbc.core package, which the classes in this package use to perform raw JDBC actions).
Subclasses should set DataSource, sql and add parameters, before invoking the compile() method. The order in which parameters are added is significant. The appropriate execute or update method can then be invoked.

Version:
$Id: RdbmsOperation.java,v 1.2 2003/05/28 16:39:14 jhoeller Exp $
Author:
Rod Johnson
See Also:
com.interface21.dao, com.interface21.jdbc.core

Field Summary
protected  org.apache.commons.logging.Log logger
           
 
Constructor Summary
protected RdbmsOperation()
          Construct a new RdbmsOperation
 
Method Summary
 void afterPropertiesSet()
          Ensures compilation if used in a bean factory
 void compile()
          Compile this query.
protected abstract  void compileInternal()
          Subclasses must implement to perform their own compilation.
 void declareParameter(SqlParameter param)
          Declare a parameter.
protected  javax.sql.DataSource getDataSource()
          Gets the DataSource in use
protected  java.util.List getDeclaredParameters()
          Return a list of the declared SqlParameter objects
 java.lang.String getSql()
          Subclasses can override this to supply dynamic SQL if they wish, but SQL is normally set by calling the setSql() method or in a subclass constructor.
 boolean isCompiled()
          Is this operation "compiled"?
 void setDataSource(javax.sql.DataSource dataSource)
          Sets the DataSource used to obtain connections
 void setSql(java.lang.String sql)
          Set the SQL executed by this operation
protected  void setTypes(int[] types)
          Add anonymous parameters, specifying only their SQL types as defined in the java.sql.Types class.
protected  void validateParameters(java.lang.Object[] parameters)
          Validate the parameters passed to an execute method based on declared parameters.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

logger

protected final org.apache.commons.logging.Log logger
Constructor Detail

RdbmsOperation

protected RdbmsOperation()
Construct a new RdbmsOperation
Method Detail

setTypes

protected void setTypes(int[] types)
                 throws InvalidDataAccessApiUsageException
Add anonymous parameters, specifying only their SQL types as defined in the java.sql.Types class.
Parameter ordering is significant. This method is an alternative to the declareParameter() method, which should normally be preferred.
Parameters:
types - array of SQL types as defined in the java.sql.Types class
Throws:
InvalidDataAccessApiUsageException - if the operation is already compiled

declareParameter

public void declareParameter(SqlParameter param)
                      throws InvalidDataAccessApiUsageException
Declare a parameter. The order in which this method is called is significant.
Parameters:
param - SqlParameter to add. This will specify SQL type and (optionally) the parameter's name.
Throws:
InvalidDataAccessApiUsageException - if the operation is already compiled, and hence cannot be configured further

getDeclaredParameters

protected java.util.List getDeclaredParameters()
Return a list of the declared SqlParameter objects
Returns:
a list of the declared SqlParameter objects

getSql

public java.lang.String getSql()
Subclasses can override this to supply dynamic SQL if they wish, but SQL is normally set by calling the setSql() method or in a subclass constructor.

setSql

public void setSql(java.lang.String sql)
Set the SQL executed by this operation
Parameters:
sql - the SQL executed by this operation

getDataSource

protected final javax.sql.DataSource getDataSource()
Gets the DataSource in use
Returns:
Returns the DataSource used to obtain connections

setDataSource

public final void setDataSource(javax.sql.DataSource dataSource)
Sets the DataSource used to obtain connections
Parameters:
dataSource - The DataSource to set

afterPropertiesSet

public void afterPropertiesSet()
Ensures compilation if used in a bean factory
Specified by:
afterPropertiesSet in interface InitializingBean
See Also:
InitializingBean.afterPropertiesSet()

isCompiled

public boolean isCompiled()
Is this operation "compiled"? Compilation, as in JDO, means that the operation is fully configured, and ready to use. The exact meaning of compilation will vary between subclasses.
Returns:
whether this operation is compiled, and ready to use.

compile

public final void compile()
                   throws InvalidDataAccessApiUsageException
Compile this query. Ignore subsequent attempts to compile
Throws:
InvalidDataAccessApiUsageException - if the object hasn't been correctly initialized, for example if no DataSource has been provided.

compileInternal

protected abstract void compileInternal()
                                 throws InvalidDataAccessApiUsageException
Subclasses must implement to perform their own compilation. Invoked after this class's compilation is complete. Subclasses can assume that sql has been supplied and that a DataSource has been supplied.
Throws:
InvalidDataAccessApiUsageException - if the subclass hasn't been properly configured.

validateParameters

protected final void validateParameters(java.lang.Object[] parameters)
                                 throws InvalidDataAccessApiUsageException
Validate the parameters passed to an execute method based on declared parameters. Subclasses should invoke this method before every execute() or update() method.
Parameters:
parameters - parameters supplied. May be null.
Throws:
InvalidDataAccessApiUsageException - if the parameters are invalid


Rod Johnson and Spring contributors 2001-2003.