org.springframework.jdbc.object
Class SqlQuery

java.lang.Object
  extended byorg.springframework.jdbc.object.RdbmsOperation
      extended byorg.springframework.jdbc.object.SqlOperation
          extended byorg.springframework.jdbc.object.SqlQuery
All Implemented Interfaces:
InitializingBean
Direct Known Subclasses:
MappingSqlQueryWithParameters, UpdatableSqlQuery

public abstract class SqlQuery
extends SqlOperation

Reusable threadsafe object to represent a SQL query. Subclasses must implement the newResultReader() method to provide an object that can save the results of iterating over the ResultSet.

This class provides a number of public execute() methods that are analogous to the different convenient JDO query execute() methods. Subclasses can either rely on one of these inherited methods, or can add their own custom execution methods, with meaningful names and typed parameters. Each custom query method will invoke one of this class's untype query methods.

Version:
$Id: SqlQuery.java,v 1.6 2004/03/18 02:46:13 trisberg Exp $
Author:
Rod Johnson, Jean-Pierre Pawlak

Field Summary
 
Fields inherited from class org.springframework.jdbc.object.RdbmsOperation
logger
 
Constructor Summary
SqlQuery()
          Allow use as a bean.
SqlQuery(javax.sql.DataSource ds, java.lang.String sql)
          Convenient constructor with DataSource and SQL string.
 
Method Summary
 java.util.List execute()
          Convenient method to execute without parameters nor context.
 java.util.List execute(int p1)
          Convenient method to execute with a single int parameter.
 java.util.List execute(int p1, int p2)
          Convenient method to execute with two int parameters.
 java.util.List execute(int p1, int p2, java.util.Map context)
          Convenient method to execute with two int parameters and context.
 java.util.List execute(int p1, java.util.Map context)
          Convenient method to execute with a single int parameter and context.
 java.util.List execute(long p1)
          Convenient method to execute with a single long parameter.
 java.util.List execute(long p1, java.util.Map context)
          Convenient method to execute with a single long parameter and context.
 java.util.List execute(java.util.Map context)
          Convenient method to execute without parameters.
 java.util.List execute(java.lang.Object[] parameters)
          Convenient method to execute without context.
 java.util.List execute(java.lang.Object[] parameters, java.util.Map context)
          All execution goes through this method
 java.util.List execute(java.lang.String p1)
          Convenient method to execute with a single String parameter.
 java.util.List execute(java.lang.String p1, java.util.Map context)
          Convenient method to execute with a single String parameter and context.
 java.lang.Object findObject(int p1)
          Convenience method to find a single object given a single int parameter.
 java.lang.Object findObject(int p1, int p2)
          Convenience method to find a single object given two int parameters.
 java.lang.Object findObject(int p1, int p2, java.util.Map context)
          Convenience method to find a single object given two int parameters and a context.
 java.lang.Object findObject(int p1, java.util.Map context)
          Convenience method to find a single object given a single int parameter and a context.
 java.lang.Object findObject(long p1)
          Convenience method to find a single object given a single long parameter.
 java.lang.Object findObject(long p1, java.util.Map context)
          Convenience method to find a single object given a single long parameter and a context.
 java.lang.Object findObject(java.lang.Object[] parameters)
          Convenience method to find a single object without context.
 java.lang.Object findObject(java.lang.Object[] parameters, java.util.Map context)
          Generic findObject method, used by all other findObject() methods.
 java.lang.Object findObject(java.lang.String p1)
          Convenience method to find a single object given a single String parameter.
 java.lang.Object findObject(java.lang.String p1, java.util.Map context)
          Convenience method to find a single object given a single String parameter and a context.
 int getRowsExpected()
          Get the number of rows expected.
protected abstract  ResultReader newResultReader(int rowsExpected, java.lang.Object[] parameters, java.util.Map context)
          Subclasses must implement this method to save a List of objects returned by the execute method.
protected  void onCompileInternal()
          Subclasses can override this method to implement custom behavior on compilation.
 void setRowsExpected(int rowsExpected)
          Set the number of rows expected.
 
Methods inherited from class org.springframework.jdbc.object.SqlOperation
compileInternal, getResultSetType, isUpdatableResults, newPreparedStatementCreator, setResultSetType, setUpdatableResults
 
Methods inherited from class org.springframework.jdbc.object.RdbmsOperation
afterPropertiesSet, compile, declareParameter, getDeclaredParameters, getJdbcTemplate, getSql, isCompiled, setDataSource, setJdbcTemplate, setSql, setTypes, validateParameters
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SqlQuery

public SqlQuery()
Allow use as a bean.


SqlQuery

public SqlQuery(javax.sql.DataSource ds,
                java.lang.String sql)
Convenient constructor with DataSource and SQL string.

Parameters:
ds - DataSource to use to get connections
sql - to execute. SQL can also be supplied at runtime by overriding the getSql() method.
Method Detail

setRowsExpected

public void setRowsExpected(int rowsExpected)
Set the number of rows expected. This can be used to ensure efficient storage of results. The default behavior is not to expect any specific number of rows.


getRowsExpected

public int getRowsExpected()
Get the number of rows expected.


execute

public java.util.List execute(java.lang.Object[] parameters,
                              java.util.Map context)
                       throws DataAccessException
All execution goes through this method

Parameters:
parameters - parameters, as to JDO queries. Primitive parameters must be represented by their Object wrapper type. The ordering of parameters is significant.
context - contextual information passed to the callback mapRow method. This parameter don't rely on the Jdbc request itself, but can be useful for creating the objects of the list.
Returns:
a list of objects, one per row of the ResultSet. Normally all these will be of the same class, although it is possible to use different types.
Throws:
DataAccessException

execute

public java.util.List execute(java.lang.Object[] parameters)
                       throws DataAccessException
Convenient method to execute without context.

Parameters:
parameters - parameters, as to JDO queries. Primitive parameters must be represented by their Object wrapper type. The ordering of parameters is significant.
Throws:
DataAccessException

execute

public java.util.List execute(java.util.Map context)
                       throws DataAccessException
Convenient method to execute without parameters.

Parameters:
context - The contextual information for object creation
Throws:
DataAccessException

execute

public java.util.List execute()
                       throws DataAccessException
Convenient method to execute without parameters nor context.

Throws:
DataAccessException

execute

public java.util.List execute(int p1,
                              java.util.Map context)
                       throws DataAccessException
Convenient method to execute with a single int parameter and context.

Parameters:
p1 - single int parameter
context - The contextual information for object creation
Throws:
DataAccessException

execute

public java.util.List execute(int p1)
                       throws DataAccessException
Convenient method to execute with a single int parameter.

Parameters:
p1 - single int parameter
Throws:
DataAccessException

execute

public java.util.List execute(int p1,
                              int p2,
                              java.util.Map context)
                       throws DataAccessException
Convenient method to execute with two int parameters and context.

Parameters:
p1 - first int parameter
p2 - second int parameter
context - The contextual information for object creation
Throws:
DataAccessException

execute

public java.util.List execute(int p1,
                              int p2)
                       throws DataAccessException
Convenient method to execute with two int parameters.

Parameters:
p1 - first int parameter
p2 - second int parameter
Throws:
DataAccessException

execute

public java.util.List execute(long p1,
                              java.util.Map context)
                       throws DataAccessException
Convenient method to execute with a single long parameter and context.

Parameters:
p1 - single long parameter
context - The contextual information for object creation
Throws:
DataAccessException

execute

public java.util.List execute(long p1)
                       throws DataAccessException
Convenient method to execute with a single long parameter.

Parameters:
p1 - single long parameter
Throws:
DataAccessException

execute

public java.util.List execute(java.lang.String p1,
                              java.util.Map context)
                       throws DataAccessException
Convenient method to execute with a single String parameter and context.

Parameters:
p1 - single String parameter
context - The contextual information for object creation
Throws:
DataAccessException

execute

public java.util.List execute(java.lang.String p1)
                       throws DataAccessException
Convenient method to execute with a single String parameter.

Parameters:
p1 - single String parameter
Throws:
DataAccessException

findObject

public java.lang.Object findObject(java.lang.Object[] parameters,
                                   java.util.Map context)
                            throws DataAccessException
Generic findObject method, used by all other findObject() methods. findObject() methods are like EJB entity bean finders, in that it is considered an error if they return more than one result.

Returns:
null if not found. Subclasses may choose to treat this as an error and throw an exception.
Throws:
DataAccessException

findObject

public java.lang.Object findObject(java.lang.Object[] parameters)
                            throws DataAccessException
Convenience method to find a single object without context.

Throws:
DataAccessException

findObject

public java.lang.Object findObject(int p1,
                                   java.util.Map context)
                            throws DataAccessException
Convenience method to find a single object given a single int parameter and a context.

Throws:
DataAccessException

findObject

public java.lang.Object findObject(int p1)
                            throws DataAccessException
Convenience method to find a single object given a single int parameter.

Throws:
DataAccessException

findObject

public java.lang.Object findObject(int p1,
                                   int p2,
                                   java.util.Map context)
                            throws DataAccessException
Convenience method to find a single object given two int parameters and a context.

Throws:
DataAccessException

findObject

public java.lang.Object findObject(int p1,
                                   int p2)
                            throws DataAccessException
Convenience method to find a single object given two int parameters.

Throws:
DataAccessException

findObject

public java.lang.Object findObject(java.lang.String p1,
                                   java.util.Map context)
                            throws DataAccessException
Convenience method to find a single object given a single String parameter and a context.

Throws:
DataAccessException

findObject

public java.lang.Object findObject(java.lang.String p1)
                            throws DataAccessException
Convenience method to find a single object given a single String parameter.

Throws:
DataAccessException

findObject

public java.lang.Object findObject(long p1,
                                   java.util.Map context)
                            throws DataAccessException
Convenience method to find a single object given a single long parameter and a context.

Throws:
DataAccessException

findObject

public java.lang.Object findObject(long p1)
                            throws DataAccessException
Convenience method to find a single object given a single long parameter.

Throws:
DataAccessException

newResultReader

protected abstract ResultReader newResultReader(int rowsExpected,
                                                java.lang.Object[] parameters,
                                                java.util.Map context)
Subclasses must implement this method to save a List of objects returned by the execute method.

Parameters:
rowsExpected - If 0, we don't know how many rows to expect. This parameter can be ignored, but may help some implementations choose the most efficient Collection type: e.g. ArrayList instead of LinkedList for large result sets.
parameters - parameters to the execute() method, in case subclass is interested. May be null if there were no parameters.
See Also:
execute(java.lang.Object[], java.util.Map)

onCompileInternal

protected void onCompileInternal()
Subclasses can override this method to implement custom behavior on compilation. This implementation does nothing.

Overrides:
onCompileInternal in class SqlOperation


Copyright (C) 2003-2004 The Spring Framework Project.