653 words

Running JPA Queries

The Queryjavax.persistence.QueryJPA interfaceInterface used to control query execution.
See JavaDoc Reference Page...
interface defines two methods for running SELECT queries:

Similarly, the TypedQueryjavax.persistence.TypedQueryJPA interfaceInterface used to control the execution of typed queries.
See JavaDoc Reference Page...
interface defines the following methods:

In addition, the Query interface defines a method for running DELETE and UPDATE queries:

Ordinary Query Execution (with getResultList)

The following query retrieves all the Country objects in the database. Because multiple result objects are expected, the query should be run using the getResultListgetResultList()TypedQuery's methodExecute a SELECT query and return the query results as a typed List.
See JavaDoc Reference Page...
method:

Both Queryjavax.persistence.QueryJPA interfaceInterface used to control query execution.
See JavaDoc Reference Page...
and TypedQueryjavax.persistence.TypedQueryJPA interfaceInterface used to control the execution of typed queries.
See JavaDoc Reference Page...
define a getResultList method, but the version of Queryjavax.persistence.QueryJPA interfaceInterface used to control query execution.
See JavaDoc Reference Page...
returns a result list of a raw type (non generic) instead of a parameterized (generic) type:

An attempt to cast the above results to a parameterized type (List<Country>) will cause a compilation warning. If, however, the new TypedQueryjavax.persistence.TypedQueryJPA interfaceInterface used to control the execution of typed queries.
See JavaDoc Reference Page...
interface is used casting is unnecessary and the warning is avoided.

The query result collection functions as any other ordinary Java collection. A result collection of a parameterized type can be iterated easily using an enhanced for loop:

  for (Country c : results) {
      System.out.println(c.getName());
  }

Note that for merely printing the country names, a query that uses projection and retrieves country names directly instead of fully built Country instances would be more efficient.

Single Result Query Execution (with getSingleResult)

The getResultListgetResultList()TypedQuery's methodExecute a SELECT query and return the query results as a typed List.
See JavaDoc Reference Page...
method (which was discussed above) can also be used to run queries that return a single result object. In this case, the result object has to be extracted from the result collection after query execution (e.g. by results.get(0)). To eliminate this routine operation JPA provides an additional method, getSingleResultgetSingleResult()TypedQuery's methodExecute a SELECT query that returns a single result.
See JavaDoc Reference Page...
, as a more convenient method when exactly one result object is expected.

The following aggregate query always returns a single result object, which is a Long object reflecting the number of Country objects in the database:

Notice that when a query returns a single object it might be tempting to prefer Queryjavax.persistence.QueryJPA interfaceInterface used to control query execution.
See JavaDoc Reference Page...
over TypedQueryjavax.persistence.TypedQueryJPA interfaceInterface used to control the execution of typed queries.
See JavaDoc Reference Page...
even when the result type is known because the casting of a single object is easy and the code is simple:

An aggregate COUNT query always returns one result, by definition. In other cases our expectation for a single object result might fail, depending on the database content. For example, the following query is expected to return a single Country object:

However, the correctness of this assumption depends on the content of the database. If the database contains multiple Country objects with the name 'Canada' (e.g. due to a bug) a NonUniqueResultExceptionjavax.persistence.NonUniqueResultExceptionJPA exceptionThrown by the persistence provider when Query.getSingleResult() or TypedQuery.getSingleResult() is executed on a query and there is more than one result from the query.
See JavaDoc Reference Page...
is thrown. On the other hand, if there are no results at all a NoResultExceptionjavax.persistence.NoResultExceptionJPA exceptionThrown by the persistence provider when Query.getSingleResult() or TypedQuery.getSingleResult()is executed on a query and there is no result to return.
See JavaDoc Reference Page...
is thrown. Therefore, using getSingleResultgetSingleResult()TypedQuery's methodExecute a SELECT query that returns a single result.
See JavaDoc Reference Page...
requires some caution and if there is any chance that these exceptions might be thrown they have to be caught and handled.

DELETE and UPDATE Query Execution (with executeUpdate)

DELETE and UPDATE queries are executed using the executeUpdateexecuteUpdate()Query's methodExecute an update or delete statement.
See JavaDoc Reference Page...
method.

For example, the following query deletes all the Country instances:

and the following query resets the area field in all the Country instances to zero:

A TransactionRequiredExceptionjavax.persistence.TransactionRequiredExceptionJPA exceptionThrown by the persistence provider when a transaction is required but is not active.
See JavaDoc Reference Page...
is thrown if no transaction is active.

On success - the executeUpdate method returns the number of objects that have been updated or deleted by the query.

The Query Structure section explains DELETE and UPDATE queries in more detail.


This documentation explains how to use JPA in the context of the ObjectDB Object Database but mostly relevant
also for ORM JPA implementations, such as Hibernate (and HQL), EclipseLink, TopLink, OpenJPA and DataNucleus.
ObjectDB is not an ORM JPA implementation but an Object Database (ODBMS) for Java with built in JPA 2 support.