com.ibm.pdq.runtime.handlers

Interface RowHandler<ROW>

All known subinterfaces:
RowHandlerWithParameters<ROW>

public interface RowHandler<ROW>
Processes one row from the query result of an SQL statement and returns the contents of that row in an object of type ROW.

For annotated and inline methods that execute SQL queries, pureQuery generally uses the return type of the method to determine how to return each row of the query result. pureQuery provides a wide variety of formats in which a row can be returned. When a format is required that is not one of the standard formats provided by pureQuery, an implementation of RowHandler<ROW> or RowHandlerWithParameters<ROW> can be specified to create the object that represents each row of the query result. In some cases, your handler class might need to reference the input parameters for the method in order to create the output object correctly. In that case, use an implementation of RowHandlerWithParameters<ROW>.

Specifying a RowHandler<ROW> implementation causes its handle(ResultSet, Object) method to be used to process each row of the results of the SQL execution and to create the object that describes the row. The created object is returned from the associated annotated or inline method.

For an annotated method that executes an INSERT, UPDATE, or MERGE SQL statement, if the first method parameter is a pureQuery bean that has properties that represent generated keys, pureQuery sets these properties with the generated values whenever it determines that the database can safely return generated keys for the specified SQL statement and the JDBC driver supports returning generated keys for the statement. A property of a pureQuery bean represents a generated key if it has the @GeneratedKey annotation. If a RowHandler<ROW> implementation is specified for such an annotated method, pureQuery does not directly update the first parameter of the annotated method. Instead, pureQuery passes the parameter to the handle method as the parameter object. The handle method can then update object to contain the values that were generated.

Attention: pureQuery calls resultSet.next() before calling handle(ResultSet resultSet, Object object), so resultSet.next()) must not be called in handle(ResultSet resultSet, Object object).

Example of creating a RowHandler<ROW> implementation

The following example demonstrates the basic syntax for creating a very simple RowHandler<ROW> implementation. Notice that this class has two constructors: one that takes no arguments and one that takes one argument. SimpleStringRowHandler represents each row as a String that lists the contents of the columns, and that separates the columns from each other with delimiter.

    public class SimpleStringRowHandler implements RowHandler<String> {
      private final String delimiter;
      public SimpleStringRowHandler () {
        delimiter = ", ";
      }
      public SimpleStringRowHandler (String delimiter) {
        this.delimiter = delimiter;
      }

      public String handle (ResultSet resultSet, String object) throws SQLException {
        int columnCount = resultSet.getMetaData().getColumnCount();
        StringBuffer myBuffer = new StringBuffer();
        if (columnCount > 0) {
          myBuffer.append(resultSet.getString(1));
          for (int ii=2; ii <= columnCount; ii++) {
            myBuffer.append(delimiter);
            myBuffer.append(resultSet.getString(ii));
          }
        }
        return myBuffer.toString();
      }
    }

Example of specifying a RowHandler<ROW> implementation for an inline method

The following example demonstrates the basic syntax for specifying the created RowHandler<ROW> implementation for an inline method.

    Connection connection = DriverManager.getConnection (...);
    Data data = DataFactory.getData (connection);
    SimpleStringRowHandler handler = new SimpleStringRowHandler ("\t");
    DepartmentBean department = ...;
    List<String> employees = data.queryList ("select * from employee where workdept = ?1.departmentNumber", handler, department);

Examples of specifying a RowHandler<ROW> implementation for annotated methods

The following two examples demonstrate the basic syntax for specifying the created RowHandler<ROW> implementation for an annotated method. The two examples assume that the annotated methods are declared in an interface named SampleInterfaceData. In the first example, the comma delimiter used by the no-argument constructor is needed. Since the handler is instantiated with a no-argument constructor, the handler is specified in the @Handler(rowHandler=...) annotation. The annotated method could be declared in an interface like this:

    @Select(sql = "select * from employee where workdept = ?1.departmentNumber")
    @Handler(rowHandler = SimpleStringRowHandler.class)
    public Iterator<String> selectEmployeesInDepartment (DepartmentBean department);

Then, after the pureQuery Generator is used to generate the implementation class for the interface, the method could be invoked like this:

    Connection connection = DriverManager.getConnection (...);
    SampleInterfaceData sampleInterfaceData = DataFactory.getData (SampleInterfaceData.class, connection);
    DepartmentBean department = ...;
    Iterator<String> employees = sampleInterfaceData.selectEmployeesInDepartment (department);

In the next example, a tab delimiter is needed, so the implementation must be instantiated with a constructor that takes an argument. As a result, the handler is specified as a parameter to the annotated method. The annotated method could be declared in an interface like this:

    @Select(sql = "SELECT * FROM employee where workdept = ?1.departmentNumber")
    Iterator<String> selectEmployeesInDepartment (DepartmentBean department, SimpleStringRowHandler rowHandler);

Then, after the pureQuery Generator is used to generate the implementation class for the interface, the method could be invoked with an instance of SimpleStringRowHandler that uses a tab delimiter, like this:

    Connection connection = DriverManager.getConnection (...);
    SampleInterfaceData sampleInterfaceData = DataFactory.getData (SampleInterfaceData.class, connection);
    SimpleStringRowHandler handler = new SimpleStringRowHandler ("\t");
    DepartmentBean department = ...;
    Iterator<String> employees = sampleInterfaceData.selectEmployeesInDepartment (department, handler);

See Also:
Handler.rowHandler(), Data.queryArray(String, Class, RowHandler, Object...), Data.queryFirst(String, RowHandler, Object...), Data.queryIterator(String, RowHandler, Object...), Data.queryList(String, RowHandler, Object...)

Method Summary

Modifier and Type Method and Description
  1. ROW
handle(ResultSet resultSet,ROW object)
Processes one row from the ResultSetfor an SQL statement and returns the contents in an object of type ROW.

Method Detail

handle

ROW handle(ResultSet resultSet,
          ROW object)
           throws SQLException
Processes one row from the ResultSet for an SQL statement and returns the contents in an object of type ROW.

Attention: pureQuery calls resultSet.next() before calling handle(ResultSet resultSet, Object object), so resultSet.next()) must not be called in handle(ResultSet resultSet, Object object).

Parameters:
resultSet - a ResultSet that represents the results from an SQL statement. Only the row currently pointed to by the ResultSet cursor should be processed.
object - either null or a pureQuery bean that contains one or more properties that represent generated keys. For an annotated method that executes either an INSERT, UPDATE, or MERGE SQL statement, if the first method parameter is a pureQuery bean that has properties that represent generated keys, and if a RowHandler<ROW> implementation is specified for the annotated method, pureQuery passes the parameter to the handle method as the parameter object whenever it determines that the database can safely return generated keys for the specified SQL statement and the JDBC driver supports returning generated keys for the statement. The handle method can then use resultSet to update object to contain the values that were generated.
Returns:
the contents (as much as is wanted) of the row pointed to by the cursor of resultSet in an object of type ROW.
Throws: