Module org.seasar.doma.core
Package org.seasar.doma.jdbc.command

Class SelectCommand<RESULT>

java.lang.Object
org.seasar.doma.jdbc.command.SelectCommand<RESULT>
Type Parameters:
RESULT - the type of result returned by this command
All Implemented Interfaces:
Command<RESULT>
public class SelectCommand<RESULT> extends Object implements Command<RESULT>
A command that executes SELECT SQL queries and processes the result sets.

This class handles the execution of database queries that retrieve data, including connection management, statement preparation, parameter binding, and result set processing. It uses a ResultSetHandler to convert the JDBC result set into the desired return type.

The command supports both eager and lazy fetching of results, with proper resource management for each approach. When using lazy fetching with streams, resources are automatically closed when the stream is closed.

  • Field Details

    • query

      protected final SelectQuery query
      The query object that contains the SELECT SQL statement and related configuration. This member is initialized in the constructor and remains unchanged throughout the command's lifecycle.

    • sql

      protected final PreparedSql sql
      The prepared SQL statement that will be executed. This is extracted from the query object and contains both the SQL string and its parameters.

    • resultSetHandler

      protected final ResultSetHandler<RESULT> resultSetHandler
      The handler responsible for processing the result set returned by the query execution. It converts the JDBC ResultSet into the desired return type specified by the RESULT generic parameter.

  • Constructor Details

    • SelectCommand

      public SelectCommand(SelectQuery query, ResultSetHandler<RESULT> resultSetHandler)
      Constructs a new SelectCommand with the specified query and result set handler.
      Parameters:
      query - the query to execute, which contains the SQL statement and configuration
      resultSetHandler - the handler that processes the result set and converts it to the desired type

  • Method Details

    • getQuery

      public SelectQuery getQuery()
      Returns the query object associated with this command.
      Specified by:
      getQuery in interface Command<RESULT>
      Returns:
      the select query object

    • execute

      public RESULT execute()
      Executes the SELECT SQL query and processes the result set.

      This method handles the entire lifecycle of a database query:

      1. Obtaining a database connection
      2. Preparing the SQL statement
      3. Setting up statement options (fetch size, max rows, timeout)
      4. Binding parameters to the statement
      5. Executing the query
      6. Processing the result set
      7. Properly closing all resources

      For lazy fetching with streams, resources are automatically closed when the stream is closed. Statistics are recorded if enabled in the configuration.

      Specified by:
      execute in interface Command<RESULT>
      Returns:
      the result of the query execution, as processed by the result set handler
      Throws:
      SqlExecutionException - if a database access error occurs

    • log

      protected void log()
      Logs the SQL statement that will be executed.

      This method uses the JDBC logger configured in the query to log the SQL statement along with the class name and method name that initiated the query.

    • setupOptions

      protected void setupOptions(PreparedStatement preparedStatement) throws SQLException
      Sets up the options for the prepared statement based on the query configuration.

      This method configures the following options if they are specified in the query:

      • Fetch size - controls how many rows are fetched from the database at once
      • Max rows - limits the maximum number of rows that can be returned
      • Query timeout - sets the maximum time in seconds that a query can execute
      Parameters:
      preparedStatement - the prepared statement to configure
      Throws:
      SQLException - if a database access error occurs

    • bindParameters

      protected void bindParameters(PreparedStatement preparedStatement) throws SQLException
      Binds the SQL parameters to the prepared statement.

      This method uses a PreparedSqlParameterBinder to set the parameter values in the prepared statement according to their types and positions.

      Parameters:
      preparedStatement - the prepared statement to bind parameters to
      Throws:
      SQLException - if a database access error occurs or if a parameter value is incompatible with the designated SQL type

    • executeQuery

      protected Supplier<RESULT> executeQuery(PreparedStatement preparedStatement) throws SQLException
      Executes the SQL query and processes the result set.

      This method executes the prepared statement and obtains a result set. It then delegates the processing of the result set to the handleResultSet(ResultSet) method. The result set is properly closed when the returned supplier is consumed, or immediately if eager fetching is used.

      Parameters:
      preparedStatement - the prepared statement to execute
      Returns:
      a supplier that provides the processed result
      Throws:
      SQLException - if a database access error occurs during query execution

    • handleResultSet

      protected Supplier<RESULT> handleResultSet(ResultSet resultSet) throws SQLException
      Processes the result set using the configured result set handler.

      This method delegates the processing of the result set to the result set handler that was provided in the constructor. It also checks if the result set is empty when a result is required, and throws a NoResultException in that case.

      Parameters:
      resultSet - the result set to process
      Returns:
      a supplier that provides the processed result
      Throws:
      SQLException - if a database access error occurs during result set processing
      NoResultException - if no result is found and a result is required by the query

    • close

      @Deprecated(forRemoval=true) protected void close(Supplier<RESULT> supplier, Runnable closeHandler)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use defer(Supplier, Runnable) instead.

    • defer

      protected Supplier<RESULT> defer(Supplier<RESULT> supplier, Runnable runnable)
      Defers the execution of a runnable until the result is consumed.

      This method is used for resource management. When lazy fetching is enabled and the result is a Stream, the runnable (typically a resource cleanup operation) is registered as an onClose handler for the stream, ensuring that resources are properly closed when the stream is closed. For non-stream results or eager fetching, the runnable is executed immediately.

      Parameters:
      supplier - the supplier of the result
      runnable - the operation to defer or execute immediately
      Returns:
      the original supplier or a new supplier that wraps the result with the deferred operation