1.1

Chapter 27
Using the Custom Result Processor API
Data-aware procedures use a separate result processor to merge the procedure results from multiple SQLFire members.
You can use the default SQLFire result processor when basic concatenation of the results are required.
Default Result Processor on page 156 describes how the default processor works.
For more complex use cases, such as sorting, merging, or joining the results from different servers, you must implement
your own result processor to customize the merge behavior. A custom processor can be used to modify a procedure's
OUT parameters and result sets before emitting the results to a client.
The sections that follow describe how to use the SQLFire result processor API to implement your own custom result
processor. Sample code is provided for a result processor that performs comparison-based sorting (merge sort) of
data-aware procedure results.
Implementing the ProcedureResultProcessor Interface
A custom result processor must implement the SQLFire ProcedureResultProcessor interface. SQLFire calls the
processor implementation after a client invokes a procedure using the WITH RESULT PROCESSOR clause
and begins retrieving results.
The basic result processor API operates in the following manner:
1. SQLFire calls the init() method of the implementation to provide the ProcedureProcessorContext object. The
ProcedureProcessorContext provides important details about the procedure implementation and the procedure
call that is returning results to the client. ProcedureProcessorContext describes the methods that you can use
to obtain context information and obtain nested JDBC connections.
2. Your implementation uses the ProcedureProcessorContext object to obtain the OUT parameters and result
sets that the procedure is returning to the client, so that it can process the results as necessary. OUT parameters
and result sets are obtained using the getIncomingOutParameters() and getIncomingResultSets() methods,
respectively. Both of these methods returns an IncomingResultSet, which you can use to obtain metadata
about the result set itself and inspect individual rows of the result set.
3. SQLFire calls the getNextResultRow() and getOutParameters() methods in your implementation to provide
modified results to the client. The getNextResultRow() method of your implementation is called each time
the next row of a particular result set must be returned to the client. The getOutParameters() should return
all of the procedure's OUT parameters to the client.
4. SQLFire calls your implementation's close() method when the associated statement is closed and the output
processor is no longer required. Free resources and perform any final cleanup in this method.
Procedure Result Processor Interfaces on page 452 provides a complete reference to the methods defined in
ProcedureResultProcessor, ProcedureProcessorContext, and IncomingResultSet.
Example Result Processor: MergeSort
This example result processor implementation uses a merge sort algorithm to return sorted results to a client.
163