/******************************************************************************* | |
* Copyright (c) 2008 - 2013 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 | |
* Linda DeMichiel - Java Persistence 2.0 | |
* | |
******************************************************************************/ | |
package javax.persistence; | |
import java.util.List; | |
import java.util.Date; | |
import java.util.Calendar; | |
/** | |
* Interface used to control the execution of typed queries. | |
* @param <X> query result type | |
* | |
* @see Query | |
* @see Parameter | |
* | |
* @since Java Persistence 2.0 | |
*/ | |
public interface TypedQuery<X> extends Query { | |
/** | |
* Execute a SELECT query and return the query results | |
* as a typed List. | |
* @return a list of the results | |
* @throws IllegalStateException if called for a Java | |
* Persistence query language UPDATE or DELETE statement | |
* @throws QueryTimeoutException if the query execution exceeds | |
* the query timeout value set and only the statement is | |
* rolled back | |
* @throws TransactionRequiredException if a lock mode other than | |
* <code>NONE</code> has been set and there is no transaction | |
* or the persistence context has not been joined to the | |
* transaction | |
* @throws PessimisticLockException if pessimistic locking | |
* fails and the transaction is rolled back | |
* @throws LockTimeoutException if pessimistic locking | |
* fails 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<X> getResultList(); | |
/** | |
* Execute a SELECT query that returns a single result. | |
* @return the result | |
* @throws NoResultException if there is no result | |
* @throws NonUniqueResultException if more than one result | |
* @throws IllegalStateException if called for a Java | |
* Persistence query language UPDATE or DELETE statement | |
* @throws QueryTimeoutException if the query execution exceeds | |
* the query timeout value set and only the statement is | |
* rolled back | |
* @throws TransactionRequiredException if a lock mode other than | |
* <code>NONE</code> has been set and there is no transaction | |
* or the persistence context has not been joined to the | |
* transaction | |
* @throws PessimisticLockException if pessimistic locking | |
* fails and the transaction is rolled back | |
* @throws LockTimeoutException if pessimistic locking | |
* fails 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 | |
*/ | |
X getSingleResult(); | |
/** | |
* Set the maximum number of results to retrieve. | |
* @param maxResult maximum number of results to retrieve | |
* @return the same query instance | |
* @throws IllegalArgumentException if the argument is negative | |
*/ | |
TypedQuery<X> setMaxResults(int maxResult); | |
/** | |
* Set the position of the first result to retrieve. | |
* @param startPosition position of the first result, | |
* numbered from 0 | |
* @return the same query instance | |
* @throws IllegalArgumentException if the argument is negative | |
*/ | |
TypedQuery<X> setFirstResult(int startPosition); | |
/** | |
* 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 and the locking mechanisms used by the provider, | |
* this hint may or may not be observed. | |
* @param hintName name of 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 | |
*/ | |
TypedQuery<X> 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> TypedQuery<X> 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 | |
*/ | |
TypedQuery<X> 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 | |
*/ | |
TypedQuery<X> 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 | |
*/ | |
TypedQuery<X> 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 | |
*/ | |
TypedQuery<X> 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 | |
*/ | |
TypedQuery<X> 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 | |
*/ | |
TypedQuery<X> 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 | |
*/ | |
TypedQuery<X> 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 | |
*/ | |
TypedQuery<X> 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 | |
*/ | |
TypedQuery<X> setFlushMode(FlushModeType flushMode); | |
/** | |
* Set the lock mode type to be used for the query execution. | |
* @param lockMode lock mode | |
* @return the same query instance | |
* @throws IllegalStateException if the query is found not to | |
* be a Java Persistence query language SELECT query | |
* or a CriteriaQuery query | |
*/ | |
TypedQuery<X> setLockMode(LockModeType lockMode); | |
} |