com.ibm.pdq.runtime.handlers
Interface RowHandlerWithParameters<ROW>
public interface RowHandlerWithParameters<ROW> extends 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
. Also provides the ability to access the method input parameter values.
This Interface is very similar to the RowHandler<ROW>
Interface.
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>
.
- For an inline method, an instance of a
RowHandlerWithParameters <ROW>
implementation can be specified by using one of the methods inData
that takes aRowHandlerWithParameters<ROW>
as a parameter. For example, two such methods areData.queryArray(String, RowHandler, Object...)
andData.queryFirst(String, RowHandler, Object...)
. - For an annotated method, a
RowHandlerWithParameters<ROW>
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(rowHandlerWithParameters=...)
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(rowHandlerWithParameters=...)
annotation. When one or more handlers are provided as parameters to an annotated method, the handlers must be the last parameters to the method.
RowHandlerWithParameters<ROW>
implementation causes its
handle(ResultSet, Object, 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
RowHandler.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);
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 |
---|---|
handle(ResultSet resultSet,ROW object,Object[] methodParameters)
Processes one row from the
ResultSet for an SQL statement and returns the contents in an object of
type ROW .
|
Methods inherited from interface com.ibm.pdq.runtime.handlers.RowHandler |
---|
handle |
Method Detail
handle
ROW handle(ResultSet resultSet, ROW object, Object[] methodParameters) throws SQLException
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. resultSet
in an
object of type ROW
.
ResultSet
for an SQL statement and returns the contents in an object of typeROW
.Attention: pureQuery calls
resultSet.next()
before callingRowHandler.handle(ResultSet resultSet, Object object)
, soresultSet.next())
must not be called inhandle(ResultSet resultSet, Object object)
.