javax.persistence
Interface Query

All Known Subinterfaces:

TypedQuery<X>

public interface Query

Interface used to control query execution.

Since:

JPA 1.0 version.

Author:

Florent Benoit

See Also:

JPA 2.0 specification

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() Get the flush mode in effect for the query execution.
Map<String,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, Class<T> type) Get the parameter object corresponding to the declared positional parameter with the given position and type.
Parameter<?>	getParameter(String name) Get the parameter object corresponding to the declared parameter of the given name.
<T> Parameter<T>	getParameter(String name, Class<T> type) Get the parameter object corresponding to the declared parameter of the given name and type.
Set<Parameter<?>>	getParameters() Get the parameter objects corresponding to the declared parameters of the query.
Object	getParameterValue(int position) Return the value bound to the positional parameter.
<T> T	getParameterValue(Parameter<T> param) Return the value bound to the parameter.
Object	getParameterValue(String name) Return the value bound to the named parameter.
List	getResultList() Execute a SELECT query and return the query results as a List.
Object	getSingleResult() Execute a SELECT query that returns a single result.
boolean	isBound(Parameter<?> param) Return a boolean indicating whether a value has been bound to the parameter.
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(String hintName, Object value) Set an implementation-specific 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, Calendar value, TemporalType temporalType) Bind an instance of java.util.Calendar to a positional parameter.
Query	setParameter(int position, Date value, TemporalType temporalType) Bind an instance of java.util.Date to a positional parameter.
Query	setParameter(int position, Object value) Bind an argument to a positional parameter.
Query	setParameter(Parameter<Calendar> param, Calendar value, TemporalType temporalType) Bind an instance of java.util.Calendar to a Parameter object.
Query	setParameter(Parameter<Date> param, Date value, TemporalType temporalType) Bind an instance of java.util.Date to a Parameter object.
<T> Query	setParameter(Parameter<T> param, T value) Bind the value of a Parameter object.
Query	setParameter(String name, Calendar value, TemporalType temporalType) Bind an instance of java.util.Calendar to a named parameter.
Query	setParameter(String name, Date value, TemporalType temporalType) Bind an instance of java.util.Date to a named parameter.
Query	setParameter(String name, Object value) Bind an argument to a named parameter.
<T> T	unwrap(Class<T> cls) Return an object of the specified type to allow access to the provider-specific API.

Method Detail

getResultList

List getResultList()

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

Returns:

a list of the results

Throws:

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

getSingleResult

Object getSingleResult()

Execute a SELECT query that returns a single result.

Returns:

the result

Throws:

NoResultException - if there is no result

NonUniqueResultException - if more than one result

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

executeUpdate

int executeUpdate()

Execute an update or delete statement.

Returns:

the number of entities updated or deleted

Throws:

IllegalStateException - if called for a Java Persistence query language SELECT statement

TransactionRequiredException - if there is no transaction

setMaxResults

Query setMaxResults(int maxResult)

Set the maximum number of results to retrieve.

Parameters:

maxResult - the given max number.

Returns:

the same query instance

Throws:

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:

startPosition - position of the first result, numbered from 0

Returns:

the same query instance

Throws:

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 the first result

setHint

Query setHint(String hintName,
              Object value)

Set an implementation-specific hint. If the hint name is not recognized, it is silently ignored.

Parameters:

hintName - the name of the hint.

value - the value of the hint.

Returns:

the same query instance

Throws:

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

getHints

Map<String,Object> getHints()

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

Returns:

query properties and hints

setParameter

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

Bind the value of a Parameter object.

Parameters:

param - parameter object

value - parameter value

Returns:

the same query instance

Throws:

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

setParameter

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

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

Parameters:

param - parameter object

value - parameter value

temporalType -

Returns:

the same query instance

Throws:

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

setParameter

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

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

Parameters:

param - parameter object

value - parameter value

temporalType -

Returns:

the same query instance

Throws:

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

setParameter

Query setParameter(String name,
                   Object value)

Bind an argument to a named parameter.

Parameters:

name - parameter name

value - parameter value

Returns:

the same query instance

Throws:

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

setParameter

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

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

Parameters:

name - parameter name

value - parameter value

temporalType -

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

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

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

Parameters:

name - parameter name

value - parameter value

temporalType -

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

Query setParameter(int position,
                   Object value)

Bind an argument to a positional parameter.

Parameters:

position -

value - parameter value

Returns:

the same query instance

Throws:

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

setParameter

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

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

Parameters:

position -

value - parameter value

temporalType -

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

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

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

Parameters:

position -

value - parameter value

temporalType -

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

getParameters

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:

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

getParameter

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 -

Returns:

parameter object

Throws:

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

getParameter

<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 - parameter name

type -

Returns:

parameter object

Throws:

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

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 -

Returns:

parameter object

Throws:

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

getParameter

<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 -

type -

Returns:

parameter object

Throws:

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

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

getParameterValue

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

Return the value bound to the parameter.

Parameters:

param - parameter object

Returns:

parameter value

Throws:

IllegalArgumentException - if the parameter is not a parameter of the query

IllegalStateException - if the parameter has not been been bound

getParameterValue

Object getParameterValue(String name)

Return the value bound to the named parameter.

Parameters:

name - parameter name

Returns:

parameter value

Throws:

IllegalStateException - if the parameter has not been been bound

IllegalArgumentException - if the parameter of the specified name does not exist

getParameterValue

Object getParameterValue(int position)

Return the value bound to the positional parameter.

Parameters:

position -

Returns:

parameter value

Throws:

IllegalStateException - if the parameter has not been been bound

IllegalArgumentException - if the parameter with the specified position does not exist

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 -

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

setLockMode

Query setLockMode(LockModeType lockMode)

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

Parameters:

lockMode -

Returns:

the same query instance

Throws:

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:

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(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