javax.persistence.TypedQuery - JPA interface
Interface used to control the execution of typed queries.
- Since:
- JPA 2.0
- See Also:
Query
Parameter
Learn how to define and use JPA/JPQL queries in
Chapter 4 of the ObjectDB/JPA manual.
Execute an update or delete statement.
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 or for a criteria query TransactionRequiredException
- if there is no 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
- Since:
- JPA 1.0
The position of the first result the query object was set to retrieve.
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
- Since:
- JPA 2.0
Get the flush mode in effect for the query execution.
Get the flush mode in effect for the query execution. If a flush mode has not been set for the query object, returns the flush mode in effect for the entity manager.
- Returns:
- flush mode
- Since:
- JPA 2.0
Get the properties and hints and associated values that are in effect for the query instance.
Get the properties and hints and associated values that are in effect for the query instance.
- Returns:
- query properties and hints
- Since:
- JPA 2.0
Get the current lock mode for the query.
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
- Since:
- JPA 2.0
The maximum number of results the query object was set to retrieve.
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
- Since:
- JPA 2.0
Get the parameter object corresponding to the declared positional parameter with the given position.
Get the parameter object corresponding to the declared positional parameter with the given position. This method is not required to be supported for native queries.
- Parameters:
position
- position
- Returns:
- parameter object
- Throws:
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:
- JPA 2.0
Get the parameter object corresponding to the declared parameter of the given name.
Get the parameter object corresponding to the declared parameter of the given name. This method is not required to be supported for native queries.
- Parameters:
name
- parameter name
- Returns:
- parameter object
- Throws:
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:
- JPA 2.0
Get the parameter object corresponding to the declared positional parameter with the given position and 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
- position type
- 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
- Since:
- JPA 2.0
Get the parameter object corresponding to the declared parameter of the given name and 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
- 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
- Since:
- JPA 2.0
Return the value bound to the positional parameter.
Return the value bound to the positional parameter.
- Parameters:
position
- 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
- Since:
- JPA 2.0
Return the value bound to the named parameter.
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
- Since:
- JPA 2.0
Return the value bound to the parameter.
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
- Since:
- JPA 2.0
Get the parameter objects corresponding to the declared parameters of the query.
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
- Since:
- JPA 2.0
Execute a SELECT query and return the query results as an untyped List.
Execute a SELECT query and return the query results as an untyped List.
- Returns:
- a list of the results
- Throws:
IllegalStateException
- if called for a Java 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 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 PersistenceException
- if the query execution exceeds the query timeout value set and the transaction is rolled back
- Since:
- JPA 1.0
Execute a SELECT query and return the query results as a typed List.
Execute a SELECT query and return the query results as a typed List.
- Returns:
- a list of the results
- Throws:
IllegalStateException
- if called for a Java 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 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 PersistenceException
- if the query execution exceeds the query timeout value set and the transaction is rolled back
- Since:
- JPA 2.0
Execute a SELECT query that returns a single untyped result.
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 IllegalStateException
- if called for a Java 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 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 PersistenceException
- if the query execution exceeds the query timeout value set and the transaction is rolled back
- Since:
- JPA 1.0
Execute a SELECT query that returns a single result.
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 QueryTimeoutException
- if the query execution exceeds the query timeout value set and only the statement is rolled back 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 PersistenceException
- if the query execution exceeds the query timeout value set and the transaction is rolled back
- Since:
- JPA 2.0
Return a boolean indicating whether a value has been bound to the parameter.
Return a boolean indicating whether a value has been bound to the parameter.
- Parameters:
param
- parameter object
- Returns:
- boolean indicating whether parameter has been bound
- Since:
- JPA 2.0
Set the position of the first result to retrieve.
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 the argument is negative
- Since:
- JPA 1.0
Set the position of the first result to retrieve.
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 the argument is negative
- Since:
- JPA 2.0
Set the flush mode type to be used for the query execution.
Set the flush mode type to be used for the query execution. The flush mode type applies to the query regardless of the flush mode type in use for the entity manager.
- Parameters:
flushMode
- flush mode
- Returns:
- the same query instance
- Since:
- JPA 1.0
Set the flush mode type to be used for the query execution.
Set the flush mode type to be used for the query execution. The flush mode type applies to the query regardless of the flush mode type in use for the entity manager.
- Parameters:
flushMode
- flush mode
- Returns:
- the same query instance
- Since:
- JPA 2.0
Set a query property or hint.
Set a query property or hint. The hints elements may be used to specify query properties and hints. Properties defined by this specification must be observed by the provider. Vendor-specific hints that are not recognized by a provider must be silently ignored. Portable applications should not rely on the standard timeout hint. Depending on the database in use and the locking mechanisms used by the provider, this hint may or may not be observed.
- Parameters:
hintName
- name of the property or hint value
- value for the property or hint
- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if the second argument is not valid for the implementation
- Since:
- JPA 1.0
Set a query property or hint.
Set a query property or hint. The hints elements may be used to specify query properties and hints. Properties defined by this specification must be observed by the provider. Vendor-specific hints that are not recognized by a provider must be silently ignored. Portable applications should not rely on the standard timeout hint. Depending on the database in use and the locking mechanisms used by the provider, this hint may or may not be observed.
- Parameters:
hintName
- name of property or hint value
- value for the property or hint
- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if the second argument is not valid for the implementation
- Since:
- JPA 2.0
Set the lock mode type to be used for the query execution.
Set the lock mode type to be used for the query execution.
- Parameters:
lockMode
- lock mode
- 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
- Since:
- JPA 2.0
Set the lock mode type to be used for the query execution.
Set the lock mode type to be used for the query execution.
- Parameters:
lockMode
- lock mode
- 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
- Since:
- JPA 2.0
Set the maximum number of results to retrieve.
Set the maximum number of results to retrieve.
- Parameters:
maxResult
- maximum number of results to retrieve
- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if the argument is negative
- Since:
- JPA 1.0
Set the maximum number of results to retrieve.
Set the maximum number of results to retrieve.
- Parameters:
maxResult
- maximum number of results to retrieve
- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if the argument is negative
- Since:
- JPA 2.0
Bind an argument to a positional parameter.
Bind an argument to a positional parameter.
- 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:
- JPA 1.0
Bind the value of a Parameter
object.
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
- Since:
- JPA 2.0
Bind an argument to a named parameter.
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
- Since:
- JPA 1.0
Bind an argument to a positional parameter.
Bind an argument to a positional parameter.
- 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:
- JPA 2.0
Bind the value of a Parameter
object.
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
- Since:
- JPA 2.0
Bind an argument to a named parameter.
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
- Since:
- JPA 2.0
Bind an instance of java.util.Date
to a positional parameter.
Bind an instance of java.util.Date
to a positional parameter.
- Parameters:
position
- position value
- parameter value temporalType
- temporal type
- 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
- Since:
- JPA 1.0
Bind an instance of java.util.Date
to a named parameter.
Bind an instance of java.util.Date
to a named parameter.
- Parameters:
name
- parameter name value
- parameter value temporalType
- temporal type
- 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
- Since:
- JPA 1.0
Bind an instance of java.util.Calendar
to a positional parameter.
Bind an instance of java.util.Calendar
to a positional parameter.
- Parameters:
position
- position value
- parameter value temporalType
- temporal type
- 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
- Since:
- JPA 1.0
Bind an instance of java.util.Date
to a positional parameter.
Bind an instance of java.util.Date
to a positional parameter.
- Parameters:
position
- position value
- parameter value temporalType
- temporal type
- 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
- Since:
- JPA 2.0
Bind an instance of java.util.Calendar
to a named parameter.
Bind an instance of java.util.Calendar
to a named parameter.
- Parameters:
name
- parameter name value
- parameter value temporalType
- temporal type
- 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
- Since:
- JPA 1.0
Bind an instance of java.util.Date
to a Parameter
object.
Bind an instance of java.util.Date
to a Parameter
object.
- Parameters:
param
- parameter object value
- parameter value temporalType
- temporal type
- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if the parameter does not correspond to a parameter of the query
- Since:
- JPA 2.0
Bind an instance of java.util.Date
to a named parameter.
Bind an instance of java.util.Date
to a named parameter.
- Parameters:
name
- parameter name value
- parameter value temporalType
- temporal type
- 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
- Since:
- JPA 2.0
Bind an instance of java.util.Calendar
to a positional parameter.
Bind an instance of java.util.Calendar
to a positional parameter.
- Parameters:
position
- position value
- parameter value temporalType
- temporal type
- 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
- Since:
- JPA 2.0
Bind an instance of java.util.Calendar
to a Parameter
object.
Bind an instance of java.util.Calendar
to a Parameter
object.
- Parameters:
param
- parameter object value
- parameter value temporalType
- temporal type
- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if the parameter does not correspond to a parameter of the query
- Since:
- JPA 2.0
Bind an instance of java.util.Date
to a Parameter
object.
Bind an instance of java.util.Date
to a Parameter
object.
- Parameters:
param
- parameter object value
- parameter value temporalType
- temporal type
- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if the parameter does not correspond to a parameter of the query
- Since:
- JPA 2.0
Bind an instance of java.util.Calendar
to a named parameter.
Bind an instance of java.util.Calendar
to a named parameter.
- Parameters:
name
- parameter name value
- parameter value temporalType
- temporal type
- 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
- Since:
- JPA 2.0
Bind an instance of java.util.Calendar
to a Parameter
object.
Bind an instance of java.util.Calendar
to a Parameter
object.
- Parameters:
param
- parameter object value
- parameter value temporalType
- temporal type
- Returns:
- the same query instance
- Throws:
IllegalArgumentException
- if the parameter does not correspond to a parameter of the query
- Since:
- JPA 2.0
Return an object of the specified type to allow access to the provider-specific API.
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
- Since:
- JPA 2.0