javax.persistence.StoredProcedureQuery Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of hibernate-jpa-2.1-api Show documentation
Show all versions of hibernate-jpa-2.1-api Show documentation
Clean-room definition of JPA APIs intended for use in developing Hibernate JPA implementation. See README.md for details
/*
* Copyright (c) 2008, 2009, 2011 Oracle, Inc. 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.
*/
package javax.persistence;
import java.util.Calendar;
import java.util.Date;
/**
* Interface used to control stored procedure query execution.
*
* @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 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 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 positional 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.
* When using parameter names, all parameters must be registered
* in the order in which they occur in the parameter list of the
* stored procedure.
*
* @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 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();
}