An entity manager manages persistent entities within a persistence context. It uses a single persistence unit that corresponds to a database instance. Persistence units include all managed entities, entity managers, and mapping configurations. If only one database instance is accessed then the entity manager can be obtained directly, as shown in the previous example. The persistence context annotation then refers to the sole persistence unit.

Persistence units are specified in the persistence.xml descriptor file, which resides under the META-INF directory. This is one of the few cases in modern Java EE where XML-based configuration is used. The persistence descriptor defines the persistence unit and optional configuration. The datasource is referenced only by its JNDI name in order to separate the configuration for accessing the database instance from the application. The actual configuration of the datasource is specified in the application server. If the application server contains only one application that uses a single database, developers can use the application server's default datasource. In that case, the datasource name can be omitted.

The following snippet shows an example persistence.xml file showing a single persistence unit using the default datasource:

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.2" 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_2.xsd">
    <persistence-unit name="vehicle" transaction-type="JTA">
    </persistence-unit>
</persistence>

This example is already sufficient for a majority of enterprise applications.

The next snippet demonstrates a persistence.xml file containing several persistence unit definitions for multiple datasources:

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.2" 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_2.xsd">

    <persistence-unit name="vehicle" transaction-type="JTA">
        <jta-data-source>jdbc/VehicleDB</jta-data-source>
    </persistence-unit>
    <persistence-unit name="order" transaction-type="JTA">
        <jta-data-source>jdbc/OrderDB</jta-data-source>
    </persistence-unit>
</persistence>

Injecting entity managers need to reference the desired persistence unit by its name. Entity managers always correspond to a single persistence context that uses a single persistence unit. The following CarManagement definition shows the previous example in an environment of several persistence units:

@Stateless
public class CarManagement {

    @PersistenceContext(unitName = "vehicle")
    EntityManager entityManager;

    public void replaceEngine(long carIdentifier, Engine engine) {
        Car car = entityManager.find(Car.class, carIdentifier);
        car.replaceEngine(engine);

        // merge operation is applied on the car and all cascading relations
        entityManager.merge(car);
    }
}

Optionally, injection of specific entity managers can be simplified by using CDI producer fields. By explicitly emitting entity managers using custom qualifiers, injection can be implemented in a typesafe way:

public class EntityManagerExposer {

    @Produces
    @VehicleDB
    @PersistenceContext(unitName = "vehicle")
    private EntityManager vehicleEntityManager;

    @Produces
    @OrderDB
    @PersistenceContext(unitName = "order")
    private EntityManager orderEntityManager;

}

The emitted entity managers can be injected, now using @Inject and the typesafe qualifier:

public class CarManagement {

    @Inject
    @VehicleDB
    EntityManager entityManager;

    ...
}

This approach can simplify usage in environments where different entity managers are injected in many locations.

There are also other possible approaches to map domain models to databases. Database mapping can also be defined in XML files. However, past approaches in J2EE, have shown that declarative configuration using annotations allows a more productive usage. Annotating domain models also provides a better overview.