Package org.springframework.jdbc.object

# Class SqlQuery<T>

java.lang.Object
org.springframework.jdbc.object.RdbmsOperation
org.springframework.jdbc.object.SqlOperation
org.springframework.jdbc.object.SqlQuery<T>

Type Parameters:
  `T` - the result type

All Implemented Interfaces:
  `org.springframework.beans.factory.InitializingBean`

Direct Known Subclasses:
  `GenericSqlQuery`, `MappingSqlQueryWithParameters`, `UpdatableSqlQuery`

public abstract class SqlQuery<T> extends SqlOperation
Reusable operation object representing an SQL query.

Subclasses must implement the `newRowMapper(java.lang.Object[], java.util.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.

Author:
  Rod Johnson, Juergen Hoeller, Thomas Risberg
See Also:
  - `SqlUpdate`

## Field Summary

### Fields inherited from class org.springframework.jdbc.object.RdbmsOperation

`logger`

## Constructor Summary

Constructors
Constructor
Description
`SqlQuery()`
Constructor to allow use as a JavaBean.
`SqlQuery(DataSource ds, String sql)`
Convenient constructor with a `DataSource` and SQL string.

## Method Summary

Modifier and Type
Method
Description
`List<T>`
`execute()`
Convenient method to execute without parameters nor context.
`List<T>`
`execute(int p1)`
Convenient method to execute with a single int parameter.
`List<T>`
`execute(int p1, int p2)`
Convenient method to execute with two int parameters.
`List<T>`
`execute(int p1, int p2, Map<?,?> context)`
Convenient method to execute with two int parameters and context.
`List<T>`
`execute(int p1, Map<?,?> context)`
Convenient method to execute with a single int parameter and context.
`List<T>`
`execute(long p1)`
Convenient method to execute with a single long parameter.
`List<T>`
`execute(long p1, Map<?,?> context)`
Convenient method to execute with a single long parameter and context.
`List<T>`
`execute(Object... params)`
Convenient method to execute without context.
`List<T>`
`execute(Object[] params, Map<?,?> context)`
Central execution method.
`List<T>`
`execute(String p1)`
Convenient method to execute with a single String parameter.
`List<T>`
`execute(String p1, Map<?,?> context)`
Convenient method to execute with a single String parameter and context.
`List<T>`
`execute(Map<?,?> context)`
Convenient method to execute without parameters.
`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(int p1, int p2)`
Convenient method to find a single object given two int parameters.
`T`
`findObject(int p1, int p2, Map<?,?> context)`
Convenient method to find a single object given two int parameters and a context.
`T`
`findObject(int p1, Map<?,?> context)`
Convenient method to find a single object given a single int parameter and a context.
`T`
`findObject(long p1)`
Convenient method to find a single object given a single long parameter.
`T`
`findObject(long p1, Map<?,?> context)`
Convenient method to find a single object given a single long parameter and a context.
`T`
`findObject(Object... params)`
Convenient method to find a single object without context.
`T`
`findObject(Object[] params, Map<?,?> context)`
Generic object finder method, used by all other `findObject` methods.
`T`
`findObject(String p1)`
Convenient method to find a single object given a single String parameter.
`T`
`findObject(String p1, Map<?,?> context)`
Convenient method to find a single object given a single String parameter and a context.
`T`
`findObjectByNamedParam(Map<String,?> paramMap)`
Convenient method to execute without context.
`T`
`findObjectByNamedParam(Map<String,?> paramMap, Map<?,?> context)`
Generic object finder method for named parameters.
`int`
`getRowsExpected()`
Deprecated, for removal: This API element is subject to removal in a future version.
since 6.2.4 with no replacement since the property has never had any affect on behavior; to be removed in 7.0
`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`.
`void`
`setRowsExpected(int rowsExpected)`
Deprecated, for removal: This API element is subject to removal in a future version.
since 6.2.4 with no replacement since the property has never had any affect on behavior; to be removed in 7.0

### Methods inherited from class org.springframework.jdbc.object.SqlOperation

`compileInternal, getParsedSql, newPreparedStatementCreator, newPreparedStatementCreator, newPreparedStatementSetter, onCompileInternal`

### Methods inherited from class org.springframework.jdbc.object.RdbmsOperation

`afterPropertiesSet, allowsUnusedParameters, checkCompiled, compile, declareParameter, getDeclaredParameters, getGeneratedKeysColumnNames, getJdbcTemplate, getResultSetType, getSql, isCompiled, isReturnGeneratedKeys, isUpdatableResults, resolveSql, setDataSource, setFetchSize, setGeneratedKeysColumnNames, setJdbcTemplate, setMaxRows, setParameters, setQueryTimeout, setResultSetType, setReturnGeneratedKeys, setSql, setTypes, setUpdatableResults, supportsLobParameters, validateNamedParameters, validateParameters`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### SqlQuery

public SqlQuery()
Constructor to allow use as a JavaBean.

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

### SqlQuery

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 `RdbmsOperation.getSql()` method.

## Method Details

### setRowsExpected

@Deprecated(since="6.2.4", forRemoval=true) public void setRowsExpected(int rowsExpected)
Deprecated, for removal: This API element is subject to removal in a future version.
since 6.2.4 with no replacement since the property has never had any affect on behavior; to be removed in 7.0
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

@Deprecated(since="6.2.4", forRemoval=true) public int getRowsExpected()
Deprecated, for removal: This API element is subject to removal in a future version.
since 6.2.4 with no replacement since the property has never had any affect on behavior; to be removed in 7.0
Get the number of rows expected.

### execute

public List<T> execute(@Nullable Object[] params, @Nullable Map<?,?> context) throws org.springframework.dao.DataAccessException
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` - 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:
  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:
  `org.springframework.dao.DataAccessException`

### execute

public List<T> execute(Object... params) throws org.springframework.dao.DataAccessException
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.
Throws:
  `org.springframework.dao.DataAccessException`

### execute

public List<T> execute(Map<?,?> context) throws org.springframework.dao.DataAccessException
Convenient method to execute without parameters.

Parameters:
  `context` - the contextual information for object creation
Throws:
  `org.springframework.dao.DataAccessException`

### execute

public List<T> execute() throws org.springframework.dao.DataAccessException
Convenient method to execute without parameters nor context.

Throws:
  `org.springframework.dao.DataAccessException`

### execute

public List<T> execute(int p1, @Nullable Map<?,?> context) throws org.springframework.dao.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:
  `org.springframework.dao.DataAccessException`

### execute

public List<T> execute(int p1) throws org.springframework.dao.DataAccessException
Convenient method to execute with a single int parameter.

Parameters:
  `p1` - single int parameter
Throws:
  `org.springframework.dao.DataAccessException`

### execute

public List<T> execute(int p1, int p2, @Nullable Map<?,?> context) throws org.springframework.dao.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:
  `org.springframework.dao.DataAccessException`

### execute

public List<T> execute(int p1, int p2) throws org.springframework.dao.DataAccessException
Convenient method to execute with two int parameters.

Parameters:
  `p1` - first int parameter
  `p2` - second int parameter
Throws:
  `org.springframework.dao.DataAccessException`

### execute

public List<T> execute(long p1, @Nullable Map<?,?> context) throws org.springframework.dao.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:
  `org.springframework.dao.DataAccessException`

### execute

public List<T> execute(long p1) throws org.springframework.dao.DataAccessException
Convenient method to execute with a single long parameter.

Parameters:
  `p1` - single long parameter
Throws:
  `org.springframework.dao.DataAccessException`

### execute

public List<T> execute(String p1, @Nullable Map<?,?> context) throws org.springframework.dao.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:
  `org.springframework.dao.DataAccessException`

### execute

public List<T> execute(String p1) throws org.springframework.dao.DataAccessException
Convenient method to execute with a single String parameter.

Parameters:
  `p1` - single String parameter
Throws:
  `org.springframework.dao.DataAccessException`

### executeByNamedParam

public List<T> executeByNamedParam(Map<String,?> paramMap, @Nullable Map<?,?> context) throws org.springframework.dao.DataAccessException
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` - 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:
  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:
  `org.springframework.dao.DataAccessException`

### executeByNamedParam

public List<T> executeByNamedParam(Map<String,?> paramMap) throws org.springframework.dao.DataAccessException
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.
Throws:
  `org.springframework.dao.DataAccessException`

### findObject

@Nullable public T findObject(@Nullable Object[] params, @Nullable Map<?,?> context) throws org.springframework.dao.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:
  the result object, or `null` if not found. Subclasses may choose to treat this as an error and throw an exception.
Throws:
  `org.springframework.dao.DataAccessException`
See Also:
  - `DataAccessUtils.singleResult(java.util.Collection<T>)`

### findObject

@Nullable public T findObject(Object... params) throws org.springframework.dao.DataAccessException
Convenient method to find a single object without context.

Throws:
  `org.springframework.dao.DataAccessException`

### findObject

@Nullable public T findObject(int p1, @Nullable Map<?,?> context) throws org.springframework.dao.DataAccessException
Convenient method to find a single object given a single int parameter and a context.

Throws:
  `org.springframework.dao.DataAccessException`

### findObject

@Nullable public T findObject(int p1) throws org.springframework.dao.DataAccessException
Convenient method to find a single object given a single int parameter.

Throws:
  `org.springframework.dao.DataAccessException`

### findObject

@Nullable public T findObject(int p1, int p2, @Nullable Map<?,?> context) throws org.springframework.dao.DataAccessException
Convenient method to find a single object given two int parameters and a context.

Throws:
  `org.springframework.dao.DataAccessException`

### findObject

@Nullable public T findObject(int p1, int p2) throws org.springframework.dao.DataAccessException
Convenient method to find a single object given two int parameters.

Throws:
  `org.springframework.dao.DataAccessException`

### findObject

@Nullable public T findObject(long p1, @Nullable Map<?,?> context) throws org.springframework.dao.DataAccessException
Convenient method to find a single object given a single long parameter and a context.

Throws:
  `org.springframework.dao.DataAccessException`

### findObject

@Nullable public T findObject(long p1) throws org.springframework.dao.DataAccessException
Convenient method to find a single object given a single long parameter.

Throws:
  `org.springframework.dao.DataAccessException`

### findObject

@Nullable public T findObject(String p1, @Nullable Map<?,?> context) throws org.springframework.dao.DataAccessException
Convenient method to find a single object given a single String parameter and a context.

Throws:
  `org.springframework.dao.DataAccessException`

### findObject

@Nullable public T findObject(String p1) throws org.springframework.dao.DataAccessException
Convenient method to find a single object given a single String parameter.

Throws:
  `org.springframework.dao.DataAccessException`

### findObjectByNamedParam

@Nullable public T findObjectByNamedParam(Map<String,?> paramMap, @Nullable Map<?,?> context) throws org.springframework.dao.DataAccessException
Generic object finder method for named parameters.

Parameters:
  `paramMap` - a Map of parameter name to parameter object, matching named parameters specified in the SQL statement. Ordering is not significant.
  `context` - 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:
  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:
  `org.springframework.dao.DataAccessException`

### findObjectByNamedParam

@Nullable public T findObjectByNamedParam(Map<String,?> paramMap) throws org.springframework.dao.DataAccessException
Convenient method to execute without context.

Parameters:
  `paramMap` - a Map of parameter name to parameter object, matching named parameters specified in the SQL statement. Ordering is not significant.
Throws:
  `org.springframework.dao.DataAccessException`

### newRowMapper

protected abstract RowMapper<T> newRowMapper(@Nullable Object[] parameters, @Nullable 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` - 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(java.lang.Object[], java.util.Map<?, ?>)`