4 Using Multiple Databases with a Composite Persistence Unit

With TopLink, you can expose multiple persistence units (each with unique sets of entity types) as a single persistence context by using a composite persistence unit. Individual persistence units that are part of a composite persistence unit are called composite member persistent units.

This chapter includes the following sections:

Section 4.1, "Understanding the Composite Persistence Unit"
Section 4.2, "Main Tasks"
Section 4.3, "Additional Resources"

4.1 Understanding the Composite Persistence Unit

With a composite persistence unit, you can:

Map relationships among any of the entities in the composite persistence unit
Access entities stored in multiple databases and different data sources
Easily perform queries and transactions across the complete set of entities

Example 4-1 shows how you can persist data from a single context into two different databases:

Example 4-1 Using Multiple Databases

em.persist(new A(..));
em.persist(new B(..));
// You can insert A into database1 and insert B into database2.
// The two databases can be from different vendors.

em.flush();

Figure 4-1 Simple Composite Persistence Unit

Description of "Figure 4-1 Simple Composite Persistence Unit"

Figure 4-1 illustrates a simple composite persistence unit. The EntityManager (passing them to Persistence.createEntityManagerFactory method) instantiates the composite persistence unit, which contains two composite member persistence units:

Class A is mapped by a persistence unit named memberPu1 located in member1.jar.
Class B is mapped by a persistence unit named memberPu2 located in member2.jar.

4.1.1 Composite Persistence Unit Requirements

When using composite persistence units, be aware of the following requirements:

The name of each composite member persistence unit must be unique within the composite.
The transaction-type and other properties that correspond to the entire persistence unit (such as target server, logging, transactions, and so on) should be defined in the composite persistence unit. If not, the application uses the defaults."
All composite members persistence units should use the same transaction-type as the composite persistence unit.

4.2 Main Tasks

This section includes the following tasks:

Task 1: Configure the Composite Persistence Unit
Task 2: Use Composite Persistence Units
Task 3: Deploy Composite Persistence Units

4.2.1 Task 1: Configure the Composite Persistence Unit

Because the composite persistence unit is a regular persistence element, it requires a persistence.xml file. Example 4-2 illustrates a sample persistence.xml file:

Example 4-2 The persistence.xml File for a Composite Persistence Unit

<persistence xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence persistence_1_0.xsd" version="1.0">
    <persistence-unit name="compositePu" transaction-type="JTA">
        <provider>
            org.eclipse.persistence.jpa.PersistenceProvider
        </provider>
 
        <jar-file>member1.jar</jar-file>
        <jar-file>member2.jar</jar-file> 
        <properties>
            <property name="eclipselink.composite-unit" value="true"/>
            <property name="eclipselink.target-server" value="WebLogic_10"/>
        </properties>
    </persistence-unit>
</persistence>

Use the <property name="eclipselink.composite-unit" value="true"/> property to identify persistence unit as a composite.

Use the <jar-file> element to specify the JAR files containing the composite member persistent units. The composite persistence unit will contain all the persistence units found in the JAR files specified.

4.2.2 Task 2: Use Composite Persistence Units

You can use a composite persistence unit as you would any other persistence unit; the EntityManager could be injected, as shown here:

@PersistenceUnit(unitName="compositePu")
EntityManagerFactory entityManagerFactory;

@PersistenceUnit(unitName="compositePu")
EntityManager entityManager;

Or create it manually:

EntityManagerFactory entityManagerFactory = Persistence.createEntityManagerFactory("compositePu", properties);

4.2.3 Task 3: Deploy Composite Persistence Units

To deploy multiple persistence units, deploy all of the JARs (the composite and its members) on he same class loader.

When deploying to Oracle WebLogic Server, package the JARs in an EAR file.
When running as a standalone application, add the JARs to the class path.

See Section 4.1.1, "Composite Persistence Unit Requirements" for important information and limitations.

4.3 Additional Resources

See http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Composite_Persistence_Units in the EclipseLink documentation for additional information on composite persistence units including:

Limitations of composite persistence units.
Configuring composite member persistence units that contain dependencies to each other.
All persistence unit properties used by composite persistence units and composite member persistence units
How to pass persistence unit properties to composite member persistence units with the Persistence.createEntityManagerFactory method, while creating a composite persistence unit EntityManagerFactory
All entity manager properties used by composite persistence unit and composite member persistence units
How to pass entity manager properties to composite member persistence units with the emf.createEntityManager method for composite persistence unit EntityManagerFactory.

4.3.1 Javadoc

For more information, see the following APIs in Oracle Fusion Middleware Java API Reference for EclipseLink.

PersistenceUnitProperties class
Persistence.createEntityManger class
EntityManagerFactory interface