jakarta.persistence.StoredProcedureQuery Maven / Gradle / Ivy
/*
* Copyright (c) 2011, 2020 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0,
* or the Eclipse Distribution License v. 1.0 which is available at
* http://www.eclipse.org/org/documents/edl-v10.php.
*
* SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
*/
// Contributors:
// Linda DeMichiel - 2.1
package jakarta.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 Query
* @see Parameter
*
* @since 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.
* @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.
* @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
*/
StoredProcedureQuery setParameter(Parameter param,
T value);
/**
* Bind an instance of java.util.Calendar to a Parameter 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 param,
Calendar value,
TemporalType temporalType);
/**
* Bind an instance of java.util.Date to a Parameter 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 param,
Date value,
TemporalType temporalType);
/**
* 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.
* @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.
* @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.
* @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.
* @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.
* @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.
* @param flushMode flush mode
* @return the same query instance
*/
StoredProcedureQuery setFlushMode(FlushModeType flushMode);
/**
* 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.
* @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
*/
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
*/
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.
* @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.
* @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.
* @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.
* @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.
* @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.
* @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();
}