https://github.com/javaee/jpa-spec: Java(TM) Persistence API 
Copyright (c) 2011 - 2017 Oracle Corporation. All rights reserved.
This program and the accompanying materials are made available under the
terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0
which accompanies this distribution.
The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
and the Eclipse Distribution License is available at
http://www.eclipse.org/org/documents/edl-v10.php.
Contributors:
    Linda DeMichiel - Java Persistence 2.1

/*******************************************************************************
 * Copyright (c) 2011 - 2017 Oracle Corporation. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0
 * which accompanies this distribution.
 * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
 * and the Eclipse Distribution License is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * Contributors:
 *     Linda DeMichiel - Java Persistence 2.1
 *
 ******************************************************************************/ 
package javax.persistence;

import java.util.Calendar;
import java.util.Date;
import java.util.List;


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 
will call 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 will be 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.
    • 



See Also:
Since:Java Persistence 2.1
/**
 * Interface used to control stored procedure query execution.
 *
 * <p>
 * Stored procedure query execution may be controlled in accordance with 
 * the following:
 * <ul>
 * <li>The <code>setParameter</code> methods are used to set the values of 
 * all required <code>IN</code> and <code>INOUT</code> parameters.  
 * It is not required to set the values of stored procedure parameters 
 * for which default values have been defined by the stored procedure.</li>
 * <li>
 * When <code>getResultList</code> and <code>getSingleResult</code> are
 * called on a <code>StoredProcedureQuery</code> object, the provider 
 * will call <code>execute</code> on an unexecuted stored procedure 
 * query before processing <code>getResultList</code> or
 * <code>getSingleResult</code>.</li>
 * <li>
 * When <code>executeUpdate</code> is called on a 
 * <code>StoredProcedureQuery</code> object, the provider will call 
 * <code>execute</code> on an unexecuted stored procedure query
 *  followed by <code>getUpdateCount</code>.  The results of 
 * <code>executeUpdate</code> will be those of <code>getUpdateCount</code>.</li>
 * <li>
 * The <code>execute</code> method supports both the simple case where 
 * scalar results are passed back only via <code>INOUT</code> and 
 * <code>OUT</code> parameters as well as the most general case 
 * (multiple result sets and/or update counts, possibly also in 
 * combination with output parameter values).</li>
 * <li>
 * The <code>execute</code> 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 <code>INOUT</code> and <code>OUT</code> parameters, 
 * if any.</li>
 * <li>
 * If the <code>execute</code> method returns true, the pending result set 
 * can be obtained by calling <code>getResultList</code> or
 * <code>getSingleResult</code>.</li>
 * <li>
 * The <code>hasMoreResults</code> method can then be used to test 
 * for further results.</li>
 * <li>
 * If <code>execute</code> or <code>hasMoreResults</code> returns false, 
 * the <code>getUpdateCount</code> method can be called to obtain the 
 * pending result if it is an update count.  The <code>getUpdateCount</code>
 * 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).</li>
 * <li>
 * For portability, results that correspond to JDBC result sets and 
 * update counts need to be processed before the values of any 
 * <code>INOUT</code> or <code>OUT</code> parameters are extracted.</li>
 * <li>
 * After results returned through <code>getResultList</code> and 
 * <code>getUpdateCount</code> have been exhausted, results returned through 
 * <code>INOUT</code> and <code>OUT</code> parameters can be retrieved.</li>
 * <li>
 * The <code>getOutputParameterValue</code> methods are used to retrieve 
 * the values passed back from the procedure through <code>INOUT</code> 
 * and <code>OUT</code> parameters.</li>
 * <li>
 * When using <code>REF_CURSOR</code> parameters for result sets the
 * update counts should be exhausted before calling <code>getResultList</code>
 * to retrieve the result set.  Alternatively, the <code>REF_CURSOR</code>
 * result set can be retrieved through <code>getOutputParameterValue</code>.
 * Result set mappings will be applied to results corresponding to
 * <code>REF_CURSOR</code> parameters in the order the <code>REF_CURSOR</code>
 * parameters were registered with the query.</li>
 * <li>
 * In the simplest case, where results are returned only via 
 * <code>INOUT</code> and <code>OUT</code> parameters, <code>execute</code>
 * can be followed immediately by calls to 
 * <code>getOutputParameterValue</code>.</li>
 * </ul>
 *
 * @see Query
 * @see Parameter
 *
 * @since Java Persistence 2.1
 */
public interface StoredProcedureQuery extends Query {

    
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.

Params:
  • hintName –  name of the property or hint
  • value –  value for the property or hint
Throws:
Returns:the same query instance
/**
     * 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.
     * @param hintName  name of the property or hint
     * @param value  value for the property or hint
     * @return the same query instance
     * @throws IllegalArgumentException if the second argument is not
     *         valid for the implementation
     */
    StoredProcedureQuery setHint(String hintName, Object value);

    
Bind the value of a Parameter object.

Params:
  • param –  parameter object
  • value –  parameter value
Throws:
Returns:the same query instance
/**
     * Bind the value of a <code>Parameter</code> object.
     * @param param  parameter object
     * @param value  parameter value
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter does not
     *         correspond to a parameter of the query
     */
    <T> StoredProcedureQuery setParameter(Parameter<T> param, 
                                          T value);

    
Bind an instance of java.util.Calendar to a Parameter object.

Params:
  • param – parameter object
  • value –  parameter value
  • temporalType –  temporal type
Throws:
Returns:the same query instance
/**
     * Bind an instance of <code>java.util.Calendar</code> to a <code>Parameter</code> object.
     * @param param parameter object
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter does not
     *         correspond to a parameter of the query
     */
    StoredProcedureQuery setParameter(Parameter<Calendar> param,
                                      Calendar value, 
                                      TemporalType temporalType);

    
Bind an instance of java.util.Date to a Parameter object.

Params:
  • param – parameter object
  • value –  parameter value
  • temporalType –  temporal type
Throws:
Returns:the same query instance
/**
     * Bind an instance of <code>java.util.Date</code> to a <code>Parameter</code> object.
     * @param param parameter object
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return the same query instance
     * @throws IllegalArgumentException if the parameter does not
     *         correspond to a parameter of the query
     */
    StoredProcedureQuery setParameter(Parameter<Date> param, 
                                      Date value, 
                                      TemporalType temporalType);

    
Bind an argument value to a named parameter.

Params:
  • name –  parameter name
  • value –  parameter value
Throws:
  • IllegalArgumentException – if the parameter name does 
        not correspond to a parameter of the query or if the
        argument is of incorrect type
Returns:the same query instance
/**
     * Bind an argument value to a named parameter.
     * @param name  parameter name
     * @param value  parameter value
     * @return 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
     */
    StoredProcedureQuery setParameter(String name, Object value);

    
Bind an instance of java.util.Calendar to a named parameter.

Params:
  • name –  parameter name
  • value –  parameter value
  • temporalType –  temporal type
Throws:
  • IllegalArgumentException – if the parameter name does 
        not correspond to a parameter of the query or if the
        value argument is of incorrect type
Returns:the same query instance
/**
     * Bind an instance of <code>java.util.Calendar</code> to a named parameter.
     * @param name  parameter name
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return 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
     */
    StoredProcedureQuery setParameter(String name, 
                                      Calendar value, 
                                      TemporalType temporalType);

    
Bind an instance of java.util.Date to a named parameter.

Params:
  • name –  parameter name
  • value –  parameter value
  • temporalType –  temporal type
Throws:
  • IllegalArgumentException – if the parameter name does 
        not correspond to a parameter of the query or if the
        value argument is of incorrect type
Returns:the same query instance
/**
     * Bind an instance of <code>java.util.Date</code> to a named parameter.
     * @param name  parameter name
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return 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
     */
    StoredProcedureQuery setParameter(String name, 
                                      Date value, 
                                      TemporalType temporalType);

    
Bind an argument value to a positional parameter.

Params:
  • position –  position
  • value –  parameter value
Throws:
  • IllegalArgumentException – if position does not
        correspond to a positional parameter of the query
        or if the argument is of incorrect type
Returns:the same query instance
/**
     * Bind an argument value to a positional parameter.
     * @param position  position
     * @param value  parameter value
     * @return 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
     */
    StoredProcedureQuery setParameter(int position, Object value);

    
Bind an instance of java.util.Calendar to a positional
parameter.

Params:
  • position –  position
  • value –  parameter value
  • temporalType –  temporal type
Throws:
  • IllegalArgumentException – if position does not
        correspond to a positional parameter of the query or
        if the value argument is of incorrect type
Returns:the same query instance
/**
     * Bind an instance of <code>java.util.Calendar</code> to a positional
     * parameter.
     * @param position  position
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return 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
     */
    StoredProcedureQuery setParameter(int position, 
                                      Calendar value,  
                                      TemporalType temporalType);

    
Bind an instance of java.util.Date to a positional parameter.

Params:
  • position –  position
  • value –  parameter value
  • temporalType –  temporal type
Throws:
  • IllegalArgumentException – if position does not
        correspond to a positional parameter of the query or
        if the value argument is of incorrect type
Returns:the same query instance
/**
     * Bind an instance of <code>java.util.Date</code> to a positional parameter.
     * @param position  position
     * @param value  parameter value
     * @param temporalType  temporal type
     * @return 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
     */
    StoredProcedureQuery setParameter(int position, 
                                      Date value,  
                                      TemporalType temporalType);

    
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.

Params:
  • flushMode –  flush mode
Returns:the same query instance
/**
     * 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.
     * @param flushMode  flush mode
     * @return the same query instance
     */
    StoredProcedureQuery setFlushMode(FlushModeType flushMode);

    
Register a positional parameter.
All parameters must be registered.

Params:
  • position –  parameter position
  • type –  type of the parameter
  • mode –  parameter mode
Returns:the same query instance
/**
     * Register a positional parameter.
     * All parameters must be registered.
     * @param position  parameter position
     * @param type  type of the parameter
     * @param mode  parameter mode 
     * @return the same query instance
     */
    StoredProcedureQuery registerStoredProcedureParameter(
	  int position,
	  Class type,
	  ParameterMode mode);

    
Register a named parameter.

Params:
  • parameterName –  name of the parameter as registered or
            specified in metadata
  • type –  type of the parameter
  • mode –  parameter mode
Returns:the same query instance
/**
     * Register a named parameter.
     * @param parameterName  name of the parameter as registered or
     *             specified in metadata
     * @param type  type of the parameter
     * @param mode  parameter mode 
     * @return the same query instance
     */
    StoredProcedureQuery registerStoredProcedureParameter(
	  String parameterName,
	  Class type,
	  ParameterMode mode);

    
 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.
 @param position  parameter position
 @return 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

/**
     *  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.
     *  @param position  parameter position
     *  @return 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
     */
    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.
 @param parameterName  name of the parameter as registered or
             specified in metadata
 @return 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

/**
     *  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.
     *  @param parameterName  name of the parameter as registered or
     *              specified in metadata
     *  @return 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
     */
    Object getOutputParameterValue(String parameterName);

    
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.

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
Returns: true if first result corresponds to result set
/**
     * 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.
     * @return  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 back
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction 
     *         is rolled back 
     */
    boolean execute();

    
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.

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
Returns:the update count or -1 if there is no pending result
or if the next result is not an update count.
/**
     * 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 <code>execute</code> on the query if needed.
     * @return 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
     * @throws QueryTimeoutException if the statement execution 
     *         exceeds the query timeout value set and only 
     *         the statement is rolled back
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction 
     *         is rolled back 
     */
    int executeUpdate();

    
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, will be retrieved
in the order the REF_CURSOR parameter was 
registered with the query.

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
Returns:a list of the results or null is the next item is not 
a result set
/**
     * Retrieve the list of results from the next result set.
     * The provider will call <code>execute</code> on the query
     * if needed.
     * A <code>REF_CURSOR</code> result set, if any, will be retrieved
     * in the order the <code>REF_CURSOR</code> parameter was 
     * registered with the query.
     * @return 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 back
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction 
     *         is rolled back 
     */
    List getResultList();

    
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, will be retrieved
in the order the REF_CURSOR parameter was 
registered with the query.

Throws:
Returns:the result or null if the next item is not a result set
/**
     * Retrieve a single result from the next result set.
     * The provider will call <code>execute</code> on the query
     * if needed.
     * A <code>REF_CURSOR</code> result set, if any, will be retrieved
     * in the order the <code>REF_CURSOR</code> parameter was 
     * registered with the query.
     * @return 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
     * @throws NonUniqueResultException if more than one result
     * @throws QueryTimeoutException if the query execution exceeds
     *         the query timeout value set and only the statement is
     *         rolled back
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction 
     *         is rolled back 
     */
    Object getSingleResult();

    
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.

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
Returns: true if next result corresponds to result set
/**
     * 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.
     * @return  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 back
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction 
     *         is rolled back 
     */
    boolean hasMoreResults();

    
Return 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
Returns: update count or -1 if there is no pending result or if
         the next result is not an update count
/**
     * Return the update count or  -1 if there is no pending result
     * or if the next result is not an update count.
     * @return  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
     * @throws PersistenceException if the query execution exceeds 
     *         the query timeout value set and the transaction 
     *         is rolled back 
     */
    int getUpdateCount();

}