Jakarta EE 11.0.0 · jakarta.persistence.StoredProcedureQuery

Interface used to control stored procedure query execution.

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

The setParameter 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 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. 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.

Method Summary

Modifier and Type	Method and Description
public boolean	Returns: true if first result corresponds to result set 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.
public int	Returns: the update count or -1 if there is no pending result or if the next result is not an update count. executeUpdate() Redeclares jakarta.persistence.Query.executeUpdate. Return the update count of -1 if there is no pending result or if the first result is not an update count.
public Object	Returns: the result that is passed back through the parameter getOutputParameterValue(int parameter position position) Retrieve a value passed back from the procedure through an INOUT or OUT parameter.
public Object	Returns: the result that is passed back through the parameter getOutputParameterValue(String name of the parameter as registered or specified in metadata parameterName) Retrieve a value passed back from the procedure through an INOUT or OUT parameter.
public List<E>	Returns: a list of the results or null is the next item is not a result set getResultList() Redeclares jakarta.persistence.Query.getResultList. Retrieve the list of results from the next result set.
public Object	Returns: the result or null if the next item is not a result set getSingleResult() Redeclares jakarta.persistence.Query.getSingleResult. Retrieve a single result from the next result set.
public Object	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 getSingleResultOrNull() Redeclares jakarta.persistence.Query.getSingleResultOrNull. Retrieve a single result from the next result set.
public int	Returns: update count or -1 if there is no pending result or if the next result is not an update count getUpdateCount() Return the update count or -1 if there is no pending result or if the next result is not an update count.
public boolean	Returns: true if next result corresponds to result set 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.
public StoredProcedureQuery	Returns: the same query instance registerStoredProcedureParameter(int parameter position position, Class<?> type of the parameter type, ParameterMode parameter mode mode) Register a positional parameter.
public StoredProcedureQuery	Returns: the same query instance registerStoredProcedureParameter(String name of the parameter as registered or specified in metadata parameterName, Class<?> type of the parameter type, ParameterMode parameter mode mode) Register a named parameter.
public StoredProcedureQuery	Returns: the same query instance setCacheRetrieveMode(CacheRetrieveMode cache retrieval mode cacheRetrieveMode) Redeclares jakarta.persistence.Query.setCacheRetrieveMode. Set the cache retrieval mode that is in effect during query execution.
public StoredProcedureQuery	Returns: the same query instance setCacheStoreMode(CacheStoreMode cache storage mode cacheStoreMode) Redeclares jakarta.persistence.Query.setCacheStoreMode. Set the cache storage mode that is in effect during query execution.
public StoredProcedureQuery	Returns: the same query instance setFlushMode(FlushModeType flush mode flushMode) Redeclares jakarta.persistence.Query.setFlushMode. Set the flush mode type to be used for the query execution.
public StoredProcedureQuery	Returns: the same query instance setHint(String name of the property or hint hintName, Object value for the property or hint value) Redeclares jakarta.persistence.Query.setHint. Set a query property or hint.
public <T> StoredProcedureQuery	Returns: the same query instance setParameter(Parameter<T> parameter object param, T parameter value value) Redeclares jakarta.persistence.Query.setParameter. Bind the value of a `Parameter` object.
public StoredProcedureQuery	Returns: the same query instance setParameter(Parameter<Calendar> parameter object param, Calendar parameter value value, TemporalType temporal type temporalType) Redeclares jakarta.persistence.Query.setParameter. Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Calendar` to a `Parameter` object.
public StoredProcedureQuery	Returns: the same query instance setParameter(Parameter<Date> parameter object param, Date parameter value value, TemporalType temporal type temporalType) Redeclares jakarta.persistence.Query.setParameter. Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Date` to a `Parameter` object.
public StoredProcedureQuery	Returns: the same query instance setParameter(String parameter name name, Object parameter value value) Redeclares jakarta.persistence.Query.setParameter. Bind an argument value to a named parameter.
public StoredProcedureQuery	Returns: the same query instance setParameter(String parameter name name, Calendar parameter value value, TemporalType temporal type temporalType) Redeclares jakarta.persistence.Query.setParameter. Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Calendar` to a named parameter.
public StoredProcedureQuery	Returns: the same query instance setParameter(String parameter name name, Date parameter value value, TemporalType temporal type temporalType) Redeclares jakarta.persistence.Query.setParameter. Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Date` to a named parameter.
public StoredProcedureQuery	Returns: the same query instance setParameter(int position position, Object parameter value value) Redeclares jakarta.persistence.Query.setParameter. Bind an argument value to a positional parameter.
public StoredProcedureQuery	Returns: the same query instance setParameter(int position position, Calendar parameter value value, TemporalType temporal type temporalType) Redeclares jakarta.persistence.Query.setParameter. Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Calendar` to a positional parameter.
public StoredProcedureQuery	Returns: the same query instance setParameter(int position position, Date parameter value value, TemporalType temporal type temporalType) Redeclares jakarta.persistence.Query.setParameter. Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Date` to a positional parameter.
public StoredProcedureQuery	Returns: the same query instance setTimeout(Integer the timeout, in milliseconds, or null to indicate no timeout timeout) Redeclares jakarta.persistence.Query.setTimeout. Set the query timeout, in milliseconds.

Method Detail

execute	back to summary
public 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:boolean true if first result corresponds to result set Exceptions 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

execute

back to summary

public 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:boolean

true if first result corresponds to result set

Exceptions

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 back to summary

executeUpdate	back to summary
public int executeUpdate() Redeclares jakarta.persistence.Query.executeUpdate. Return the update count of -1 if there is no pending result or if the first result is not an update count. The provider will call `execute` on the query if needed. Returns:int the update count or -1 if there is no pending result or if the next result is not an update count. Exceptions 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

public int executeUpdate()

Redeclares jakarta.persistence.Query.executeUpdate.

Return the update count of -1 if there is no pending result or if the first result is not an update count. The provider will call execute on the query if needed.

Returns:int

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

Exceptions

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

getOutputParameterValue	back to summary
public 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:int parameter position Returns:Object the result that is passed back through the parameter Exceptions IllegalArgumentException: if the position does not correspond to a parameter of the query or is not an INOUT or OUT parameter

getOutputParameterValue

back to summary

public 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:int: parameter position

Returns:Object

the result that is passed back through the parameter

Exceptions

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

getOutputParameterValue	back to summary
public 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:String name of the parameter as registered or specified in metadata Returns:Object the result that is passed back through the parameter Exceptions IllegalArgumentException: if the parameter name does not correspond to a parameter of the query or is not an INOUT or OUT parameter

getOutputParameterValue

back to summary

public Object getOutputParameterValue(String parameterName)

Parameters

parameterName:String: name of the parameter as registered or specified in metadata

Returns:Object

the result that is passed back through the parameter

Exceptions

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

getResultList back to summary

getResultList	back to summary
public List<E> getResultList() Redeclares jakarta.persistence.Query.getResultList. Retrieve the list of results from the next result set. The provider will call `execute` on the query if needed. A `REF_CURSOR` result set, if any, is retrieved in the order the `REF_CURSOR` parameter was registered with the query. Returns:List<E> a list of the results or null is the next item is not a result set Exceptions 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

public List<E> getResultList()

Redeclares jakarta.persistence.Query.getResultList.

Retrieve the list of results from the next result set. The provider will call execute on the query if needed. A REF_CURSOR result set, if any, is retrieved in the order the REF_CURSOR parameter was registered with the query.

Returns:List<E>

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

Exceptions

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 back to summary

getSingleResult	back to summary
public Object getSingleResult() Redeclares jakarta.persistence.Query.getSingleResult. Retrieve a single result from the next result set. The provider will call `execute` on the query if needed. A `REF_CURSOR` result set, if any, is retrieved in the order the `REF_CURSOR` parameter was registered with the query. Returns:Object the result or null if the next item is not a result set Exceptions 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

public Object getSingleResult()

Redeclares jakarta.persistence.Query.getSingleResult.

Retrieve a single result from the next result set. The provider will call execute on the query if needed. A REF_CURSOR result set, if any, is retrieved in the order the REF_CURSOR parameter was registered with the query.

Returns:Object

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

Exceptions

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 back to summary

getSingleResultOrNull	back to summary
public Object getSingleResultOrNull() Redeclares jakarta.persistence.Query.getSingleResultOrNull. Retrieve a single result from the next result set. The provider will call `execute` on the query if needed. A `REF_CURSOR` result set, if any, is retrieved in the order the `REF_CURSOR` parameter was registered with the query. Returns:Object the result or null if the next item is not a result set or if there is no result in the next result set Exceptions 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

public Object getSingleResultOrNull()

Redeclares jakarta.persistence.Query.getSingleResultOrNull.

Returns:Object

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

Exceptions

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

getUpdateCount	back to summary
public 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:int update count or -1 if there is no pending result or if the next result is not an update count Exceptions 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

back to summary

public 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:int

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

Exceptions

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

hasMoreResults	back to summary
public 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:boolean true if next result corresponds to result set Exceptions 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

hasMoreResults

back to summary

public 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:boolean

true if next result corresponds to result set

Exceptions

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

registerStoredProcedureParameter	back to summary
public StoredProcedureQuery registerStoredProcedureParameter(int position, Class<?> type, ParameterMode mode) Register a positional parameter. All parameters must be registered. Parameters position:int parameter position type:Class<?> type of the parameter mode:ParameterMode parameter mode Returns:StoredProcedureQuery the same query instance

registerStoredProcedureParameter

back to summary

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

Parameters

position:int: parameter position
type:Class<?>: type of the parameter
mode:ParameterMode: parameter mode

public Interface StoredProcedureQuery

Method Summary

Method Detail