org.springframework.jdbc.object
Class RdbmsOperation

java.lang.Object
  org.springframework.jdbc.object.RdbmsOperation

All Implemented Interfaces:

InitializingBean

Direct Known Subclasses:

SqlCall, SqlOperation

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 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 org.springframework.dao package (and as thrown by the org.springframework.jdbc.core package, which the classes in this package use to perform raw JDBC actions).

Subclasses should set 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.8 2004/03/18 02:46:13 trisberg Exp $

Author:

Rod Johnson

See Also:

org.springframework.dao, org.springframework.jdbc.core

Field Summary

protected org.apache.commons.logging.Log

logger

Constructor Summary

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 java.util.List	getDeclaredParameters() Return a list of the declared SqlParameter objects.
protected JdbcTemplate	getJdbcTemplate() Return the JdbcTemplate object used by this object.
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"? Compilation, as in JDO, means that the operation is fully configured, and ready to use.
void	setDataSource(javax.sql.DataSource dataSource) Set the JDBC DataSource to obtain connections from.
void	setJdbcTemplate(JdbcTemplate jdbcTemplate) An alternative to the more commonly used setDataSource() when you want to use the same JdbcTemplate in multiple RdbmsOperations.
void	setSql(java.lang.String sql) Set the SQL executed by this operation.
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

public RdbmsOperation()

Method Detail

setDataSource

public void setDataSource(javax.sql.DataSource dataSource)

Set the JDBC DataSource to obtain connections from.

setJdbcTemplate

public void setJdbcTemplate(JdbcTemplate jdbcTemplate)

An alternative to the more commonly used setDataSource() when you want to use the same JdbcTemplate in multiple RdbmsOperations. This is appropriate if the JdbcTemplate has special configuration such as a SQLExceptionTranslator that should apply to multiple RdbmsOperation objects.

Parameters:

jdbcTemplate -

getJdbcTemplate

protected JdbcTemplate getJdbcTemplate()

Return the JdbcTemplate object used by this object.

setTypes

public 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.

setSql

public void setSql(java.lang.String sql)

Set the SQL executed by this operation.

Parameters:

sql - the SQL executed by this operation

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.

afterPropertiesSet

public void afterPropertiesSet()

Ensures compilation if used in a bean factory.

Specified by:

afterPropertiesSet in interface InitializingBean

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 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 executeQuery() or update() method.

Parameters:

parameters - parameters supplied. May be null.

Throws:

InvalidDataAccessApiUsageException - if the parameters are invalid