Jakarta Persistence (JPA) Interface

jakarta.persistence.TypedQuery<X>

Type Parameters:: <X> - query result type

Super Interfaces:: Query

Interface used to control the execution of typed queries.

See Also:: Query
Parameter

Since:: Jakarta Persistence (JPA) 2.0

Chapter 4 - JPA Queries (JPQL / Criteria) explains how to use TypedQuery.

Public Instance Methods

int executeUpdate()

Execute an update or delete statement.

Inherited from Query

Returns:: the number of entities updated or deleted.

Throws:: IllegalStateException - if called for a Jakarta Persistence query language SELECT statement or for a criteria query.; PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back.; 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.

Since:: Jakarta Persistence (JPA) 1.0

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

Inherited from Query

Since:: Jakarta Persistence (JPA) 3.2

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

Inherited from Query

Since:: Jakarta Persistence (JPA) 3.2

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.

Inherited from Query

Returns:: position of the first result.

Since:: Jakarta Persistence (JPA) 2.0

The Running JPA Queries article explains how to use getFirstResult.

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.

Inherited from Query

Returns:: flush mode.

Since:: Jakarta Persistence (JPA) 2.0

Map<String,Object> getHints()

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

Inherited from Query

Returns:: query properties and hints.

Since:: Jakarta Persistence (JPA) 2.0

Get the current lock mode for the query.

Returns null if a lock mode has not been set on the query object.

Inherited from Query

Returns:: lock mode.

Throws:: IllegalStateException - if the query is found not to be a Jakarta Persistence query language SELECT query or a CriteriaQuery<T> query.

Since:: Jakarta Persistence (JPA) 2.0

int getMaxResults()

The maximum number of results the query object was set to retrieve.

Returns Integer.java.lang.Integer/MAX_VALUE if Query.setMaxResults was not applied to the query object.

Inherited from Query

Returns:: maximum number of results.

Since:: Jakarta Persistence (JPA) 2.0

Get the parameter object corresponding to the declared parameter of the given name.

This method is not required to be supported for native queries.

Inherited from Query

Parameters:: name - parameter name

Returns:: parameter object.

Throws:: IllegalStateException - if invoked on a native query when the implementation does not support this use.; IllegalArgumentException - if the parameter of the specified name does not exist.

Since:: Jakarta Persistence (JPA) 2.0

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.

Inherited from Query

Parameters:: name - parameter name; type - type

Returns:: parameter object.

Throws:: IllegalStateException - if invoked on a native query or Jakarta Persistence query language query when the implementation does not support this use.; IllegalArgumentException - if the parameter of the specified name does not exist or is not assignable to the type.

Since:: Jakarta Persistence (JPA) 2.0

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.

Inherited from Query

Parameters:: position - position

Returns:: parameter object.

Throws:: IllegalStateException - if invoked on a native query when the implementation does not support this use.; IllegalArgumentException - if the parameter with the specified position does not exist.

Since:: Jakarta Persistence (JPA) 2.0

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.

Inherited from Query

Parameters:: position - position; type - type

Returns:: parameter object.

Throws:: IllegalStateException - if invoked on a native query or Jakarta Persistence query language query when the implementation does not support this use.; IllegalArgumentException - if the parameter with the specified position does not exist or is not assignable to the type.

Since:: Jakarta Persistence (JPA) 2.0

T getParameterValue(Parameter<T> param)

Return the input value bound to the parameter.

(Note that OUT parameters are unbound.)

Inherited from Query

Parameters:: param - parameter object

Returns:: parameter value.

Throws:: IllegalStateException - if the parameter has not been bound.; IllegalArgumentException - if the parameter is not a parameter of the query.

Since:: Jakarta Persistence (JPA) 2.0

Object getParameterValue(String name)

Return the input value bound to the named parameter.

(Note that OUT parameters are unbound.)

Inherited from Query

Parameters:: name - parameter name

Returns:: parameter value.

Throws:: IllegalStateException - if the parameter has not been bound.; IllegalArgumentException - if the parameter of the specified name does not exist.

Since:: Jakarta Persistence (JPA) 2.0

Object getParameterValue(int position)

Return the input value bound to the positional parameter.

(Note that OUT parameters are unbound.)

Inherited from Query

Parameters:: position - position

Returns:: parameter value.

Throws:: IllegalStateException - if the parameter has not been bound.; IllegalArgumentException - if the parameter with the specified position does not exist.

Since:: Jakarta Persistence (JPA) 2.0

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.

Inherited from Query

Returns:: set of the parameter objects.

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

Since:: Jakarta Persistence (JPA) 2.0

List<X> getResultList()

Execute a SELECT query and return the query results as a typed List<X>.

Overrides Query.getResultList

Returns:: a list of the results, each of type X, or an empty list if there are no results.

Throws:: IllegalStateException - if called for a Jakarta Persistence query language UPDATE or DELETE statement.; 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.; 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.; QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back.

Since:: Jakarta Persistence (JPA) 1.0

Stream<X> getResultStream()

Execute a SELECT query and return the query result as a typed Stream<X>.

By default, this method delegates to getResultList().stream(), however, persistence provider may choose to override this method to provide additional capabilities.

Overrides Query.getResultStream

Returns:: a stream of the results, each of type X, or an empty stream if there are no results.

Throws:: IllegalStateException - if called for a Jakarta Persistence query language UPDATE or DELETE statement.; 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.; 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.; QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back.

See Also:: Stream
::getResultList()

Since:: Jakarta Persistence (JPA) 2.2

X getSingleResult()

Execute a SELECT query that returns a single result.

Overrides Query.getSingleResult

Returns:: the result, of type X.

Throws:: IllegalStateException - if called for a Jakarta Persistence query language UPDATE or DELETE statement.; LockTimeoutException - if pessimistic locking fails and only the statement is rolled back.; NonUniqueResultException - if more than one result.; QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back.; PessimisticLockException - if pessimistic locking fails and the transaction is rolled back.; NoResultException - if there is no result.; PersistenceException - if the query execution exceeds the query timeout value set and the transaction 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.

Since:: Jakarta Persistence (JPA) 1.0

X getSingleResultOrNull()

Execute a SELECT query that returns a single untyped result.

Overrides Query.getSingleResultOrNull

Returns:: the result, of type X, or null if there is no result.

Throws:: IllegalStateException - if called for a Jakarta Persistence query language UPDATE or DELETE statement.; LockTimeoutException - if pessimistic locking fails and only the statement is rolled back.; NonUniqueResultException - if more than one result.; QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back.; PessimisticLockException - if pessimistic locking fails and the transaction is rolled back.; PersistenceException - if the query execution exceeds the query timeout value set and the transaction 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.

Since:: Jakarta Persistence (JPA) 3.2

Integer getTimeout()

The query timeout.

Inherited from Query

Since:: Jakarta Persistence (JPA) 3.2

boolean isBound(Parameter<?> param)

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

Inherited from Query

Parameters:: param - parameter object

Returns:: boolean indicating whether parameter has been bound.

Since:: Jakarta Persistence (JPA) 2.0

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.

Overrides Query.setCacheRetrieveMode

Parameters:: cacheRetrieveMode - cache retrieval mode

Returns:: the same query instance.

Since:: Jakarta Persistence (JPA) 3.2

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.

Overrides Query.setCacheStoreMode

Parameters:: cacheStoreMode - cache storage mode

Returns:: the same query instance.

Since:: Jakarta Persistence (JPA) 3.2

Set the position of the first result to retrieve.

Overrides Query.setFirstResult

Parameters:: startPosition - position of the first result, numbered from 0

Returns:: the same query instance.

Throws:: IllegalArgumentException - if the argument is negative.

Since:: Jakarta Persistence (JPA) 1.0

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.

Overrides Query.setFlushMode

Parameters:: flushMode - flush mode

Returns:: the same query instance.

Since:: Jakarta Persistence (JPA) 1.0

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.

Overrides Query.setHint

Parameters:: value - value for the property or hint; hintName - name of property or hint

Returns:: the same query instance.

Throws:: IllegalArgumentException - if the second argument is not valid for the implementation.

Since:: Jakarta Persistence (JPA) 1.0

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

Overrides Query.setLockMode

Parameters:: lockMode - lock mode

Returns:: the same query instance.

Throws:: IllegalStateException - if the query is found not to be a Jakarta Persistence query language SELECT query or a CriteriaQuery<T> query.

Since:: Jakarta Persistence (JPA) 1.0

Set the maximum number of results to retrieve.

Overrides Query.setMaxResults

Parameters:: maxResult - maximum number of results to retrieve

Returns:: the same query instance.

Throws:: IllegalArgumentException - if the argument is negative.

Since:: Jakarta Persistence (JPA) 1.0

Bind the value of a Parameter object.

Overrides Query.setParameter

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.

Since:: Jakarta Persistence (JPA) 1.0

Bind an instance of Calendar to a Parameter<T> object.

Overrides Query.setParameter

Parameters:: temporalType - temporal type; 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.

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

Since:: Jakarta Persistence (JPA) 1.0

Bind an instance of Date to a Parameter<T> object.

Overrides Query.setParameter

Parameters:: temporalType - temporal type; 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.

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

Since:: Jakarta Persistence (JPA) 1.0

Bind an argument value to a named parameter.

Overrides Query.setParameter

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.

Since:: Jakarta Persistence (JPA) 1.0

Bind an instance of Calendar to a named parameter.

Overrides Query.setParameter

Parameters:: name - parameter name; temporalType - temporal type; 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 value argument is of incorrect type.

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

Since:: Jakarta Persistence (JPA) 1.0

Bind an instance of Date to a named parameter.

Overrides Query.setParameter

Parameters:: name - parameter name; temporalType - temporal type; 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 value argument is of incorrect type.

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

Since:: Jakarta Persistence (JPA) 1.0

Bind an argument value to a positional parameter.

Overrides Query.setParameter

Parameters:: position - 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.

Since:: Jakarta Persistence (JPA) 1.0

Bind an instance of Calendar to a positional parameter.

Overrides Query.setParameter

Parameters:: position - position; temporalType - temporal type; 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 value argument is of incorrect type.

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

Since:: Jakarta Persistence (JPA) 1.0

Bind an instance of Date to a positional parameter.

Overrides Query.setParameter

Parameters:: position - position; temporalType - temporal type; 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 value argument is of incorrect type.

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

Since:: Jakarta Persistence (JPA) 1.0

Set the query timeout, in milliseconds.

This is a hint, and is an alternative to setting the hint jakarta.persistence.query.timeout.

Overrides Query.setTimeout

Parameters:: timeout - the timeout, in milliseconds, or null to indicate no timeout

Returns:: the same query instance.

Since:: Jakarta Persistence (JPA) 3.2

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.

Inherited from Query

Parameters:: cls - the type of the object to be returned. This is usually either the underlying class implementing Query or an interface it implements.

Returns:: an instance of the specified class.

Throws:: PersistenceException - if the provider does not support the given type.

Since:: Jakarta Persistence (JPA) 2.0