-
Method Summary
Modifier and TypeMethodDescriptionExecute a SELECT query and return the query results as a typedList<X>
.Execute a SELECT query and return the query result as a typedStream<X>
.Execute a SELECT query that returns a single result.Execute a SELECT query that returns a single untyped result.setCacheRetrieveMode
(CacheRetrieveMode cacheRetrieveMode) Set the cache retrieval mode that is in effect during query execution.setCacheStoreMode
(CacheStoreMode cacheStoreMode) Set the cache storage mode that is in effect during query execution.setFirstResult
(int startPosition) Set the position of the first result to retrieve.setFlushMode
(FlushModeType flushMode) Set the flush mode type to be used for the query execution.Set a query property or hint.setLockMode
(LockModeType lockMode) Set the lock mode type to be used for the query execution.setMaxResults
(int maxResult) Set the maximum number of results to retrieve.setParameter
(int position, Object value) Bind an argument value to a positional parameter.setParameter
(int position, Calendar value, TemporalType temporalType) Deprecated.setParameter
(int position, Date value, TemporalType temporalType) Deprecated.Newly-written code should use the date/time types defined injava.time
.setParameter
(Parameter<Calendar> param, Calendar value, TemporalType temporalType) Deprecated.Newly-written code should use the date/time types defined injava.time
.setParameter
(Parameter<Date> param, Date value, TemporalType temporalType) Deprecated.Newly-written code should use the date/time types defined injava.time
.<T> TypedQuery
<X> setParameter
(Parameter<T> param, T value) Bind the value of aParameter
object.setParameter
(String name, Object value) Bind an argument value to a named parameter.setParameter
(String name, Calendar value, TemporalType temporalType) Deprecated.Newly-written code should use the date/time types defined injava.time
.setParameter
(String name, Date value, TemporalType temporalType) Deprecated.Newly-written code should use the date/time types defined injava.time
.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
Execute a SELECT query and return the query results as a typedList<X>
.- Specified by:
getResultList
in interfaceQuery
- 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 statementQueryTimeoutException
- if the query execution exceeds the query timeout value set and only the statement is rolled backTransactionRequiredException
- if a lock mode other thanNONE
has been set and there is no transaction or the persistence context has not been joined to the transactionPessimisticLockException
- if pessimistic locking fails and the transaction is rolled backLockTimeoutException
- if pessimistic locking fails and only the statement is rolled backPersistenceException
- if the query execution exceeds the query timeout value set and the transaction is rolled back
-
getResultStream
Execute a SELECT query and return the query result as a typedStream<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 interfaceQuery
- 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 statementQueryTimeoutException
- if the query execution exceeds the query timeout value set and only the statement is rolled backTransactionRequiredException
- if a lock mode other thanNONE
has been set and there is no transaction or the persistence context has not been joined to the transactionPessimisticLockException
- if pessimistic locking fails and the transaction is rolled backLockTimeoutException
- if pessimistic locking fails and only the statement is rolled backPersistenceException
- if the query execution exceeds the query timeout value set and the transaction is rolled back- Since:
- 2.2
- See Also:
-
getSingleResult
X getSingleResult()Execute a SELECT query that returns a single result.- Specified by:
getSingleResult
in interfaceQuery
- Returns:
- the result, of type
TypedQuery
- Throws:
NoResultException
- if there is no resultNonUniqueResultException
- if more than one resultIllegalStateException
- if called for a Jakarta Persistence query language UPDATE or DELETE statementQueryTimeoutException
- if the query execution exceeds the query timeout value set and only the statement is rolled backTransactionRequiredException
- if a lock mode other thanNONE
has been set and there is no transaction or the persistence context has not been joined to the transactionPessimisticLockException
- if pessimistic locking fails and the transaction is rolled backLockTimeoutException
- if pessimistic locking fails and only the statement is rolled backPersistenceException
- 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 interfaceQuery
- Returns:
- the result, of type
TypedQuery
, or null if there is no result - Throws:
NonUniqueResultException
- if more than one resultIllegalStateException
- if called for a Jakarta Persistence query language UPDATE or DELETE statementQueryTimeoutException
- if the query execution exceeds the query timeout value set and only the statement is rolled backTransactionRequiredException
- if a lock mode other thanNONE
has been set and there is no transaction or the persistence context has not been joined to the transactionPessimisticLockException
- if pessimistic locking fails and the transaction is rolled backLockTimeoutException
- if pessimistic locking fails and only the statement is rolled backPersistenceException
- if the query execution exceeds the query timeout value set and the transaction is rolled back
-
setMaxResults
Set the maximum number of results to retrieve.- Specified by:
setMaxResults
in interfaceQuery
- Parameters:
maxResult
- maximum number of results to retrieve- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if the argument is negative
-
setFirstResult
Set the position of the first result to retrieve.- Specified by:
setFirstResult
in interfaceQuery
- Parameters:
startPosition
- position of the first result, numbered from 0- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if the argument is negative
-
setHint
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 interfaceQuery
- Parameters:
hintName
- name of property or hintvalue
- value for the property or hint- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if the second argument is not valid for the implementation
-
setParameter
Bind the value of aParameter
object.- Specified by:
setParameter
in interfaceQuery
- Parameters:
param
- parameter objectvalue
- 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 injava.time
.- Specified by:
setParameter
in interfaceQuery
- Parameters:
param
- parameter objectvalue
- parameter valuetemporalType
- 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 injava.time
.- Specified by:
setParameter
in interfaceQuery
- Parameters:
param
- parameter objectvalue
- parameter valuetemporalType
- temporal type- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if the parameter does not correspond to a parameter of the query
-
setParameter
Bind an argument value to a named parameter.- Specified by:
setParameter
in interfaceQuery
- Parameters:
name
- parameter namevalue
- 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 injava.time
.Bind an instance ofCalendar
to a named parameter.- Specified by:
setParameter
in interfaceQuery
- Parameters:
name
- parameter namevalue
- parameter valuetemporalType
- 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 injava.time
.Bind an instance ofDate
to a named parameter.- Specified by:
setParameter
in interfaceQuery
- Parameters:
name
- parameter namevalue
- parameter valuetemporalType
- 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
Bind an argument value to a positional parameter.- Specified by:
setParameter
in interfaceQuery
- Parameters:
position
- positionvalue
- 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 injava.time
.Bind an instance ofCalendar
to a positional parameter.- Specified by:
setParameter
in interfaceQuery
- Parameters:
position
- positionvalue
- parameter valuetemporalType
- 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 injava.time
.Bind an instance ofDate
to a positional parameter.- Specified by:
setParameter
in interfaceQuery
- Parameters:
position
- positionvalue
- parameter valuetemporalType
- 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
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 interfaceQuery
- Parameters:
flushMode
- flush mode- Returns:
- the same query instance
-
setLockMode
Set the lock mode type to be used for the query execution.- Specified by:
setLockMode
in interfaceQuery
- 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 aCriteriaQuery
query
-
setCacheRetrieveMode
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 interfaceQuery
- Parameters:
cacheRetrieveMode
- cache retrieval mode- Returns:
- the same query instance
- Since:
- 3.2
-
setCacheStoreMode
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 interfaceQuery
- Parameters:
cacheStoreMode
- cache storage mode- Returns:
- the same query instance
- Since:
- 3.2
-
setTimeout
Set the query timeout, in milliseconds. This is a hint, and is an alternative to setting the hintjakarta.persistence.query.timeout
.- Specified by:
setTimeout
in interfaceQuery
- Parameters:
timeout
- the timeout, in milliseconds, or null to indicate no timeout- Returns:
- the same query instance
- Since:
- 3.2
-
java.time
.