Package jakarta.persistence
Interface StoredProcedureQuery
-
- All Superinterfaces:
Query
public interface StoredProcedureQuery extends Query
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 requiredIN
andINOUT
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
andgetSingleResult
are called on aStoredProcedureQuery
object, the provider will callexecute
on an unexecuted stored procedure query before processinggetResultList
orgetSingleResult
. -
When
executeUpdate
is called on aStoredProcedureQuery
object, the provider will callexecute
on an unexecuted stored procedure query followed bygetUpdateCount
. The results ofexecuteUpdate
will be those ofgetUpdateCount
. -
The
execute
method supports both the simple case where scalar results are passed back only viaINOUT
andOUT
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 throughINOUT
andOUT
parameters, if any. -
If the
execute
method returns true, the pending result set can be obtained by callinggetResultList
orgetSingleResult
. -
The
hasMoreResults
method can then be used to test for further results. -
If
execute
orhasMoreResults
returns false, thegetUpdateCount
method can be called to obtain the pending result if it is an update count. ThegetUpdateCount
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
orOUT
parameters are extracted. -
After results returned through
getResultList
andgetUpdateCount
have been exhausted, results returned throughINOUT
andOUT
parameters can be retrieved. -
The
getOutputParameterValue
methods are used to retrieve the values passed back from the procedure throughINOUT
andOUT
parameters. -
When using
REF_CURSOR
parameters for result sets the update counts should be exhausted before callinggetResultList
to retrieve the result set. Alternatively, theREF_CURSOR
result set can be retrieved throughgetOutputParameterValue
. Result set mappings will be applied to results corresponding toREF_CURSOR
parameters in the order theREF_CURSOR
parameters were registered with the query. -
In the simplest case, where results are returned only via
INOUT
andOUT
parameters,execute
can be followed immediately by calls togetOutputParameterValue
.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description 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 of -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.Object
getOutputParameterValue(String parameterName)
Retrieve a value passed back from the procedure through an INOUT or OUT parameter.List
getResultList()
Retrieve the list of results from the next result set.Object
getSingleResult()
Retrieve a single result from the next result set.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.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
setFlushMode(FlushModeType flushMode)
Set the flush mode type to be used for the query execution.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)
Bind an instance ofjava.util.Calendar
to a positional parameter.StoredProcedureQuery
setParameter(int position, Date value, TemporalType temporalType)
Bind an instance ofjava.util.Date
to a positional parameter.StoredProcedureQuery
setParameter(Parameter<Calendar> param, Calendar value, TemporalType temporalType)
Bind an instance ofjava.util.Calendar
to aParameter
object.StoredProcedureQuery
setParameter(Parameter<Date> param, Date value, TemporalType temporalType)
Bind an instance ofjava.util.Date
to aParameter
object.<T> StoredProcedureQuery
setParameter(Parameter<T> param, T value)
Bind the value of aParameter
object.StoredProcedureQuery
setParameter(String name, Object value)
Bind an argument value to a named parameter.StoredProcedureQuery
setParameter(String name, Calendar value, TemporalType temporalType)
Bind an instance ofjava.util.Calendar
to a named parameter.StoredProcedureQuery
setParameter(String name, Date value, TemporalType temporalType)
Bind an instance ofjava.util.Date
to a named parameter.-
Methods inherited from interface jakarta.persistence.Query
getFirstResult, getFlushMode, getHints, getLockMode, getMaxResults, getParameter, getParameter, getParameter, getParameter, getParameters, getParameterValue, getParameterValue, getParameterValue, getResultStream, isBound, setFirstResult, setLockMode, setMaxResults, unwrap
-
-
-
-
Method Detail
-
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 interfaceQuery
- Parameters:
hintName
- name of the property or hintvalue
- 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> param, T value)
Bind the value of aParameter
object.- Specified by:
setParameter
in interfaceQuery
- Parameters:
param
- parameter objectvalue
- parameter value- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if the parameter does not correspond to a parameter of the query
-
setParameter
StoredProcedureQuery setParameter(Parameter<Calendar> param, Calendar value, TemporalType temporalType)
Bind an instance ofjava.util.Calendar
to aParameter
object.- Specified by:
setParameter
in interfaceQuery
- Parameters:
param
- parameter objectvalue
- parameter valuetemporalType
- temporal type- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if the parameter does not correspond to a parameter of the query
-
setParameter
StoredProcedureQuery setParameter(Parameter<Date> param, Date value, TemporalType temporalType)
Bind an instance ofjava.util.Date
to aParameter
object.- Specified by:
setParameter
in interfaceQuery
- Parameters:
param
- parameter objectvalue
- parameter valuetemporalType
- 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 interfaceQuery
- Parameters:
name
- parameter namevalue
- parameter value- 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 incorrect type
-
setParameter
StoredProcedureQuery setParameter(String name, Calendar value, TemporalType temporalType)
Bind an instance ofjava.util.Calendar
to a named parameter.- Specified by:
setParameter
in interfaceQuery
- Parameters:
name
- parameter namevalue
- parameter valuetemporalType
- 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 incorrect type
-
setParameter
StoredProcedureQuery setParameter(String name, Date value, TemporalType temporalType)
Bind an instance ofjava.util.Date
to a named parameter.- Specified by:
setParameter
in interfaceQuery
- Parameters:
name
- parameter namevalue
- parameter valuetemporalType
- 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 incorrect type
-
setParameter
StoredProcedureQuery setParameter(int position, Object value)
Bind an argument value to a positional parameter.- Specified by:
setParameter
in interfaceQuery
- Parameters:
position
- positionvalue
- parameter value- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if position does not correspond to a positional parameter of the query or if the argument is of incorrect type
-
setParameter
StoredProcedureQuery setParameter(int position, Calendar value, TemporalType temporalType)
Bind an instance ofjava.util.Calendar
to a positional parameter.- Specified by:
setParameter
in interfaceQuery
- Parameters:
position
- positionvalue
- parameter valuetemporalType
- temporal type- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if position does not correspond to a positional parameter of the query or if the value argument is of incorrect type
-
setParameter
StoredProcedureQuery setParameter(int position, Date value, TemporalType temporalType)
Bind an instance ofjava.util.Date
to a positional parameter.- Specified by:
setParameter
in interfaceQuery
- Parameters:
position
- positionvalue
- parameter valuetemporalType
- temporal type- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if position does not correspond to a positional parameter of the query or if the value argument is of incorrect type
-
setFlushMode
StoredProcedureQuery setFlushMode(FlushModeType flushMode)
Set the flush mode type to be used for the query execution. The flush mode type applies to the query regardless of the flush mode type in use for the entity manager.- Specified by:
setFlushMode
in interfaceQuery
- Parameters:
flushMode
- flush mode- Returns:
- the same query instance
-
registerStoredProcedureParameter
StoredProcedureQuery registerStoredProcedureParameter(int position, Class type, ParameterMode mode)
Register a positional parameter. All parameters must be registered.- Parameters:
position
- parameter positiontype
- type of the parametermode
- parameter mode- Returns:
- the same query instance
-
registerStoredProcedureParameter
StoredProcedureQuery registerStoredProcedureParameter(String parameterName, Class type, ParameterMode mode)
Register a named parameter.- Parameters:
parameterName
- name of the parameter as registered or specified in metadatatype
- type of the parametermode
- 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
- 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
-
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 first result corresponds to result set
- Throws:
QueryTimeoutException
- if the query execution exceeds the query timeout value set and only the statement is rolled backPersistenceException
- if the query execution exceeds the query timeout value set and the transaction is rolled back
-
executeUpdate
int 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 callexecute
on the query if needed.- Specified by:
executeUpdate
in interfaceQuery
- 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 transactionQueryTimeoutException
- if the statement execution exceeds the query timeout value set and only the statement is rolled backPersistenceException
- if the query execution exceeds the query timeout value set and the transaction is rolled back
-
getResultList
List getResultList()
Retrieve the list of results from the next result set. The provider will callexecute
on the query if needed. AREF_CURSOR
result set, if any, will be retrieved in the order theREF_CURSOR
parameter was registered with the query.- Specified by:
getResultList
in interfaceQuery
- Returns:
- a list of the results or null is 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 backPersistenceException
- 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 will callexecute
on the query if needed. AREF_CURSOR
result set, if any, will be retrieved in the order theREF_CURSOR
parameter was registered with the query.- Specified by:
getSingleResult
in interfaceQuery
- 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 setNonUniqueResultException
- if more than one resultQueryTimeoutException
- if the query execution exceeds the query timeout value set and only the statement is rolled backPersistenceException
- if the query execution exceeds the query timeout value set and the transaction is rolled back
-
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 next result corresponds to result set
- Throws:
QueryTimeoutException
- if the query execution exceeds the query timeout value set and only the statement is rolled backPersistenceException
- 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:
- 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 backPersistenceException
- if the query execution exceeds the query timeout value set and the transaction is rolled back
-
-