com.ibm.pdq.runtime
Interface Data
public interface DataProvides 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
pureQuery Runtime documentation for more details about the use of the Data
interface in
pureQuery.
The methods that are provided in this interface include:
- Methods for running single SQL statements and returning the query results in various data structures
-
updateMany
methods for running homogeneous batches of SQL statements - An
updateMany
method for running heterogeneous batches of SQL statements without parameters - Methods for creating and running heterogeneous updates with parameters
- Methods for enabling and disabling auto-commit mode and for running database commit and rollback operations (when a connection to the data source exists)
- Methods for retrieving or closing a connection to the data source (when such a connection exists)
Method Summary
Modifier and Type | Method and Description |
---|---|
|
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.
|
|
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.
|
call(String sql,Object... parameters)
Runs the given SQL stored procedure call
sql and causes this method to return an instance of StoredProcedureResult that represents the results of running sql .
|
|
|
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.
|
|
cancelBatch()
Terminates an existing Batch without executing the Batch.
|
|
close()
Frees all resources and closes the associated instance of
Connection by calling
Connection.close() for that instance.
|
|
commit()
Delegates a commit request (
Connection.commit() ) to the associated instance of
Connection .
|
|
endBatch()
Runs the INSERT, UPDATE, MERGE, and DELETE SQL statements that are queued for a heterogeneous update with parameters and
returns an
int[][] that describes the results of the execution.
|
|
getAutoCommit()
Returns a
boolean that indicates whether auto-commit mode is enabled for the associated instance of Connection .
|
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.
|
|
getConnection()
Returns the
Connection object that is associated with the instance of Data , if such
an object exists.
|
|
getLogger()
Returns the instance of
DataLogger to use for all of the logging that
occurs in association with the instance of Data .
|
|
|
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.
|
|
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.
|
|
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.
|
|
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> .
|
|
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> .
|
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 .
|
|
|
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> .
|
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.
|
|
|
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> .
|
|
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> .
|
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 .
|
|
|
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> .
|
|
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> .
|
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 .
|
|
|
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> .
|
|
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> .
|
queryList(String sql,Object... parameters)
|
|
|
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> .
|
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 .
|
|
queryResults(String sql,Object... parameters)
Runs the given SQL statement
sql and returns the contents of the query results in an instance of ResultSet .
|
|
|
rollback()
Delegates a rollback request
Connection.rollback() to the associated instance of
Connection .
|
|
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.
|
|
startBatch(HeterogeneousBatchKind batchKind)
Starts a batch for a heterogeneous update with parameters.
|
|
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.
|
|
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.
|
|
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).
|
|
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 .
|
|
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.
|
|
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)
CAL
- the generic type of the object to return. <CAL>
is indicated by the generic type of
callHandler
. 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. CallHandler
call
<CAL> CAL call(String sql, CallHandlerWithParameters<CAL> callHandlerWithParameters, Object... parameters)
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:
CAL
- the generic type of the object to return. <CAL>
is indicated by the generic type of
callHandlerWithParameters
. 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. CallHandlerWithParameters
call
StoredProcedureResult call(String sql, Object... parameters)
sql
and causes this method to return 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:
- The passed-in parameter is a
Map
or a pureQuery bean. - The parameter is specified as an OUT or INOUT parameter in the actual stored procedure call.
However, the updated values of all the OUT and INOUT parameters of the called stored procedure can be obtained by
calling StoredProcedureResult.getOutputParms()
.
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 Map
s 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()
. StoredProcedureResult
that represents the results of running
sql
call
<CAL> CAL call(String sql, ParameterHandler parameterHandler, CallHandlerWithParameters<CAL> callHandlerWithParameters, Object... parameters)
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:
CAL
- the generic type of the object to return. <CAL>
is indicated by the generic type of
callHandlerWithParameters
. 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. Note: If set to null
, the default inline ParameterHandler
is used. callHandlerWithParameters
- an instance of an implementation of the class
CallHandlerWithParameters
. Note: If set to null
, the
default inline CallHandlerWithParameters
is used. This default inline CallHandlerWithParameters
returns an
instance of StoredProcedureResult
that represents the results of running
sql
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. CallHandlerWithParameters
cancelBatch
void cancelBatch()
A pureQuery Runtime Heterogeneous Batch (see startBatch(HeterogeneousBatchKind)
and
endBatch()
may need to be canceled instead of executed when an unrecoverable error occurs while
defining the Heterogeneous Batch (adding SQL statements to the batch), typically within a catch block. Calling
cancelBatch()
will free all resources and terminate the batch without executing any of the
successfully added SQL Statements that would be executed by calling endBatch()
.
cancelBatch()
can be called even if the startBatch(HeterogeneousBatchKind)
was not
successful and you are not within a batch. No SQLException
thrown while closing
PreparedStatement
(s) within the batch will be re-thrown. This means that normally the call
to cancelBatch()
does not need to be within a try / catch block.
close
void close()
Connection
by calling
Connection.close()
for that instance.
commit
void commit()
Connection.commit()
) to the associated instance of
Connection
.
endBatch
int[][] endBatch()
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, MERGE, 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
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, MERGE, 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, MERGE, and DELETE to the batch (by calling methods that run SQL statements that are
not INSERT, UPDATE, MERGE, 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.
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. getAutoCommit
boolean getAutoCommit()
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
.
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
. getBatchKind
HeterogeneousBatchKind getBatchKind( )
HeterogeneousBatchKind
, which indicates that SQL statements are
being run immediately, or that a batch for a heterogeneous update with parameters is being created.
HeterogeneousBatchKind
, which indicates that SQL statements are
being run immediately, or that a batch for a heterogeneous update with parameters is being created. getConnection
Connection getConnection()
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
.
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
. getLogger
Logger getLogger()
DataLogger
to use for all of the logging that
occurs in association with the instance of Data
.
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)
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)
.
RES
- the generic type of the Object
to return. <RES>
is indicated by the
generic type of handler
. 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 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. Note: If set to null
, the default inline ParameterHandler
is used. 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. 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)
. query
<RES> RES query(int type, int concurrency, int holdability, String sql, ResultHandler<RES> resultHandler, Object... parameters)
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)
.
RES
- the generic type of the Object
to return. <RES>
is indicated by the
generic type of handler
. 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. 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)
. query
<RES> RES query(String sql, ResultHandler<RES> handler, Object... parameters)
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)
.
RES
- the generic type of the Object
to return. <RES>
is indicated by the
generic type of handler
. 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. 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)
. queryArray
<ROW> ROW[] queryArray(String sql, Class<ROW> returnClass, Object... parameters)
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 pureQuery Runtime documentation for details about how pureQuery maps
query results to pureQuery beans.
ROW
- the generic type of the array to return. <ROW>
is indicated by the generic type of
returnClass
. 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. <ROW>
. queryArray
<ROW> ROW[] queryArray(String sql, Class<ROW> returnClass, RowHandler<ROW> rowHandler, Object... parameters)
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>
.
ROW
- the generic type of the array to return. <ROW>
is indicated by the generic type of
rowHandler
. 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. <ROW>
queryArray
Map<String,Object>[] queryArray( String sql, Object... parameters)
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.
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. Map
. queryFirst
<ROW> ROW queryFirst(String sql, Class<ROW> returnClass, Object... parameters)
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>
. If the query results contain no rows,
this method returns null
. See the pureQuery Runtime documentation for details about how
pureQuery maps query results to pureQuery beans.
ROW
- the generic type of the Object
to return. <ROW>
is indicated by the
generic type of returnClass
. 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. <ROW>
, or null
if the query results contain no rows. See the
pureQuery Runtime documentation for details about how pureQuery maps query results to pureQuery
beans. queryFirst
Map<String,Object> queryFirst(String sql, Object... parameters)
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. If the query results contain no rows, this method returns null
.
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. 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. If
the query results contain no rows, this method returns null
. queryFirst
<ROW> ROW queryFirst(String sql, RowHandler<ROW> rowHandler, Object... parameters)
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>
. If the query
results contain no rows, this method returns null
.
ROW
- the generic type of the Object
to return. <ROW>
is indicated by the
generic type of rowHandler
. 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. first
row of the query results in an instance of the class
<ROW>
, or null
if the query results contain no rows. queryIterator
<ROW> Iterator<ROW> queryIterator( int type, int concurrency, int holdability, String sql, Class<ROW> returnClass, Object... parameters)
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
pureQuery Runtime documentation for details about how pureQuery maps query results to pureQuery beans.
ROW
- the generic type of the Iterator
to return. <ROW>
is indicated by
the generic type of returnClass
. 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. 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)
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.
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. 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)
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>
.
ROW
- the generic type of the Iterator
to return. <ROW>
is indicated by
the generic type of rowHandler
. 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. 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)
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
pureQuery Runtime documentation for details about how pureQuery maps query results to pureQuery beans.
ROW
- the generic type of the Iterator
to return. <ROW>
is indicated by
the generic type of returnClass
. 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. 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)
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.
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. 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)
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>
.
ROW
- the generic type of the Iterator
to return. <ROW>
is indicated by
the generic type of rowHandler
. 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. 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)
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 pureQuery Runtime documentation for details
about how pureQuery maps query results to pureQuery beans.
ROW
- the generic type of the List
to return. <ROW>
is indicated by the
generic type of returnClass
. 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. 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)
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.
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. queryList
<ROW> List<ROW> queryList(String sql, RowHandler<ROW> rowHandler, Object... parameters)
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>
.
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. 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)
sql
and returns the contents of the query results in an instance of
ResultSet
. The returned ResultSet
is read-only.
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. ResultSet
. The returned
ResultSet
is read-only. queryResults
ResultSet queryResults(String sql, Object... parameters)
sql
and returns the contents of the query results in an instance of
ResultSet
. The returned ResultSet
is read-only.
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. ResultSet
. The returned
ResultSet
is read-only. rollback
void rollback()
Connection.rollback()
to the associated instance of
Connection
.
setAutoCommit
void setAutoCommit(boolean autoCommit)
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.
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. startBatch
void startBatch(HeterogeneousBatchKind batchKind)
pureQuery performs heterogeneous updates with parameters by queueing INSERT, UPDATE, MERGE, 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
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, MERGE, 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, MERGE, and DELETE to the batch (by calling methods that run SQL statements that are
not INSERT, UPDATE, MERGE, 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, MERGE, and DELETE SQL statements to the batch, methods that perform
update
s return Statement.SUCCESS_NO_INFO
, and methods that perform
updateMany
s 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.
batchKind
- the type of batch to create. The only valid value is
HeterogeneousBatchKind.heterogeneousModify__
. update
<ROW> ROW update(String sql, Class<ROW> returnClass, String[] columnNames, Object... parameters)
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:
- If
columnNames
is notnull
, the set of columns is the columns whose names are listed incolumnNames
. - If
columnNames
isnull
, and the first parameter ofparameters
is a pureQuery bean, then the set of columns contains the columns that are represented by properties in the bean that have the@GeneratedKey
annotation.
When pureQuery 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,
this method returns an instance of the class
returnClass
. Otherwise, this method returns null
. When an instance of the class
returnClass
is returned, it is as follows:
- If the class
returnClass
isObject[].class
, anObject[]
is returned 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 returnedarray
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 notObject[].class
, a scalar value is returned that contains the value of the first column in the set of columns. IfcolumnNames
is notnull
, the returned scalar value is the value of the column that is indicated by the name incolumnNames[0]
.
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:
- INSERT
- UPDATE
- MERGE
- DELETE
- Any other statement for which no query results are returned
ROW
- the generic type of the Object
that is used to contain an autogenerated key.
<ROW>
is indicated by the generic type of returnClass
. sql
- the SQL string to run returnClass
- the class that pureQuery must use to return the values of the requested columns.
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 the value of
columnNames
is null
, 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. returnClass
or null
.
When pureQuery 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,
an instance of the class returnClass
is returned. Otherwise, null
is returned. When an instance of the class returnClass
is returned, it is as follows:
- If the class
returnClass
isObject[].class
, anObject[]
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 returnedarray
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 notObject[].class
, a scalar value is returned containing the value of the first column in the set of columns. IfcolumnNames
is notnull
, the returned scalar value is the value of the column that is indicated by the name incolumnNames[0]
.
update
int update(String sql, Object... parameters)
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:
- INSERT
- UPDATE
- MERGE
- DELETE
- Any other statement for which no query results are returned
If the first parameter of parameters
is a pureQuery
bean in which one or more properties have the @GeneratedKey
annotation,
and pureQuery 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,
pureQuery updates the annotated properties with the new values of the corresponding columns.
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. int
that indicates how many rows in the data source are updated updateMany
int[] updateMany(String... heterogeneousBatchSQL)
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.
heterogeneousBatchSQL
- multiple SQL strings (or one String
array) that cannot be
null
. The SQL cannot return a ResultSet
or contain a parameter marker. 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)
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:
- INSERT
- UPDATE
- MERGE
- DELETE
- Any other statement for which no query results are returned
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. int[]
that provides the update counts for running the SQL in the format that is used for
the return value of Statement.executeBatch()
updateMany
<T> int[] updateMany(String sql, Iterator<T> parameters)
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:
- INSERT
- UPDATE
- MERGE
- DELETE
- Any other statement for which no query results are returned
T
- the generic type of 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. int[]
that provides the update counts for running the SQL in the format that is used for
the return value of Statement.executeBatch()
. updateMany
<T> int[] updateMany(String sql, T[] parameters)
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:
- INSERT
- UPDATE
- MERGE
- DELETE
- Any other statement for which no query results are returned
T
- the generic type of the parameters T[]
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. int[]
that provides the update counts for running the SQL in the format that is used for
the return value of Statement.executeBatch()
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 thecallHandler
, and the object that is returned is the object that is returned bycallHandler.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 theCallHandler<CAL>
, and it can be any of the following types:Map
Map
sIterator
of beans orMap
sList
of beans orMap
s