Jakarta EE 11.0.0 · jakarta.persistence.Query · APIdia, the JavaDoc alternative

Method Summary

Modifier and Type	Method and Description
public int	Returns: the number of entities updated or deleted executeUpdate() Execute an update or delete statement.
public CacheRetrieveMode	getCacheRetrieveMode() The cache retrieval mode that will be in effect during query execution.
public CacheStoreMode	getCacheStoreMode() The cache storage mode that will be in effect during query execution.
public int	Returns: position of the first result getFirstResult() The position of the first result the query object was set to retrieve.
public FlushModeType	Returns: flush mode getFlushMode() Get the flush mode in effect for the query execution.
public Map<String, Object>	Returns: query properties and hints getHints() Get the properties and hints and associated values that are in effect for the query instance.
public LockModeType	Returns: lock mode getLockMode() Get the current lock mode for the query.
public int	Returns: maximum number of results getMaxResults() The maximum number of results the query object was set to retrieve.
public Parameter<?>	Returns: parameter object getParameter(String parameter name name) Get the parameter object corresponding to the declared parameter of the given name.
public <T> Parameter<T>	Returns: parameter object getParameter(String parameter name name, Class<T> type type) Get the parameter object corresponding to the declared parameter of the given name and type.
public Parameter<?>	Returns: parameter object getParameter(int position position) Get the parameter object corresponding to the declared positional parameter with the given position.
public <T> Parameter<T>	Returns: parameter object getParameter(int position position, Class<T> type type) Get the parameter object corresponding to the declared positional parameter with the given position and type.
public Set<Parameter<?>>	Returns: set of the parameter objects getParameters() Get the parameter objects corresponding to the declared parameters of the query.
public <T> T	Returns: parameter value getParameterValue(Parameter<T> parameter object param) Return the input value bound to the parameter.
public Object	Returns: parameter value getParameterValue(String parameter name name) Return the input value bound to the named parameter.
public Object	Returns: parameter value getParameterValue(int position position) Return the input value bound to the positional parameter.
public List<E>	Returns: a list of the results, or an empty list if there are no results getResultList() Execute a SELECT query and return the query results as an untyped `List`.
public default Stream<T>	Returns: a stream of the results, or an empty stream if there are no results getResultStream() Execute a SELECT query and return the query results as an untyped `java.util.stream.Stream`.
public Object	Returns: the result getSingleResult() Execute a SELECT query that returns a single untyped result.
public Object	Returns: the result, or null if there is no result getSingleResultOrNull() Execute a SELECT query that returns a single untyped result.
public Integer	getTimeout() The query timeout.
public boolean	Returns: boolean indicating whether parameter has been bound isBound(Parameter<?> parameter object param) Return a boolean indicating whether a value has been bound to the parameter.
public Query	Returns: the same query instance setCacheRetrieveMode(CacheRetrieveMode cache retrieval mode cacheRetrieveMode) Set the cache retrieval mode that is in effect during query execution.
public Query	Returns: the same query instance setCacheStoreMode(CacheStoreMode cache storage mode cacheStoreMode) Set the cache storage mode that is in effect during query execution.
public Query	Returns: the same query instance setFirstResult(int position of the first result, numbered from 0 startPosition) Set the position of the first result to retrieve.
public Query	Returns: the same query instance setFlushMode(FlushModeType flush mode flushMode) Set the flush mode type to be used for the query execution.
public Query	Returns: the same query instance setHint(String name of the property or hint hintName, Object value for the property or hint value) Set a query property or hint.
public Query	Returns: the same query instance setLockMode(LockModeType lock mode lockMode) Set the lock mode type to be used for the query execution.
public Query	Returns: the same query instance setMaxResults(int maximum number of results to retrieve maxResult) Set the maximum number of results to retrieve.
public <T> Query	Returns: the same query instance setParameter(Parameter<T> parameter object param, T parameter value value) Bind the value of a `Parameter` object.
public Query	Returns: the same query instance setParameter(Parameter<Calendar> parameter object param, Calendar parameter value value, TemporalType temporal type temporalType) Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Calendar` to a `Parameter` object.
public Query	Returns: the same query instance setParameter(Parameter<Date> parameter object param, Date parameter value value, TemporalType temporal type temporalType) Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Date` to a `Parameter` object.
public Query	Returns: the same query instance setParameter(String parameter name name, Object parameter value value) Bind an argument value to a named parameter.
public Query	Returns: the same query instance setParameter(String parameter name name, Calendar parameter value value, TemporalType temporal type temporalType) Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Calendar` to a named parameter.
public Query	Returns: the same query instance setParameter(String parameter name name, Date parameter value value, TemporalType temporal type temporalType) Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Date` to a named parameter.
public Query	Returns: the same query instance setParameter(int position position, Object parameter value value) Bind an argument value to a positional parameter.
public Query	Returns: the same query instance setParameter(int position position, Calendar parameter value value, TemporalType temporal type temporalType) Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Calendar` to a positional parameter.
public Query	Returns: the same query instance setParameter(int position position, Date parameter value value, TemporalType temporal type temporalType) Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Date` to a positional parameter.
public Query	Returns: the same query instance setTimeout(Integer the timeout, in milliseconds, or null to indicate no timeout timeout) Set the query timeout, in milliseconds.
public <T> T	Returns: an instance of the specified class unwrap(Class<T> the type of the object to be returned. This is usually either the underlying class implementing `Query` or an interface it implements. cls) Return an object of the specified type to allow access to a provider-specific API.

Method Detail

executeUpdate	back to summary
public int executeUpdate() Execute an update or delete statement. Returns:int the number of entities updated or deleted Exceptions IllegalStateException: if called for a Jakarta Persistence query language SELECT statement or for a criteria query TransactionRequiredException: if there is no transaction or the persistence context has not been joined to the 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

executeUpdate

back to summary

public int executeUpdate()

Execute an update or delete statement.

Returns:int

the number of entities updated or deleted

Exceptions

IllegalStateException:: if called for a Jakarta Persistence query language SELECT statement or for a criteria query
TransactionRequiredException:: if there is no transaction or the persistence context has not been joined to the 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

getCacheRetrieveMode	back to summary
public CacheRetrieveMode getCacheRetrieveMode() The cache retrieval mode that will be in effect during query execution. Since 3.2

getCacheRetrieveMode

back to summary

public CacheRetrieveMode getCacheRetrieveMode()

The cache retrieval mode that will be in effect during query execution.

Since: 3.2

getCacheStoreMode	back to summary
public CacheStoreMode getCacheStoreMode() The cache storage mode that will be in effect during query execution. Since 3.2

getCacheStoreMode

back to summary

public CacheStoreMode getCacheStoreMode()

The cache storage mode that will be in effect during query execution.

Since: 3.2

getFirstResult back to summary

getFirstResult	back to summary
public int getFirstResult() 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:int position of the first result Since 2.0

public int getFirstResult()

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:int: position of the first result
Since: 2.0

getFlushMode	back to summary
public 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:FlushModeType flush mode Since 2.0

getFlushMode

back to summary

public 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:FlushModeType: flush mode
Since: 2.0

getHints	back to summary
public Map<String, Object> getHints() Get the properties and hints and associated values that are in effect for the query instance. Returns:Map<String, Object> query properties and hints Since 2.0

getHints

back to summary

public Map<String, Object> getHints()

Get the properties and hints and associated values that are in effect for the query instance.

Returns:Map<String, Object>: query properties and hints
Since: 2.0

getLockMode back to summary

getLockMode	back to summary
public 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:LockModeType lock mode Exceptions IllegalStateException: if the query is found not to be a Jakarta Persistence query language SELECT query or a `jakarta.persistence.criteria.CriteriaQuery` query Since 2.0

public 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:LockModeType

lock mode

Exceptions

IllegalStateException:: if the query is found not to be a Jakarta Persistence query language SELECT query or a jakarta.persistence.criteria.CriteriaQuery query

Since

2.0

getMaxResults back to summary

getMaxResults	back to summary
public int getMaxResults() 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:int maximum number of results Since 2.0

public int getMaxResults()

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:int: maximum number of results
Since: 2.0

getParameter	back to summary
public Parameter<?> getParameter(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:String parameter name Returns:Parameter<?> parameter object Exceptions 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 Since 2.0

getParameter

back to summary

public Parameter<?> getParameter(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:String: parameter name

Returns:Parameter<?>

parameter object

Exceptions

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

Since

2.0

getParameter	back to summary
public <T> Parameter<T> getParameter(String name, 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:String parameter name type:Class<T> type Returns:Parameter<T> parameter object Exceptions 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 Jakarta Persistence query language query when the implementation does not support this use Since 2.0

getParameter

back to summary

public <T> Parameter<T> getParameter(String name, 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:String: parameter name
type:Class<T>: type

Returns:Parameter<T>

parameter object

Exceptions

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 Jakarta Persistence query language query when the implementation does not support this use

Since

2.0

getParameter	back to summary
public 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:int position Returns:Parameter<?> parameter object Exceptions 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 Since 2.0

getParameter

back to summary

public 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:int: position

Returns:Parameter<?>

parameter object

Exceptions

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

Since

2.0

getParameter	back to summary
public <T> Parameter<T> getParameter(int position, 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:int position type:Class<T> type Returns:Parameter<T> parameter object Exceptions 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 Jakarta Persistence query language query when the implementation does not support this use Since 2.0

getParameter

back to summary

public <T> Parameter<T> getParameter(int position, 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:int: position
type:Class<T>: type

Returns:Parameter<T>

parameter object

Exceptions

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 Jakarta Persistence query language query when the implementation does not support this use

Since

2.0

getParameters	back to summary
public 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<Parameter<?>> set of the parameter objects Exceptions IllegalStateException: if invoked on a native query when the implementation does not support this use Since 2.0

getParameters

back to summary

public 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<Parameter<?>>

set of the parameter objects

Exceptions

IllegalStateException:: if invoked on a native query when the implementation does not support this use

Since

2.0

getParameterValue	back to summary
public <T> T getParameterValue(Parameter<T> param) Return the input value bound to the parameter. (Note that OUT parameters are unbound.) Parameters param:Parameter<T> parameter object Returns:T parameter value Exceptions IllegalArgumentException: if the parameter is not a parameter of the query IllegalStateException: if the parameter has not been bound Since 2.0

getParameterValue

back to summary

public <T> T getParameterValue(Parameter<T> param)

Return the input value bound to the parameter. (Note that OUT parameters are unbound.)

Parameters

param:Parameter<T>: parameter object

Returns:T

parameter value

Exceptions

IllegalArgumentException:: if the parameter is not a parameter of the query
IllegalStateException:: if the parameter has not been bound

Since

2.0

getParameterValue	back to summary
public Object getParameterValue(String name) Return the input value bound to the named parameter. (Note that OUT parameters are unbound.) Parameters name:String parameter name Returns:Object parameter value Exceptions IllegalStateException: if the parameter has not been bound IllegalArgumentException: if the parameter of the specified name does not exist Since 2.0

getParameterValue

back to summary

public Object getParameterValue(String name)

Return the input value bound to the named parameter. (Note that OUT parameters are unbound.)

Parameters

name:String: parameter name

Returns:Object

parameter value

Exceptions

IllegalStateException:: if the parameter has not been bound
IllegalArgumentException:: if the parameter of the specified name does not exist

Since

2.0

getParameterValue	back to summary
public Object getParameterValue(int position) Return the input value bound to the positional parameter. (Note that OUT parameters are unbound.) Parameters position:int position Returns:Object parameter value Exceptions IllegalStateException: if the parameter has not been bound IllegalArgumentException: if the parameter with the specified position does not exist Since 2.0

getParameterValue

back to summary

public Object getParameterValue(int position)

Return the input value bound to the positional parameter. (Note that OUT parameters are unbound.)

Parameters

position:int: position

Returns:Object

parameter value

Exceptions

IllegalStateException:: if the parameter has not been bound
IllegalArgumentException:: if the parameter with the specified position does not exist

Since

2.0

getResultList back to summary

getResultList	back to summary
public List<E> getResultList() Execute a SELECT query and return the query results as an untyped `List`. Returns:List<E> a list of the results, or an empty list if there are no results Annotations @SuppressWarnings:rawtypes Exceptions 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

public List<E> getResultList()

Execute a SELECT query and return the query results as an untyped List.

Returns:List<E>

a list of the results, or an empty list if there are no results

Annotations

@SuppressWarnings:rawtypes

Exceptions

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 back to summary

getResultStream	back to summary
public default Stream<T> getResultStream() Execute a SELECT query and return the query results as an untyped `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. Returns:Stream<T> a stream of the results, or an empty stream if there are no results Annotations @SuppressWarnings:rawtypes Exceptions 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()`

public default Stream<T> getResultStream()

Execute a SELECT query and return the query results as an untyped 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.

Returns:Stream<T>

a stream of the results, or an empty stream if there are no results

Annotations

@SuppressWarnings:rawtypes

Exceptions

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 back to summary

getSingleResult	back to summary
public Object getSingleResult() Execute a SELECT query that returns a single untyped result. Returns:Object the result Exceptions 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

public Object getSingleResult()

Execute a SELECT query that returns a single untyped result.

Returns:Object

the result

Exceptions

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 back to summary

getSingleResultOrNull	back to summary
public Object getSingleResultOrNull() Execute a SELECT query that returns a single untyped result. Returns:Object the result, or null if there is no result Exceptions 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

public Object getSingleResultOrNull()

Execute a SELECT query that returns a single untyped result.

Returns:Object

the result, or null if there is no result

Exceptions

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

getTimeout	back to summary
public Integer getTimeout() The query timeout. Since 3.2

getTimeout

back to summary

public Integer getTimeout()

The query timeout.

Since: 3.2

isBound	back to summary
public boolean isBound(Parameter<?> param) Return a boolean indicating whether a value has been bound to the parameter. Parameters param:Parameter<?> parameter object Returns:boolean boolean indicating whether parameter has been bound Since 2.0

isBound

back to summary

public boolean isBound(Parameter<?> param)

Return a boolean indicating whether a value has been bound to the parameter.

Parameters

param:Parameter<?>: parameter object

Returns:boolean

boolean indicating whether parameter has been bound

Since

2.0

setCacheRetrieveMode	back to summary
public 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:CacheRetrieveMode cache retrieval mode Returns:Query the same query instance Since 3.2

setCacheRetrieveMode

back to summary

public 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:CacheRetrieveMode: cache retrieval mode

Returns:Query

the same query instance

Since

3.2

setCacheStoreMode	back to summary
public 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:CacheStoreMode cache storage mode Returns:Query the same query instance Since 3.2

setCacheStoreMode

back to summary

public 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:CacheStoreMode: cache storage mode

Returns:Query

the same query instance

Since

3.2

setFirstResult	back to summary
public Query setFirstResult(int startPosition) Set the position of the first result to retrieve. Parameters startPosition:int position of the first result, numbered from 0 Returns:Query the same query instance Exceptions IllegalArgumentException: if the argument is negative

setFirstResult

back to summary

public Query setFirstResult(int startPosition)

Set the position of the first result to retrieve.

Parameters

startPosition:int: position of the first result, numbered from 0

Returns:Query

the same query instance

Exceptions

IllegalArgumentException:: if the argument is negative

setFlushMode	back to summary
public 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:FlushModeType flush mode Returns:Query the same query instance

setFlushMode

back to summary

public 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:FlushModeType: flush mode

Returns:Query

the same query instance

setHint	back to summary
public Query 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. Parameters hintName:String name of the property or hint value:Object value for the property or hint Returns:Query the same query instance Exceptions IllegalArgumentException: if the second argument is not valid for the implementation

setHint

back to summary

public Query 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.

Parameters

hintName:String: name of the property or hint
value:Object: value for the property or hint

Returns:Query

the same query instance

Exceptions

IllegalArgumentException:: if the second argument is not valid for the implementation

setLockMode back to summary

setLockMode	back to summary
public Query setLockMode(LockModeType lockMode) Set the lock mode type to be used for the query execution. Parameters lockMode:LockModeType lock mode Returns:Query the same query instance Exceptions IllegalStateException: if the query is found not to be a Jakarta Persistence query language SELECT query or a `jakarta.persistence.criteria.CriteriaQuery` query Since 2.0

public Query setLockMode(LockModeType lockMode)

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

Parameters

lockMode:LockModeType: lock mode

Returns:Query

the same query instance

Exceptions

IllegalStateException:: if the query is found not to be a Jakarta Persistence query language SELECT query or a jakarta.persistence.criteria.CriteriaQuery query

Since

2.0

setMaxResults	back to summary
public Query setMaxResults(int maxResult) Set the maximum number of results to retrieve. Parameters maxResult:int maximum number of results to retrieve Returns:Query the same query instance Exceptions IllegalArgumentException: if the argument is negative

setMaxResults

back to summary

public Query setMaxResults(int maxResult)

Set the maximum number of results to retrieve.

Parameters

maxResult:int: maximum number of results to retrieve

Returns:Query

the same query instance

Exceptions

IllegalArgumentException:: if the argument is negative

setParameter back to summary

setParameter	back to summary
public <T> Query setParameter(Parameter<T> param, T value) Bind the value of a `Parameter` object. Parameters param:Parameter<T> parameter object value:T parameter value Returns:Query the same query instance Exceptions IllegalArgumentException: if the parameter does not correspond to a parameter of the query Since 2.0

public <T> Query setParameter(Parameter<T> param, T value)

Bind the value of a Parameter object.

Parameters

param:Parameter<T>: parameter object
value:T: parameter value

Returns:Query

the same query instance

Exceptions

IllegalArgumentException:: if the parameter does not correspond to a parameter of the query

Since

2.0

setParameter back to summary

setParameter	back to summary
public Query setParameter(Parameter<Calendar> param, Calendar value, TemporalType temporalType) Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Calendar` to a `Parameter` object. Parameters param:Parameter<Calendar> parameter object value:Calendar parameter value temporalType:TemporalType temporal type Returns:Query the same query instance Annotations @Deprecated since:3.2 Exceptions IllegalArgumentException: if the parameter does not correspond to a parameter of the query Since 2.0

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

Deprecated

since 3.2.

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

Bind an instance of java.util.Calendar to a Parameter object.

Parameters

param:Parameter<Calendar>: parameter object
value:Calendar: parameter value
temporalType:TemporalType: temporal type

Returns:Query

the same query instance

Annotations

@Deprecated
since:3.2

Exceptions

IllegalArgumentException:: if the parameter does not correspond to a parameter of the query

Since

2.0

setParameter back to summary

setParameter	back to summary
public Query setParameter(Parameter<Date> param, Date value, TemporalType temporalType) Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Date` to a `Parameter` object. Parameters param:Parameter<Date> parameter object value:Date parameter value temporalType:TemporalType temporal type Returns:Query the same query instance Annotations @Deprecated since:3.2 Exceptions IllegalArgumentException: if the parameter does not correspond to a parameter of the query Since 2.0

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

Deprecated

since 3.2.

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

Bind an instance of java.util.Date to a Parameter object.

Parameters

param:Parameter<Date>: parameter object
value:Date: parameter value
temporalType:TemporalType: temporal type

Returns:Query

the same query instance

Annotations

@Deprecated
since:3.2

Exceptions

IllegalArgumentException:: if the parameter does not correspond to a parameter of the query

Since

2.0

setParameter	back to summary
public Query setParameter(String name, Object value) Bind an argument value to a named parameter. Parameters name:String parameter name value:Object parameter value Returns:Query the same query instance Exceptions IllegalArgumentException: if the parameter name does not correspond to a parameter of the query or if the argument is of incorrect type

setParameter

back to summary

public Query setParameter(String name, Object value)

Bind an argument value to a named parameter.

Parameters

name:String: parameter name
value:Object: parameter value

Returns:Query

the same query instance

Exceptions

IllegalArgumentException:: if the parameter name does not correspond to a parameter of the query or if the argument is of incorrect type

setParameter back to summary

setParameter	back to summary
public Query setParameter(String name, Calendar value, TemporalType temporalType) Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Calendar` to a named parameter. Parameters name:String parameter name value:Calendar parameter value temporalType:TemporalType temporal type Returns:Query the same query instance Annotations @Deprecated since:3.2 Exceptions IllegalArgumentException: if the parameter name does not correspond to a parameter of the query or if the value argument is of incorrect type

public Query setParameter(String name, Calendar value, TemporalType temporalType)

Deprecated

since 3.2.

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

Bind an instance of java.util.Calendar to a named parameter.

Parameters

name:String: parameter name
value:Calendar: parameter value
temporalType:TemporalType: temporal type

Returns:Query

the same query instance

Annotations

@Deprecated
since:3.2

Exceptions

IllegalArgumentException:: if the parameter name does not correspond to a parameter of the query or if the value argument is of incorrect type

setParameter back to summary

setParameter	back to summary
public Query setParameter(String name, Date value, TemporalType temporalType) Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Date` to a named parameter. Parameters name:String parameter name value:Date parameter value temporalType:TemporalType temporal type Returns:Query the same query instance Annotations @Deprecated since:3.2 Exceptions IllegalArgumentException: if the parameter name does not correspond to a parameter of the query or if the value argument is of incorrect type

public Query setParameter(String name, Date value, TemporalType temporalType)

Deprecated

since 3.2.

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

Bind an instance of java.util.Date to a named parameter.

Parameters

name:String: parameter name
value:Date: parameter value
temporalType:TemporalType: temporal type

Returns:Query

the same query instance

Annotations

@Deprecated
since:3.2

Exceptions

IllegalArgumentException:: if the parameter name does not correspond to a parameter of the query or if the value argument is of incorrect type

setParameter	back to summary
public Query setParameter(int position, Object value) Bind an argument value to a positional parameter. Parameters position:int position value:Object parameter value Returns:Query the same query instance Exceptions IllegalArgumentException: if position does not correspond to a positional parameter of the query or if the argument is of incorrect type

setParameter

back to summary

public Query setParameter(int position, Object value)

Bind an argument value to a positional parameter.

Parameters

position:int: position
value:Object: parameter value

Returns:Query

the same query instance

Exceptions

IllegalArgumentException:: if position does not correspond to a positional parameter of the query or if the argument is of incorrect type

setParameter back to summary

setParameter	back to summary
public Query setParameter(int position, Calendar value, TemporalType temporalType) Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Calendar` to a positional parameter. Parameters position:int position value:Calendar parameter value temporalType:TemporalType temporal type Returns:Query the same query instance Annotations @Deprecated since:3.2 Exceptions IllegalArgumentException: if position does not correspond to a positional parameter of the query or if the value argument is of incorrect type

public Query setParameter(int position, Calendar value, TemporalType temporalType)

Deprecated

since 3.2.

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

Bind an instance of java.util.Calendar to a positional parameter.

Parameters

position:int: position
value:Calendar: parameter value
temporalType:TemporalType: temporal type

Returns:Query

the same query instance

Annotations

@Deprecated
since:3.2

Exceptions

IllegalArgumentException:: if position does not correspond to a positional parameter of the query or if the value argument is of incorrect type

setParameter back to summary

setParameter	back to summary
public Query setParameter(int position, Date value, TemporalType temporalType) Deprecated since 3.2. Newly-written code should use the date/time types defined in `java.time`. Bind an instance of `java.util.Date` to a positional parameter. Parameters position:int position value:Date parameter value temporalType:TemporalType temporal type Returns:Query the same query instance Annotations @Deprecated since:3.2 Exceptions IllegalArgumentException: if position does not correspond to a positional parameter of the query or if the value argument is of incorrect type

public Query setParameter(int position, Date value, TemporalType temporalType)

Deprecated

since 3.2.

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

Bind an instance of java.util.Date to a positional parameter.

Parameters

position:int: position
value:Date: parameter value
temporalType:TemporalType: temporal type

Returns:Query

the same query instance

Annotations

@Deprecated
since:3.2

Exceptions

IllegalArgumentException:: if position does not correspond to a positional parameter of the query or if the value argument is of incorrect type

setTimeout back to summary

setTimeout	back to summary
public Query 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`. Parameters timeout:Integer the timeout, in milliseconds, or null to indicate no timeout Returns:Query the same query instance Since 3.2

public Query 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.

Parameters

timeout:Integer: the timeout, in milliseconds, or null to indicate no timeout

Returns:Query

the same query instance

Since

3.2

unwrap back to summary

unwrap	back to summary
public <T> T unwrap(Class<T> cls) Return an object of the specified type to allow access to a provider-specific API. If the provider implementation of `Query` does not support the given type, the `PersistenceException` is thrown. Parameters cls:Class<T> the type of the object to be returned. This is usually either the underlying class implementing `Query` or an interface it implements. Returns:T an instance of the specified class Exceptions PersistenceException: if the provider does not support the given type Since 2.0

public <T> T unwrap(Class<T> cls)

Return an object of the specified type to allow access to a provider-specific API. If the provider implementation of Query does not support the given type, the PersistenceException is thrown.

Parameters

cls:Class<T>: the type of the object to be returned. This is usually either the underlying class implementing Query or an interface it implements.

Returns:T

an instance of the specified class

Exceptions

PersistenceException:: if the provider does not support the given type

Since

2.0

public Interface Query

Method Summary

Method Detail