/*
 * 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;
import java.util.List;
import java.util.Map;
import java.util.Set;

Interface used to control query execution.
See Also:
TypedQuery
Parameter
Since:
Java Persistence 1.0/**
 * Interface used to control query execution.
 *
 * @see TypedQuery
 * @see Parameter
 * @since Java Persistence 1.0
 */
public interface Query {

  
Execute a SELECT query and return the query results
as an untyped List.
Throws:
IllegalStateException –        if called for a Java
                                     Persistence query language UPDATE or DELETE statement
QueryTimeoutException –        if the query execution exceeds
                                     the query timeout value set and only the statement is
                                     rolled back
TransactionRequiredException – if a lock mode has
                                     been set and there is no transaction
PessimisticLockException –     if pessimistic locking
                                     fails and the transaction is rolled back
LockTimeoutException –         if pessimistic locking
                                     fails and only the statement is rolled back
PersistenceException –         if the query execution exceeds
                                     the query timeout value set and the transaction
                                     is rolled back
Returns:
a list of the results/**
   * Execute a SELECT query and return the query results
   * as an untyped 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 has
   *                                      been set and there is no 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 getResultList();

  
Execute a SELECT query that returns a single untyped result.
Throws:
NoResultException –            if there is no result
NonUniqueResultException –     if more than one result
IllegalStateException –        if called for a Java
                                     Persistence query language UPDATE or DELETE statement
QueryTimeoutException –        if the query execution exceeds
                                     the query timeout value set and only the statement is
                                     rolled back
TransactionRequiredException – if a lock mode has
                                     been set and there is no transaction
PessimisticLockException –     if pessimistic locking
                                     fails and the transaction is rolled back
LockTimeoutException –         if pessimistic locking
                                     fails and only the statement is rolled back
PersistenceException –         if the query execution exceeds
                                     the query timeout value set and the transaction
                                     is rolled back
Returns:
the result/**
   * Execute a SELECT query that returns a single untyped 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 has
   *                                      been set and there is no 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
   */
  Object getSingleResult();

  
Execute an update or delete statement.
Throws:
IllegalStateException –        if called for a Java
                                     Persistence query language SELECT statement or for
                                     a criteria query
TransactionRequiredException – if there is
                                     no transaction
QueryTimeoutException –        if the statement execution
                                     exceeds the query timeout value set and only
                                     the statement is rolled back
PersistenceException –         if the query execution exceeds
                                     the query timeout value set and the transaction
                                     is rolled back
Returns:
the number of entities updated or deleted/**
   * Execute an update or delete statement.
   *
   * @return the number of entities updated or deleted
   * @throws IllegalStateException        if called for a Java
   *                                      Persistence query language SELECT statement or for
   *                                      a criteria query
   * @throws TransactionRequiredException if there is
   *                                      no 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();

  
Set the maximum number of results to retrieve.
Params:
maxResult – maximum number of results to retrieve
Throws:
IllegalArgumentException – if the argument is negative
Returns:
the same query instance/**
   * 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
   */
  Query setMaxResults(int maxResult);

  
The maximum number of results the query object was set to
retrieve. Returns Integer.MAX_VALUE if setMaxResults was not
applied to the query object.
Returns:
maximum number of results
Since:
Java Persistence 2.0/**
   * The maximum number of results the query object was set to
   * retrieve. Returns <code>Integer.MAX_VALUE</code> if <code>setMaxResults</code> was not
   * applied to the query object.
   *
   * @return maximum number of results
   * @since Java Persistence 2.0
   */
  int getMaxResults();

  
Set the position of the first result to retrieve.
Params:
startPosition – position of the first result,
                     numbered from 0
Throws:
IllegalArgumentException – if the argument is negative
Returns:
the same query instance/**
   * 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
   */
  Query setFirstResult(int startPosition);

  
The position of the first result the query object was set to
retrieve. Returns 0 if setFirstResult was not applied to the
query object.
Returns:
position of the first result
Since:
Java Persistence 2.0/**
   * The position of the first result the query object was set to
   * retrieve. Returns 0 if <code>setFirstResult</code> was not applied to the
   * query object.
   *
   * @return position of the first result
   * @since Java Persistence 2.0
   */
  int getFirstResult();

  
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.
Params:
hintName – name of the property or hint
value –    value for the property or hint
Throws:
IllegalArgumentException – if the second argument is not
                                 valid for the implementation
Returns:
the same query instance/**
   * 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 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
   */
  Query setHint(String hintName, Object value);

  
Get the properties and hints and associated values that are
in effect for the query instance.
Returns:
query properties and hints
Since:
Java Persistence 2.0/**
   * Get the properties and hints and associated values that are
   * in effect for the query instance.
   *
   * @return query properties and hints
   * @since Java Persistence 2.0
   */
  Map<String, Object> getHints();

  
Bind the value of a Parameter object.
Params:
param – parameter object
value – parameter value
Type parameters:
<T> –   type
Throws:
IllegalArgumentException – if the parameter
                                 does not correspond to a parameter of the
                                 query
Returns:
the same query instance
Since:
Java Persistence 2.0/**
   * Bind the value of a <code>Parameter</code> object.
   *
   * @param param parameter object
   * @param value parameter value
   * @param <T>   type
   * @return the same query instance
   * @throws IllegalArgumentException if the parameter
   *                                  does not correspond to a parameter of the
   *                                  query
   * @since Java Persistence 2.0
   */
  <T> Query setParameter(Parameter<T> param, T value);

  
Bind an instance of java.util.Calendar to a Parameter object.
Params:
param –        parameter object
value –        parameter value
temporalType – temporal type
Throws:
IllegalArgumentException – if the parameter does not
                                 correspond to a parameter of the query
Returns:
the same query instance
Since:
Java Persistence 2.0/**
   * 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
   * @since Java Persistence 2.0
   */
  Query setParameter(Parameter<Calendar> param, Calendar value,
                     TemporalType temporalType);

  
Bind an instance of java.util.Date to a Parameter object.
Params:
param –        parameter object
value –        parameter value
temporalType – temporal type
Throws:
IllegalArgumentException – if the parameter does not
                                 correspond to a parameter of the query
Returns:
the same query instance
Since:
Java Persistence 2.0/**
   * 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
   * @since Java Persistence 2.0
   */
  Query setParameter(Parameter<Date> param, Date value,
                     TemporalType temporalType);

  
Bind an argument to a named parameter.
Params:
name –  parameter name
value – parameter value
Throws:
IllegalArgumentException – if the parameter name does
                                 not correspond to a parameter of the query or if
                                 the argument is of incorrect type
Returns:
the same query instance/**
   * 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
   */
  Query setParameter(String name, Object value);

  
Bind an instance of java.util.Calendar to a named parameter.
Params:
name –         parameter name
value –        parameter value
temporalType – temporal type
Throws:
IllegalArgumentException – if the parameter name does
                                 not correspond to a parameter of the query or if
                                 the value argument is of incorrect type
Returns:
the same query instance/**
   * 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
   */
  Query setParameter(String name, Calendar value,
                     TemporalType temporalType);

  
Bind an instance of java.util.Date to a named parameter.
Params:
name –         parameter name
value –        parameter value
temporalType – temporal type
Throws:
IllegalArgumentException – if the parameter name does
                                 not correspond to a parameter of the query or if
                                 the value argument is of incorrect type
Returns:
the same query instance/**
   * 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
   */
  Query setParameter(String name, Date value,
                     TemporalType temporalType);

  
Bind an argument to a positional parameter.
Params:
position – position
value –    parameter value
Throws:
IllegalArgumentException – if position does not
                                 correspond to a positional parameter of the
                                 query or if the argument is of incorrect type
Returns:
the same query instance/**
   * 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
   */
  Query setParameter(int position, Object value);

  
Bind an instance of java.util.Calendar to a positional
parameter.
Params:
position –     position
value –        parameter value
temporalType – temporal type
Throws:
IllegalArgumentException – if position does not
                                 correspond to a positional parameter of the query or
                                 if the value argument is of incorrect type
Returns:
the same query instance/**
   * 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
   */
  Query setParameter(int position, Calendar value,
                     TemporalType temporalType);

  
Bind an instance of java.util.Date to a positional parameter.
Params:
position –     position
value –        parameter value
temporalType – temporal type
Throws:
IllegalArgumentException – if position does not
                                 correspond to a positional parameter of the query or
                                 if the value argument is of incorrect type
Returns:
the same query instance/**
   * 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
   */
  Query setParameter(int position, Date value,
                     TemporalType temporalType);

  
Get the parameter objects corresponding to the declared
parameters of the query.
Returns empty set if the query has no parameters.
This method is not required to be supported for native
queries.
Throws:
IllegalStateException – if invoked on a native
                              query when the implementation does not support
                              this use
Returns:
set of the parameter objects
Since:
Java Persistence 2.0/**
   * Get the parameter objects corresponding to the declared
   * parameters of the query.
   * Returns empty set if the query has no parameters.
   * This method is not required to be supported for native
   * queries.
   *
   * @return set of the parameter objects
   * @throws IllegalStateException if invoked on a native
   *                               query when the implementation does not support
   *                               this use
   * @since Java Persistence 2.0
   */
  Set<Parameter<?>> getParameters();

  
Get the parameter object corresponding to the declared
parameter of the given name.
This method is not required to be supported for native
queries.
Params:
name – parameter name
Throws:
IllegalArgumentException – if the parameter of the
                                 specified name does not exist
IllegalStateException –    if invoked on a native
                                 query when the implementation does not support
                                 this use
Returns:
parameter object
Since:
Java Persistence 2.0/**
   * Get the parameter object corresponding to the declared
   * parameter of the given name.
   * This method is not required to be supported for native
   * queries.
   *
   * @param name parameter name
   * @return parameter object
   * @throws IllegalArgumentException if the parameter of the
   *                                  specified name does not exist
   * @throws IllegalStateException    if invoked on a native
   *                                  query when the implementation does not support
   *                                  this use
   * @since Java Persistence 2.0
   */
  Parameter<?> getParameter(String name);

  
Get the parameter object corresponding to the declared
parameter of the given name and type.
This method is required to be supported for criteria queries
only.
Params:
name – parameter name
type – type
Type parameters:
<T> –  type
Throws:
IllegalArgumentException – if the parameter of the
                                 specified name does not exist or is not assignable
                                 to the type
IllegalStateException –    if invoked on a native
                                 query or Java Persistence query language query when
                                 the implementation does not support this use
Returns:
parameter object
Since:
Java Persistence 2.0/**
   * Get the parameter object corresponding to the declared
   * parameter of the given name and type.
   * This method is required to be supported for criteria queries
   * only.
   *
   * @param name parameter name
   * @param type type
   * @param <T>  type
   * @return parameter object
   * @throws IllegalArgumentException if the parameter of the
   *                                  specified name does not exist or is not assignable
   *                                  to the type
   * @throws IllegalStateException    if invoked on a native
   *                                  query or Java Persistence query language query when
   *                                  the implementation does not support this use
   * @since Java Persistence 2.0
   */
  <T> Parameter<T> getParameter(String name, Class<T> type);

  
Get the parameter object corresponding to the declared
positional parameter with the given position.
This method is not required to be supported for native
queries.
Params:
position – position
Throws:
IllegalArgumentException – if the parameter with the
                                 specified position does not exist
IllegalStateException –    if invoked on a native
                                 query when the implementation does not support
                                 this use
Returns:
parameter object
Since:
Java Persistence 2.0/**
   * Get the parameter object corresponding to the declared
   * positional parameter with the given position.
   * This method is not required to be supported for native
   * queries.
   *
   * @param position position
   * @return parameter object
   * @throws IllegalArgumentException if the parameter with the
   *                                  specified position does not exist
   * @throws IllegalStateException    if invoked on a native
   *                                  query when the implementation does not support
   *                                  this use
   * @since Java Persistence 2.0
   */
  Parameter<?> getParameter(int position);

  
Get the parameter object corresponding to the declared
positional parameter with the given position and type.
This method is not required to be supported by the provider.
Params:
position – position
type –     type
Type parameters:
<T> –      Type
Throws:
IllegalArgumentException – if the parameter with the
                                 specified position does not exist or is not assignable
                                 to the type
IllegalStateException –    if invoked on a native
                                 query or Java Persistence query language query when
                                 the implementation does not support this use
Returns:
parameter object
Since:
Java Persistence 2.0/**
   * Get the parameter object corresponding to the declared
   * positional parameter with the given position and type.
   * This method is not required to be supported by the provider.
   *
   * @param position position
   * @param type     type
   * @param <T>      Type
   * @return parameter object
   * @throws IllegalArgumentException if the parameter with the
   *                                  specified position does not exist or is not assignable
   *                                  to the type
   * @throws IllegalStateException    if invoked on a native
   *                                  query or Java Persistence query language query when
   *                                  the implementation does not support this use
   * @since Java Persistence 2.0
   */
  <T> Parameter<T> getParameter(int position, Class<T> type);

  
Return a boolean indicating whether a value has been bound
to the parameter.
Params:
param – parameter object
Returns:
boolean indicating whether parameter has been bound
Since:
Java Persistence 2.0/**
   * Return a boolean indicating whether a value has been bound
   * to the parameter.
   *
   * @param param parameter object
   * @return boolean indicating whether parameter has been bound
   * @since Java Persistence 2.0
   */
  boolean isBound(Parameter<?> param);

  
Return the value bound to the parameter.
Params:
param – parameter object
Type parameters:
<T> –   Type
Throws:
IllegalArgumentException – if the parameter is not
                                 a parameter of the query
IllegalStateException –    if the parameter has not been
                                 been bound
Returns:
parameter value
Since:
Java Persistence 2.0/**
   * Return the value bound to the parameter.
   *
   * @param param parameter object
   * @param <T>   Type
   * @return parameter value
   * @throws IllegalArgumentException if the parameter is not
   *                                  a parameter of the query
   * @throws IllegalStateException    if the parameter has not been
   *                                  been bound
   * @since Java Persistence 2.0
   */
  <T> T getParameterValue(Parameter<T> param);

  
Return the value bound to the named parameter.
Params:
name – parameter name
Throws:
IllegalStateException –    if the parameter has not been
                                 been bound
IllegalArgumentException – if the parameter of the
                                 specified name does not exist
Returns:
parameter value
Since:
Java Persistence 2.0/**
   * Return the value bound to the named parameter.
   *
   * @param name parameter name
   * @return parameter value
   * @throws IllegalStateException    if the parameter has not been
   *                                  been bound
   * @throws IllegalArgumentException if the parameter of the
   *                                  specified name does not exist
   * @since Java Persistence 2.0
   */
  Object getParameterValue(String name);

  
Return the value bound to the positional parameter.
Params:
position – position
Throws:
IllegalStateException –    if the parameter has not been
                                 been bound
IllegalArgumentException – if the parameter with the
                                 specified position does not exist
Returns:
parameter value
Since:
Java Persistence 2.0/**
   * Return the value bound to the positional parameter.
   *
   * @param position position
   * @return parameter value
   * @throws IllegalStateException    if the parameter has not been
   *                                  been bound
   * @throws IllegalArgumentException if the parameter with the
   *                                  specified position does not exist
   * @since Java Persistence 2.0
   */
  Object getParameterValue(int position);

  
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.
Params:
flushMode – flush mode
Returns:
the same query instance/**
   * 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
   */
  Query setFlushMode(FlushModeType flushMode);

  
Get the flush mode in effect for the query execution.
If a flush mode has not been set for the query object,
returns the flush mode in effect for the entity manager.
Returns:
flush mode
Since:
Java Persistence 2.0/**
   * Get the flush mode in effect for the query execution.
   * If a flush mode has not been set for the query object,
   * returns the flush mode in effect for the entity manager.
   *
   * @return flush mode
   * @since Java Persistence 2.0
   */
  FlushModeType getFlushMode();

  
Set the lock mode type to be used for the query execution.
Params:
lockMode – lock mode
Throws:
IllegalStateException – if the query is found not to be
                              a Java Persistence query language SELECT query
                              or a Criteria API query
Returns:
the same query instance
Since:
Java Persistence 2.0/**
   * 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 Criteria API query
   * @since Java Persistence 2.0
   */
  Query setLockMode(LockModeType lockMode);

  
Get the current lock mode for the query.
Throws:
IllegalStateException – if the query is found not to be
                              a Java Persistence query language SELECT query or
                              a Criteria API query
Returns:
lock mode
Since:
Java Persistence 2.0/**
   * Get the current lock mode for the query.
   *
   * @return lock mode
   * @throws IllegalStateException if the query is found not to be
   *                               a Java Persistence query language SELECT query or
   *                               a Criteria API query
   * @since Java Persistence 2.0
   */
  LockModeType getLockMode();

  
Return an object of the specified type to allow access to
the provider-specific API.  If the provider's query
implementation does not support the specified class, the
PersistenceException is thrown.
Params:
cls – the class of the object to be returned.  This is
           normally either the underlying query
           implementation class or an interface that it
           implements.
Type parameters:
<T> – Type
Throws:
PersistenceException – if the provider does not support
                             the call
Returns:
an instance of the specified class
Since:
Java Persistence 2.0/**
   * Return an object of the specified type to allow access to
   * the provider-specific API.  If the provider's query
   * implementation does not support the specified class, the
   * <code>PersistenceException</code> is thrown.
   *
   * @param cls the class of the object to be returned.  This is
   *            normally either the underlying query
   *            implementation class or an interface that it
   *            implements.
   * @param <T> Type
   * @return an instance of the specified class
   * @throws PersistenceException if the provider does not support
   *                              the call
   * @since Java Persistence 2.0
   */
  <T> T unwrap(Class<T> cls);
}