https://github.com/javaee/jpa-spec: Java(TM) Persistence API 
Copyright (c) 2008 - 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:
    Lukas Jungmann  - Java Persistence 2.2
    Linda DeMichiel - Java Persistence 2.1
    Linda DeMichiel - Java Persistence 2.0

/*******************************************************************************
 * Copyright (c) 2008 - 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:
 *     Lukas Jungmann  - Java Persistence 2.2
 *     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;
import java.util.stream.Stream;


Interface used to control the execution of typed queries.

Type parameters:
  • <X> – query result type
See Also:
Since:Java Persistence 2.0
/**
 * 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.

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 other than
        NONE has been set and there is no transaction
        or the persistence context has not been joined to the
        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 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 and return the query results
as a typed java.util.stream.Stream.
By default this method delegates to getResultList().stream(),
however persistence provider may choose to override this method
to provide additional capabilities.

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 other than
        NONE has been set and there is no transaction
        or the persistence context has not been joined to the 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
See Also:
Returns:a stream of the results
Since:2.2
/**
     * Execute a SELECT query and return the query results
     * as a typed <code>java.util.stream.Stream</code>.
     * By default this method delegates to <code>getResultList().stream()</code>,
     * however persistence provider may choose to override this method
     * to provide additional capabilities.
     *
     * @return a stream 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
     * @see Stream
     * @see #getResultList()
     * @since 2.2
     */
    default Stream<X> getResultStream() {
        return getResultList().stream();
    }

    
Execute a SELECT query that returns a single result.

Throws:
Returns:the result
/**
     * 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.

Params:
  • maxResult –  maximum number of results to retrieve
Throws:
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
     */
    TypedQuery<X> setMaxResults(int maxResult);

    
Set the position of the first result to retrieve.

Params:
  • startPosition – position of the first result, 
       numbered from 0
Throws:
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
     */
    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.

Params:
  • hintName –  name of property or hint
  • value –  value for the property or hint
Throws:
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 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 Parameter object.

Params:
  • param –  parameter object
  • value –  parameter value
Throws:
Returns:the same query instance
/**
     * 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 java.util.Calendar to a Parameter object.

Params:
  • param –  parameter object
  • value –  parameter value
  • temporalType –  temporal type
Throws:
Returns:the same query instance
/**
     * 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 java.util.Date to a Parameter object.

Params:
  • param –  parameter object
  • value –  parameter value
  • temporalType –  temporal type
Throws:
Returns:the same query instance
/**
     * 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.

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 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 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
     */
    TypedQuery<X> 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
     */
    TypedQuery<X> setParameter(String name, Date value, 
                               TemporalType temporalType);

    
Bind an argument value 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 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 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
     */
    TypedQuery<X> 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
     */
    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.

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
      */
     TypedQuery<X> setFlushMode(FlushModeType flushMode);

     
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 CriteriaQuery query
Returns:the same query instance
/**
      * 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);

}