Top Description Fields Constructors Methods
org.springframework.jdbc.object

public abstract Class SqlQuery<T>

extends SqlOperation
Class Inheritance
Known Direct Subclasses
org.springframework.jdbc.object.UpdatableSqlQuery, org.springframework.jdbc.object.GenericSqlQuery, org.springframework.jdbc.object.MappingSqlQueryWithParameters
Type Parameters
<T>
the result type
Imports
java.util.List, .Map, javax.sql.DataSource, org.springframework.dao.DataAccessException, org.springframework.dao.support.DataAccessUtils, org.springframework.jdbc.core.RowMapper, org.springframework.jdbc.core.namedparam.MapSqlParameterSource, .NamedParameterUtils, .ParsedSql, org.springframework.lang.Nullable
Reusable operation object representing an SQL query.

Subclasses must implement the newRowMapper 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.

Authors
Rod Johnson, Juergen Hoeller, Thomas Risberg
See Also
SqlUpdate

Field Summary

Modifier and TypeField and Description
private int
rowsExpected

The number of rows to expect; if 0, unknown.

Constructor Summary

AccessConstructor and Description
public
SqlQuery()

Constructor to allow use as a JavaBean.

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

Convenient constructor with a DataSource and SQL string.

Method Summary

Modifier and TypeMethod and Description
public List<T>

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.
execute(Object[]
parameters, similar to JDO query parameters. Primitive parameters must be represented by their Object wrapper type. The ordering of parameters is significant.
params, Map<?, ?>
the 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.
context)

Central execution method.

public List<T>
execute(Object...
parameters for the query. Primitive parameters must be represented by their Object wrapper type. The ordering of parameters is significant.
params)

Convenient method to execute without context.

public List<T>
execute(Map<?, ?>
the contextual information for object creation
context)

Convenient method to execute without parameters.

public List<T>
execute()

Convenient method to execute without parameters nor context.

public List<T>
execute(int
single int parameter
p1, Map<?, ?>
the contextual information for object creation
context)

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

public List<T>
execute(int
single int parameter
p1)

Convenient method to execute with a single int parameter.

public List<T>
execute(int
first int parameter
p1, int
second int parameter
p2, Map<?, ?>
the contextual information for object creation
context)

Convenient method to execute with two int parameters and context.

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

Convenient method to execute with two int parameters.

public List<T>
execute(long
single long parameter
p1, Map<?, ?>
the contextual information for object creation
context)

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

public List<T>
execute(long
single long parameter
p1)

Convenient method to execute with a single long parameter.

public List<T>
execute(String
single String parameter
p1, Map<?, ?>
the contextual information for object creation
context)

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

public List<T>
execute(String
single String parameter
p1)

Convenient method to execute with a single String parameter.

public List<T>

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.
executeByNamedParam(Map<String, ?>
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.
paramMap, Map<?, ?>
the 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.
context)

Central execution method.

public List<T>
executeByNamedParam(Map<String, ?>
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.
paramMap)

Convenient method to execute without context.

public T

Returns:

the result object, or null if not found. Subclasses may choose to treat this as an error and throw an exception.
findObject(Object[] params, Map<?, ?> context)

Generic object finder method, used by all other findObject methods.

public T
findObject(Object... params)

Convenient method to find a single object without context.

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(int p1)

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

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(int p1, int p2)

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

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(long p1)

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

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(String p1)

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

public T

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.
findObjectByNamedParam(Map<String, ?>
a Map of parameter name to parameter object, matching named parameters specified in the SQL statement. Ordering is not significant.
paramMap, Map<?, ?>
the 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.
context)

Generic object finder method for named parameters.

public T
findObjectByNamedParam(Map<String, ?>
a Map of parameter name to parameter object, matching named parameters specified in the SQL statement. Ordering is not significant.
paramMap)

Convenient method to execute without context.

public int
getRowsExpected()

Get the number of rows expected.

protected abstract RowMapper<T>
newRowMapper(Object[]
the parameters to the execute() method, in case subclass is interested; may be null if there were no parameters.
parameters, Map<?, ?>
the 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.
context)

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

public void
setRowsExpected(int rowsExpected)

Set the number of rows expected.

Inherited from org.springframework.jdbc.object.SqlOperation:
compileInternalgetParsedSqlnewPreparedStatementCreatornewPreparedStatementCreatornewPreparedStatementSetteronCompileInternal

Field Detail

rowsExpectedback to summary
private int rowsExpected

The number of rows to expect; if 0, unknown.

Constructor Detail

SqlQueryback to summary
public SqlQuery()

Constructor to allow use as a JavaBean.

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

SqlQueryback to summary
public SqlQuery(DataSource ds, String sql)

Convenient constructor with a DataSource and SQL string.

Parameters
ds:DataSource

the DataSource to use to get connections

sql:String

the SQL to execute; SQL can also be supplied at runtime by overriding the getSql() method.

Method Detail

executeback to summary
public List<T> execute(Object[] params, Map<?, ?> context) throws DataAccessException

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

Parameters
params:Object[]

parameters, similar to JDO query parameters. Primitive parameters must be represented by their Object wrapper type. The ordering of parameters is significant.

context:Map<?, ?>

the 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:List<T>

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.

executeback to summary
public List<T> execute(Object... params) throws DataAccessException

Convenient method to execute without context.

Parameters
params:Object[]

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

executeback to summary
public List<T> execute(Map<?, ?> context) throws DataAccessException

Convenient method to execute without parameters.

Parameters
context:Map<?, ?>

the contextual information for object creation

executeback to summary
public List<T> execute() throws DataAccessException

Convenient method to execute without parameters nor context.

executeback to summary
public List<T> execute(int p1, Map<?, ?> context) throws DataAccessException

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

Parameters
p1:int

single int parameter

context:Map<?, ?>

the contextual information for object creation

executeback to summary
public List<T> execute(int p1) throws DataAccessException

Convenient method to execute with a single int parameter.

Parameters
p1:int

single int parameter

executeback to summary
public List<T> execute(int p1, int p2, Map<?, ?> context) throws DataAccessException

Convenient method to execute with two int parameters and context.

Parameters
p1:int

first int parameter

p2:int

second int parameter

context:Map<?, ?>

the contextual information for object creation

executeback to summary
public List<T> execute(int p1, int p2) throws DataAccessException

Convenient method to execute with two int parameters.

Parameters
p1:int

first int parameter

p2:int

second int parameter

executeback to summary
public List<T> execute(long p1, Map<?, ?> context) throws DataAccessException

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

Parameters
p1:long

single long parameter

context:Map<?, ?>

the contextual information for object creation

executeback to summary
public List<T> execute(long p1) throws DataAccessException

Convenient method to execute with a single long parameter.

Parameters
p1:long

single long parameter

executeback to summary
public List<T> execute(String p1, Map<?, ?> context) throws DataAccessException

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

Parameters
p1:String

single String parameter

context:Map<?, ?>

the contextual information for object creation

executeback to summary
public List<T> execute(String p1) throws DataAccessException

Convenient method to execute with a single String parameter.

Parameters
p1:String

single String parameter

executeByNamedParamback to summary
public List<T> executeByNamedParam(Map<String, ?> paramMap, Map<?, ?> context) throws DataAccessException

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

Parameters
paramMap:Map<String, ?>

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:Map<?, ?>

the 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:List<T>

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.

executeByNamedParamback to summary
public List<T> executeByNamedParam(Map<String, ?> paramMap) throws DataAccessException

Convenient method to execute without context.

Parameters
paramMap:Map<String, ?>

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.

findObjectback to summary
public T findObject(Object[] params, Map<?, ?> context) throws DataAccessException

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:T

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

Annotations
@Nullable
See Also
org.springframework.dao.support.DataAccessUtils#singleResult
findObjectback to summary
public T findObject(Object... params) throws DataAccessException

Convenient method to find a single object without context.

Annotations
@Nullable
findObjectback to summary
public T findObject(int p1, Map<?, ?> context) throws DataAccessException

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

Annotations
@Nullable
findObjectback to summary
public T findObject(int p1) throws DataAccessException

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

Annotations
@Nullable
findObjectback to summary
public T findObject(int p1, int p2, Map<?, ?> context) throws DataAccessException

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

Annotations
@Nullable
findObjectback to summary
public T findObject(int p1, int p2) throws DataAccessException

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

Annotations
@Nullable
findObjectback to summary
public T findObject(long p1, Map<?, ?> context) throws DataAccessException

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

Annotations
@Nullable
findObjectback to summary
public T findObject(long p1) throws DataAccessException

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

Annotations
@Nullable
findObjectback to summary
public T findObject(String p1, Map<?, ?> context) throws DataAccessException

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

Annotations
@Nullable
findObjectback to summary
public T findObject(String p1) throws DataAccessException

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

Annotations
@Nullable
findObjectByNamedParamback to summary
public T findObjectByNamedParam(Map<String, ?> paramMap, Map<?, ?> context) throws DataAccessException

Generic object finder method for named parameters.

Parameters
paramMap:Map<String, ?>

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

context:Map<?, ?>

the 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:T

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.

Annotations
@Nullable
findObjectByNamedParamback to summary
public T findObjectByNamedParam(Map<String, ?> paramMap) throws DataAccessException

Convenient method to execute without context.

Parameters
paramMap:Map<String, ?>

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

Annotations
@Nullable
getRowsExpectedback to summary
public int getRowsExpected()

Get the number of rows expected.

newRowMapperback to summary
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:Object[]

the parameters to the execute() method, in case subclass is interested; may be null if there were no parameters.

context:Map<?, ?>

the 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
execute
setRowsExpectedback to summary
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.