Obtaining an Entity Manager

The entity manager is the central interface used to interact with entities, but it first has to be obtained by an application. Depending on whether it is a container-managed environment (like you’ll see in Chapter 7 with EJBs) or an application-managed environment, the code can be quite different. For example, in a container-managed environment, the transactions are managed by the container. That means you don’t need to explicitly write the commit or rollback, which you have to do in an application-managed environment.

The term “application managed” means an application is responsible for explicitly obtaining an instance of EntityManager and managing its life cycle (it closes the entity manager when finished, for example). The code in Listing 6-2 demonstrates how a class running in a Java SE environment gets an instance of an entity manager. It uses the Persistence class to bootstrap an EntityManagerFactory associated with a persistence unit (chapter06PU), which is then used to create an entity manager. Notice that in an application-managed environment the developer is responsible for creating and closing the entity manager (i.e., managing its life cycle).

Listing 6-2.  A Main Class Creating an EntityManager with an EntityManagerFactory

public class Main {
 
  public static void main(String[] args) {
 
    // Creates an instance of book
    Book book = new Book ("H2G2", "The Hitchhiker's Guide to the Galaxy", 12.5F, →
                         "1-84023-742-2", 354, false);
 
    // Obtains an entity manager and a transaction
    EntityManagerFactory emf = Persistence .createEntityManagerFactory(" chapter06PU ");
    EntityManager em = emf.createEntityManager();
 
    // Persists the book to the database
    EntityTransaction tx = em.getTransaction();
    tx.begin();
    em.persist(book);
    tx.commit();
 
    // Closes the entity manager and the factory
    em.close();
    emf.close();
  }
}

Creating an application-managed entity manager is simple enough using a factory, but what differentiates application managed from container managed is how the factory is acquired. A container-managed environment is when the application evolves in a Servlet or an EJB container. In a Java EE environment, the most common way to acquire an entity manager is by the @PersistenceContext annotation, or by JNDI lookup. The component running in a container (Servlet, EJB, web service, etc.) doesn’t need to create or close the entity manager, as its life cycle is managed by the container. Listing 6-3 shows the code of a stateless session bean into which we inject a reference of the chapter06PU persistence unit.

Listing 6-3.  A Stateless EJB Injected with a Reference of an Entity Manager

@Stateless
public class BookEJB {
 
  @PersistenceContext(unitName = "chapter06PU")
  private EntityManager em;
 
  public void createBook() {
 
    // Creates an instance of book
    Book book = new Book ("H2G2", "The Hitchhiker's Guide to the Galaxy", 12.5F, →
                         "1-84023-742-2", 354, false);
 
    // Persists the book to the database
    em.persist(book);
  }
}

Compared with Listing 6-2, the code in Listing 6-3 is much simpler. First, there is no Persistence or EntityManagerFactory as the container injects the entity manager instance. The application is not responsible for managing the life cycle of the EntityManager (creating and closing the EntityManager). Second, because stateless beans manage the transactions, there is no explicit commit or rollback. Chapter 7 demonstrates this style of entity manager.

Persistence Context

Before exploring the EntityManager API in detail, you need to understand a crucial concept: the persistence context. A persistence context is a set of managed entity instances at a given time for a given user’s transaction: only one entity instance with the same persistent identity can exist in a persistence context. For example, if a Book instance with an ID of 12 exists in the persistence context, no other book with this ID can exist within that same persistence context. Only entities that are contained in the persistence context are managed by the entity manager, meaning that changes will be reflected in the database.

The entity manager updates or consults the persistence context whenever a method of the javax.persistence.EntityManager interface is called. For example, when a persist() method is called, the entity passed as an argument will be added to the persistence context if it doesn’t already exist. Similarly, when an entity is found by its primary key, the entity manager first checks whether the requested entity is already present in the persistence context. The persistence context can be seen as a first-level cache. It’s a short, live space where the entity manager stores entities before flushing the content to the database. By default, objects just live in the persistent context for the duration of the transaction.

To summarize, let’s look at Figure 6-1 where two users need to access entities whose data are stored in the database. Each user has his own persistence context that lasts for the duration of his own transaction. User 1 gets the Book entities with IDs equal to 12 and 56 from the database, so both get stored in his persistence context. User 2 gets the entities 12 and 34. As you can see, the entity with ID = 12 is stored in each user’s persistence context. While the transaction runs, the persistence context acts like a first-level cache storing the entities that can be managed by the EntityManager. Once the transaction ends, the persistence context ends and the entities are cleared.

The configuration for an entity manager is bound to the factory that created it. Whether application or container managed, the factory needs a persistence unit from which to create an entity manager. A persistence unit dictates the settings to connect to the database and the list of entities that can be managed in a persistence context. The persistence.xml file (see Listing 6-4) located in the META-INF directory defines the persistence unit. The persistence unit has a name (chapter06PU) and a set of attributes.

Listing 6-4.  A Persistence Unit with a Set of Manageable Entities

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns=" http://xmlns.jcp.org/xml/ns/persistence "
             xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance "
             xsi:schemaLocation=" http://xmlns.jcp.org/xml/ns/persistence →
             http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd "
             version="2.1">
 
  <persistence-unit name=" chapter06PU " transaction-type="RESOURCE_LOCAL">
    <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
    <class>org.agoncal.book.javaee7.chapter06. Book </class>
    <class>org.agoncal.book.javaee7.chapter06. Customer </class>
    <class>org.agoncal.book.javaee7.chapter06. Address </class>
    <properties>
      <property name="javax.persistence.schema-generation.database.action" →
               value="drop-and-create"/>
      <property name="javax.persistence.jdbc.driver" →
               value="org.apache.derby.jdbc.EmbeddedDriver"/>
      <property name=" javax.persistence.jdbc.url " →
               value="jdbc:derby:memory: chapter06DB ;create=true"/>
      <property name=" eclipselink.logging.level " value="INFO"/>
    </properties>
  </persistence-unit>
</persistence>

The persistence unit is the bridge between the persistence context and the database. On one hand, the <class> tag lists all the entities that could be managed in the persistence context, and, on the other, it gives all the information to physically connect to the database (using properties). This is because you are in an application-managed environment (transaction-type="RESOURCE_LOCAL"). As you’ll see in Chapter 7, in a container-managed environment, the persistence.xml would define a data source instead of the database connection properties and set the transaction type to JTA (transaction-type="JTA").

In JPA 2.1, some properties of the persistence.xml file have been standardized (see Table 6-1). They all start with javax.persistence such as javax.persistence.jdbc.url. JPA providers are required to support these standard properties, but they may provide custom properties of their own, such as the EclipseLink property in the example (e.g., eclipselink.logging.level).

Manipulating Entities

Being the central piece of JPA, we use the entity manager for both simple entity manipulation and complex JPQL query execution. When manipulating single entities, the EntityManager interface can be seen as a generic Data Access Object (DAO), which allows CRUD operations on any entity (see Table 6-2).

To help you gain a better understanding of these methods, I use a simple example of a one-way, one-to-one relationship between a Customer and an Address. Both entities have automatically generated identifiers (thanks to the @GeneratedValue annotation), and Customer (see Listing 6-5) has a lazy fetch to Address (see Listing 6-6).

Listing 6-5.  The Customer Entity with a One-Way, One-to-One Address

@Entity
public class Customer {
 
  @Id @GeneratedValue
  private Long id;
  private String firstName;
  private String lastName;
  private String email;
  @OneToOne (fetch = FetchType.LAZY)
  @JoinColumn(name = "address_fk")
  private Address address;
 
  // Constructors, getters, setters
}

Listing 6-6.  The Address Entity

@Entity
public class Address {
 
  @Id @GeneratedValue
  private Long id;
  private String street1;
  private String city;
  private String zipcode;
  private String country;
 
  // Constructors, getters, setters
}

These two entities will get mapped into the database structure shown in Figure 6-2. Note the ADDRESS_FK column is the foreign key to ADDRESS.

For better readability, the fragments of code used in the upcoming section assume that the em attribute is of type EntityManager and tx of type EntityTransaction.

Customer customer = new Customer("Antony", "Balla", " [email protected] ");
Address address = new Address("Ritherdon Rd", "London", "8QE", "UK");
customer.setAddress(address);
 
tx.begin();
em. persist (customer);
em. persist (address);
tx.commit();
 
assertNotNull(customer.getId());
assertNotNull(address.getId());

Customer customer = em.find (Customer.class, 1234L)
if (customer!= null) {
  // Process the object
}

try {
  Customer customer = em.getReference (Customer.class, 1234L)
  // Process the object
} catch(EntityNotFoundException ex) {
  // Entity not found
}

Customer customer = new Customer("Antony", "Balla", " [email protected] ");
Address address = new Address("Ritherdon Rd", "London", "8QE", "UK");
customer.setAddress(address);
 
tx.begin();
em.persist(customer);
em.persist(address);
tx.commit();
tx.begin();
em. remove (customer);
tx.commit();
 
// The data is removed from the database but the object is still accessible
assertNotNull( customer );

@Entity
public class Customer {
 
  @Id @GeneratedValue
  private Long id;
  private String firstName;
  private String lastName;
  private String email;
  @OneToOne (fetch = FetchType.LAZY, orphanRemoval=true )
  private Address address;
 
  // Constructors, getters, setters
}

tx.begin();
em.persist(customer);
em.persist(address);
tx.commit();

tx.begin();
em.persist(customer);
em. flush ();
em.persist(address);
tx.commit();

Customer customer = em.find(Customer.class, 1234L)
assertEquals(customer.getFirstName(), " Antony ");
 
customer.setFirstName(" William ");
 
em.refresh(customer);
assertEquals(customer.getFirstName(), " Antony ");
");

Customer customer = new Customer("Antony", "Balla", " [email protected] ");
 
tx.begin();
em.persist(customer);
tx.commit();
 
assertTrue ( em.contains(customer) );
 
tx.begin();
em.remove(customer);
tx.commit();
 
assertFalse(em.contains(customer) );

Customer customer = new Customer("Antony", "Balla", " [email protected] ");
 
tx.begin();
em.persist(customer);
tx.commit();
 
assertTrue (em.contains(customer));
 

em.detach(customer); 
 
assertFalse (em.contains(customer));

Customer customer = new Customer("Antony", "Balla", " [email protected] ");
 
tx.begin();
em.persist(customer);
tx.commit();
 
em.clear();
 
// Sets a new value to a detached entity
customer.setFirstName("William");
 
tx.begin();
em.merge(customer);
tx.commit();

Customer customer = new Customer(" Antony ", "Balla", " [email protected] ");
 
tx.begin();
em. persist (customer);
 
customer.setFirstName("Williman");
 
tx.commit();

Customer customer = new Customer("Antony", "Balla", " [email protected] ");
Address address = new Address("Ritherdon Rd", "London", "8QE", "UK");
customer.setAddress(address);
 
tx.begin();
em.persist(customer);
em.persist(address);
tx.commit();

Customer customer = new Customer("Antony", "Balla", " [email protected] ");
Address address = new Address("Ritherdon Rd", "London", "8QE", "UK");
customer.setAddress(address);
 
tx.begin();
em.persist(customer);
tx.commit();

@Entity
public class Customer {
 
  @Id @GeneratedValue
  private Long id;
  private String firstName;
  private String lastName;
  private String email;
  @OneToOne (fetch = FetchType.LAZY, cascade = {CascadeType.PERSIST, CascadeType.REMOVE} )
  @JoinColumn(name = "address_fk")
  private Address address;
 
  // Constructors, getters, setters
}

Select

The SELECT clause follows the path expressions syntax and results in one of the following forms: an entity, an entity attribute, a constructor expression, an aggregate function, or some sequence of these Path expressions are the building blocks of queries and are used to navigate on entity attributes or across entity relationships (or a collection of entities) via the dot (.) navigation using the following syntax:

SELECT [DISTINCT] <expression> [[AS] <identification variable>]
expression ::= { NEW | TREAT | AVG | MAX | MIN | SUM | COUNT }

A simple SELECT returns an entity. For example, if a Customer entity has an alias called c, SELECT c will return an entity or a list of entities.

SELECT c
FROM Customer c

But a SELECT clause can also return attributes. If the Customer entity has a first name, SELECT c.firstName will return a String or a collection of Strings with the first names.

SELECT c.firstName
FROM Customer c

To retrieve the first name and the last name of a customer, you create a list containing the following two attributes:

SELECT c.firstName, c.lastName
FROM Customer c

Since JPA 2.0, an attribute can be retrieved depending on a condition (using a CASE WHEN ... THEN ... ELSE ... END expression). For example, instead of retrieving the price of a book, a statement can return a computation of the price (e.g., 50% discount) depending on the publisher (e.g., 50% discount on the Apress books, 20% discount for all the other books).

SELECT CASE b.editor WHEN 'Apress'
                     THEN b.price * 0.5
                     ELSE b.price * 0.8
       END
FROM Book b

If a Customer entity has a one-to-one relationship with Address, c.address refers to the address of the customer, and the result of the following query will return not a list of customers but a list of addresses:

SELECT c.address
FROM Customer c

Navigation expressions can be chained together to traverse complex entity graphs. Using this technique, path expressions such as c.address.country.code can be constructed, referring to the country code of the customer’s address.

SELECT c.address.country.code
FROM Customer c

A constructor may be used in the SELECT expression to return an instance of a Java class initialized with the result of the query. The class doesn’t have to be an entity, but the constructor must be fully qualified and match the attributes.

SELECT NEW org.agoncal.javaee7.CustomerDTO(c.firstName, c.lastName, c.address.street1)
FROM Customer c

The result of this query is a list of CustomerDTO objects that have been instantiated with the new operator and initialized with the first name, last name, and street of the customers.

Executing these queries will return either a single value or a collection of zero or more entities (or attributes) including duplicates. To remove the duplicates, the DISTINCT operator must be used.

SELECT DISTINCT c
FROM Customer c
 
SELECT DISTINCT c.firstName
FROM Customer c

The result of a query may be the result of an aggregate function applied to a path expression. The following aggregate functions can be used in the SELECT clause: AVG, COUNT, MAX, MIN, SUM. The results may be grouped in the GROUP BY clause and filtered using the HAVING clause.

SELECT COUNT (c)
FROM Customer c

Scalar expressions also can be used in the SELECT clause of a query as well as in the WHERE and HAVING clauses. These expressions can be used on numeric (ABS, SQRT, MOD, SIZE, INDEX), String (CONCAT, SUBSTRING, TRIM, LOWER, UPPER, LENGTH, LOCATE), and date-time (CURRENT_DATE, CURRENT_TIME, CURRENT_TIMESTAMP) values.

From

The FROM clause of a query defines entities by declaring identification variables. An identification variable, or alias, is an identifier that can be used in the other clauses (SELECT, WHERE, etc.). The syntax of the FROM clause consists of an entity and an alias. In the following example, Customer is the entity and c the identification variable:

SELECT c
FROM Customer c

Where

The WHERE clause of a query consists of a conditional expression used to restrict the result of a SELECT, UPDATE, or DELETE statement. The WHERE clause can be a simple expression or a set of conditional expressions used to filter the query.

The simplest way to restrict the result of a query is to use the attribute of an entity. For example, the following query selects all customers named Vincent:

SELECT c
FROM Customer c
WHERE c.firstName = 'Vincent'

You can further restrict queries by using the logical operators AND and OR. The following example uses AND to select all customers named Vincent, living in France:

SELECT c
FROM Customer c
WHERE c.firstName = 'Vincent' AND c.address.country = 'France'

The WHERE clause also uses comparison operators: =, >, >=, <, <=, <>, [NOT] BETWEEN, [NOT] LIKE, [NOT] IN, IS [NOT] NULL, IS [NOT] EMPTY, [NOT] MEMBER [OF]. The following shows an example using two of these operators:

SELECT c
FROM Customer c
WHERE c.age > 18
 
SELECT c
FROM Customer c
WHERE c.age NOT BETWEEN 40 AND 50
 
SELECT c
FROM Customer c
WHERE c.address.country IN ('USA', 'Portugal')

The LIKE expression consists of a String and optional escape characters that define the match conditions: the underscore (_) for single-character wildcards and the percent sign (%) for multicharacter wildcards.

SELECT c
FROM Customer c
WHERE c.email LIKE '%mail.com'

SELECT c
FROM Customer c
WHERE c.firstName = ?1 AND c.address.country = ?2

SELECT c
FROM Customer c
WHERE c.firstName = :fname AND c.address.country = :country

SELECT c
FROM Customer c
WHERE c.age = ( SELECT MIN(cust. age) FROM Customer cust )
)

Order By

The ORDER BY clause allows the entities or values that are returned by a SELECT query to be ordered. The ordering applies to the entity attribute specified in this clause followed by the ASC or DESC keyword. The keyword ASC specifies that ascending ordering be used; DESC, the inverse, specifies that descending ordering be used. Ascending is the default and can be omitted.

SELECT c
FROM Customer c
WHERE c.age > 18
ORDER BY c.age DESC

Multiple expressions may also be used to refine the sort order.

SELECT c
FROM Customer c
WHERE c.age > 18
ORDER BY c.age DESC , c.address.country ASC

Group By and Having

The GROUP BY construct enables the aggregation of result values according to a set of properties. The entities are divided into groups based on the values of the entity field specified in the GROUP BY clause. To group customers by country and count them, use the following query:

SELECT c.address.country, count(c)
FROM Customer c
GROUP BY c.address.country

The GROUP BY defines the grouping expressions (c.address.country) over which the results will be aggregated and counted (count(c)). Note that expressions that appear in the GROUP BY clause must also appear in the SELECT clause.

The HAVING clause defines an applicable filter after the query results have been grouped, similar to a secondary WHERE clause, filtering the result of the GROUP BY. Using the previous query, by adding a HAVING clause, a result of countries other than the UK can be returned.

SELECT c.address.country, count(c)
FROM Customer c
GROUP BY c.address.country
HAVING c.address.country <> 'UK'

GROUP BY and HAVING can only be used within a SELECT clause (not a DELETE or an UPDATE).

Bulk Delete

You know how to remove an entity with the EntityManager.remove() method and query a database to retrieve a list of entities that correspond to certain criteria. To remove a list of entities, you can execute a query, iterate through it, and remove each entity individually. Although this is a valid algorithm, it is terrible in terms of performance (too many database accesses). There is a better way to do it: bulk deletes.

JPQL performs bulk delete operations across multiple instances of a specific entity class. These are used to delete a large number of entities in a single operation. The DELETE statement looks like the SELECT statement, as it can have a restricting WHERE clause and use parameters. As a result, the number of entity instances affected by the operation is returned. The syntax of the DELETE statement is

DELETE FROM <entity name> [[AS] <identification variable>]
[WHERE <where clause>]

As an example, to delete all customers younger than 18, you can use a bulk removal via a DELETE statement.

DELETE FROM Customer c
WHERE c.age < 18

Bulk Update

Bulk updates of entities are accomplished with the UPDATE statement, setting one or more attributes of the entity subject to conditions in the WHERE clause. The UPDATE statement syntax is

UPDATE <entity name> [[AS] <identification variable>]
SET <update statement> {, <update statement>}*
[WHERE <where clause>]

Rather than deleting all the young customers, their first name can be changed to “too young” with the following statement:

UPDATE Customer c
SET c.firstName = 'TOO YOUNG'
WHERE c.age < 18

Dynamic Queries

Dynamic queries are defined on the fly as needed by the application. To create a dynamic query, use the EntityManager.createQuery() method, which takes a String as a parameter that represents a JPQL query.

In the following code, the JPQL query selects all the customers from the database. The result of this query is a list, so when you invoke the getResultList() method, it returns a list of Customer entities (List<Customer>). However, if you know that your query only returns a single entity, use the getSingleResult() method. It returns a single entity and avoids the work of retrieving the data as a list.

Query query = em. createQuery ("SELECT c FROM Customer c");
List<Customer> customers = query. getResultList ();

This JPQL query returns a Query object. When you invoke the query.getResultList() method, it returns a list of untyped objects. If you want the same query to return a list of type Customer, you need to use the TypedQuery as follows:

TypedQuery <Customer> query = em.createQuery("SELECT c FROM Customer c", Customer.class );
List<Customer> customers = query.getResultList();

This query string can also be dynamically created by the application, which can then specify a complex query at runtime not known ahead of time. String concatenation is used to construct the query dynamically depending on the criteria.

String jpqlQuery = "SELECT c FROM Customer c";
if (someCriteria)
    jpqlQuery += " WHERE c.firstName = 'Betty'";
query = em.createQuery( jpqlQuery );
List<Customer> customers = query.getResultList();

The previous query retrieves customers named Betty, but you might want to introduce a parameter for the first name. There are two possible choices for passing a parameter: using names or positions. In the following example, I use a named parameter called :fname (note the : symbol) in the query and bound it with the setParameter method:

query = em.createQuery("SELECT c FROM Customer c where c.firstName = :fname ");
query.setParameter(" fname ", "Betty");
List<Customer> customers = query.getResultList();

Note that the parameter name fname does not include the colon used in the query. The code using a position parameter would look like the following:

query = em.createQuery("SELECT c FROM Customer c where c.firstName = ?1 ");
query.setParameter( 1 , "Betty");
List<Customer> customers = query.getResultList();

If you need to use pagination to display the list of customers by chunks of ten, you can use the setMaxResults method as follows:

query = em.createQuery("SELECT c FROM Customer c", Customer.class);
query. setMaxResults (10);
List<Customer> customers = query.getResultList();

An issue to consider with dynamic queries is the cost of translating the JPQL string into an SQL statement at runtime. Because the query is dynamically created and cannot be predicted, the persistence provider has to parse the JPQL string, get the ORM metadata, and generate the equivalent SQL. The performance cost of processing each of these dynamic queries can be an issue. If you have static queries that are unchangeable and want to avoid this overhead, then you can use named queries instead.

Named Queries

Named queries are different from dynamic queries in that they are static and unchangeable. In addition to their static nature, which does not allow the flexibility of a dynamic query, named queries can be more efficient to execute because the persistence provider can translate the JPQL string to SQL once the application starts, rather than every time the query is executed.

Named queries are static queries expressed in metadata inside either a @NamedQuery annotation or the XML equivalent. To define these reusable queries, annotate an entity with the @NamedQuery annotation, which takes two elements: the name of the query and its content. So let’s change the Customer entity and statically define three queries using annotations (see Listing 6-22).

Listing 6-22.  The Customer Entity Defining Named Queries

@Entity
@NamedQueries({
  @NamedQuery ( name = " findAll ", query ="select c from Customer c"),
  @NamedQuery(name = "findVincent", →
              query="select c from Customer c where c.firstName = 'Vincent'"),
  @NamedQuery(name = "findWithParam", →
              query="select c from Customer c where c.firstName = :fname")
})
public class Customer {
 
  @Id @GeneratedValue
  private Long id;
  private String firstName;
  private String lastName;
  private Integer age;
  private String email;
  @OneToOne
  @JoinColumn(name = "address_fk")
  private Address address;
 
  // Constructors, getters, setters
}

Because the Customer entity defines more than one named query, it uses the @NamedQueries annotation, which takes an array of @NamedQuery. The first query, called findAll, selects all customers from the database with no restriction (no WHERE clause). The findWithParam query uses the parameter :fname to restrict customers by their first name. Listing 6-22 shows an array of @NamedQuery, but, if the Customer only had one query, it would have been defined as follows:

@Entity
@NamedQuery ( name = " findAll ", query ="select c from Customer c")
public class Customer {...}

The way to execute these named queries resembles the way dynamic queries are used. The EntityManager.createNamedQuery() method is invoked and passed to the query name defined by the annotations. This method returns a Query or a TypedQuery that can be used to set parameters, the max results, fetch modes, and so on. To execute the findAll query, write the following code:

Query query = em. createNamedQuery (" findAll ");

Again, if you need to type the query to return a list of Customer objects, you’ll need to use the TypedQuery as follows:

TypedQuery <Customer> query = em.createNamedQuery("findAll", Customer.class );

The following is a fragment of code calling the findWithParam named query, passing the parameter :fname, and setting the maximum result to 3:

Query query = em.createNamedQuery("findWithParam");
query.setParameter("fname", "Vincent");
query. setMaxResults (3);
List<Customer> customers = query.getResultList();

Because most of the methods of the Query API return a Query object, you can use the following elegant shortcut to write queries. You call methods one after the other (setParameter().setMaxResults(), etc.).

Query query = em.createNamedQuery("findWithParam").setParameter("fname", "Vincent") →
                                                  .setMaxResults(3);

Named queries are useful for organizing query definitions and powerful for improving application performance. The organization comes from the fact that the named queries are defined statically on entities and are typically placed on the entity class that directly corresponds to the query result (here the findAll query returns customers, so it should be defined in the Customer entity).

There is a restriction in that the name of the query is scoped to the persistence unit and must be unique within that scope, meaning that only one findAll method can exist. A findAll query for customers and a findAll query for addresses should be named differently. A common practice is to prefix the query name with the entity name. For example, the findAll query for the Customer entity would be named Customer.findAll.

Another problem is that the name of the query, which is a String, is manipulated, and, if you make a typo or refactor your code, you may get some exceptions indicating that the query doesn’t exist. To limit the risks, you can replace the name of a query with a constant. Listing 6-23 shows how to refactor the Customer entity.

Listing 6-23.  The Customer Entity Defining a Named Query with a Constant

@Entity
@NamedQuery(name = Customer.FIND_ALL , query="select c from Customer c"),
public class Customer {
 
  public static final String FIND_ALL = "Customer.findAll";
 
  // Attributes, constructors, getters, setters
}

The FIND_ALL constant identifies the findAll query nonambiguously by prefixing the name of the query with the name of the entity. The same constant is then used in the @NamedQuery annotation, and you can use this constant to execute the query as follows:

TypedQuery<Customer> query = em.createNamedQuery( Customer.FIND_ALL , Customer.class);

Criteria API (or Object-Oriented Queries)

Until now, I’ve been using Strings to write JPQL (dynamic or named queries) statements. This has the advantage of writing a database query concisely but the inconvenience of being error prone and difficult for an external framework to manipulate: it is a String, you end up concatenating Strings and so many typos can be made. For example, you could have typos on JPQL keywords (SLECT instead of SELECT), class names (Custmer instead of Customer), or attributes (firstname instead of firstName). You can also write a syntactically incorrect statement (SELECT c WHERE c.firstName = 'John' FROM Customer). Any of these mistakes will be discovered at runtime, and it may sometimes be difficult to find where the bug comes from.

JPA 2.0 created a new API, called Criteria API and defined in the package javax.persistence.criteria. It allows you to write any query in an object-oriented and syntactically correct way. Most of the mistakes that a developer could make writing a statement are found at compile time, not at runtime. The idea is that all the JPQL keywords (SELECT, UPDATE, DELETE, WHERE, LIKE, GROUP BY. . .) are defined in this API. In other words, the Criteria API supports everything JPQL can do but with an object-based syntax. Let’s have a first look at a query that retrieves all the customers named “Vincent.” In JPQL, it would look as follows:

SELECT c FROM Customer c WHERE c.firstName = 'Vincent'

This JPQL statement is rewritten in Listing 6-24 in an object-oriented way using the Criteria API.

Listing 6-24.  A Criteria Query Selecting All the Customers Named Vincent

CriteriaBuilder builder = em.getCriteriaBuilder();
CriteriaQuery <Customer> criteriaQuery = builder.createQuery(Customer.class);
Root <Customer> c = criteriaQuery . from (Customer.class);
criteriaQuery . select (c). where (builder.equal( c.get("firstName") , "Vincent"));
Query query = em.createQuery( criteriaQuery ).getResultList();
List<Customer> customers = query.getResultList();

Without going into too much detail, you can see that the SELECT, FROM, and WHERE keywords have an API representation through the methods select(), from(), and where(). And this rule applies for every JPQL keyword. Criteria queries are constructed through the CriteriaBuilder interface that is obtained by the EntityManager (the em attribute in Listings 6-24 and 6-25). It contains methods to construct the query definition (this interface defines keywords such as desc(), asc(), avg(), sum(), max(), min(), count(), and(), or(), greaterThan(), lowerThan(). . .). The other role of the CriteriaBuilder is to serve as the main factory of criteria queries (CriteriaQuery) and criteria query elements. This interface defines methods such as select(), from(), where(), orderBy(), groupBy(), and having(), which have the equivalent meaning in JPQL. In Listing 6-24, the way you get the alias c (as in SELECT c FROM Customer) is through the Root interface (Root<Customer> c). Then you just have to use the builder, the query, and the root to write any JPQL statement you want: from the simplest (select all the entities from the database) to the most complex (joins, subqueries, case expressions, functions . . .).

Listing 6-25.  A Criteria Query Selecting All the Customers Older Than 40

CriteriaBuilder builder = em.getCriteriaBuilder();
CriteriaQuery<Customer> criteriaQuery = builder.createQuery(Customer.class);
Root<Customer> c = criteriaQuery.from(Customer.class);
criteriaQuery.select(c).where(builder.greaterThan( c.get("age").as(Integer.class) , 40));
Query query = em.createQuery(criteriaQuery).getResultList();
List<Customer> customers = query.getResultList();

Let’s take another example. Listing 6-25 shows a query that retrieves all the customers older than 40. The c.get("age") gets the attribute age from the Customer entity and checks if it’s greater than 40.

I started this section saying that the Criteria API allows you to write error-free statements. But it’s not completely true yet. When you look at Listings 6-24 and 6-25, you can still see some strings ("firstName" and "age") that represent the attributes of the Customer entity. So typos can still be made. In Listing 6-25, we even need to cast the age into an Integer (c.get("age").as(Integer.class)) because there is no other way to discover that the age attribute is of type Integer. To solve these problems, the Criteria API comes with a static metamodel class for each entity, bringing type safety to the API.

@Entity
public class Customer {
 
  @Id @GeneratedValue
  private Long id;
  private String firstName;
  private String lastName;
  private Integer age;
  private String email;
  private Address address;
 
  // Constructors, getters, setters
}

@Generated("EclipseLink")
@StaticMetamodel(Customer.class)
public class Customer_ {
 
  public static volatile SingularAttribute<Customer, Long > id;
  public static volatile SingularAttribute<Customer, String > firstName;
  public static volatile SingularAttribute<Customer, String> lastName;
  public static volatile SingularAttribute<Customer, Integer > age;
  public static volatile SingularAttribute<Customer, String> email;
  public static volatile SingularAttribute<Customer, Address > address;
}

CriteriaBuilder builder = em.getCriteriaBuilder();
CriteriaQuery<Customer> criteriaQuery = builder.createQuery(Customer.class);
Root<Customer> c = criteriaQuery.from(Customer.class);
criteriaQuery.select(c).where(builder.greaterThan( c.get(Customer_.age) , 40));
Query query = em.createQuery(criteriaQuery).getResultList();
List<Customer> customers = query.getResultList();

Native Queries

JPQL has a very rich syntax that allows you to handle entities in any form and ensures portability across databases. JPA enables you to use specific features of a database by using native queries. Native queries take a native SQL statement (SELECT, UPDATE, or DELETE) as the parameter and return a Query instance for executing that SQL statement. However, native queries are not expected to be portable across databases.

If the code is not portable, why not use JDBC calls? The main reason to use JPA native queries rather than JDBC calls is because the result of the query will be automatically converted back to entities. If you want to retrieve all the customer entities from the database using SQL, you need to use the EntityManager.createNativeQuery() method that has as parameters the SQL query and the entity class that the result should be mapped to.

Query query = em.createNativeQuery (" SELECT * FROM t_customer ", Customer.class);
List<Customer> customers = query.getResultList();

As you can see in the preceding code fragment, the SQL query is a String that can be dynamically created at runtime (just like JPQL dynamic queries). Again, the query could be complex, and, because the persistence provider doesn’t know in advance, it will interpret it each time. Like named queries, native queries can use annotations to define static SQL queries. Named native queries are defined using the @NamedNativeQuery annotation, which must be placed on any entity (see code below). Like JPQL named queries, the name of the query must be unique within the persistence unit.

@Entity
@NamedNativeQuery(name = "findAll", query="select * from t_customer")
@Table(name = "t_customer")
public class Customer {...}

Stored Procedure Queries

So far all the different queries (JPQL or SQL) have the same purpose: send a query from your application to the database that will execute it and send back a result. Stored procedures are different in the sense that they are actually stored in the database itself and executed within this database.

A stored procedure is a subroutine available to applications that access a relational database. Typical usage could be extensive or complex processing that requires execution of several SQL statements or a data-intensive repetitive task. Stored procedures are usually written in a proprietary language close to SQL and therefore not easily portable across database vendors. But storing the code inside the database even in a nonportable way provides many advantages, like

• Better performance due to precompilation of the stored procedure as well as reutilizing its execution plan,
• Keeping statistics on the code to keep it optimized,
• Reducing the amount of data passed over a network by keeping the code on the server,
• Altering the code in a central location without replicating in several different programs,
• Stored procedures, which can be used by multiple programs written in different languages (not just Java),
• Hiding the raw data by allowing only stored procedures to gain access to the data, and
• Enhancing security controls by granting users permission to execute a stored procedure independently of underlying table permissions.

Let’s take a look at a practical example: archiving old books and CDs. After a certain date books and CDs have to be archived in a certain warehouse, meaning they have to be physically transferred from a warehouse to a reseller. Archiving books and CDs can be a time-consuming process as several tables have to be updated (Inventory, Warehouse, Book, CD, Transportation tables, etc.). So we can write a stored procedure to regroup several SQL statements and improve performance. The stored procedure sp_archive_books defined in Listing 6-29 takes an archive date and a warehouse code as parameters and updates the T_Inventory and the T_Transport tables.

Listing 6-29.  Abstract of a Stored Procedure Archiving Books

CREATE PROCEDURE sp_archive_books @archiveDate DATE, @warehouseCode VARCHAR AS
  UPDATE T_Inventory
  SET Number_Of_Books_Left - 1
  WHERE Archive_Date < @archiveDate AND Warehouse_Code = @warehouseCode ;
 
  UPDATE T_Transport
  SET Warehouse_To_Take_Books_From = @warehouseCode ;
END

The stored procedure in Listing 6-29 is compiled into the database and can then be invoked through its name (sp_archive_books). As you can see, a stored procedure accepts data in the form of input or output parameters. Input parameters (@archiveDate and @warehouseCode in our example) are utilized in the execution of the stored procedure which, in turn, can produce some output result. This result is returned to the application through the use of a result set.

In JPA 2.1 the StoredProcedureQuery interface (which extends Query) supports stored procedures. Unlike dynamic, named, or native queries, the API only allows you to invoke a stored procedure that already exists in the database, not define it. You can invoke a stored procedure with annotations (with @NamedStoredProcedureQuery) or dynamically.

Listing 6-30 shows the Book entity that declares the sp_archive_books stored procedure using named query annotations. The NamedStoredProcedureQuery annotation specifies name of the stored procedure to invoke the types of all parameters (Date.class and String.class), their corresponding parameter modes (IN, OUT, INOUT, REF_CURSOR), and how result sets, if any, are to be mapped. A StoredProcedureParameter annotation needs to be provided for each parameter.

Listing 6-30.  Entity Declaring a Named Stored Procedure

@Entity
@NamedStoredProcedureQuery (name = "archiveOldBooks", procedureName = " sp_archive_books ",
  parameters = {
    @StoredProcedureParameter (name = " archiveDate ", mode = IN, type = Date.class),
    @StoredProcedureParameter(name = " warehouse ", mode = IN, type = String.class)
  }
)
public class Book {
 
  @Id @GeneratedValue
  private Long id;
  private String title;
  private Float price;
  private String description;
  private String isbn;
  private String editor;
  private Integer nbOfPage;
  private Boolean illustrations;
 
  // Constructors, getters, setters
}

To invoke the sp_archive_books stored procedure, you need to use the entity manager and create a named stored procedure query by passing its name (archiveOldBooks). This returns a StoredProcedureQuery on which you can set the parameters and execute it as shown in Listing 6-31.

Listing 6-31.  Calling a StoredProcedureQuery

StoredProcedureQuery query = em. createNamedStoredProcedureQuery (" archiveOldBooks ");
query.setParameter("archiveDate", new Date());
query.setParameter("maxBookArchived", 1000);
query.execute();

If the stored procedure is not defined using metadata (@NamedStoredProcedureQuery), you can use the API to dynamically specify a stored procedure query. This means that parameters and result set information must be provided programmatically. This can be done using the registerStoredProcedureParameter method of the StoredProcedureQuery interface as shown in Listing 6-32.

Listing 6-32.  Registering and Calling a StoredProcedureQuery

StoredProcedureQuery query = em. createStoredProcedureQuery ("sp_archive_old_books");
query. registerStoredProcedureParameter (" archiveDate ", Date.class, ParameterMode.IN);
query. registerStoredProcedureParameter (" maxBookArchived ", Integer.class, ParameterMode.IN);
 
query.setParameter("archiveDate", new Date());
query.setParameter("maxBookArchived", 1000);
query.execute();

Versioning

Java specifications use versioning: Java SE 5.0, Java SE 6.0, EJB 3.1, JAX-RS 1.0, and so on. When a new version of JAX-RS is released, its version number is increased, and you upgrade to JAX-RS 1.1. JPA uses this exact mechanism when you need to version entities. So, when you persist an entity for the first time in the database, it will get the version number 1. Later, if you update an attribute and commit this change to the database, the entity version will get the number 2, and so on. This versioning will evolve each time a change is made to the entity.

In order for this to happen, the entity must have an attribute to store the version number, and it has to be annotated by @Version. This version number is then mapped to a column in the database. The attribute types supported for versioning can be int, Integer, short, Short, long, Long, or Timestamp. Listing 6-36 shows how to add a version attribute to the Book entity.

Listing 6-36.  The Book Entity with a @Version Annotation on an Integer

@Entity
public class Book {
 
  @Id @GeneratedValue
  private Long id;
  @Version
  private Integer version;
  private String title;
  private Float price;
  private String description;
  private String isbn;
  private Integer nbOfPage;
  private Boolean illustrations;
 
  // Constructors, getters, setters
}

The entity can access the value of its version property but must not modify it. Only the persistence provider is permitted to set or update the value of the version attribute when the object is written or updated to the database. Let’s look at an example to illustrate the behavior of this versioning. In Listing 6-37, a new Book entity is persisted to the database. Once the transaction is committed, the persistence provider sets the version to 1. Later, the price of the book is updated, and, once the data are flushed to the database, the version number is incremented to 2.

Listing 6-37.  Transactions tx1 and tx2 Updating the Price of a Book Concurrently

Book book = new Book("H2G2", 21f, "Best IT book", "123-456", 321, false);
 
tx.begin();
em.persist(book);
tx.commit();
assertEquals( 1, book.getVersion() );
 
tx.begin();
book.raisePriceByTwoDollars();
tx.commit();
assertEquals( 2, book.getVersion() );

The version attribute is not required but is recommended when the entity can be concurrently modified by more than one process or thread. Versioning is the core of optimistic locking and provides protection for infrequent concurrent entity modification. In fact, an entity is automatically enabled for optimistic locking if it has a property mapped with a @Version annotation.

Optimistic Locking

As its name indicates, optimistic locking is based on the fact that database transactions don’t conflict with each other. In other words, there is a good chance that the transaction updating an entity will be the only one that actually updates the entity during that interval. Therefore, the decision to acquire a lock on the entity is actually made at the end of the transaction. This ensures that updates to an entity are consistent with the current state of the database. Transactions that would cause this constraint to be violated result in an OptimisticLockException being thrown and the transaction marked for rollback.

How would you throw an OptimisticLockException? Either by explicitly locking the entity (with the lock or the find methods that you saw, passing a LockModeType) or by letting the persistence provider check the attribute annotated with @Version. The use of a dedicated @Version annotation on an entity allows the EntityManager to perform optimistic locking simply by comparing the value of the version attribute in the entity instance with the value of the column in the database. Without an attribute annotated with @Version, the entity manager will not be able to do optimistic locking automatically (implicitly).

Let’s look again at the example of increasing the price of a book. Transactions tx1 and tx2 both get an instance of the same Book entity. At that moment, the version of the Book entity is 1. The first transaction raises the price of the book by $2 and commits this change. When the data are flushed to the database, the persistence provider increases the version number and sets it to 2. At that moment, the second transaction raises the price by $5 and commits the change. The entity manager for tx2 realizes that the version number in the database is different from that of the entity. This means the version has been changed by a different transaction, so an OptimisticLockException is thrown, as shown in Figure 6-5.

This is the default behavior when the @Version annotation is used: an OptimisticLockException is thrown when the data are flushed (at commit time or by explicitly calling the em.flush() method). You can also control where you want to add the optimistic lock using read then lock or read and lock. The code of read and lock, for example, would look like this:

Book book = em.find(Book.class, 12);
// Lock to raise the price
em.lock(book, LockModeType.OPTIMISTIC);
book.raisePriceByTwoDollars();

With optimistic locking, the LockModeType that you pass as a parameter can take two values: OPTIMISTIC and OPTIMISTIC_FORCE_INCREMENT (or READ and WRITE, respectively, but these values are deprecated). The only difference is that OPTIMISTIC_FORCE_INCREMENT will force an update (increment) to the entity’s version column.

Applications are strongly encouraged to enable optimistic locking for all entities that may be concurrently accessed. Failure to use a locking mechanism may lead to inconsistent entity state, lost updates, and other state irregularities. Optimistic locking is a useful performance optimization that offloads work that would otherwise be required of the database and is an alternative to pessimistic locking, which requires low-level database locking.

Pessimistic Locking

Pessimistic locking is based on the opposite assumption to optimistic locking, because a lock is eagerly obtained on the entity before operating on it. This is very resource restrictive and results in significant performance degradation, as a database lock is held using a SELECT ... FOR UPDATE SQL statement to read data.

Databases typically offer a pessimistic locking service that allows the entity manager to lock a row in a table to prevent another thread from updating the same row. This is an effective mechanism to ensure that two clients do not modify the same row at the same time, but it requires expensive, low-level checks inside the database. Transactions that would cause this constraint to be violated result in a PessimisticLockException being thrown and the transaction marked for rollback.

Optimistic locking is appropriate in dealing with moderate contention among concurrent transactions. But in some applications with a higher risk of contentions, pessimistic locking may be more appropriate, as the database lock is immediately obtained as opposed to the often late failure of optimistic transactions. For example, in times of economic crises, stock markets receive huge numbers of selling orders. If 100 million Americans need to sell their stock options at the same time, the system needs to use pessimistic locks to ensure data consistency. Note that at the moment the market is rather pessimistic instead of optimistic, and that has nothing to do with JPA.

Pessimistic locking may be applied to entities that do not contain the annotated @Version attribute.