Module jakarta.persistence
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(jakarta.persistence.Parameter<T>, 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: