![[Note]](images.admon/note.gif) | |
| |
EntityManager interface provides the following methods for creating Query object:
Query createQuery(String qlString)
Creates an instance of Query for executing a Java Persistence Query Language statement.
If the argument to the createQuery method is not a valid Java Persistence Query string, the IllegalArgumentException may be thrown or the query execution will fail.
Query createNamedQuery(String name)
Creates an instance of Query for executing a named query (in the Java Persistence Query Language or in native SQL).
Query createNativeQuery(String sqlString)
Creates an instance of Query for executing a native SQL statement, e.g., for UPDATE or DELETE.
Query createNativeQuery(String sqlString, Class resultClass)
Creates an instance of Query for executing a native SQL query. resultClass - the class of the resulting instance(s).
If a native query is not a valid query for the database in use or if the result set specification is incompatible with the result of the query, the query execution will fail and a PersistenceException will be thrown when the query is executed.
Query createNativeQuery(String sqlString, String resultSetMapping)
Creates an instance of Query for executing a native SQL query. resultSetMapping - the name of the result set mapping.
The Query API is used for both static queries (i.e., named queries) and dynamic queries. The Query API also supports named parameter binding and pagination control.
Query interface defines the following methods:
List getResultList()
Executes a SELECT query and returns the query results as a List. Throws IllegalStateException if called for a Java Persistence Query Language UPDATE or DELETE statement
Object getSingleResult()
Executes a SELECT query that returns a single 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.
int executeUpdate()
Executes 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.
Query setMaxResults(int maxResult)
Sets the maximum number of results to retrieve. Returns the same query instance.
Query setFirstResult(int startPosition)
Set the position of the first result to retrieve. The parameter is the start position of the first result, numbered from 0. Returns the same query instance.
Query setParameter(String name, Object value)
Binds an argument to a named parameter. name - the parameter name, value - the parameter value. Returns the same query instance. Throws IllegalArgumentException if parameter name does not correspond to parameter in query string or argument is of incorrect type.
A named parameter is an identifier that is prefixed by the ":" symbol in JPQL. Named parameters are case-sensitive.
The parameter names passed to the setParameter methods DO NOT include the ":" prefix.
Query setParameter(String name, Date value, TemporalType temporalType)
Binds an instance of java.util.Date to a named parameter. Returns the same query instance.
Query setParameter(String name, Calendar value, TemporalType temporalType)
Binds an instance of java.util.Calendar to a named parameter. Returns the same query instance.
Query setParameter(int position, Object value)
Binds an argument to a positional parameter. Returns the same query instance.
Query setParameter(int position, Date value, TemporalType temporalType)
Binds an instance of java.util.Date to a positional parameter. Returns the same query instance.
Query setParameter(int position, Calendar value, TemporalType temporalType)
Binds an instance of java.util.Calendar to a positional parameter. Returns the same query instance.
Query setFlushMode(FlushModeType flushMode)
Sets 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.
The elements of the result of a Java Persistence query whose SELECT clause consists of more than one select expression are of type Object[]. If the SELECT clause consists of only one select expression, the elements of the query result are of type Object. When native SQL queries are used, the SQL result set mapping, determines how many items (entities, scalar values, etc.) are returned. If multiple items are returned, the elements of the query result are of type Object[]. If only a single item is returned as a result of the SQL result set mapping or if a result class is specified, the elements of the query result are of type Object.
An IllegalArgumentException is thrown if a parameter name is specified that does not correspond to a named parameter in the query string, if a positional value is specified that does not correspond to a positional parameter in the query string, or if the type of the parameter is not valid for the query. This exception may be thrown when the parameter is bound, or the execution of the query may fail.
The effect of applying setMaxResults or setFirstResult to a query involving fetch joins over collections is undefined.
Query methods other than the executeUpdate method are NOT REQUIRED to be invoked within a transaction context. In particular, the getResultList and getSingleResult methods are not required to be invoked within a transaction context. If an entity manager with transaction-scoped persistence context is in use, the resulting entities will be DETACHED; if an entity manager with an extended persistence context is used, they will be MANAGED.
Runtime exceptions other than the NoResultException and NonUniqueResultException thrown by the methods of the Query interface cause the current transaction to be ROLLED BACK.
