public abstract class

SqlQuery

extends SqlOperation
java.lang.Object
   ↳ org.springframework.jdbc.object.RdbmsOperation
     ↳ org.springframework.jdbc.object.SqlOperation
       ↳ org.springframework.jdbc.object.SqlQuery<T>
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

Reusable operation object representing a SQL query.

Subclasses must implement the newRowMapper(Object[], Map) method to provide an object that can extract the results of iterating over the ResultSet created during the execution of the query.

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 (definitely a best practice). Each custom query method will invoke one of this class's untyped query methods.

Like all RdbmsOperation classes that ship with the Spring Framework, SqlQuery instances are thread-safe after their initialization is complete. That is, after they are constructed and configured via their setter methods, they can be used safely from multiple threads.

See Also

Summary

[Expand]
Inherited Fields
From class org.springframework.jdbc.object.RdbmsOperation
Public Constructors
SqlQuery()
Constructor to allow use as a JavaBean.
SqlQuery(DataSource ds, String sql)
Convenient constructor with a DataSource and SQL string.
Public Methods
List<T> execute(String p1)
Convenient method to execute with a single String parameter.
List<T> execute(long p1)
Convenient method to execute with a single long parameter.
List<T> execute(int p1, int p2)
Convenient method to execute with two int parameters.
List<T> execute()
Convenient method to execute without parameters nor context.
List<T> execute(int p1, Map context)
Convenient method to execute with a single int parameter and context.
List<T> execute(Map context)
Convenient method to execute without parameters.
List<T> execute(String p1, Map context)
Convenient method to execute with a single String parameter and context.
List<T> execute(int p1)
Convenient method to execute with a single int parameter.
List<T> execute(Object... params)
Convenient method to execute without context.
List<T> execute(int p1, int p2, Map context)
Convenient method to execute with two int parameters and context.
List<T> execute(Object[] params, Map context)
Central execution method.
List<T> execute(long p1, Map context)
Convenient method to execute with a single long parameter and context.
List<T> executeByNamedParam(Map<String, ?> paramMap)
Convenient method to execute without context.
List<T> executeByNamedParam(Map<String, ?> paramMap, Map context)
Central execution method.
T findObject(int p1)
Convenient method to find a single object given a single int parameter.
T findObject(Object[] params, Map context)
Generic object finder method, used by all other findObject methods.
T findObject(int p1, Map context)
Convenient method to find a single object given a single int parameter and a context.
T findObject(String p1, Map context)
Convenient method to find a single object given a single String parameter and a context.
T findObject(Object... params)
Convenient method to find a single object without context.
T findObject(long p1, Map context)
Convenient method to find a single object given a single long parameter and a context.
T findObject(int p1, int p2, Map context)
Convenient method to find a single object given two int parameters and a context.
T findObject(long p1)
Convenient method to find a single object given a single long parameter.
T findObject(int p1, int p2)
Convenient method to find a single object given two int parameters.
T findObject(String p1)
Convenient method to find a single object given a single String parameter.
T findObjectByNamedParam(Map<String, ?> paramMap, Map context)
Generic object finder method for named parameters.
T findObjectByNamedParam(Map<String, ?> paramMap)
Convenient method to execute without context.
int getRowsExpected()
Get the number of rows expected.
void setRowsExpected(int rowsExpected)
Set the number of rows expected.
Protected Methods
abstract RowMapper<T> newRowMapper(Object[] parameters, Map context)
Subclasses must implement this method to extract an object per row, to be returned by the execute method as an aggregated List.
[Expand]
Inherited Methods
From class org.springframework.jdbc.object.SqlOperation
From class org.springframework.jdbc.object.RdbmsOperation
From class java.lang.Object
From interface org.springframework.beans.factory.InitializingBean

Public Constructors

public SqlQuery ()

Constructor to allow use as a JavaBean.

The DataSource and SQL must be supplied before compilation and use.

public SqlQuery (DataSource ds, String sql)

Convenient constructor with a DataSource and SQL string.

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

Public Methods

public List<T> execute (String p1)

Convenient method to execute with a single String parameter.

Parameters
p1 single String parameter

public List<T> execute (long p1)

Convenient method to execute with a single long parameter.

Parameters
p1 single long parameter

public List<T> execute (int p1, int p2)

Convenient method to execute with two int parameters.

Parameters
p1 first int parameter
p2 second int parameter

public List<T> execute ()

Convenient method to execute without parameters nor context.

public List<T> execute (int p1, Map context)

Convenient method to execute with a single int parameter and context.

Parameters
p1 single int parameter
context the contextual information for object creation

public List<T> execute (Map context)

Convenient method to execute without parameters.

Parameters
context the contextual information for object creation

public List<T> execute (String p1, Map context)

Convenient method to execute with a single String parameter and context.

Parameters
p1 single String parameter
context the contextual information for object creation

public List<T> execute (int p1)

Convenient method to execute with a single int parameter.

Parameters
p1 single int parameter

public List<T> execute (Object... params)

Convenient method to execute without context.

Parameters
params parameters for the query. Primitive parameters must be represented by their Object wrapper type. The ordering of parameters is significant.

public List<T> execute (int p1, int p2, Map context)

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

public List<T> execute (Object[] params, Map context)

Central execution method. All un-named parameter execution goes through this method.

Parameters
params parameters, similar to JDO query parameters. Primitive parameters must be represented by their Object wrapper type. The ordering of parameters is significant.
context contextual information passed to the mapRow callback method. The JDBC operation itself doesn't rely on this parameter, but it can be useful for creating the objects of the result 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.

public List<T> execute (long p1, Map context)

Convenient method to execute with a single long parameter and context.

Parameters
p1 single long parameter
context the contextual information for object creation

public List<T> executeByNamedParam (Map<String, ?> paramMap)

Convenient method to execute without context.

Parameters
paramMap parameters associated with the name specified while declaring the SqlParameters. Primitive parameters must be represented by their Object wrapper type. The ordering of parameters is not significant.

public List<T> executeByNamedParam (Map<String, ?> paramMap, Map context)

Central execution method. All named parameter execution goes through this method.

Parameters
paramMap parameters associated with the name specified while declaring the SqlParameters. Primitive parameters must be represented by their Object wrapper type. The ordering of parameters is not significant since they are supplied in a SqlParameterMap which is an implementation of the Map interface.
context contextual information passed to the mapRow callback method. The JDBC operation itself doesn't rely on this parameter, but it can be useful for creating the objects of the result 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.

public T findObject (int p1)

Convenient method to find a single object given a single int parameter.

public T findObject (Object[] params, Map context)

Generic object finder method, used by all other findObject methods. Object finder methods are like EJB entity bean finders, in that it is considered an error if they return more than one result.

Returns
  • the result object, or null if not found. Subclasses may choose to treat this as an error and throw an exception.

public T findObject (int p1, Map context)

Convenient method to find a single object given a single int parameter and a context.

public T findObject (String p1, Map context)

Convenient method to find a single object given a single String parameter and a context.

public T findObject (Object... params)

Convenient method to find a single object without context.

public T findObject (long p1, Map context)

Convenient method to find a single object given a single long parameter and a context.

public T findObject (int p1, int p2, Map context)

Convenient method to find a single object given two int parameters and a context.

public T findObject (long p1)

Convenient method to find a single object given a single long parameter.

public T findObject (int p1, int p2)

Convenient method to find a single object given two int parameters.

public T findObject (String p1)

Convenient method to find a single object given a single String parameter.

public T findObjectByNamedParam (Map<String, ?> paramMap, Map context)

Generic object finder method for named parameters.

Parameters
paramMap Map of parameter name to parameter object, matching named parameters specified in the SQL statement. Ordering is not significant.
context contextual information passed to the mapRow callback method. The JDBC operation itself doesn't rely on this parameter, but it can be useful for creating the objects of the result 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.

public T findObjectByNamedParam (Map<String, ?> paramMap)

Convenient method to execute without context.

Parameters
paramMap Map of parameter name to parameter object, matching named parameters specified in the SQL statement. Ordering is not significant.

public int getRowsExpected ()

Get the number of rows expected.

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.

Protected Methods

protected abstract RowMapper<T> newRowMapper (Object[] parameters, Map context)

Subclasses must implement this method to extract an object per row, to be returned by the execute method as an aggregated List.

Parameters
parameters the parameters to the execute() method, in case subclass is interested; may be null if there were no parameters.
context contextual information passed to the mapRow callback method. The JDBC operation itself doesn't rely on this parameter, but it can be useful for creating the objects of the result list.
See Also