|
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface StoredProcedureResult
Provides methods that can be used to retrieve the OUT and INOUT parameters of an SQL stored procedure call and also can be used to access its series of query results sequentially.
If a data source supports returning update counts from stored procedure calls and if accessing the update counts is wanted, a user can write a custom implementation of CallHandlerWithParameters
that retrieves the update
counts. A probable approach would be to call Statement.getUpdateCount()
for the instance of CallableStatement
.
The following three methods in the interface control the StoredProcedureResult
as a whole, navigate through the multiple query results, and retrieve the OUT and INOUT
parameters:
getOutputParms()
StoredProcedureResult
instance has been closed.
It is a good idea to call getOutputParms()
before calling getXXX()
because getXXX()
automatically closes the StoredProcedureResult
instance
if it is called when there are no more query results.getXXX()
methodsgetXXX()
method signature. For example,
getArray()
returns the content of the query result in an array in which each row is
represented by a Map
. and getList(Class returnClass)
returns the
content of the query result in a List
in which each row is represented by an instance of returnClass
. If the query result does not exist, these methods return
null
and close the StoredProcedureResult
instance.moveToNext()
true
if there is another query result after the skipped query result. Returns false
and
closes the StoredProcedureResult
instance if there is not another query result after the skipped query result. moveToNext()
can be used to skip a query result
without materializing it.close()
StoredProcedureResult
instance.Attention: Some JDBC drivers cannot have multiple query results from an SQL stored procedure call open at the same time. When one of these JDBC drivers is used, calling a
getXXX()
method closes the query result of the previous getXXX()
method, if one is open. This means that if the previous getXXX()
method returned an
Iterator, the ResultSet
from which the Iterator retrieves rows is closed, and if the Iterator.hasNext()
method is called again for the Iterator, a RuntimeException
is thrown. If such a JDBC driver is being used, this problem can be avoided by calling getXXX()
methods that
return query results in formats in which they they are fully-materialized (such as arrays or List
s). This approach allows the next result to be retrieved without affecting the
already-returned query result, because it already has been retrieved in its entirety from the database.
Given an instance of StoredProcedureResult
, OUT and INOUT parameters first can be retrieved by using getOutputParms()
. Each result then can be retrieved by using a getXXX()
method.
Finally, the StoredProcedureResult
instance can be closed by calling close()
.
The following code provides an example of using StoredProcedureResult
correctly:
storedProcedureResult =
dataObject.call("{call MyStoredProcedure(?,?,?)}",
parameter1,parameter2,parameter3);
// get the OUT and INOUT parameters
outAndInoutParameters =
storedProcedureResult.getOutputParms();
// do something with outAndInoutParameters
// get Iterators of EmployeeBean until no more results available (null returned)
while ((empBeanIterator =
storedProcedureResult.getIterator(EmployeeBean.class)) != null) {
// do something with empBeanIterator
}
// close the StoredProcedureResult
storedProcedureResult.close();
Return Data Type | Method Name and Description | |
---|---|---|
void |
close() Closes the StoredProcedureResult instance. |
|
Map<String,Object>[] |
getArray() Advances to the next (or first) query result for the stored procedure call, if one exists, and returns the contents of the query result in an array such that each element in the array contains the contents of a row of the query result in a Map . |
|
|
getArray(Class<ROW> returnClass) Advances to the next (or first) query result for the stored procedure call, if one exists, and returns the contents of the query result in an array such that each element in the array contains the contents of a row of the query result in a pureQuery bean that is an instance of the class <ROW> . |
|
|
getArray(Class<ROW> returnClass, RowHandler<ROW> singleRowHandler) Advances to the next (or first) query result for the stored procedure call, if one exists, and returns the contents of the query result in an array such that each element in the array contains the contents of a row of the query result in a an instance of the class <ROW> . |
|
|
getArray(RowHandler<ROW> singleRowHandler) Deprecated. |
|
Iterator<Map<String,Object>> |
getIterator() Advances to the next (or first) query result for the stored procedure call, if one exists, and returns the contents of the query result in an Iterator instance such that each call to the Iterator.next() method of the instance provides the
contents of a row of the query result in a Map . |
|
|
getIterator(Class<ROW> returnClass) Advances to the next (or first) query result for the stored procedure call, if one exists, and returns the contents of the query result in 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 result in a pureQuery bean that is an instance of the class <ROW> . |
|
|
getIterator(RowHandler<ROW> singleRowHandler) Advances to the next (or first) query result for the stored procedure call, if one exists, and returns the contents of the query result in 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 result in an instance of the class <ROW> . |
|
List<Map<String,Object>> |
getList() Advances to the next (or first) query result for the stored procedure call, if one exists, and returns the contents of the query result in a List instance such that each element in the instance contains the
contents of a row of the query result in a Map . |
|
|
getList(Class<ROW> returnClass) Advances to the next (or first) query result for the stored procedure call, if one exists, and returns the contents of the query result in a List instance such that each element in the List
instance contains the contents of a row of the query result in a pureQuery bean that is an instance of the class <ROW> . |
|
|
getList(RowHandler<ROW> singleRowHandler) Advances to the next (or first) query result for the stored procedure call, if one exists, and returns the contents of the query result in a List instance such that each element in the List
instance contains the contents of a row of the query result in an instance of the class <ROW> . |
|
Object[] |
getOutputParms() Returns an Object[] of OUT and INOUT parameters. |
|
|
getQuery(ResultHandler<RES> handler) Advances to the next (or first) query result for the stored procedure call, if one exists, and returns the contents of the query result in an Object of type
<RES> . |
|
ResultSet |
getResults() Advances to the next (or first) query result for the stored procedure call, if one eists, and returns the contents of the query result in an instance of ResultSet . |
|
boolean |
moveToNext() Deprecated. |
Method Detail |
---|
void close()
StoredProcedureResult
instance. This includes closing any associated Statement
.
If close()
is called for a StoredProcedureResult
instance that is closed
already, there are no changes or consequences. However, calling any other method of a closed StoredProcedureResult
instance results in a RuntimeException
.
Map<String,Object>[] getArray()
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. When the
value in a column is SQL NULL, the corresponding value in the Map
has the value of null
. If a next (or first) query result does not exist, null
is
returned, and the StoredProcedureResult
instance is closed.Map
. Returns null
if a next (or first) query result
does not exist.<ROW> ROW[] getArray(Class<ROW> returnClass)
<ROW>
. When the value in a column is SQL NULL, the corresponding
property in the bean has the value of null
. See the IBM Optim pureQuery Runtime documentation for details about how pureQuery maps query results to pureQuery beans. If a next (or
first) query result does not exist, null
is returned, and the StoredProcedureResult
instance is closed.ROW
- the generic type of the array to return. <ROW>
is indicated by the generic type of returnClass
.returnClass
- the class to use to represent each row of the query result in the returned array. This parameter indicates the type that is represented by
<ROW>
.<ROW>
. Returns null
if a next (or first) query result does not exist.<ROW> ROW[] getArray(Class<ROW> returnClass, RowHandler<ROW> singleRowHandler)
<ROW>
. pureQuery uses singleRowHandler
(specifically singleRowHandler.handle(ResultSet, Object)
) to create each object of type
<ROW>
. If a next (or first) query result does not exist, null
is returned, and the StoredProcedureResult
instance is closed.ROW
- the generic type of the array to return. <ROW>
is indicated by the generic type of returnClass
and
singleRowHandler
.returnClass
- the class to use to represent each row of the query result in the returned array. This parameter indicates the type that is represented by
<ROW>
.singleRowHandler
- the RowHandler
whose singleRowHandler.handle(ResultSet, Object)
method maps the contents of
each row to an Object
of type <ROW>
<ROW>
. Returns null
if a next (or first) query result does not exist.
@Deprecated
<ROW> ROW[] getArray(RowHandler<ROW> singleRowHandler)
<ROW>
. pureQuery uses singleRowHandler
(specifically singleRowHandler.handle(ResultSet, Object)
) to create each object of type
<ROW>
. If a next (or first) query result does not exist, null
is returned, and the StoredProcedureResult
instance is closed.ROW
- the generic type of the array to return. <ROW>
is indicated by the generic type of singleRowHandler
.singleRowHandler
- the RowHandler
whose singleRowHandler.handle(ResultSet, Object)
method maps the contents of
each row to an Object
of type <ROW>
.<ROW>
. Returns null
if a next (or first) query result does snot exist.Iterator<Map<String,Object>> getIterator()
Iterator
instance such that each call to the Iterator.next()
method of the instance provides the contents
of a row of the query result 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. When the value in a
column is SQL NULL, the corresponding value in the Map
has the value of null
. If a next (or first) query result does not exist, null
is returned, and
the StoredProcedureResult
instance is closed.Iterator
instance if a next (or first) query
result exists, where each call to the Iterator.next()
method of the instance provides the contents of a row of the query result in a Map
. Returns null
if a next (or first) query does
not exist.<ROW> Iterator<ROW> getIterator(Class<ROW> returnClass)
Iterator
instance such that each call to the Iterator.next()
method of the Iterator
instance
provides the contents of a row of the query result in a pureQuery bean that is an instance of the class <ROW>
. When the value in a column is SQL NULL, the corresponding
property in the bean has the value of null
. See the IBM Optim pureQuery Runtime documentation for details about how pureQuery maps query results to pureQuery beans. If a next (or
first) query result does not exist, null
is returned, and the StoredProcedureResult
instance is closed.ROW
- the generic type of the Iterator
to return. <ROW>
is indicated by the generic type of returnClass
.returnClass
- the class to use to represent each row of the query result in the returned instance of Iterator
. This parameter indicates the type that is
represented by <ROW>
.Iterator
instance if a next (or first) query
result exists, where each call to the Iterator.next()
method of the Iterator
instance provides the contents of a row of the query result in a pureQuery bean
that is an instance of the class <ROW>
. Returns null
if a next (or first) query result does not exist.<ROW> Iterator<ROW> getIterator(RowHandler<ROW> singleRowHandler)
Iterator
instance such that each call to the Iterator.next()
method of the Iterator
instance
provides the contents of a row of the query result in an instance of the class <ROW>
. pureQuery uses singleRowHandler
(specifically singleRowHandler.handle(ResultSet, Object)
) to create each object of type
<ROW>
. If a next (or first) query result does not exist, null
is returned, and the StoredProcedureResult
instance is closed.ROW
- the generic type of the Iterator
to return. <ROW>
is indicated by the generic type of singleRowHandler
.singleRowHandler
- the RowHandler
whose singleRowHandler.handle(ResultSet, Object)
method maps the contents of
each row to an Object
of type <ROW>
Iterator
instance if a next (or first) query
result exists, where each call to the Iterator.next()
method of the Iterator
instance provides the contents of a row of the query result in an instance of
the class <ROW>
. Returns null
if a next (or first) query result does not exist.List<Map<String,Object>> getList()
List
instance such that each element in the instance contains the
contents of a row of the query result 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. When the value in a
column is SQL NULL, the corresponding value in the Map
has the value of null
. If a next (or first) query result does not exist, null
is returned, and
the StoredProcedureResult
instance is closed.List
instance if a next (or first) query result
exists, where each element in the instance contains the contents of a row of the query result in a Map
. Returns null
if a next (or first) query result does not exist.<ROW> List<ROW> getList(Class<ROW> returnClass)
List
instance such that each element in the List
instance
contains the contents of a row of the query result in a pureQuery bean that is an instance of the class <ROW>
. When the value in a column is SQL NULL, the corresponding
property in the bean has the value of null
. See the IBM Optim pureQuery Runtime documentation for details about how pureQuery maps query results to pureQuery beans. If a next (or
first) query result does not exist, null
is returned, and the StoredProcedureResult
instance is closed.ROW
- the generic type of the List
to
return. <ROW>
is indicated by the generic type of returnClass
.returnClass
- the class to use to represent each row of the query result in the returned instance of List
. This parameter indicates the type that is represented by
<ROW>
.List
instance if a next (or first) query result
exists, where each element in the List
instance contains the contents of a row of the query result in a pureQuery bean that is an instance of the class
<ROW>
. Returns null
if a next (or first) query result does not exist.<ROW> List<ROW> getList(RowHandler<ROW> singleRowHandler)
List
instance such that each element in the List
instance
contains the contents of a row of the query result in an instance of the class <ROW>
. pureQuery uses singleRowHandler
(specifically singleRowHandler.handle(ResultSet, Object)
) to create each object of type
<ROW>
. If a next (or first) query result does not exist, null
is returned, and the StoredProcedureResult
instance is closed.ROW
- the generic type of the List
to
return. <ROW>
is indicated by the generic type of singleRowHandler
.singleRowHandler
- the RowHandler
whose singleRowHandler.handle(ResultSet, Object)
method maps the contents of
each row to an Object
of type <ROW>
List
instance if a next (or first) query result
exists, where each element in the List
instance contains the contents of a row of the query result in an instance of the class <ROW>
. Returns
null
if a next (or first) query result does not exist.Object[] getOutputParms()
Object[]
of OUT and INOUT parameters. The size of the array is the number of parameter markers in the executed SQL. The parameters are returned in the order that
they are defined by the called stored procedure. IN parameters are not returned, and they are represented by placeholders of Java null
.
For example, suppose the following stored procedure is created and called. DB2 syntax is used in this example, although the parameters are handled the same way for any database.
CREATE PROCEDURE SAMPLE.EXAMPLE_PROCEDURE
(IN parameter1 CHAR(8),
OUT parameter2 SMALLINT,
OUT parameter3 BIGINT)
LANGUAGE SQL
BEGIN
⁄* do something here *⁄
END
In this case, getOutputParms()
returns an Object[]
of size 3. The
value of Object[0]
is null
. Object[1]
contains the updated value of parameter2
and Object[2]
contains the updated value of
parameter3
.
If getOutputParms()
is called before the stored procedure call is executed or
after the StoredProcedureResult
instance is closed, then a RuntimeException
is thrown.
Object[]
of OUT and INOUT parameters. The parameters are returned in the order that they are defined by the called stored procedure. Input parameters are not
returned, and they are represented by placeholders of Java null
.<RES> RES getQuery(ResultHandler<RES> handler)
Object
of type
<RES>
. The actual processing of the query result is done by the handler
, and the Object
that is returned is the Object
that is
returned by handler.handle(ResultSet)
. If a next (or first) query result does
not exist, null
is returned, and the StoredProcedureResult
instance is closed.RES
- the generic type of the Object
to return. <RES>
is indicated by the generic type of handler
.handler
- the ResultHandler<RES>
whose handler.handle(ResultSet)
method processes the current query result and
returns the contents of the query result in an Object
of type <RES>
. The Object
that is returned by this method (getQuery(ResultHandler)
) is actually the
Object
that is returned by handle(ResultSet)
.ResultSet
if a next (or first)
query result exists, that contains the contents of the query result. Returns null
if a next (or first) query result does not exist.ResultSet getResults()
ResultSet
. The returned ResultSet
is read-only. If a
next (or first) query result does not exist, null
is returned, null
is returned, and the StoredProcedureResult
instance is closed.ResultSet
if a next (or first)
query result exists, that contains the contents of the query result. The returned ResultSet
is read-only. Returns null
if a next (or first) query result does
not exist.
@Deprecated
boolean moveToNext()
true
if there is another query result after the skipped query result. Returns
false
and closes the StoredProcedureResult
instance if there is not another query result after the skipped query result. moveToNext()
can be used to
skip a query result without materializing it.true
if another query result exists after the skipped query result, and false
if another one does not exist
|
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |