9 Using Multiple Databases with a Composite Persistence Unit

This chapter describes how, with Oracle 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 this composite persistence unit are called composite member persistence units.

Note:

TopLink also supports multiple databases through partitioning. See Chapter 10, "Scaling Applications in Clusters" for more information.

This chapter includes the following sections:

Use Case

Users need to map expose multiple persistence units as a single persistence context within an application.

Solution

TopLink supports a "composite" persistence unit which can include multiple member persistence units.

Components

Sample

See the following EclipseLink examples for related information:

9.1 Introduction to the Solution

With a composite persistence unit, you can:

  • Map relationships among any of the entities in multiple persistence units

  • Access entities stored in multiple databases and different data sources

  • Easily perform queries and transactions across the complete set of entities

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

Example 9-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 9-1 illustrates a simple composite persistence unit. EclipseLink processes the persistence.xml file and detects the composite persistence unit, which contains two composite member persistence units:

  • Class A is mapped by a persistence unit named memberPu1 located in the member1.jar file.

  • Class B is mapped by a persistence unit named memberPu2 located in the member2.jar file.

Figure 9-1 A Simple Composite Persistence Unit

Description of Figure 9-1 follows
Description of "Figure 9-1 A Simple Composite Persistence Unit"

9.1.1 Composite Persistence Unit Requirements

When using composite persistence units, note 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 transaction types, target server information, and logging properties defined with composite members will be ignored.

9.2 Implementing the Solution

This section includes the following tasks:

9.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 9-2 illustrates a sample persistence.xml file. Notice that there are no datasource or jdbc properties.

Example 9-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>

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

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

9.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 follows:

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

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

Or create it manually:

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

9.2.3 Task 3: Deploy Composite Persistence Units

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

  • When deploying to Oracle WebLogic Server, package the JAR files in an EAR file or the WEB-INF/lib folder of a WAR file.

  • When running as a standalone application, add the JAR files to the class path.

For important requirements, see Section 9.1.1, "Composite Persistence Unit Requirements."

9.3 Additional Resources

See the following resources for more information about the technologies and tools used to implement the solutions in this chapter:

For the following additional information about composite persistence units, see "@CompositeMember," "composite.unit," and "composite-unit.member" in Java Persistence API (JPA) Extensions Reference for Oracle TopLink:

  • Limitations of composite persistence units.

  • Configuring composite member persistence units that contain dependencies.

  • 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 the composite persistence unit EntityManagerFactory

9.3.1 Related Javadoc

For more information, see the following APIs in Java API Reference for Oracle TopLink:

  • PersistenceUnitProperties class

  • Persistence.createEntityManger class

  • EntityManagerFactory interface