com.ibm.pdq.runtime.handlers

Interface ResultHandler<RES>

---

public interface ResultHandler<RES>

Processes the entire query result of an SQL statement and returns the contents in an object of type RES.

For annotated and inline methods that execute SQL queries, pureQuery generally uses the return type of the method to determine how to return the query result. pureQuery provides a wide variety of formats in which a query result can be returned. When a format is required that is not one of the standard formats provided by pureQuery, an implementation of ResultHandler<RES> can be specified to create the object that represents the query result.

• For an inline method, an instance of a ResultHandler<RES> implementation can be specified by using the method Data.query(String, ResultHandler, Object...).
• For an annotated method, a ResultHandler<RES> implementation can be specified in one of two ways.
• An implementation that can be instantiated by using a public no-argument constructor can be specified by using the @Handler(resultHandler=...) annotation. In this approach, pureQuery creates a single instance of the implementation, and uses that instance every time the annotated method is invoked.
• An implementation can be specified as a parameter in an annotated method declaration. An instance of the implementation is then passed as an argument to the method at runtime. This approach should be used only when necessary because performance is slightly better when handlers are specified by using the @Handler(resultHandler=...) annotation. When one or more handlers are provided as parameters to an annotated method, the handlers must be the last parameters to the method.

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

Examples of creating ResultHandler<RES> implementations

For simple examples of how ResultHandler<RES>s can be implemented, see JSONResultHandler and XMLResultHandler.

Example of specifying a ResultHandler<RES> implementation for an inline method

The following example demonstrates the basic syntax for specifying a ResultHandler<RES> implementation for an inline method. It uses the IteratorPagingResultHandler to return rows 11 through 20 of the query result.

    Connection connection = DriverManager.getConnection (...);
    Data data = DataFactory.getData (connection);
    IteratorPagingResultHandler<EmployeeBean> handler = new IteratorPagingResultHandler<EmployeeBean> (EmployeeBean.class, 11, 20);
    DepartmentBean department = ...;
    Iterator<EmployeeBean> employees = data.query ("select * from employee where workdept = ?1.departmentNumber", handler, department);


Examples of specifying ResultHandler<RES> implementations for annotated methods

The following two examples demonstrate the basic syntax for specifying a ResultHandler<RES> implementation for an annotated method. The two examples assume that the annotated methods are declared in an interface named SampleInterfaceData. The first example uses the JSONResultHandler. Because the JSONResultHanlder is instantiated with a no-argument constructor, the handler is specified in the @Handler(resultHandler=...) annotation. The annotated method could be declared in an interface like this:

    @Select(sql = "select * from employee where workdept = ?1.departmentNumber")
    @Handler(resultHandler = JSONResultHandler.class)
    String selectEmployeesInDepartmentAsJSONString (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 = ...;
    String employees = sampleInterfaceData.selectEmployeesInDepartmentAsJSONString (department);


The next example uses the IteratorPagingResultHandler. Because the IteratorPagingResultHandler does not have a no-argument constructor, 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<EmployeeBean> selectEmployeesInDepartment (DepartmentBean department, IteratorPagingResultHandler resultHandler);


Then, after the pureQuery Generator is used to generate the implementation class for the interface, the method could be invoked to return rows 11 through 20 of the query result like this:

    Connection connection = DriverManager.getConnection (...);
    SampleInterfaceData sampleInterfaceData = DataFactory.getData (SampleInterfaceData.class, connection);
    IteratorPagingResultHandler<EmployeeBean> handler = new IteratorPagingResultHandler<EmployeeBean> (EmployeeBean.class, 11, 20);
    DepartmentBean department = ...;
    Iterator<EmployeeBean> employees = sampleInterfaceData.selectEmployeesInDepartment (department, handler);


---

Method Summary

Modifier and Type	Method and Description
RES	handle(ResultSet resultSet) Processes an entire ResultSetfor an SQL statement and returns the contents in an object of type RES.

Method Detail

handle

RES handle(ResultSet resultSet)