Interface StoredProcedureQuery

All Superinterfaces:

AutoCloseable, Query

public interface StoredProcedureQuery
extends Query, AutoCloseable

Interface used to control execution of a stored procedure query.

Before a stored procedure can be executed, each of its parameters must be explicitly registered by specifying:

• the type of the parameter,
• its position or name, and
• whether its mode is IN, OUT, INOUT, or REF_CURSOR.

Each parameter is registered by calling a registration method such as registerParameter(int, Class, ParameterMode) or registerParameter(String, Class, ParameterMode), depending on whether it is a positional or named parameter.

Stored procedure query execution may be controlled in accordance with the following:

• The setParameter(Parameter, T) methods are used to set the values of all required IN and INOUT parameters. It is not required to set the values of stored procedure parameters for which default values have been defined by the stored procedure.
• When getResultList() and getSingleResult() are called on a StoredProcedureQuery object, the provider calls execute() on an unexecuted stored procedure query before processing getResultList or getSingleResult.
• When executeUpdate() is called on a StoredProcedureQuery object, the provider will call execute() on an unexecuted stored procedure query, followed by getUpdateCount(). The results of executeUpdate will be those of getUpdateCount.
• The execute() method supports both the simple case where scalar results are passed back only via INOUT and OUT parameters as well as the most general case (multiple result sets and/or update counts, possibly also in combination with output parameter values).
• The execute method returns true if the first result is a result set, and false if it is an update count or there are no results other than through INOUT and OUT parameters, if any.
• If the execute method returns true, the pending result set can be obtained by calling getResultList() or getSingleResult().
• The hasMoreResults() method can then be used to test for further results.
• If execute or hasMoreResults returns false, the getUpdateCount() method can be called to obtain the pending result if it is an update count. The getUpdateCount method will return either the update count (zero or greater) or -1 if there is no update count (i.e., either the next result is a result set or there is no next update count).
• For portability, results that correspond to JDBC result sets and update counts need to be processed before the values of any INOUT or OUT parameters are extracted.
• After results returned through getResultList() and getUpdateCount() have been exhausted, results returned through INOUT and OUT parameters can be retrieved.
• The getOutputParameterValue(int) methods are used to retrieve the values passed back from the procedure through INOUT and OUT parameters.
• When using REF_CURSOR parameters for result sets the update counts should be exhausted before calling getResultList() to retrieve the result set. Alternatively, the REF_CURSOR result set can be retrieved through getOutputParameterValue(int). Result set mappings are applied to results corresponding to REF_CURSOR parameters in the order the REF_CURSOR parameters were registered with the query.
• In the simplest case, where results are returned only via INOUT and OUT parameters, execute can be followed immediately by calls to getOutputParameterValue(int).

Since:

2.1

See Also:

• Query
• Parameter

Method Summary

Modifier and Type	Method	Description
void	close()	Immediately destroy all resources associated with this query.
boolean	execute()	Return true if the first result corresponds to a result set, and false if it is an update count or if there are no results other than through INOUT and OUT parameters, if any.
int	executeUpdate()	Return the update count or -1 if there is no pending result or if the first result is not an update count.
Object	getOutputParameterValue(int position)	Retrieve a value passed back from the procedure through an INOUT or OUT parameter.
<T> T	getOutputParameterValue(Parameter<T> parameter)	Retrieve a value passed back from the procedure through an INOUT or OUT parameter.
Object	getOutputParameterValue(String parameterName)	Retrieve a value passed back from the procedure through an INOUT or OUT parameter.
List	getResultList()	Deprecated, for removal: This API element is subject to removal in a future version. This method returns a raw List.
<R> List<R>	getResultList(ResultSetMapping<R> mapping)	Retrieve the list of results from the next result set, specifying a result set mapping which overrides any mapping or result class already specified.
<R> List<R>	getResultList(Class<R> resultClass)	Retrieve the list of results from the next result set, returning instances of the given result class, which overrides any result class already specified.
Object	getSingleResult()	Retrieve a single result from the next result set.
<R> R	getSingleResult(ResultSetMapping<R> mapping)	Retrieve a single result from the next result set, specifying a result set mapping which overrides any mapping or result class already specified.
<R> R	getSingleResult(Class<R> resultClass)	Retrieve a single result from the next result set, returning instances of the given result class, which overrides any result class already specified.
Object	getSingleResultOrNull()	Retrieve a single result from the next result set.
<R> R	getSingleResultOrNull(ResultSetMapping<R> mapping)	Retrieve a single result from the next result set, specifying a result set mapping which overrides any mapping or result class already specified.
<R> R	getSingleResultOrNull(Class<R> resultClass)	Retrieve a single result from the next result set, returning instances of the given result class, which overrides any result class already specified.
int	getUpdateCount()	Return the update count or -1 if there is no pending result or if the next result is not an update count.
boolean	hasMoreResults()	Return true if the next result corresponds to a result set, and false if it is an update count or if there are no results other than through INOUT and OUT parameters, if any.
<T> Parameter<T>	registerConvertedParameter(int position, Class<? extends AttributeConverter<T,?>> converter, ParameterMode mode)	Register a positional parameter whose value is bound via a converter.
<T> Parameter<T>	registerConvertedParameter(String parameterName, Class<? extends AttributeConverter<T,?>> converter, ParameterMode mode)	Register a named parameter whose value is bound via a converter.
<T> Parameter<T>	registerParameter(int position, Class<T> type, ParameterMode mode)	Register a positional parameter.
<T> Parameter<T>	registerParameter(String parameterName, Class<T> type, ParameterMode mode)	Register a named parameter.
<T> Parameter<T>	registerResultParameter(Class<T> resultType)	Mark this as a call to a stored procedure with a result parameter and register the type of the result parameter.
StoredProcedureQuery	registerStoredProcedureParameter(int position, Class<?> type, ParameterMode mode)	Register a positional parameter.
StoredProcedureQuery	registerStoredProcedureParameter(String parameterName, Class<?> type, ParameterMode mode)	Register a named parameter.
StoredProcedureQuery	setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode)	Set the cache retrieval mode in effect during query execution.
StoredProcedureQuery	setCacheStoreMode(CacheStoreMode cacheStoreMode)	Set the cache storage mode in effect during query execution.
<P> StoredProcedureQuery	setConvertedParameter(int position, P value, Class<? extends AttributeConverter<P,?>> converter)	Bind an argument value to a named parameter, explicitly specifying an attribute converter to use.
<P> StoredProcedureQuery	setConvertedParameter(String name, P value, Class<? extends AttributeConverter<P,?>> converter)	Bind an argument value to a named parameter, explicitly specifying an attribute converter to use.
StoredProcedureQuery	setFlushMode(FlushModeType flushMode)	Set the flush mode type to be used when the query is executed.
StoredProcedureQuery	setHint(String hintName, Object value)	Set a query property or hint.
StoredProcedureQuery	setParameter(int position, Object value)	Bind an argument value to a positional parameter.
StoredProcedureQuery	setParameter(int position, Calendar value, TemporalType temporalType)	Deprecated. Newly written code should use the date/time types defined in java.time.
StoredProcedureQuery	setParameter(int position, Date value, TemporalType temporalType)	Deprecated. Newly written code should use the date/time types defined in java.time.
<P> StoredProcedureQuery	setParameter(int position, P value, Type<P> type)	Bind an argument value to a positional parameter, explicitly specifying the parameter type.
<P> StoredProcedureQuery	setParameter(int position, P value, Class<P> type)	Bind an argument value to a positional parameter, explicitly specifying the parameter type.
StoredProcedureQuery	setParameter(Parameter<Calendar> param, Calendar value, TemporalType temporalType)	Deprecated. Newly written code should use the date/time types defined in java.time.
StoredProcedureQuery	setParameter(Parameter<Date> param, Date value, TemporalType temporalType)	Deprecated. Newly written code should use the date/time types defined in java.time.
<T> StoredProcedureQuery	setParameter(Parameter<T> parameter, T value)	Bind an argument to a parameter of this query respresented as a Parameter object.
StoredProcedureQuery	setParameter(String name, Object value)	Bind an argument value to a named parameter.
StoredProcedureQuery	setParameter(String name, Calendar value, TemporalType temporalType)	Deprecated. Newly written code should use the date/time types defined in java.time.
StoredProcedureQuery	setParameter(String name, Date value, TemporalType temporalType)	Deprecated. Newly written code should use the date/time types defined in java.time.
<P> StoredProcedureQuery	setParameter(String name, P value, Type<P> type)	Bind an argument value to a named parameter, explicitly specifying the parameter type.
<P> StoredProcedureQuery	setParameter(String name, P value, Class<P> type)	Bind an argument value to a named parameter, explicitly specifying the parameter type.
StoredProcedureQuery	setTimeout(Timeout timeout)	Set the query timeout.
StoredProcedureQuery	setTimeout(Integer timeout)	Set the query timeout, in milliseconds.

Methods inherited from interface Query

asStatement, getCacheRetrieveMode, getCacheStoreMode, getFirstResult, getFlushMode, getHints, getLockMode, getMaxResults, getParameter, getParameter, getParameter, getParameter, getParameters, getParameterValue, getParameterValue, getParameterValue, getResultStream, getTimeout, isBound, ofType, setFirstResult, setLockMode, setMaxResults, unwrap, withEntityGraph

Method Details

setHint

StoredProcedureQuery setHint(String hintName,
 Object value)

Set a query property or hint. The hints elements may be used to specify query properties and hints. Properties defined by this specification must be observed by the provider. Vendor-specific hints that are not recognized by a provider must be silently ignored. Portable applications should not rely on the standard timeout hint. Depending on the database in use, this hint may or may not be observed.

Specified by:

setHint in interface Query

Parameters:

hintName - The name of the property or hint

value - The value for the property or hint

Returns:

the same query instance

Throws:

IllegalArgumentException - if the second argument is not valid for the implementation

setParameter

<T> StoredProcedureQuery setParameter(Parameter<T> parameter,
 T value)

Bind an argument to a parameter of this query respresented as a Parameter object.

Specified by:

setParameter in interface Query

Parameters:

parameter - The parameter object

value - The argument to the parameter

Returns:

the same query instance

Throws:

IllegalArgumentException - if the parameter does not correspond to a parameter of the query

setParameter

@Deprecated(since="3.2")
StoredProcedureQuery setParameter(Parameter<Calendar> param,
 Calendar value,
 TemporalType temporalType)

Deprecated.

Newly written code should use the date/time types defined in java.time.

Bind an instance of Calendar to a Parameter object.

Specified by:

setParameter in interface Query

Parameters:

param - The parameter object

value - The argument to the parameter

temporalType - A temporal type

Returns:

the same query instance

Throws:

IllegalArgumentException - if the parameter does not correspond to a parameter of the query

setParameter

@Deprecated(since="3.2")
StoredProcedureQuery setParameter(Parameter<Date> param,
 Date value,
 TemporalType temporalType)

Deprecated.

Newly written code should use the date/time types defined in java.time.

Bind an instance of Date to a Parameter object.

Specified by:

setParameter in interface Query

Parameters:

param - The parameter object

value - The argument to the parameter

temporalType - A temporal type

Returns:

the same query instance

Throws:

IllegalArgumentException - if the parameter does not correspond to a parameter of the query

setParameter

StoredProcedureQuery setParameter(String name,
 Object value)

Bind an argument value to a named parameter.

Specified by:

setParameter in interface Query

Parameters:

name - The name of the parameter

value - The argument to the parameter

Returns:

the same query instance

Throws:

IllegalArgumentException - if the parameter name does not correspond to a parameter of the query, or if the argument is of incompatible type

setParameter

@Deprecated(since="3.2")
StoredProcedureQuery setParameter(String name,
 Calendar value,
 TemporalType temporalType)

Deprecated.

Newly written code should use the date/time types defined in java.time.

Bind an instance of Calendar to a named parameter.

Specified by:

setParameter in interface Query

Parameters:

name - The name of the parameter

value - The argument to the parameter

temporalType - A temporal type

Returns:

the same query instance

Throws:

IllegalArgumentException - if the parameter name does not correspond to a parameter of the query, or if the value argument is of incompatible type

setParameter

@Deprecated(since="3.2")
StoredProcedureQuery setParameter(String name,
 Date value,
 TemporalType temporalType)

Deprecated.

Newly written code should use the date/time types defined in java.time.

Bind an instance of Date to a named parameter.

Specified by:

setParameter in interface Query

Parameters:

name - The name of the parameter

value - The argument to the parameter

temporalType - A temporal type

Returns:

the same query instance

Throws:

IllegalArgumentException - if the parameter name does not correspond to a parameter of the query, or if the value argument is of incompatible type

setParameter

StoredProcedureQuery setParameter(int position,
 Object value)

Bind an argument value to a positional parameter.

Specified by:

setParameter in interface Query

Parameters:

position - The parameter position

value - The argument to the parameter

Returns:

the same query instance

Throws:

IllegalArgumentException - if the given position does not correspond to a positional parameter of the query, or if the argument is of incompatible type

setParameter

@Deprecated(since="3.2")
StoredProcedureQuery setParameter(int position,
 Calendar value,
 TemporalType temporalType)

Deprecated.

Newly written code should use the date/time types defined in java.time.

Bind an instance of Calendar to a positional parameter.

Specified by:

setParameter in interface Query

Parameters:

position - The parameter position

value - The argument to the parameter

temporalType - A temporal type

Returns:

the same query instance

Throws:

IllegalArgumentException - if the given position does not correspond to a positional parameter of the query, or if the argument is of incompatible type

setParameter

@Deprecated(since="3.2")
StoredProcedureQuery setParameter(int position,
 Date value,
 TemporalType temporalType)

Deprecated.

Newly written code should use the date/time types defined in java.time.

Bind an instance of Date to a positional parameter.

Specified by:

setParameter in interface Query

Parameters:

position - The parameter position

value - The argument to the parameter

temporalType - A temporal type

Returns:

the same query instance

Throws:

IllegalArgumentException - if the given position does not correspond to a positional parameter of the query, or if the argument is of incompatible type

setParameter

<P> StoredProcedureQuery setParameter(String name,
 P value,
 Class<P> type)

Bind an argument value to a named parameter, explicitly specifying the parameter type. This is most useful when the argument might be null.

Specified by:

setParameter in interface Query

Parameters:

name - The name of the parameter

value - The argument to the parameter

type - A class object representing the parameter type

Returns:

the same query instance

Throws:

IllegalArgumentException - if the parameter name does not correspond to a parameter of the query, or if the argument is of incompatible type

Since:

4.0

setParameter

<P> StoredProcedureQuery setParameter(String name,
 P value,
 Type<P> type)

Bind an argument value to a named parameter, explicitly specifying the parameter type. This is most useful when the binding is affected by an attribute converter.

Specified by:

setParameter in interface Query

Parameters:

name - The name of the parameter

value - The argument to the parameter

type - The Type of the parameter

Returns:

the same query instance

Throws:

IllegalArgumentException - if the parameter name does not correspond to a parameter of the query, or if the argument is of incompatible type

Since:

4.0

setConvertedParameter

<P> StoredProcedureQuery setConvertedParameter(String name,
 P value,
 Class<? extends AttributeConverter<P,?>> converter)

Bind an argument value to a named parameter, explicitly specifying an attribute converter to use.

Specified by:

setConvertedParameter in interface Query

Parameters:

name - The name of the parameter

value - The argument to the parameter

converter - The class of the attribute converter

Returns:

the same query instance

Throws:

IllegalArgumentException - if the parameter name does not correspond to a parameter of the query, or if the argument is of incompatible type

Since:

4.0

setParameter

<P> StoredProcedureQuery setParameter(int position,
 P value,
 Class<P> type)

Bind an argument value to a positional parameter, explicitly specifying the parameter type. This is most useful when the argument might be null.

Specified by:

setParameter in interface Query

Parameters:

position - position

value - The argument to the parameter

type - A class object representing the parameter type

Returns:

the same query instance

Throws:

IllegalArgumentException - if the given position does not correspond to a positional parameter of the query, or if the argument is of incompatible type

Since:

4.0

setParameter

<P> StoredProcedureQuery setParameter(int position,
 P value,
 Type<P> type)

Bind an argument value to a positional parameter, explicitly specifying the parameter type. This is most useful when the binding is affected by an attribute converter.

Specified by:

setParameter in interface Query

Parameters:

position - position

value - The argument to the parameter

type - The Type of the parameter

Returns:

the same query instance

Throws:

IllegalArgumentException - if the given position does not correspond to a positional parameter of the query, or if the argument is of incompatible type

Since:

4.0

setConvertedParameter

<P> StoredProcedureQuery setConvertedParameter(int position,
 P value,
 Class<? extends AttributeConverter<P,?>> converter)

Bind an argument value to a named parameter, explicitly specifying an attribute converter to use.

Specified by:

setConvertedParameter in interface Query

Parameters:

position - The parameter position

value - The argument to the parameter

converter - The class of the attribute converter

Returns:

the same query instance

Throws:

IllegalArgumentException - if the given position does not correspond to a parameter of the query, or if the argument is of incompatible type

Since:

4.0

setFlushMode

StoredProcedureQuery setFlushMode(FlushModeType flushMode)

Set the flush mode type to be used when the query is executed. This flush mode overrides the flush mode type of the entity manager.

Specified by:

setFlushMode in interface Query

Parameters:

flushMode - The new flush mode

Returns:

the same query instance

setCacheRetrieveMode

StoredProcedureQuery setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode)

Set the cache retrieval mode in effect during query execution. This cache retrieval mode overrides the cache retrieve mode of the entity manager.

Specified by:

setCacheRetrieveMode in interface Query

Parameters:

cacheRetrieveMode - The new cache retrieval mode

Returns:

the same query instance

Since:

3.2

setCacheStoreMode

StoredProcedureQuery setCacheStoreMode(CacheStoreMode cacheStoreMode)

Set the cache storage mode in effect during query execution. This cache storage mode overrides the cache storage mode of the entity manager.

Specified by:

setCacheStoreMode in interface Query

Parameters:

cacheStoreMode - The new cache storage mode

Returns:

the same query instance

Since:

3.2

setTimeout

StoredProcedureQuery setTimeout(Integer timeout)

Set the query timeout, in milliseconds. This is a hint, and is an alternative to setting the hint jakarta.persistence.query.timeout.

Specified by:

setTimeout in interface Query

Parameters:

timeout - the timeout, in milliseconds, or null to indicate no timeout

Returns:

the same query instance

Since:

3.2

setTimeout

StoredProcedureQuery setTimeout(Timeout timeout)

Set the query timeout. This is a hint.

Specified by:

setTimeout in interface Query

Parameters:

timeout - the timeout, or null to indicate no timeout

Returns:

the same query instance

Since:

4.0

registerResultParameter

<T> Parameter<T> registerResultParameter(Class<T> resultType)

Mark this as a call to a stored procedure with a result parameter and register the type of the result parameter. This is typically required when calling a stored function. The result may be retrieved after execution by calling getOutputParameterValue(Parameter).

Parameters:

resultType - the type of the result parameter

Returns:

an object representing the parameter, which may be passed to setParameter(Parameter, Object) and getOutputParameterValue(Parameter)

Since:

4.0

registerParameter

<T> Parameter<T> registerParameter(int position,
 Class<T> type,
 ParameterMode mode)

Register a positional parameter. The result of an OUT parameter may be retrieved after execution by calling getOutputParameterValue(Parameter). All parameters must be registered.

Parameters:

position - the parameter position

type - the type of the parameter

mode - the parameter mode

Returns:

an object representing the parameter, which may be passed to setParameter(Parameter, Object) and getOutputParameterValue(Parameter)

Since:

4.0

registerParameter

<T> Parameter<T> registerParameter(String parameterName,
 Class<T> type,
 ParameterMode mode)

Register a named parameter. The result of an OUT parameter may be retrieved after execution by calling getOutputParameterValue(Parameter). All parameters must be registered.

Parameters:

parameterName - the name of the parameter as registered or specified in metadata

type - the type of the parameter

mode - the parameter mode

Returns:

an object representing the parameter, which may be passed to setParameter(Parameter, Object) and getOutputParameterValue(Parameter)

Since:

4.0

registerConvertedParameter

<T> Parameter<T> registerConvertedParameter(int position,
 Class<? extends AttributeConverter<T,?>> converter,
 ParameterMode mode)

Register a positional parameter whose value is bound via a converter. The result of an OUT parameter may be retrieved after execution by calling getOutputParameterValue(Parameter). All parameters must be registered.

Parameters:

position - the parameter position

converter - the class of the attribute converter

mode - the parameter mode

Returns:

an object representing the parameter, which may be passed to setParameter(Parameter, Object) and getOutputParameterValue(Parameter)

Since:

4.0

registerConvertedParameter

<T> Parameter<T> registerConvertedParameter(String parameterName,
 Class<? extends AttributeConverter<T,?>> converter,
 ParameterMode mode)

Register a named parameter whose value is bound via a converter. The result of an OUT parameter may be retrieved after execution by calling getOutputParameterValue(Parameter). All parameters must be registered.

Parameters:

parameterName - the name of the parameter as registered or specified in metadata

converter - the class of the attribute converter

mode - the parameter mode

Returns:

an object representing the parameter, which may be passed to setParameter(Parameter, Object) and getOutputParameterValue(Parameter)

Since:

4.0

registerStoredProcedureParameter

StoredProcedureQuery registerStoredProcedureParameter(int position,
 Class<?> type,
 ParameterMode mode)

Register a positional parameter. All parameters must be registered.

Parameters:

position - parameter position

type - type of the parameter

mode - parameter mode

Returns:

the same query instance

registerStoredProcedureParameter

StoredProcedureQuery registerStoredProcedureParameter(String parameterName,
 Class<?> type,
 ParameterMode mode)

Register a named parameter. All parameters must be registered.

Parameters:

parameterName - name of the parameter as registered or specified in metadata

type - type of the parameter

mode - parameter mode

Returns:

the same query instance

getOutputParameterValue

Object getOutputParameterValue(int position)

Retrieve a value passed back from the procedure through an INOUT or OUT parameter. For portability, all results corresponding to result sets and update counts must be retrieved before the values of output parameters.

Parameters:

position - parameter position

Returns:

the result that is passed back through the parameter

Throws:

IllegalArgumentException - if the position does not correspond to a parameter of the query or is not an INOUT or OUT parameter

getOutputParameterValue

Object getOutputParameterValue(String parameterName)

Retrieve a value passed back from the procedure through an INOUT or OUT parameter. For portability, all results corresponding to result sets and update counts must be retrieved before the values of output parameters.

Parameters:

parameterName - The name of the parameter as registered or specified in metadata

Returns:

the result that is passed back through the parameter

Throws:

IllegalArgumentException - if the parameter name does not correspond to a parameter of the query or is not an INOUT or OUT parameter

getOutputParameterValue

<T> T getOutputParameterValue(Parameter<T> parameter)

Retrieve a value passed back from the procedure through an INOUT or OUT parameter. For portability, all results corresponding to result sets and update counts must be retrieved before the values of output parameters.

Parameters:

parameter - The parameter object

Returns:

the result that is passed back through the parameter

Throws:

IllegalArgumentException - if the parameter name does not correspond to a parameter of the query or is not an INOUT or OUT parameter

Since:

4.0

execute

boolean execute()

Return true if the first result corresponds to a result set, and false if it is an update count or if there are no results other than through INOUT and OUT parameters, if any.

Returns:

true if the first result is a result set

Throws:

QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back

PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back

executeUpdate

int executeUpdate()

Return the update count or -1 if there is no pending result or if the first result is not an update count. The provider calls execute() if necessary.

Specified by:

executeUpdate in interface Query

Returns:

the update count or -1 if there is no pending result or if the next result is not an update count.

Throws:

TransactionRequiredException - if there is no transaction or the persistence context has not been joined to the transaction

QueryTimeoutException - if the statement execution exceeds the query timeout value set and only the statement is rolled back

PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back

getResultList

@Deprecated(since="4.0",
            forRemoval=true)
List getResultList()

Deprecated, for removal: This API element is subject to removal in a future version.

This method returns a raw List. Use getResultList(Class) instead.

Retrieve the list of results from the next result set. The provider calls execute() if necessary. A REF_CURSOR result set, if any, is retrieved in the order the REF_CURSOR parameter was registered with the query.

Specified by:

getResultList in interface Query

Returns:

a list of the results or null if the next item is not a result set

Throws:

QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back

PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back

getSingleResult

Object getSingleResult()

Retrieve a single result from the next result set. The provider calls execute() if necessary. A REF_CURSOR result set, if any, is retrieved in the order the REF_CURSOR parameter was registered with the query.

Specified by:

getSingleResult in interface Query

Returns:

the result or null if the next item is not a result set

Throws:

NoResultException - if there is no result in the next result set

NonUniqueResultException - if more than one result

QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back

PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back

getSingleResultOrNull

Object getSingleResultOrNull()

Retrieve a single result from the next result set. The provider calls execute() if necessary. A REF_CURSOR result set, if any, is retrieved in the order the REF_CURSOR parameter was registered with the query.

Specified by:

getSingleResultOrNull in interface Query

Returns:

the result or null if the next item is not a result set or if there is no result in the next result set

Throws:

NonUniqueResultException - if more than one result

QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back

PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back

getResultList

<R> List<R> getResultList(Class<R> resultClass)

Retrieve the list of results from the next result set, returning instances of the given result class, which overrides any result class already specified. The provider calls execute() if necessary. A REF_CURSOR result set, if any, is retrieved in the order the REF_CURSOR parameter was registered with the query.

Either:

• the result class is an entity class and is interpreted as a managed entity result with implicit field mappings determined by the names of the columns in the result set and the object/relational mapping of the entity,
• the result class is the class of a basic type and the result set must have a single column which is interpreted as a scalar result,
• the result class is a non-abstract class or record type with a constructor with the same number of parameters as the result set has columns, and is interpreted as a constructor result including all the columns of the result set, or
• the result class is Object[].class and each query result is packaged in an array of type Object[], with the array elements corresponding by position with the columns of the select list and column values obtained according to the default type mappings defined by the JDBC specification.

Parameters:

resultClass - The type of the query result

Returns:

a list of the results or null if the next item is not a result set

Throws:

QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back

PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back

Since:

4.0

getResultList

<R> List<R> getResultList(ResultSetMapping<R> mapping)

Retrieve the list of results from the next result set, specifying a result set mapping which overrides any mapping or result class already specified. The provider calls execute() if necessary. A REF_CURSOR result set, if any, is retrieved in the order the REF_CURSOR parameter was registered with the query.

Parameters:

mapping - The result set mapping to apply to the results

Returns:

a list of the results or null if the next item is not a result set

Throws:

QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back

PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back

Since:

4.0

getSingleResult

<R> R getSingleResult(Class<R> resultClass)

Retrieve a single result from the next result set, returning instances of the given result class, which overrides any result class already specified. The provider calls execute() if necessary. A REF_CURSOR result set, if any, is retrieved in the order the REF_CURSOR parameter was registered with the query.

Either:

• the result class is an entity class and is interpreted as a managed entity result with implicit field mappings determined by the names of the columns in the result set and the object/relational mapping of the entity,
• the result class is the class of a basic type and the result set must have a single column which is interpreted as a scalar result,
• the result class is a non-abstract class or record type with a constructor with the same number of parameters as the result set has columns, and is interpreted as a constructor result including all the columns of the result set, or
• the result class is Object[].class and each query result is packaged in an array of type Object[], with the array elements corresponding by position with the columns of the select list and column values obtained according to the default type mappings defined by the JDBC specification.

Parameters:

resultClass - The type of the query result

Returns:

the result or null if the next item is not a result set

Throws:

NoResultException - if there is no result in the next result set

NonUniqueResultException - if more than one result

QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back

PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back

Since:

4.0

getSingleResult

<R> R getSingleResult(ResultSetMapping<R> mapping)

Retrieve a single result from the next result set, specifying a result set mapping which overrides any mapping or result class already specified. The provider calls execute() if necessary. A REF_CURSOR result set, if any, is retrieved in the order the REF_CURSOR parameter was registered with the query.

Parameters:

mapping - The result set mapping to apply to the results

Returns:

the result or null if the next item is not a result set

Throws:

NoResultException - if there is no result in the next result set

NonUniqueResultException - if more than one result

QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back

PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back

Since:

4.0

getSingleResultOrNull

<R> R getSingleResultOrNull(Class<R> resultClass)

Retrieve a single result from the next result set, returning instances of the given result class, which overrides any result class already specified. The provider calls execute() if necessary. A REF_CURSOR result set, if any, is retrieved in the order the REF_CURSOR parameter was registered with the query.

Either:

• the result class is an entity class and is interpreted as a managed entity result with implicit field mappings determined by the names of the columns in the result set and the object/relational mapping of the entity,
• the result class is the class of a basic type and the result set must have a single column which is interpreted as a scalar result,
• the result class must be a non-abstract class or record type with a constructor with the same number of parameters as the result set has columns, and is interpreted as a constructor result including all the columns of the result set, or
• the result class is Object[].class and each query result is packaged in an array of type Object[], with the array elements corresponding by position with the columns of the select list and column values obtained according to the default type mappings defined by the JDBC specification.

Parameters:

resultClass - The type of the query result

Returns:

the result or null if the next item is not a result set or if there is no result in the next result set

Throws:

NonUniqueResultException - if more than one result

QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back

PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back

Since:

4.0

getSingleResultOrNull

<R> R getSingleResultOrNull(ResultSetMapping<R> mapping)

Retrieve a single result from the next result set, specifying a result set mapping which overrides any mapping or result class already specified. The provider calls execute() if necessary. A REF_CURSOR result set, if any, is retrieved in the order the REF_CURSOR parameter was registered with the query.

Either:

• the result class is an entity class and is interpreted as a managed entity result with implicit field mappings determined by the names of the columns in the result set and the object/relational mapping of the entity,
• the result class is the class of a basic type and the result set must have a single column which is interpreted as a scalar result, or
• the result class must be a non-abstract class or record type with a constructor with the same number of parameters as the result set has columns, and is interpreted as a constructor result including all the columns of the result set.

Parameters:

mapping - The result set mapping to apply to the results

Returns:

the result or null if the next item is not a result set or if there is no result in the next result set

Throws:

NonUniqueResultException - if more than one result

QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back

PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back

Since:

4.0

hasMoreResults

boolean hasMoreResults()

Return true if the next result corresponds to a result set, and false if it is an update count or if there are no results other than through INOUT and OUT parameters, if any.

Returns:

true if the next result is a result set

Throws:

QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back

PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back

getUpdateCount

int getUpdateCount()

Return the update count or -1 if there is no pending result or if the next result is not an update count.

Returns:

the update count or -1 if there is no pending result or if the next result is not an update count

Throws:

QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back

PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back

close

void close()

Immediately destroy all resources associated with this query. If the client does not call this method before the end of the current transaction, the behavior is undefined. A provider might release resources when all query results are exhausted, at the end of the current transaction, or when the entity manager or entity agent is closed.

After invocation of close(), every method of the StoredProcedureQuery throws IllegalStateException.

Specified by:

close in interface AutoCloseable

Since:

4.0