Java tutorial
/******************************************************************************* * 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. * * <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. * @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 <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 <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 <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. * @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 <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 <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. * @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 <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 <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. * @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 <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 <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 <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. * @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(); }