fine-third/fine-jpa/src/com/fr/third/javax/persistence/StoredProcedureQuery.java

/*
 * 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 com.fr.third.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
	 */
	<T> StoredProcedureQuery setParameter(
			Parameter<T> 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<Calendar> 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<Date> 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
	 * <p/>
	 * 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();

}