javax.persistence
Interface Query

All Known Subinterfaces:

JpaQuery

public interface Query

Interface used to control query execution.

Since:

Java Persistence 2.0

Method Summary

int	executeUpdate() Execute an update or delete statement.
int	getFirstResult() The position of the first result the query object was set to retrieve.
FlushModeType	getFlushMode() The flush mode in effect for the query execution.
java.util.Map<java.lang.String,java.lang.Object>	getHints() Get the 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.
<T> Parameter<T>	getParameter(int position, java.lang.Class<T> type) Get the positional parameter with the given position and type.
<T> Parameter<T>	getParameter(java.lang.String name, java.lang.Class<T> type) Get the parameter of the given name and type.
java.util.Set<Parameter<?>>	getParameters() Get the query parameter objects.
<T> T	getParameterValue(Parameter<T> param) Return the value that has been bound to the parameter.
<T> ResultItem<T>	getResultItem(int position, java.lang.Class<T> type) Get the result item with the given position in the result list and type.
<T> ResultItem<T>	getResultItem(java.lang.String alias, java.lang.Class<T> type) Get the result item with the given alias and type.
java.util.List<ResultItem<?>>	getResultItems() Get the result items of the query.
java.util.List	getResultList() Execute a SELECT query and return the query results as an untyped List.
java.lang.Object	getSingleResult() Execute a SELECT query that returns a single untyped result.
java.util.Set<java.lang.String>	getSupportedHints() Get the names of the hints that are supported for query objects.
java.util.List<Result>	getTypedResultList() Execute a query and return the results as a typed List.
Result	getTypedSingleResult() Execute a query that returns a single, typed result.
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 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.util.Calendar value, TemporalType temporalType) Bind an instance of java.util.Calendar to a positional parameter.
Query	setParameter(int position, java.util.Date value, TemporalType temporalType) Bind an instance of java.util.Date to a positional parameter.
Query	setParameter(int position, java.lang.Object value) Bind an argument to a positional parameter.
<T> Query	setParameter(Parameter<T> param, T value) Bind the value of a Parameter object.
Query	setParameter(java.lang.String name, java.util.Calendar value, TemporalType temporalType) Bind an instance of java.util.Calendar to a named parameter.
Query	setParameter(java.lang.String name, java.util.Date value, TemporalType temporalType) Bind an instance of java.util.Date to a named parameter.
Query	setParameter(java.lang.String name, java.lang.Object value) Bind an argument to a named parameter.
<T> T	unwrap(java.lang.Class<T> cls) Return an object of the specified type to allow access to the provider-specific API.

Method Detail

getTypedResultList

java.util.List<Result> getTypedResultList()

Execute a query and return the results as a typed List.

Returns:

a list of the results

Throws:

java.lang.IllegalStateException - if called for a Java Persistence query language UPDATE or DELETE statement

QueryTimeoutException - if the query execution exceeds the query timeout value set

TransactionRequiredException - if a lock mode has been set and there is no transaction

PessimisticLockException - if pessimistic locking fails and the transaction is rolled back

LockTimeoutException - if pessimistic locking fails and only the statement is rolled back

getTypedSingleResult

Result getTypedSingleResult()

Execute a query that returns a single, typed result.

Returns:

the result

Throws:

NoResultException - if there is no result

NonUniqueResultException - if more than one result

java.lang.IllegalStateException - if called for a Java Persistence query language UPDATE or DELETE statement

QueryTimeoutException - if the query execution exceeds the query timeout value set

TransactionRequiredException - if a lock mode has been set and there is no transaction

PessimisticLockException - if pessimistic locking fails and the transaction is rolled back

LockTimeoutException - if pessimistic locking fails and only the statement is rolled back

getResultList

java.util.List getResultList()

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

Returns:

a list of the results

Throws:

java.lang.IllegalStateException - if called for a Java Persistence query language UPDATE or DELETE statement

QueryTimeoutException - if the query execution exceeds the query timeout value set

TransactionRequiredException - if a lock mode has been set and there is no transaction

PessimisticLockException - if pessimistic locking fails and the transaction is rolled back

LockTimeoutException - if pessimistic locking fails and only the statement is rolled back

getSingleResult

java.lang.Object getSingleResult()

Execute a SELECT query that returns a single untyped result.

Returns:

the result

Throws:

NoResultException - if there is no result

NonUniqueResultException - if more than one result

java.lang.IllegalStateException - if called for a Java Persistence query language UPDATE or DELETE statement

QueryTimeoutException - if the query execution exceeds the query timeout value set

TransactionRequiredException - if a lock mode has been set and there is no transaction

PessimisticLockException - if pessimistic locking fails and the transaction is rolled back

LockTimeoutException - if pessimistic locking fails and only the statement is rolled back

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 Java Persistence query language SELECT statement or for a criteria query

TransactionRequiredException - if there is no transaction

QueryTimeoutException - if the statement execution exceeds the query timeout value set

setMaxResults

Query setMaxResults(int maxResult)

Set the maximum number of results to retrieve.

Parameters:

maxResult -

Returns:

the same query instance

Throws:

java.lang.IllegalArgumentException - if argument is negative

getMaxResults

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:

maximum number of results

setFirstResult

Query setFirstResult(int startPosition)

Set the position of the first result to retrieve.

Parameters:

start - position of the first result, numbered from 0

Returns:

the same query instance

Throws:

java.lang.IllegalArgumentException - if argument is negative

getFirstResult

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:

position of first result

setHint

Query setHint(java.lang.String hintName,
              java.lang.Object value)

Set a query hint. If a vendor-specific hint is not recognized, it is 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, the hint may or may not be observed.

Parameters:

hintName -

value -

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 hints and associated values that are in effect for the query instance.

Returns:

query hints

getSupportedHints

java.util.Set<java.lang.String> getSupportedHints()

Get the names of the hints that are supported for query objects. These hints correspond to hints that may be passed to the methods of the Query interface that take hints as arguments or used with the NamedQuery and NamedNativeQuery annotations. These include all standard query hints as well as vendor-specific hints supported by the provider. These hints may or may not currently be in effect.

Returns:

hints

setParameter

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

Bind the value of a Parameter object.

Parameters:

param - parameter to be set

value - parameter value

Returns:

query instance

Throws:

java.lang.IllegalArgumentException - if parameter does not correspond to a parameter of the query

setParameter

Query setParameter(java.lang.String name,
                   java.lang.Object value)

Bind an argument to a named parameter.

Parameters:

name - the parameter name

value -

Returns:

the same query instance

Throws:

java.lang.IllegalArgumentException - if parameter name does not correspond to a parameter of the query or if the argument is of incorrect type

setParameter

Query setParameter(java.lang.String name,
                   java.util.Date value,
                   TemporalType temporalType)

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

Parameters:

name -

value -

temporalType -

Returns:

the same query instance

Throws:

java.lang.IllegalArgumentException - if parameter name does not correspond to a parameter of the query

setParameter

Query setParameter(java.lang.String name,
                   java.util.Calendar value,
                   TemporalType temporalType)

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

Parameters:

name -

value -

temporalType -

Returns:

the same query instance

Throws:

java.lang.IllegalArgumentException - if parameter name does not correspond to a parameter of the query

setParameter

Query setParameter(int position,
                   java.lang.Object value)

Bind an argument to a positional parameter.

Parameters:

position -

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

Query setParameter(int position,
                   java.util.Date value,
                   TemporalType temporalType)

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

Parameters:

position -

value -

temporalType -

Returns:

the same query instance

Throws:

java.lang.IllegalArgumentException - if position does not correspond to a positional parameter of the query

setParameter

Query setParameter(int position,
                   java.util.Calendar value,
                   TemporalType temporalType)

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

Parameters:

position -

value -

temporalType -

Returns:

the same query instance

Throws:

java.lang.IllegalArgumentException - if position does not correspond to a positional parameter of the query

getParameters

java.util.Set<Parameter<?>> getParameters()

Get the query parameter objects. Returns empty set if the query has no parameters.

Returns:

parameter objects

getParameter

<T> Parameter<T> getParameter(java.lang.String name,
                              java.lang.Class<T> type)

Get the parameter of the given name and type.

Returns:

parameter object

Throws:

java.lang.IllegalArgumentException - if the parameter of the specified name and type doesn�t exist

getParameter

<T> Parameter<T> getParameter(int position,
                              java.lang.Class<T> type)

Get the positional parameter with the given position and type.

Returns:

parameter object

Throws:

java.lang.IllegalArgumentException - if the parameter with the specified position and type doesn�t exist

getParameterValue

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

Return the value that has been bound to the parameter.

Parameters:

param - parameter object

Returns:

parameter value

Throws:

java.lang.IllegalStateException - if the parameter has not been been bound

getResultItem

<T> ResultItem<T> getResultItem(java.lang.String alias,
                                java.lang.Class<T> type)

Get the result item with the given alias and type. If the type of the specified item is not assignable to the specified type, the IllegalArgumentException is thrown.

Returns:

result item

Throws:

java.lang.IllegalArgumentException - if the result item of the specified name does not exist or is not assignable to the specified type

getResultItem

<T> ResultItem<T> getResultItem(int position,
                                java.lang.Class<T> type)

Get the result item with the given position in the result list and type. The first position is 0. If the type of the specified item is not assignable to the specified type, the IllegalArgumentException is thrown.

Returns:

result item object

Throws:

java.lang.IllegalArgumentException - if the result item with the specified position does not exist or is not assignable to the specified type

getResultItems

java.util.List<ResultItem<?>> getResultItems()

Get the result items of the query.

Returns:

result item list

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 -

getFlushMode

FlushModeType getFlushMode()

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

setLockMode

Query setLockMode(LockModeType lockMode)

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

Parameters:

lockMode -

Throws:

java.lang.IllegalStateException - if the query is found not to be a Java Persistence query language SELECT query or a Criteria API query

getLockMode

LockModeType getLockMode()

Get the current lock mode for the query.

Returns:

lock mode

Throws:

java.lang.IllegalStateException - if the query is found not to be a Java Persistence query language SELECT query or a Criteria API query

unwrap

<T> T unwrap(java.lang.Class<T> cls)

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

Parameters:

cls - the class of the object to be returned. This is normally either the underlying Query implementation class or an interface that it implements.

Returns:

an instance of the specified class

Throws:

PersistenceException - if the provider does not support the call.