Package org.springframework.jdbc.object

Class SqlQuery<T>

  • All Implemented Interfaces:
    InitializingBean
    Direct Known Subclasses:
    GenericSqlQuery, MappingSqlQueryWithParameters, UpdatableSqlQuery
    public abstract class SqlQuery<T>
extends SqlOperation
    Reusable operation object representing a 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

    • Constructor Detail

      • 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 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 List<T> execute​(Object[] params,
                       Map<?,​?> context)
                throws 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 - 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:
        DataAccessException

      • execute

        public List<T> execute​(Object... params)
                throws 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:
        DataAccessException

      • execute

        public List<T> execute​(int p1,
                       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 List<T> execute​(int p1,
                       int p2,
                       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 List<T> execute​(long p1,
                       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

      • executeByNamedParam

        public List<T> executeByNamedParam​(Map<String,​?> paramMap,
                                   Map<?,​?> context)
                            throws 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 - 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:
        DataAccessException

      • executeByNamedParam

        public List<T> executeByNamedParam​(Map<String,​?> paramMap)
                            throws 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:
        DataAccessException

      • findObjectByNamedParam

        public T findObjectByNamedParam​(Map<String,​?> paramMap,
                                Map<?,​?> context)
                         throws DataAccessException
        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.
        Throws:
        DataAccessException

      • newRowMapper

        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:
        execute(java.lang.Object[], java.util.Map<?, ?>)