com.ibm.pdq.runtime
Interface Data


public interface Data

Provides methods that can be used to access data sources, which can be databases or in-memory collections.

In both the inline programming style and the annotated-method programming style, the DataFactory must be used to obtain instances of Data. With the pureQuery inline methods, developers use the methods in the Data interface directly. In the annotated-method programming style, developers create interfaces that contain pureQuery annotated methods, and use the pureQuery Generator to generate an implementation class for these interfaces. The DataFactory can then be used to create instances of the interfaces. Each created instance also implements Data, although users do not need to access the methods in the Data interface directly. See the IBM Optim pureQuery Runtime documentation for more details about the use of the Data interface in pureQuery.

The methods that are provided in this interface include:


Method Summary

Method Summary
Return Data TypeMethod Name and Description
<CAL> CAL
call(String sql, CallHandler<CAL> callHandler, Object... parameters)
Runs the given SQL stored procedure call sql and returns an object of type <CAL> that indicates the results of the stored procedure call.
<CAL> CAL
call(String sql, CallHandlerWithParameters<CAL> callHandlerWithParameters, Object... parameters)
Runs the given SQL stored procedure call sql and returns an object of type <CAL> that indicates the results of the stored procedure call.
StoredProcedureResult call(String sql, Object... parameters)
Runs the given SQL stored procedure call sql and returns an instance of StoredProcedureResult that represents the results of running sql.
<CAL> CAL
call(String sql, ParameterHandler parameterHandler, CallHandlerWithParameters<CAL> callHandlerWithParameters, Object... parameters)
Runs the given SQL stored procedure call sql and returns an object of type <CAL> that indicates the results of the stored procedure call.
void close()
Frees all resources and closes the associated instance of Connection by calling Connection.close() for that instance.
void commit()
Delegates a commit request (Connection.commit()) to the associated instance of Connection.
int[][] endBatch()
Runs the INSERT, UPDATE, and DELETE SQL statements that are queued for a heterogeneous update with parameters and returns an int[][] that describes the results of the execution.
boolean getAutoCommit()
Returns a boolean that indicates whether auto-commit mode is enabled for the associated instance of Connection.
HeterogeneousBatchKind getBatchKind()
Returns a value of HeterogeneousBatchKind, which indicates that SQL statements are being run immediately, or that a batch for a heterogeneous update with parameters is being created.
Connection getConnection()
Returns the Connection object that is associated with the instance of Data, if such an object exists.
com.ibm.pdq.runtime.internal.trace.DataLogger getLogger()
Returns the instance of DataLogger to use for all of the logging that occurs in association with the instance of Data.
<RES> RES
query(int type, int concurrency, int holdability, String sql, ParameterHandler parameterHandler, ResultHandler<RES> resultHandler, Object... parameters)
Runs the given SQL statement sql and returns an Object of type <RES> that indicates the results of the statement.
<RES> RES
query(int type, int concurrency, int holdability, String sql, ResultHandler<RES> resultHandler, Object... parameters)
Runs the given SQL statement sql and returns an Object of type <RES> that indicates the results of the statement.
<RES> RES
query(String sql, ResultHandler<RES> handler, Object... parameters)
Runs the given SQL statement sql and returns an Object of type <RES> that indicates the query results of the statement.
<ROW> ROW[]
queryArray(String sql, Class<ROW> returnClass, Object... parameters)
Runs the given SQL statement sql and returns an array such that each element in the array contains the contents of a row of the query results in a pureQuery bean that is an instance of the class <ROW>.
<ROW> ROW[]
queryArray(String sql, Class<ROW> returnClass, RowHandler<ROW> rowHandler, Object... parameters)
Runs the given SQL statement sql and returns an array such that each element in the array contains the contents of a row of the query results in an instance of the class <ROW>.
Map<String,Object>[] queryArray(String sql, Object... parameters)
Runs the given SQL statement sql and returns an array such that each element in the array contains the contents of a row of the query results in a Map.
<ROW> ROW
queryFirst(String sql, Class<ROW> returnClass, Object... parameters)
Runs the given SQL statement sql and returns the contents of the first row of the query results in a pureQuery bean that is an instance of the class <ROW>.
Map<String,Object> queryFirst(String sql, Object... parameters)
Runs the given SQL statement sql and returns a Map that represents the first row of the results that is returned from running the sql statement.
<ROW> ROW
queryFirst(String sql, RowHandler<ROW> rowHandler, Object... parameters)
Runs the given SQL statement sql and returns the contents of the first row of the query results in an instance of the class <ROW>.
<ROW> Iterator<ROW>
queryIterator(int type, int concurrency, int holdability, String sql, Class<ROW> returnClass, Object... parameters)
Runs the given SQL statement sql and returns an Iterator instance such that each call to the Iterator.next() method of the Iterator instance provides the contents of a row of the query results in a pureQuery bean that is an instance of the class <ROW>.
Iterator<Map<String,Object>> queryIterator(int type, int concurrency, int holdability, String sql, Object... parameters)
Runs the given SQL statement sql and returns an Iterator instance such that each call to the Iterator.next() method of the instance provides the contents of a row of the query results in a Map.
<ROW> Iterator<ROW>
queryIterator(int type, int concurrency, int holdability, String sql, RowHandler<ROW> rowHandler, Object... parameters)
Runs the given SQL statement sql and returns an Iterator instance such that each call to the Iterator.next() method of the Iterator instance provides the contents of a row of the query results in an instance of the class <ROW>.
<ROW> Iterator<ROW>
queryIterator(String sql, Class<ROW> returnClass, Object... parameters)
Runs the given SQL statement sql and returns an Iterator instance such that each call to the Iterator.next() method of the Iterator instance provides the contents of a row of the query results in a pureQuery bean that is an instance of the class <ROW>.
Iterator<Map<String,Object>> queryIterator(String sql, Object... parameters)
Runs the given SQL statement sql and returns an Iterator instance such that each call to the Iterator.next() method of the instance provides the contents of a row of the query results in a Map.
<ROW> Iterator<ROW>
queryIterator(String sql, RowHandler<ROW> rowHandler, Object... parameters)
Runs the given SQL statement sql and returns an Iterator instance such that each call to the Iterator.next() method of the Iterator instance provides the contents of a row of the query results in an instance of the class <ROW>.
<ROW> List<ROW>
queryList(String sql, Class<ROW> returnClass, Object... parameters)
Runs the given SQL statement sql and returns a List instance such that each element in the List instance contains the contents of a row of the query results in a pureQuery bean that is an instance of the class <ROW>.
List<Map<String,Object>> queryList(String sql, Object... parameters)
Runs the given SQL statement sql and returns a List instance such that each element in the List instance contains the contents of a row of the query results in a Map.
<ROW> List<ROW>
queryList(String sql, RowHandler<ROW> rowHandler, Object... parameters)
Runs the given SQL statement sql and returns a List instance such that each element in the List instance contains the contents of a row of the query results in an instance of the class <ROW>.
ResultSet queryResults(int type, int concurrency, int holdability, String sql, Object... parameters)
Runs the given SQL statement sql and returns the contents of the query results in an instance of ResultSet.
ResultSet queryResults(String sql, Object... parameters)
Runs the given SQL statement sql and returns the contents of the query results in an instance of ResultSet.
void rollback()
Delegates a rollback request Connection.rollback() to the associated instance of Connection.
void setAutoCommit(boolean autoCommit)
Sets whether auto-commit mode is enabled for the associated instance of Connection by calling Connection.setAutoCommit(boolean) for the Connection instance.
void startBatch(HeterogeneousBatchKind batchKind)
Starts a batch for a heterogeneous update with parameters.
<ROW> ROW
update(String sql, Class<ROW> returnClass, String[] columnNames, Object... parameters)
Runs the given SQL statement sql, retrieves the new values of a set of columns, and returns an object of type returnClass that describes the results.
int update(String sql, Object... parameters)
Runs the given SQL statement sql and returns an int that indicates how many rows in the data source are updated.
int[] updateMany(String... heterogeneousBatchSQL)
Runs the multiple SQL strings given in one round trip to the server (or in a batch, if the JDBC driver supports round trip processing).
<T> int[]
updateMany(String sql, Iterable<T> parameters)
Runs the given SQL statement sql once for each element in parameters and returns an int[] in which each element in the int[] indicates the update count (that is, the number of rows that were updated) for the corresponding execution of sql.
<T> int[]
updateMany(String sql, Iterator<T> parameters)
Runs the given SQL statement sql once for each element in parameters and returns an int[] in which each element in the int[] indicates the update count (that is, the number of rows that were updated) for the corresponding execution of the sql statement.
<T> int[]
updateMany(String sql, T[] parameters)
Runs the given SQL statement sql once for each element in parameters and returns an int[] in which each element in the int[] indicates the update count (that is, the number of rows that were updated) for the corresponding execution of sql.

Method Detail

call

<CAL> CAL call(String sql,
               CallHandler<CAL> callHandler,
               Object... parameters)
Runs the given SQL stored procedure call sql and returns an object of type <CAL> that indicates the results of the stored procedure call. The actual processing of the results of the stored procedure call is done by the callHandler, and the object that is returned is the object that is returned by callHandler.handleCall(CallableStatement)

Attention: It is recommended that call(String, CallHandlerWithParameters, Object...) be used instead of this method (call(String, CallHandler, Object...)).

The generic return type <CAL> is indicated by the type of the CallHandler<CAL>, and it can be any of the following types:

Type Parameters:
CAL - the generic type of the object to return. <CAL> is indicated by the generic type of callHandler.
Parameters:
sql - the SQL string to run
callHandler - an instance of an implementation of the CallHandler
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers. The parameters are not passed to the callHandler, and the values of the OUT and INOUT parameters are not updated. If the values of the OUT and INOUT parameters should be updated, call(String, CallHandlerWithParameters, Object...) must be used instead of this method.
Returns:
the output of the CallHandler
See Also:
call(String, CallHandlerWithParameters, Object...), CallHandler

call

<CAL> CAL call(String sql,
               CallHandlerWithParameters<CAL> callHandlerWithParameters,
               Object... parameters)
Runs the given SQL stored procedure call sql and returns an object of type <CAL> that indicates the results of the stored procedure call. The actual processing of the results of the stored procedure call is done by the callHandlerWithParameters, and the object that is returned is the object that is returned by callHandlerWithParameters.handleCall(CallableStatement, Object...)

The generic return type <CAL> is indicated by the type of the CallHandlerWithParameters<CAL>, and it can be any of the following types:

Type Parameters:
CAL - the generic type of the object to return. <CAL> is indicated by the generic type of callHandlerWithParameters.
Parameters:
sql - the SQL string to run
callHandlerWithParameters - an instance of an implementation of the class CallHandlerWithParameters
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers. The parameters are also passed as parameters to handleCall(CallableStatement, Object...). The parameters can include IN, OUT, and INOUT parameters. pureQuery updates the values of the OUT and INOUT parameters if callHandlerWithParameters updates the values. Updateable parameters must be mutable; for example, they cannot be String or Integer objects.
Returns:
the output of the CallHandlerWithParameters
See Also:
CallHandlerWithParameters

call

StoredProcedureResult call(String sql,
                           Object... parameters)
Runs the given SQL stored procedure call sql and returns an instance of StoredProcedureResult that represents the results of running sql. The returned StoredProcedureResult instance contains the returned query results and an Object[] that contains the user's parameters.

parameters contains the parameters for the SQL stored procedure call. Certain passed-in parameters are updated with the values that are assigned to the corresponding SQL parameters during the execution of the call. To be updated, a passed-in parameter must meet both of the following conditions:

However, the updated values of all the OUT and INOUT parameters of the called stored procedure can be obtained by calling StoredProcedureResult.getOutputParms().

Parameters:
sql - the SQL string to execute
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers. The parameters can include IN, OUT, and INOUT parameters. The values of the OUT and INOUT parameters that are Maps and pureQuery beans are updated with the values that are set during the called stored procedure. The updated values of all of the OUT and INOUT parameters to the stored procedure call can be obtained by calling StoredProcedureResult.getOutputParms().
Returns:
an instance of StoredProcedureResult that represents the results of running sql
See Also:
StoredProcedureResult

call

<CAL> CAL call(String sql,
               ParameterHandler parameterHandler,
               CallHandlerWithParameters<CAL> callHandlerWithParameters,
               Object... parameters)
Runs the given SQL stored procedure call sql and returns an object of type <CAL> that indicates the results of the stored procedure call. The actual processing of the results of the stored procedure call is done by the callHandlerWithParameters, and the object that is returned is the object that is returned by callHandlerWithParameters.handleCall(CallableStatement, Object...)

The generic return type <CAL> is indicated by the type of the CallHandlerWithParameters<CAL>, and it can be any of the following types:

Type Parameters:
CAL - the generic type of the object to return. <CAL> is indicated by the generic type of callHandlerWithParameters.
Parameters:
sql - the SQL string to execute
parameterHandler - an instance of an implementation of ParameterHandler. The method parameterHandler.handleParameters(PreparedStatement stmt, Object... parameters) is invoked by pureQuery to process the parameters of sql. The method must set the values of the parameters in the CallableStatement stmt that the method runs. This method must also register any OUT and INOUT parameters.
callHandlerWithParameters - an instance of an implementation of the class CallHandlerWithParameters
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers. The parameters are also passed as parameters to handleCall(CallableStatement, Object...). The parameters can include IN, OUT, and INOUT parameters. pureQuery updates the values of the OUT and INOUT parameters if callHandlerWithParameters updates the values. Updateable parameters must be mutable; for example, they cannot be String or Integer objects.
Returns:
the output of the CallHandlerWithParameters
See Also:
CallHandlerWithParameters

close

void close()
Frees all resources and closes the associated instance of Connection by calling Connection.close() for that instance.
See Also:
Connection.close()

commit

void commit()
Delegates a commit request (Connection.commit()) to the associated instance of Connection.
See Also:
Connection, Connection.commit()

endBatch

int[][] endBatch()
Runs the INSERT, UPDATE, and DELETE SQL statements that are queued for a heterogeneous update with parameters and returns an int[][] that describes the results of the execution. After this method is called, the database connection resumes running SQL statements immediately, instead of queueing them in a batch.

pureQuery performs heterogeneous updates with parameters by queueing INSERT, UPDATE, and DELETE SQL statements in memory for a particular instance of Data, and then running the queued statements in one network trip. The implementation classes that the pureQuery Generator creates for user-supplied interfaces of annotated methods implement the user-provided interfaces, in addition to the Data interface. See the IBM Optim pureQuery Runtime documentation for an explanation of how to perform heterogeneous batches with parameters when using the annotated-method programming style.

Calling data.startBatch (HeterogeneousBatchKind.heterogeneousModify__) starts a batch for a heterogeneous update with parameters for the instance of Data. INSERT, UPDATE, and DELETE SQL statement are then queued in the batch by calling pureQuery annotated and inline methods in the instance of Data. If an attempt is made to add SQL statements other than INSERT, UPDATE, and DELETE to the batch (by calling methods that run SQL statements that are not INSERT, UPDATE, or DELETE), an exception is thrown, the current batch is cleared, and none of the SQL statements are run. When all of the necessary SQL statements are added to the batch, the batch can be run by calling data.endBatch().

Heterogeneous updates with parameters use functionality that is unique to DB2 and the IBM Data Server Driver for JDBC and SQLJ. An exception is thrown if startBatch(HeterogeneousBatchKind) or endBatch() is called with any other database or database driver.

Returns:
an int array of arrays that describes the results of running the heterogeneous update with parameters. This is an array of the int[]s that are returned from running each SQL statement that was added to the batch. These int[]s follow the format that is used for the return value of Statement.executeBatch(), which is the format that is used by pureQuery to return the results of homogeneous batches. If an UpdateManyException is thrown, then the int[][] of updates can be retrieved by calling UpdateManyException.getHeterogeneousUpdateCounts() on the exception.
See Also:
startBatch(HeterogeneousBatchKind), getBatchKind(), UpdateManyException, HeterogeneousBatchKind

getAutoCommit

boolean getAutoCommit()
Returns a boolean that indicates whether auto-commit mode is enabled for the associated instance of Connection. If true is returned, auto-commit mode is currently enabled. If false is returned, auto-commit mode is currently disabled. The return value is found by calling Connection.getAutoCommit() for the associated instance of Connection.
Returns:
a boolean that indicates whether auto-commit mode is enabled for the associated instance of Connection. If true is returned, auto-commit mode is currently enabled. If false is returned, auto-commit mode is currently disabled. The return value is found by calling Connection.getAutoCommit() for the associated instance of Connection.
See Also:
Connection, Connection.getAutoCommit()

getBatchKind

HeterogeneousBatchKind getBatchKind()
Returns a value of HeterogeneousBatchKind, which indicates that SQL statements are being run immediately, or that a batch for a heterogeneous update with parameters is being created.
Returns:
a value of HeterogeneousBatchKind, which indicates that SQL statements are being run immediately, or that a batch for a heterogeneous update with parameters is being created.
See Also:
endBatch(), startBatch(HeterogeneousBatchKind), HeterogeneousBatchKind

getConnection

Connection getConnection()
Returns the Connection object that is associated with the instance of Data, if such an object exists. A RuntimeException is thrown if no such Connection object is associated with the instance of Data.
Returns:
the Connection object that is associated with the instance of Data, if such an object exists. A RuntimeException is thrown if no such Connection object is associated with the instance of Data.
See Also:
Connection

getLogger

com.ibm.pdq.runtime.internal.trace.DataLogger getLogger()
Returns the instance of DataLogger to use for all of the logging that occurs in association with the instance of Data.
Returns:
the instance of DataLogger to use for all of the logging that occurs in association with the instance of Data

query

<RES> RES query(int type,
                int concurrency,
                int holdability,
                String sql,
                ParameterHandler parameterHandler,
                ResultHandler<RES> resultHandler,
                Object... parameters)
Runs the given SQL statement sql and returns an Object of type <RES> that indicates the results of the statement. The actual processing of the results of the statement is done by the handler, and the Object that is returned is the Object that is returned by handler.handle(ResultSet).
Type Parameters:
RES - the generic type of the Object to return. <RES> is indicated by the generic type of handler.
Parameters:
type - the type runtime attribute for query processing. Supported values are: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_SENSITIVE, and ResultSet.TYPE_SCROLL_INSENSITIVE.
concurrency - the concurrency runtime attribute for query processing. Supported values are: ResultSet.CONCUR_READ_ONLY and ResultSet.CONCUR_UPDATABLE.
holdability - the holdability runtime attribute for query processing. Supported values are: ResultSet.CLOSE_CURSORS_AT_COMMIT and ResultSet.HOLD_CURSORS_OVER_COMMIT.
sql - the SQL string to execute
parameterHandler - an instance of an implementation of ParameterHandler. The method parameterHandler.handleParameters(PreparedStatement stmt, Object... parameters) is invoked to set the values of parameters in the PreparedStatement stmt that the method runs.
resultHandler - the ResultHandler whose handler.handle(ResultSet) method processes the results that are produced by running sql and returns some or all of the query results in an Object of type <RES>. The Object that is returned by this method (query(String, ResultHandler, Object...)) is the Object that is returned by handle(ResultSet).
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
an Object of type <RES> that contains some or all of the contents of the results that are produced by running the SQL statement sql. The returned Object is the Object that is returned by handler.handle(ResultSet).
See Also:
ResultHandler

query

<RES> RES query(int type,
                int concurrency,
                int holdability,
                String sql,
                ResultHandler<RES> resultHandler,
                Object... parameters)
Runs the given SQL statement sql and returns an Object of type <RES> that indicates the results of the statement. The actual processing of the results of the statement is done by the handler, and the Object that is returned is the Object that is returned by handler.handle(ResultSet).
Type Parameters:
RES - the generic type of the Object to return. <RES> is indicated by the generic type of handler.
Parameters:
type - the type runtime attribute for query processing. Supported values are: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_SENSITIVE, and ResultSet.TYPE_SCROLL_INSENSITIVE.
concurrency - the concurrency runtime attribute for query processing. Supported values are: ResultSet.CONCUR_READ_ONLY and ResultSet.CONCUR_UPDATABLE.
holdability - the holdability runtime attribute for query processing. Supported values are: ResultSet.CLOSE_CURSORS_AT_COMMIT and ResultSet.HOLD_CURSORS_OVER_COMMIT.
sql - the SQL string to run
resultHandler - the ResultHandler whose handler.handle(ResultSet) method processes the results that are produced by running sql and returns some or all of the query results in an Object of type <RES>. The Object that is returned by this method (query(String, ResultHandler, Object...)) is the Object that is returned by handle(ResultSet).
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
an Object of type <RES> that contains some or all of the contents of the results that are produced by running the SQL statement sql. The returned Object is the Object that is returned by handler.handle(ResultSet).
See Also:
ResultHandler

query

<RES> RES query(String sql,
                ResultHandler<RES> handler,
                Object... parameters)
Runs the given SQL statement sql and returns an Object of type <RES> that indicates the query results of the statement. The actual processing of the results of the statement is done by the handler, and the Object that is returned is the Object that is returned by handler.handle(ResultSet).
Type Parameters:
RES - the generic type of the Object to return. <RES> is indicated by the generic type of handler.
Parameters:
sql - the SQL string to run
handler - the ResultHandler whose handler.handle(ResultSet) method processes the results that are produced by the execution of sql and returns some or all of the results in an Object of type <RES>. The Object that is returned by this method (query(String, ResultHandler, Object...)) is the Object that is returned by handle(ResultSet).
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
an Object of type <RES> that contains some or all of the contents of the results that are produced by running the SQL statement sql. The returned Object is the same Object that is returned by handler.handle(ResultSet).
See Also:
ResultHandler

queryArray

<ROW> ROW[] queryArray(String sql,
                       Class<ROW> returnClass,
                       Object... parameters)
Runs the given SQL statement sql and returns an array such that each element in the array contains the contents of a row of the query results in a pureQuery bean that is an instance of the class <ROW>. See the IBM Optim pureQuery Runtime documentation for details about how pureQuery maps query results to pureQuery beans.
Type Parameters:
ROW - the generic type of the array to return. <ROW> is indicated by the generic type of returnClass.
Parameters:
sql - the SQL string to run.
returnClass - used to represent each row of the results in the returned array. This parameter indicates the type that is represented by <ROW>.
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
an array such that each element in the array contains the contents of a row of the query results in a pureQuery bean that is an instance of the class <ROW>.

queryArray

<ROW> ROW[] queryArray(String sql,
                       Class<ROW> returnClass,
                       RowHandler<ROW> rowHandler,
                       Object... parameters)
Runs the given SQL statement sql and returns an array such that each element in the array contains the contents of a row of the query results in an instance of the class <ROW>. pureQuery uses singleRowHandler (specifically singleRowHandler.handle(ResultSet, Object)) to create each object of type <ROW>.
Type Parameters:
ROW - the generic type of the array to return. <ROW> is indicated by the generic type of rowHandler.
Parameters:
sql - the SQL string to run.
returnClass - used to represent each row of the results in the returned array. This parameter indicates the type that is represented by <ROW>.
rowHandler - the RowHandler whose rowHandler.handle(ResultSet, Object) method maps the contents of each row to an Object of type <ROW>
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
an array such that each element in the array contains the contents of a row of the query results in an instance of the class <ROW>

queryArray

Map<String,Object>[] queryArray(String sql,
                                Object... parameters)
Runs the given SQL statement sql and returns an array such that each element in the array contains the contents of a row of the query results in a Map. The keys in the Map are the labels of the columns from the row, and the values in the Map are the values that are stored in the particular columns of that row.
Parameters:
sql - the SQL string to run.
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
an array such that each element in the array contains the contents of a row of the query results in a Map.

queryFirst

<ROW> ROW queryFirst(String sql,
                     Class<ROW> returnClass,
                     Object... parameters)
Runs the given SQL statement sql and returns the contents of the first row of the query results in a pureQuery bean that is an instance of the class <ROW>. See the IBM Optim pureQuery Runtime documentation for details about how pureQuery maps query results to pureQuery beans.
Type Parameters:
ROW - the generic type of the Object to return. <ROW> is indicated by the generic type of returnClass.
Parameters:
sql - the SQL string to run.
returnClass - used to represent the first row of the results. This parameter indicates the type that is represented by <ROW>.
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
the contents of the first row of the query results in a pureQuery bean that is an instance of the class <ROW>. See the IBM Optim pureQuery Runtime documentation for details about how pureQuery maps query results to pureQuery beans.

queryFirst

Map<String,Object> queryFirst(String sql,
                              Object... parameters)
Runs the given SQL statement sql and returns a Map that represents the first row of the results that is returned from running the sql statement. The keys in the Map are the labels of the columns from the row. The values in the Map are the values that are stored in the particular columns of that row.
Parameters:
sql - the SQL string to run.
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
a Map that represents the first row of the results that is returned from running the SQL statement sql. The keys in the Map are the labels of the columns from the row. The values in the Map are the values that are stored in the particular columns of that row.

queryFirst

<ROW> ROW queryFirst(String sql,
                     RowHandler<ROW> rowHandler,
                     Object... parameters)
Runs the given SQL statement sql and returns the contents of the first row of the query results in an instance of the class <ROW>. pureQuery uses singleRowHandler (specifically singleRowHandler.handle(ResultSet, Object)) to create each object of type <ROW>.
Type Parameters:
ROW - the generic type of the Object to return. <ROW> is indicated by the generic type of rowHandler.
Parameters:
sql - the SQL string to run.
rowHandler - the RowHandler whose rowHandler.handle(ResultSet, Object) method maps the contents of each row to an Object of type <ROW>.
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
the contents of the first row of the query results in an instance of the class <ROW>.

queryIterator

<ROW> Iterator<ROW> queryIterator(int type,
                                  int concurrency,
                                  int holdability,
                                  String sql,
                                  Class<ROW> returnClass,
                                  Object... parameters)
Runs the given SQL statement sql and returns an Iterator instance such that each call to the Iterator.next() method of the Iterator instance provides the contents of a row of the query results in a pureQuery bean that is an instance of the class <ROW>. See the IBM Optim pureQuery Runtime documentation for details about how pureQuery maps query results to pureQuery beans.
Type Parameters:
ROW - the generic type of the Iterator to return. <ROW> is indicated by the generic type of returnClass.
Parameters:
type - the type runtime attribute for query processing. Supported values are: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_SENSITIVE, and ResultSet.TYPE_SCROLL_INSENSITIVE.
concurrency - the concurrency runtime attribute for query processing. Supported values are: ResultSet.CONCUR_READ_ONLY and ResultSet.CONCUR_UPDATABLE.
holdability - the holdability runtime attribute for query processing. Supported values are: ResultSet.CLOSE_CURSORS_AT_COMMIT and ResultSet.HOLD_CURSORS_OVER_COMMIT.
sql - the SQL string to run.
returnClass - used to represent each row of the results in the returned instance of Iterator. This parameter indicates the type that is represented by <ROW>.
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
an Iterator instance such that each call to the Iterator.next() method of the Iterator instance provides the contents of a row of the query results in a pureQuery bean that is an instance of the class <ROW>.

queryIterator

Iterator<Map<String,Object>> queryIterator(int type,
                                           int concurrency,
                                           int holdability,
                                           String sql,
                                           Object... parameters)
Runs the given SQL statement sql and returns an Iterator instance such that each call to the Iterator.next() method of the instance provides the contents of a row of the query results in a Map. The keys in the Map are the labels of the columns from the row. The values in the Map are the values that are stored in the particular columns of that row.
Parameters:
type - the type runtime attribute for query processing. Supported values are: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_SENSITIVE, and ResultSet.TYPE_SCROLL_INSENSITIVE.
concurrency - the concurrency runtime attribute for query processing. Supported values are: ResultSet.CONCUR_READ_ONLY and ResultSet.CONCUR_UPDATABLE.
holdability - the holdability runtime attribute for query processing. Supported values are: ResultSet.CLOSE_CURSORS_AT_COMMIT and ResultSet.HOLD_CURSORS_OVER_COMMIT.
sql - the SQL string to run.
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
an Iterator instance such that each call to the Iterator.next() method of the instance provides the contents of a row of the query results in a Map.

queryIterator

<ROW> Iterator<ROW> queryIterator(int type,
                                  int concurrency,
                                  int holdability,
                                  String sql,
                                  RowHandler<ROW> rowHandler,
                                  Object... parameters)
Runs the given SQL statement sql and returns an Iterator instance such that each call to the Iterator.next() method of the Iterator instance provides the contents of a row of the query results in an instance of the class <ROW>. pureQuery uses singleRowHandler (specifically singleRowHandler.handle(ResultSet, Object)) to create each object of type <ROW>.
Type Parameters:
ROW - the generic type of the Iterator to return. <ROW> is indicated by the generic type of rowHandler.
Parameters:
type - the type runtime attribute for query processing. Supported values are: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_SENSITIVE, and ResultSet.TYPE_SCROLL_INSENSITIVE.
concurrency - the concurrency runtime attribute for query processing. Supported values are: ResultSet.CONCUR_READ_ONLY and ResultSet.CONCUR_UPDATABLE.
holdability - the holdability runtime attribute for query processing. Supported values are: ResultSet.CLOSE_CURSORS_AT_COMMIT and ResultSet.HOLD_CURSORS_OVER_COMMIT.
sql - the SQL string to run.
rowHandler - the RowHandler whose rowHandler.handle(ResultSet, Object) method maps the contents of each row to an Object of type <ROW>.
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
an Iterator instance such that each call to the Iterator.next() method of the Iterator instance provides the contents of a row of the query results in an instance of the class <ROW>.

queryIterator

<ROW> Iterator<ROW> queryIterator(String sql,
                                  Class<ROW> returnClass,
                                  Object... parameters)
Runs the given SQL statement sql and returns an Iterator instance such that each call to the Iterator.next() method of the Iterator instance provides the contents of a row of the query results in a pureQuery bean that is an instance of the class <ROW>. See the IBM Optim pureQuery Runtime documentation for details about how pureQuery maps query results to pureQuery beans.
Type Parameters:
ROW - the generic type of the Iterator to return. <ROW> is indicated by the generic type of returnClass.
Parameters:
sql - the SQL string to run.
returnClass - used to represent each row of the results in the returned instance of Iterator. This parameter indicates the type that is represented by <ROW>.
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
an Iterator instance such that each call to the Iterator.next() method of the Iterator instance provides the contents of a row of the query results in a pureQuery bean that is an instance of the class <ROW>.

queryIterator

Iterator<Map<String,Object>> queryIterator(String sql,
                                           Object... parameters)
Runs the given SQL statement sql and returns an Iterator instance such that each call to the Iterator.next() method of the instance provides the contents of a row of the query results in a Map. The keys in the Map are the labels of the columns from the row. The values in the Map are the values that are stored in the particular columns of that row.
Parameters:
sql - the SQL string to execute
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
an Iterator instance such that each call to the Iterator.next() method of the instance provides the contents of a row of the query results in a Map.

queryIterator

<ROW> Iterator<ROW> queryIterator(String sql,
                                  RowHandler<ROW> rowHandler,
                                  Object... parameters)
Runs the given SQL statement sql and returns an Iterator instance such that each call to the Iterator.next() method of the Iterator instance provides the contents of a row of the query results in an instance of the class <ROW>. pureQuery uses singleRowHandler (specifically singleRowHandler.handle(ResultSet, Object)) to create each object of type <ROW>.
Type Parameters:
ROW - the generic type of the Iterator to return. <ROW> is indicated by the generic type of rowHandler.
Parameters:
sql - the SQL string to run.
rowHandler - the RowHandler whose rowHandler.handle(ResultSet, Object) method maps the contents of each row to an Object of type <ROW>.
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
an Iterator instance such that each call to the Iterator.next() method of the Iterator instance provides the contents of a row of the query results in a an instance of the class <ROW>.

queryList

<ROW> List<ROW> queryList(String sql,
                          Class<ROW> returnClass,
                          Object... parameters)
Runs the given SQL statement sql and returns a List instance such that each element in the List instance contains the contents of a row of the query results in a pureQuery bean that is an instance of the class <ROW>. See the IBM Optim pureQuery Runtime documentation for details about how pureQuery maps query results to pureQuery beans.
Type Parameters:
ROW - the generic type of the List to return. <ROW> is indicated by the generic type of returnClass.
Parameters:
sql - the SQL string to run.
returnClass - used to represent each row of the results in the returned instance of List. This parameter indicates the type that is represented by <ROW>.
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
a List instance such that each element in the List instance contains the contents of a row of the query results in a pureQuery bean that is an instance of the class <ROW>.

queryList

List<Map<String,Object>> queryList(String sql,
                                   Object... parameters)
Runs the given SQL statement sql and returns a List instance such that each element in the List instance contains the contents of a row of the query results in a Map. The keys in the Map are the labels of the columns from the row, and the values in the Map are the values that are stored in the particular columns of that row.
Parameters:
sql - the SQL string to run.
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
a List instance such that each element in the List instance contains the contents of a row of the query results in a Map.

queryList

<ROW> List<ROW> queryList(String sql,
                          RowHandler<ROW> rowHandler,
                          Object... parameters)
Runs the given SQL statement sql and returns a List instance such that each element in the List instance contains the contents of a row of the query results in an instance of the class <ROW>. pureQuery uses singleRowHandler (specifically singleRowHandler.handle(ResultSet, Object)) to create each object of type <ROW>.
Type Parameters:
ROW - the generic type of the List to return. <ROW> is indicated by the generic type of rowHandler.
Parameters:
sql - the SQL string to run.
rowHandler - the RowHandler whose rowHandler.handle(ResultSet, Object) method maps the contents of each row to an Object of type <ROW>.
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
a List instance such that each element in the List instance contains the contents of a row of the query results in an instance of the class <ROW>.

queryResults

ResultSet queryResults(int type,
                       int concurrency,
                       int holdability,
                       String sql,
                       Object... parameters)
Runs the given SQL statement sql and returns the contents of the query results in an instance of ResultSet. The returned ResultSet is read-only.
Parameters:
type - the type runtime attribute for query processing. Supported values are: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_SENSITIVE, and ResultSet.TYPE_SCROLL_INSENSITIVE.
concurrency - the concurrency runtime attribute for query processing. Supported values are: ResultSet.CONCUR_READ_ONLY and ResultSet.CONCUR_UPDATABLE.
holdability - the holdability runtime attribute for query processing. Supported values are: ResultSet.CLOSE_CURSORS_AT_COMMIT and ResultSet.HOLD_CURSORS_OVER_COMMIT.
sql - the SQL string to run.
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
the contents of the query results in an instance of ResultSet. The returned ResultSet is read-only.

queryResults

ResultSet queryResults(String sql,
                       Object... parameters)
Runs the given SQL statement sql and returns the contents of the query results in an instance of ResultSet. The returned ResultSet is read-only.
Parameters:
sql - the SQL string to run.
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
the contents of the query results in an instance of ResultSet. The returned ResultSet is read-only.

rollback

void rollback()
Delegates a rollback request Connection.rollback() to the associated instance of Connection.
See Also:
Connection, Connection.rollback()

setAutoCommit

void setAutoCommit(boolean autoCommit)
Sets whether auto-commit mode is enabled for the associated instance of Connection by calling Connection.setAutoCommit(boolean) for the Connection instance. Calling this method with autoCommit equal to true causes auto-commit mode to be enabled. Calling this method with autoCommit equal to false causes auto-commit mode to be disabled.
Parameters:
autoCommit - a boolean indicator of whether to enable or disable auto-commit mode. Calling this method with autoCommit equal to true causes auto-commit mode to be enabled. Calling this method with autoCommit equal to false causes auto-commit mode to be disabled.
See Also:
Connection, Connection.setAutoCommit(boolean)

startBatch

void startBatch(HeterogeneousBatchKind batchKind)
Starts a batch for a heterogeneous update with parameters.

pureQuery performs heterogeneous updates with parameters by queueing INSERT, UPDATE, and DELETE SQL statements in memory for a particular instance of Data, and then running the queued statements in one network trip. The implementation classes that the pureQuery Generator creates for user-supplied interfaces of annotated methods implement the user-provided interfaces, in addition to the Data interface. See the IBM Optim pureQuery Runtime documentation for an explanation of how to perform heterogeneous batches with parameters when using the annotated-method programming style.

Calling data.startBatch (HeterogeneousBatchKind.heterogeneousModify__) starts a batch for a heterogeneous update with parameters for the instance of Data. INSERT, UPDATE, and DELETE SQL statement are then queued in the batch by calling pureQuery annotated and inline methods in the instance of Data. If an attempt is made to add SQL statements other than INSERT, UPDATE, and DELETE to the batch (by calling methods that run SQL statements that are not INSERT, UPDATE, or DELETE), an exception is thrown, the current batch is cleared, and none of the SQL statements are run. When all of the necessary SQL statements are added to the batch, the batch can be run by calling data.endBatch().

When methods are called to add INSERT, UPDATE, and DELETE SQL statements to the batch, methods that perform updates return Statement.SUCCESS_NO_INFO, and methods that perform updateManys return null. These results indicate that the SQL statement is successfully added to the batch; the SQL statements are not run against the database until endBatch() is called.

A batch of SQL statements is passed to the database as a single transaction. Therefore, commit() and rollback() cannot be called after startBatch(HeterogeneousBatchKind) is called and before endBatch() is called. If commit() or rollback is called while a batch is being constructed, an exception is thrown, the current batch is cleared, and none of the SQL statements are run.

Heterogeneous updates with parameters use functionality that is unique to DB2 and the IBM Data Server Driver for JDBC and SQLJ. An exception is thrown if startBatch(HeterogeneousBatchKind) or endBatch() is called with any other database or database driver.

Parameters:
batchKind - the type of batch to create. The only valid value is HeterogeneousBatchKind.heterogeneousModify__.
See Also:
endBatch(), getBatchKind(), HeterogeneousBatchKind

update

<ROW> ROW update(String sql,
                 Class<ROW> returnClass,
                 String[] columnNames,
                 Object... parameters)
Runs the given SQL statement sql, retrieves the new values of a set of columns, and returns an object of type returnClass that describes the results.

The set of columns whose values are retrieved from the data source depends on the situation:

The object that is returned from this method depends on the situation:

sql must be a statement for which PreparedStatement.executeUpdate() can be performed. That is, the SQL statement sql must be one of the following types of statements:

Type Parameters:
ROW - the generic type of the Object that is used to contain an autogenerated key. <ROW> is indicated by the generic type of returnClass.
Parameters:
sql - the SQL string to run
returnClass - the class that pureQuery must use to return the values of the requested columns when sql is an SQL INSERT statement. This parameter indicates the type that is represented by <ROW>.
columnNames - a String[] in which each element indicates the name of a column whose value must be returned from the data source, if sql is an SQL INSERT statement. If the value of columnNames is null, sql is an SQL insert statement, and the first parameter in parameters is a pureQuery bean, then the set of columns that are retrieved is the set of columns that are represented by properties that have the @GeneratedKey annotation in the bean.
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
null if sql is an SQL UPDATE or DELETE statement. If sql is an SQL INSERT statement, returns an instance of the class returnClass such that:
  • If the class returnClass is Object[].class, an Object[] with a size n equal to one more than the number of columns that are retrieved from the database. The first n-1 elements in the returned array are the new values of the columns in the set of columns that are retrieved. The last element in the returned array is an update count that indicates the number of rows that were updated when the SQL statement was run.
  • If the class returnClass is not Object[].class, a scalar value is returned containing the value of the first column in the set of columns. If columnNames is not null, the returned scalar value is the value of the column that is indicated by the name in columnNames[0].

update

int update(String sql,
           Object... parameters)
Runs the given SQL statement sql and returns an int that indicates how many rows in the data source are updated.

sql must be a statement for which PreparedStatement.executeUpdate() can be performed. That is, the SQL statement sql must be one of the following types of statements:

If sql is an SQL INSERT statement, and the first parameter of parameters is a pureQuery bean in which one or more properties have the @GeneratedKey annotation, pureQuery updates the annotated properties with the new values of the corresponding columns.

Parameters:
sql - the SQL string to run
parameters - used to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers.
Returns:
an int that indicates how many rows in the data source are updated

updateMany

int[] updateMany(String... heterogeneousBatchSQL)
Runs the multiple SQL strings given in one round trip to the server (or in a batch, if the JDBC driver supports round trip processing). The SQL cannot return a results set and cannot contain parameter markers or host variables. All data must be literals. An int[] of update counts is returned in the format that is used for the return value of Statement.executeBatch(). If one or more SQLExceptions are returned from the JDBC driver, they are wrapped within an UpdateManyException as the "cause." Because multiple SQLExceptions can be returned by the JDBC driver, they are chained together and can be retrieved by calling the SQLException method getNextException (which returns an SQLException) until a null is returned.
Parameters:
heterogeneousBatchSQL - multiple SQL strings (or one String array) that cannot be null. The SQL cannot return a ResultSet or contain a parameter marker.
Returns:
an int[] that provides the update counts for running the SQL in the format that is used for the return value of Statement.executeBatch(). The length of the int array is the same as the number of SQL statements that are given. An array of size 0 is returned if the batch is never executed.

updateMany

<T> int[] updateMany(String sql,
                     Iterable<T> parameters)
Runs the given SQL statement sql once for each element in parameters and returns an int[] in which each element in the int[] indicates the update count (that is, the number of rows that were updated) for the corresponding execution of sql. The order of entries in the returned int[] matches the order in which the SQL statements were run; therefore, it corresponds to the order of statements that are represented by parameters.

parameters is an Iterable in which each element is a Map or an Object[] of parameters for the SQL statement. sql is run one time for each element of parameters. Each time, the parameters for sql are provided by the Map or Object[] in the element.

sql must be a statement for which Statement.executeBatch() can be performed. That is, the SQL statement sql must be one of the following types of statements:

Type Parameters:
T - the generic type of the parameters Iterable
Parameters:
sql - the SQL string to run
parameters - an Iterable of type <T> in which each entry is either a Map or an Object[] that contains objects that pureQuery uses to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers. sql is run once for each element in parameters. Each time sql is run, the contents of the Map or Object[] in that element are the parameters for sql for that execution.
Returns:
an int[] that provides the update counts for running the SQL in the format that is used for the return value of Statement.executeBatch()
See Also:
Statement.executeBatch()

updateMany

<T> int[] updateMany(String sql,
                     Iterator<T> parameters)
Runs the given SQL statement sql once for each element in parameters and returns an int[] in which each element in the int[] indicates the update count (that is, the number of rows that were updated) for the corresponding execution of the sql statement. The order of entries in the returned int[] matches the order in which the SQL statements were run; therefore, it corresponds to the order of statements that are represented by parameters.

parameters is an Iterator in which each element is a Map or an Object[] of parameters for the SQL statement. sql is run one time for each element of parameters. Each time the parameters for sql are provided by the Map or Object[] in the element.

sql must be a statement for which Statement.executeBatch() can be performed. That is, the SQL statement sql must be one of the following types of statements:

Type Parameters:
T - the generic type of parameters
Parameters:
sql - the SQL string to run
parameters - an Iterator of type <T> in which each entry is either a Map or an Object[] that contains objects that pureQuery uses to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers. sql is run once for each element in parameters. Each time sql is run, the contents of the Map or Object[] in that element are the parameters for sql for that execution.
Returns:
an int[] that provides the update counts for running the SQL in the format that is used for the return value of Statement.executeBatch().
See Also:
Statement.executeBatch()

updateMany

<T> int[] updateMany(String sql,
                     T[] parameters)
Runs the given SQL statement sql once for each element in parameters and returns an int[] in which each element in the int[] indicates the update count (that is, the number of rows that were updated) for the corresponding execution of sql. The order of entries in the returned int[] matches the order in which the SQL statements were run; therefore, it corresponds to the order of statements that are represented by parameters.

parameters is a T[] in which each element is a Map or an Object[] of parameters for the SQL statement. sql is run one time for each element of parameters, and each time, the parameters for sql are provided by the Map or Object[] in the element.

sql must be a statement for which Statement.executeBatch() can be performed. That is, the SQL statement sql must be one of the following types of statements:

Type Parameters:
T - the generic type of the parameters T[]
Parameters:
sql - the SQL string to run
parameters - a T[] in which each element is either a Map or an Object[] that contains objects that pureQuery uses to set the values of the parameters to sql. The parameters to sql are indicated by parameter markers. sql statement is run once for each element in parameters. Each time sql statement is run, the contents of the Map or Object[] in that element are the parameters for sql for that execution.
Returns:
an int[] that provides the update counts for running the SQL in the format that is used for the return value of Statement.executeBatch()
See Also:
Statement.executeBatch()