-
- All Known Subinterfaces:
StoredProcedureQuery
,TypedQuery<X>
public interface Query
Interface used to control query execution.- Since:
- 1.0
- See Also:
TypedQuery
,StoredProcedureQuery
,Parameter
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description int
executeUpdate()
Execute an update or delete statement.CacheRetrieveMode
getCacheRetrieveMode()
The cache retrieval mode that will be in effect during query execution.CacheStoreMode
getCacheStoreMode()
The cache storage mode that will be in effect during query execution.int
getFirstResult()
The position of the first result the query object was set to retrieve.FlushModeType
getFlushMode()
Get the flush mode in effect for the query execution.java.util.Map<java.lang.String,java.lang.Object>
getHints()
Get the properties and hints and associated values that are in effect for the query instance.LockModeType
getLockMode()
Get the current lock mode for the query.int
getMaxResults()
The maximum number of results the query object was set to retrieve.Parameter<?>
getParameter(int position)
Get the parameter object corresponding to the declared positional parameter with the given position.<T> Parameter<T>
getParameter(int position, java.lang.Class<T> type)
Get the parameter object corresponding to the declared positional parameter with the given position and type.Parameter<?>
getParameter(java.lang.String name)
Get the parameter object corresponding to the declared parameter of the given name.<T> Parameter<T>
getParameter(java.lang.String name, java.lang.Class<T> type)
Get the parameter object corresponding to the declared parameter of the given name and type.java.util.Set<Parameter<?>>
getParameters()
Get the parameter objects corresponding to the declared parameters of the query.java.lang.Object
getParameterValue(int position)
Return the input value bound to the positional parameter.<T> T
getParameterValue(Parameter<T> param)
Return the input value bound to the parameter.java.lang.Object
getParameterValue(java.lang.String name)
Return the input value bound to the named parameter.java.util.List
getResultList()
Execute a SELECT query and return the query results as an untypedList
.default java.util.stream.Stream
getResultStream()
Execute a SELECT query and return the query results as an untypedStream
.java.lang.Object
getSingleResult()
Execute a SELECT query that returns a single untyped result.java.lang.Object
getSingleResultOrNull()
Execute a SELECT query that returns a single untyped result.java.lang.Integer
getTimeout()
The query timeout.boolean
isBound(Parameter<?> param)
Return a boolean indicating whether a value has been bound to the parameter.Query
setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode)
Set the cache retrieval mode that is in effect during query execution.Query
setCacheStoreMode(CacheStoreMode cacheStoreMode)
Set the cache storage mode that is in effect during query execution.Query
setFirstResult(int startPosition)
Set the position of the first result to retrieve.Query
setFlushMode(FlushModeType flushMode)
Set the flush mode type to be used for the query execution.Query
setHint(java.lang.String hintName, java.lang.Object value)
Set a query property or hint.Query
setLockMode(LockModeType lockMode)
Set the lock mode type to be used for the query execution.Query
setMaxResults(int maxResult)
Set the maximum number of results to retrieve.Query
setParameter(int position, java.lang.Object value)
Bind an argument value to a positional parameter.Query
setParameter(int position, java.util.Calendar value, TemporalType temporalType)
Deprecated.Newly-written code should use the date/time types defined injava.time
.Query
setParameter(int position, java.util.Date value, TemporalType temporalType)
Deprecated.Newly-written code should use the date/time types defined injava.time
.Query
setParameter(Parameter<java.util.Calendar> param, java.util.Calendar value, TemporalType temporalType)
Deprecated.Newly-written code should use the date/time types defined injava.time
.Query
setParameter(Parameter<java.util.Date> param, java.util.Date value, TemporalType temporalType)
Deprecated.Newly-written code should use the date/time types defined injava.time
.<T> Query
setParameter(Parameter<T> param, T value)
Bind the value of aParameter
object.Query
setParameter(java.lang.String name, java.lang.Object value)
Bind an argument value to a named parameter.Query
setParameter(java.lang.String name, java.util.Calendar value, TemporalType temporalType)
Deprecated.Newly-written code should use the date/time types defined injava.time
.Query
setParameter(java.lang.String name, java.util.Date value, TemporalType temporalType)
Deprecated.Newly-written code should use the date/time types defined injava.time
.Query
setTimeout(java.lang.Integer timeout)
Set the query timeout, in milliseconds.<T> T
unwrap(java.lang.Class<T> cls)
Return an object of the specified type to allow access to a provider-specific API.
-
-
-
Method Detail
-
getResultList
java.util.List getResultList()
Execute a SELECT query and return the query results as an untypedList
.- Returns:
- a list of the results, or an empty list if there are no results
- Throws:
java.lang.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
default java.util.stream.Stream getResultStream()
Execute a SELECT query and return the query results as an untypedStream
.By default, this method delegates to
getResultList().stream()
, however persistence provider may choose to override this method to provide additional capabilities.- Returns:
- a stream of the results, or an empty stream if there are no results
- Throws:
java.lang.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:
Stream
,getResultList()
-
getSingleResult
java.lang.Object getSingleResult()
Execute a SELECT query that returns a single untyped result.- Returns:
- the result
- Throws:
NoResultException
- if there is no resultNonUniqueResultException
- if more than one resultjava.lang.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
-
getSingleResultOrNull
java.lang.Object getSingleResultOrNull()
Execute a SELECT query that returns a single untyped result.- Returns:
- the result, or null if there is no result
- Throws:
NonUniqueResultException
- if more than one resultjava.lang.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:
- 3.2
-
executeUpdate
int executeUpdate()
Execute an update or delete statement.- Returns:
- the number of entities updated or deleted
- Throws:
java.lang.IllegalStateException
- if called for a Jakarta Persistence query language SELECT statement or for a criteria queryTransactionRequiredException
- if there is no transaction or the persistence context has not been joined to the transactionQueryTimeoutException
- if the statement execution exceeds the query timeout value set and only the statement is rolled backPersistenceException
- if the query execution exceeds the query timeout value set and the transaction is rolled back
-
setMaxResults
Query setMaxResults(int maxResult)
Set the maximum number of results to retrieve.- Parameters:
maxResult
- maximum number of results to retrieve- Returns:
- the same query instance
- Throws:
java.lang.IllegalArgumentException
- if the argument is negative
-
getMaxResults
int getMaxResults()
The maximum number of results the query object was set to retrieve. ReturnsInteger.MAX_VALUE
ifsetMaxResults(int)
was not applied to the query object.- Returns:
- maximum number of results
- Since:
- 2.0
-
setFirstResult
Query setFirstResult(int startPosition)
Set the position of the first result to retrieve.- Parameters:
startPosition
- position of the first result, numbered from 0- Returns:
- the same query instance
- Throws:
java.lang.IllegalArgumentException
- if the argument is negative
-
getFirstResult
int getFirstResult()
The position of the first result the query object was set to retrieve. Returns0
ifsetFirstResult
was not applied to the query object.- Returns:
- position of the first result
- Since:
- 2.0
-
setHint
Query setHint(java.lang.String hintName, java.lang.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.- Parameters:
hintName
- name of the property or hintvalue
- value for the property or hint- Returns:
- the same query instance
- Throws:
java.lang.IllegalArgumentException
- if the second argument is not valid for the implementation
-
getHints
java.util.Map<java.lang.String,java.lang.Object> getHints()
Get the properties and hints and associated values that are in effect for the query instance.- Returns:
- query properties and hints
- Since:
- 2.0
-
setParameter
<T> Query setParameter(Parameter<T> param, T value)
Bind the value of aParameter
object.- Parameters:
param
- parameter objectvalue
- parameter value- Returns:
- the same query instance
- Throws:
java.lang.IllegalArgumentException
- if the parameter does not correspond to a parameter of the query- Since:
- 2.0
-
setParameter
@Deprecated(since="3.2") Query setParameter(Parameter<java.util.Calendar> param, java.util.Calendar value, TemporalType temporalType)
Deprecated.Newly-written code should use the date/time types defined injava.time
.Bind an instance ofCalendar
to aParameter
object.- Parameters:
param
- parameter objectvalue
- parameter valuetemporalType
- temporal type- Returns:
- the same query instance
- Throws:
java.lang.IllegalArgumentException
- if the parameter does not correspond to a parameter of the query- Since:
- 2.0
-
setParameter
@Deprecated(since="3.2") Query setParameter(Parameter<java.util.Date> param, java.util.Date value, TemporalType temporalType)
Deprecated.Newly-written code should use the date/time types defined injava.time
.Bind an instance ofDate
to aParameter
object.- Parameters:
param
- parameter objectvalue
- parameter valuetemporalType
- temporal type- Returns:
- the same query instance
- Throws:
java.lang.IllegalArgumentException
- if the parameter does not correspond to a parameter of the query- Since:
- 2.0
-
setParameter
Query setParameter(java.lang.String name, java.lang.Object value)
Bind an argument value to a named parameter.- Parameters:
name
- parameter namevalue
- parameter value- Returns:
- the same query instance
- Throws:
java.lang.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") Query setParameter(java.lang.String name, java.util.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.- Parameters:
name
- parameter namevalue
- parameter valuetemporalType
- temporal type- Returns:
- the same query instance
- Throws:
java.lang.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") Query setParameter(java.lang.String name, java.util.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.- Parameters:
name
- parameter namevalue
- parameter valuetemporalType
- temporal type- Returns:
- the same query instance
- Throws:
java.lang.IllegalArgumentException
- if the parameter name does not correspond to a parameter of the query or if the value argument is of incorrect type
-
setParameter
Query setParameter(int position, java.lang.Object value)
Bind an argument value to a positional parameter.- Parameters:
position
- positionvalue
- parameter value- Returns:
- the same query instance
- Throws:
java.lang.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") Query setParameter(int position, java.util.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.- Parameters:
position
- positionvalue
- parameter valuetemporalType
- temporal type- Returns:
- the same query instance
- Throws:
java.lang.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") Query setParameter(int position, java.util.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.- Parameters:
position
- positionvalue
- parameter valuetemporalType
- temporal type- Returns:
- the same query instance
- Throws:
java.lang.IllegalArgumentException
- if position does not correspond to a positional parameter of the query or if the value argument is of incorrect type
-
getParameters
java.util.Set<Parameter<?>> getParameters()
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.- Returns:
- set of the parameter objects
- Throws:
java.lang.IllegalStateException
- if invoked on a native query when the implementation does not support this use- Since:
- 2.0
-
getParameter
Parameter<?> getParameter(java.lang.String name)
Get the parameter object corresponding to the declared parameter of the given name. This method is not required to be supported for native queries.- Parameters:
name
- parameter name- Returns:
- parameter object
- Throws:
java.lang.IllegalArgumentException
- if the parameter of the specified name does not existjava.lang.IllegalStateException
- if invoked on a native query when the implementation does not support this use- Since:
- 2.0
-
getParameter
<T> Parameter<T> getParameter(java.lang.String name, java.lang.Class<T> type)
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.- Parameters:
name
- parameter nametype
- type- Returns:
- parameter object
- Throws:
java.lang.IllegalArgumentException
- if the parameter of the specified name does not exist or is not assignable to the typejava.lang.IllegalStateException
- if invoked on a native query or Jakarta Persistence query language query when the implementation does not support this use- Since:
- 2.0
-
getParameter
Parameter<?> getParameter(int position)
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.- Parameters:
position
- position- Returns:
- parameter object
- Throws:
java.lang.IllegalArgumentException
- if the parameter with the specified position does not existjava.lang.IllegalStateException
- if invoked on a native query when the implementation does not support this use- Since:
- 2.0
-
getParameter
<T> Parameter<T> getParameter(int position, java.lang.Class<T> type)
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.- Parameters:
position
- positiontype
- type- Returns:
- parameter object
- Throws:
java.lang.IllegalArgumentException
- if the parameter with the specified position does not exist or is not assignable to the typejava.lang.IllegalStateException
- if invoked on a native query or Jakarta Persistence query language query when the implementation does not support this use- Since:
- 2.0
-
isBound
boolean isBound(Parameter<?> param)
Return a boolean indicating whether a value has been bound to the parameter.- Parameters:
param
- parameter object- Returns:
- boolean indicating whether parameter has been bound
- Since:
- 2.0
-
getParameterValue
<T> T getParameterValue(Parameter<T> param)
Return the input value bound to the parameter. (Note that OUT parameters are unbound.)- Parameters:
param
- parameter object- Returns:
- parameter value
- Throws:
java.lang.IllegalArgumentException
- if the parameter is not a parameter of the queryjava.lang.IllegalStateException
- if the parameter has not been bound- Since:
- 2.0
-
getParameterValue
java.lang.Object getParameterValue(java.lang.String name)
Return the input value bound to the named parameter. (Note that OUT parameters are unbound.)- Parameters:
name
- parameter name- Returns:
- parameter value
- Throws:
java.lang.IllegalStateException
- if the parameter has not been boundjava.lang.IllegalArgumentException
- if the parameter of the specified name does not exist- Since:
- 2.0
-
getParameterValue
java.lang.Object getParameterValue(int position)
Return the input value bound to the positional parameter. (Note that OUT parameters are unbound.)- Parameters:
position
- position- Returns:
- parameter value
- Throws:
java.lang.IllegalStateException
- if the parameter has not been boundjava.lang.IllegalArgumentException
- if the parameter with the specified position does not exist- Since:
- 2.0
-
setFlushMode
Query 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.- Parameters:
flushMode
- flush mode- Returns:
- the same query instance
-
getFlushMode
FlushModeType getFlushMode()
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:
- 2.0
-
setLockMode
Query setLockMode(LockModeType lockMode)
Set the lock mode type to be used for the query execution.- Parameters:
lockMode
- lock mode- Returns:
- the same query instance
- Throws:
java.lang.IllegalStateException
- if the query is found not to be a Jakarta Persistence query language SELECT query or aCriteriaQuery
query- Since:
- 2.0
-
getLockMode
LockModeType getLockMode()
Get the current lock mode for the query. Returns null if a lock mode has not been set on the query object.- Returns:
- lock mode
- Throws:
java.lang.IllegalStateException
- if the query is found not to be a Jakarta Persistence query language SELECT query or aCriteriaQuery
query- Since:
- 2.0
-
setCacheRetrieveMode
Query 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.- Parameters:
cacheRetrieveMode
- cache retrieval mode- Returns:
- the same query instance
- Since:
- 3.2
-
setCacheStoreMode
Query 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.- Parameters:
cacheStoreMode
- cache storage mode- Returns:
- the same query instance
- Since:
- 3.2
-
getCacheRetrieveMode
CacheRetrieveMode getCacheRetrieveMode()
The cache retrieval mode that will be in effect during query execution.- Since:
- 3.2
-
getCacheStoreMode
CacheStoreMode getCacheStoreMode()
The cache storage mode that will be in effect during query execution.- Since:
- 3.2
-
setTimeout
Query setTimeout(java.lang.Integer timeout)
Set the query timeout, in milliseconds. This is a hint, and is an alternative to setting the hintjakarta.persistence.query.timeout
.- Parameters:
timeout
- the timeout, in milliseconds, or null to indicate no timeout- Returns:
- the same query instance
- Since:
- 3.2
-
getTimeout
java.lang.Integer getTimeout()
The query timeout.- Since:
- 3.2
-
unwrap
<T> T unwrap(java.lang.Class<T> cls)
Return an object of the specified type to allow access to a provider-specific API. If the provider implementation ofQuery
does not support the given type, thePersistenceException
is thrown.- Parameters:
cls
- the type of the object to be returned. This is usually either the underlying class implementingQuery
or an interface it implements.- Returns:
- an instance of the specified class
- Throws:
PersistenceException
- if the provider does not support the given type- Since:
- 2.0
-
-