Type Parameters:: X - query result type

All Superinterfaces:: Query

public interface TypedQuery<X> extends Query

Interface used to control the execution of typed queries.

Since:

2.0

See Also:

Method Summary

Modifier and Type

Method

Description

List<X>

getResultList()

Execute a SELECT query and return the query results as a typed List<X>.

default Stream<X>

getResultStream()

Execute a SELECT query and return the query result as a typed Stream<X>.

X

getSingleResult()

Execute a SELECT query that returns a single result.

X

getSingleResultOrNull()

Execute a SELECT query that returns a single untyped result.

TypedQuery<X>

setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode)

Set the cache retrieval mode that is in effect during query execution.

TypedQuery<X>

setCacheStoreMode(CacheStoreMode cacheStoreMode)

Set the cache storage mode that is in effect during query execution.

TypedQuery<X>

setFirstResult(int startPosition)

Set the position of the first result to retrieve.

TypedQuery<X>

setFlushMode(FlushModeType flushMode)

Set the flush mode type to be used for the query execution.

TypedQuery<X>

setHint(String hintName, Object value)

Set a query property or hint.

TypedQuery<X>

setLockMode(LockModeType lockMode)

Set the lock mode type to be used for the query execution.

TypedQuery<X>

setMaxResults(int maxResult)

Set the maximum number of results to retrieve.

TypedQuery<X>

setParameter(int position, Object value)

Bind an argument value to a positional parameter.

TypedQuery<X>

setParameter(int position, Calendar value, TemporalType temporalType)

Deprecated.
Newly-written code should use the date/time types defined in java.time.

TypedQuery<X>

setParameter(int position, Date value, TemporalType temporalType)

Deprecated.
Newly-written code should use the date/time types defined in java.time.

TypedQuery<X>

setParameter(Parameter<Calendar> param, Calendar value, TemporalType temporalType)

Deprecated.
Newly-written code should use the date/time types defined in java.time.

TypedQuery<X>

setParameter(Parameter<Date> param, Date value, TemporalType temporalType)

Deprecated.
Newly-written code should use the date/time types defined in java.time.

<T> TypedQuery<X>

setParameter(Parameter<T> param, T value)

Bind the value of a Parameter object.

TypedQuery<X>

setParameter(String name, Object value)

Bind an argument value to a named parameter.

TypedQuery<X>

setParameter(String name, Calendar value, TemporalType temporalType)

Deprecated.
Newly-written code should use the date/time types defined in java.time.

TypedQuery<X>

setParameter(String name, Date value, TemporalType temporalType)

Deprecated.
Newly-written code should use the date/time types defined in java.time.

TypedQuery<X>

setTimeout(Integer timeout)

Set the query timeout, in milliseconds.

Methods inherited from interface jakarta.persistence.Query
executeUpdate, getCacheRetrieveMode, getCacheStoreMode, getFirstResult, getFlushMode, getHints, getLockMode, getMaxResults, getParameter, getParameter, getParameter, getParameter, getParameters, getParameterValue, getParameterValue, getParameterValue, getTimeout, isBound, unwrap

Method Details
- getResultList
  
  List<X> getResultList()
  
  Execute a SELECT query and return the query results as a typed List<X>.
  
  Specified by:
  
  getResultList in interface Query
  
  Returns:
  
  a list of the results, each of type TypedQuery, or an empty list if there are no results
  
  Throws:
  
  IllegalStateException - if called for a Jakarta 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
- getResultStream
  
  default Stream<X> getResultStream()
  
  Execute a SELECT query and return the query result as a typed Stream<X>.
  By default, this method delegates to getResultList().stream(), however, persistence provider may choose to override this method to provide additional capabilities.
  Specified by:
  
  getResultStream in interface Query
  
  Returns:
  
  a stream of the results, each of type TypedQuery, or an empty stream if there are no results
  
  Throws:
  
  IllegalStateException - if called for a Jakarta 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
  
  Since:
  
  2.2
  
  See Also:
  
  Stream
  
  getResultList()
- getSingleResult
  
  X getSingleResult()
  
  Execute a SELECT query that returns a single result.
  
  Specified by:
  
  getSingleResult in interface Query
  
  Returns:
  
  the result, of type TypedQuery
  
  Throws:
  
  NoResultException - if there is no result
  
  NonUniqueResultException - if more than one result
  
  IllegalStateException - if called for a Jakarta 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
- getSingleResultOrNull
  
  X getSingleResultOrNull()
  
  Execute a SELECT query that returns a single untyped result.
  
  Specified by:
  
  getSingleResultOrNull in interface Query
  
  Returns:
  
  the result, of type TypedQuery, or null if there is no result
  
  Throws:
  
  NonUniqueResultException - if more than one result
  
  IllegalStateException - if called for a Jakarta 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
  
  Since:
  
  3.2
- setMaxResults
  
  TypedQuery<X> setMaxResults(int maxResult)
  
  Set the maximum number of results to retrieve.
  
  Specified by:
  
  setMaxResults in interface Query
  
  Parameters:
  
  maxResult - maximum number of results to retrieve
  
  Returns:
  
  the same query instance
  
  Throws:
  
  IllegalArgumentException - if the argument is negative
- setFirstResult
  
  TypedQuery<X> setFirstResult(int startPosition)
  
  Set the position of the first result to retrieve.
  
  Specified by:
  
  setFirstResult in interface Query
  
  Parameters:
  
  startPosition - position of the first result, numbered from 0
  
  Returns:
  
  the same query instance
  
  Throws:
  
  IllegalArgumentException - if the argument is negative
- setHint
  
  TypedQuery<X> setHint(String hintName, Object value)
  
  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.
  
  Specified by:
  
  setHint in interface Query
  
  Parameters:
  
  hintName - name of property or hint
  
  value - value for the property or hint
  
  Returns:
  
  the same query instance
  
  Throws:
  
  IllegalArgumentException - if the second argument is not valid for the implementation
- setParameter
  
  <T> TypedQuery<X> setParameter(Parameter<T> param, T value)
  
  Bind the value of a Parameter object.
  
  Specified by:
  
  setParameter in interface Query
  
  Parameters:
  
  param - parameter object
  
  value - parameter value
  
  Returns:
  
  the same query instance
  
  Throws:
  
  IllegalArgumentException - if the parameter does not correspond to a parameter of the query
- setParameter
  
  @Deprecated(since="3.2") TypedQuery<X> setParameter(Parameter<Calendar> param, Calendar value, TemporalType temporalType)
  
  Deprecated.
  Newly-written code should use the date/time types defined in java.time.
  
  Bind an instance of Calendar to a Parameter object.
  
  Specified by:
  
  setParameter in interface Query
  
  Parameters:
  
  param - parameter object
  
  value - parameter value
  
  temporalType - temporal type
  
  Returns:
  
  the same query instance
  
  Throws:
  
  IllegalArgumentException - if the parameter does not correspond to a parameter of the query
- setParameter
  
  @Deprecated(since="3.2") TypedQuery<X> setParameter(Parameter<Date> param, Date value, TemporalType temporalType)
  
  Deprecated.
  Newly-written code should use the date/time types defined in java.time.
  
  Bind an instance of Date to a Parameter object.
  
  Specified by:
  
  setParameter in interface Query
  
  Parameters:
  
  param - parameter object
  
  value - parameter value
  
  temporalType - temporal type
  
  Returns:
  
  the same query instance
  
  Throws:
  
  IllegalArgumentException - if the parameter does not correspond to a parameter of the query
- setParameter
  
  TypedQuery<X> setParameter(String name, Object value)
  
  Bind an argument value to a named parameter.
  
  Specified by:
  
  setParameter in interface Query
  
  Parameters:
  
  name - parameter name
  
  value - parameter value
  
  Returns:
  
  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
- setParameter
  
  @Deprecated(since="3.2") TypedQuery<X> setParameter(String name, Calendar value, TemporalType temporalType)
  
  Deprecated.
  Newly-written code should use the date/time types defined in java.time.
  
  Bind an instance of Calendar to a named parameter.
  
  Specified by:
  
  setParameter in interface Query
  
  Parameters:
  
  name - parameter name
  
  value - parameter value
  
  temporalType - temporal type
  
  Returns:
  
  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
- setParameter
  
  @Deprecated(since="3.2") TypedQuery<X> setParameter(String name, Date value, TemporalType temporalType)
  
  Deprecated.
  Newly-written code should use the date/time types defined in java.time.
  
  Bind an instance of Date to a named parameter.
  
  Specified by:
  
  setParameter in interface Query
  
  Parameters:
  
  name - parameter name
  
  value - parameter value
  
  temporalType - temporal type
  
  Returns:
  
  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
- setParameter
  
  TypedQuery<X> setParameter(int position, Object value)
  
  Bind an argument value to a positional parameter.
  
  Specified by:
  
  setParameter in interface Query
  
  Parameters:
  
  position - position
  
  value - parameter value
  
  Returns:
  
  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
- setParameter
  
  @Deprecated(since="3.2") TypedQuery<X> setParameter(int position, Calendar value, TemporalType temporalType)
  
  Deprecated.
  Newly-written code should use the date/time types defined in java.time.
  
  Bind an instance of Calendar to a positional parameter.
  
  Specified by:
  
  setParameter in interface Query
  
  Parameters:
  
  position - position
  
  value - parameter value
  
  temporalType - temporal type
  
  Returns:
  
  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
- setParameter
  
  @Deprecated(since="3.2") TypedQuery<X> setParameter(int position, Date value, TemporalType temporalType)
  
  Deprecated.
  Newly-written code should use the date/time types defined in java.time.
  
  Bind an instance of Date to a positional parameter.
  
  Specified by:
  
  setParameter in interface Query
  
  Parameters:
  
  position - position
  
  value - parameter value
  
  temporalType - temporal type
  
  Returns:
  
  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
- setFlushMode
  
  TypedQuery<X> setFlushMode(FlushModeType flushMode)
  
  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.
  
  Specified by:
  
  setFlushMode in interface Query
  
  Parameters:
  
  flushMode - flush mode
  
  Returns:
  
  the same query instance
- setLockMode
  
  TypedQuery<X> setLockMode(LockModeType lockMode)
  
  Set the lock mode type to be used for the query execution.
  
  Specified by:
  
  setLockMode in interface Query
  
  Parameters:
  
  lockMode - lock mode
  
  Returns:
  
  the same query instance
  
  Throws:
  
  IllegalStateException - if the query is found not to be a Jakarta Persistence query language SELECT query or a CriteriaQuery query
- setCacheRetrieveMode
  
  TypedQuery<X> setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode)
  
  Set the cache retrieval mode that is in effect during query execution. This cache retrieval mode overrides the cache retrieve mode in use by the entity manager.
  
  Specified by:
  
  setCacheRetrieveMode in interface Query
  
  Parameters:
  
  cacheRetrieveMode - cache retrieval mode
  
  Returns:
  
  the same query instance
  
  Since:
  
  3.2
- setCacheStoreMode
  
  TypedQuery<X> setCacheStoreMode(CacheStoreMode cacheStoreMode)
  
  Set the cache storage mode that is in effect during query execution. This cache storage mode overrides the cache storage mode in use by the entity manager.
  
  Specified by:
  
  setCacheStoreMode in interface Query
  
  Parameters:
  
  cacheStoreMode - cache storage mode
  
  Returns:
  
  the same query instance
  
  Since:
  
  3.2
- setTimeout
  
  TypedQuery<X> setTimeout(Integer timeout)
  
  Set the query timeout, in milliseconds. This is a hint, and is an alternative to setting the hint jakarta.persistence.query.timeout.
  
  Specified by:
  
  setTimeout in interface Query
  
  Parameters:
  
  timeout - the timeout, in milliseconds, or null to indicate no timeout
  
  Returns:
  
  the same query instance
  
  Since:
  
  3.2

Interface TypedQuery<X>

Method Summary

Methods inherited from interface jakarta.persistence.Query

Method Details

getResultList

getResultStream

getSingleResult

getSingleResultOrNull

setMaxResults

setFirstResult

setHint

setParameter

setParameter

setParameter

setParameter

setParameter

setParameter

setParameter

setParameter

setParameter

setFlushMode

setLockMode

setCacheRetrieveMode

setCacheStoreMode

setTimeout