javax.persistence.StoredProcedureQuery Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of javax.persistence Show documentation
Show all versions of javax.persistence Show documentation
javax.persistence build based upon git transaction cfcdce1
/*******************************************************************************
* 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 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.
* @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();
}