Jump to: navigation, search

Difference between revisions of "EclipseLink/Examples/JPA/Composite"

(Relationship Example)
 
(7 intermediate revisions by the same user not shown)
Line 11: Line 11:
 
== Basic Composition Example ==
 
== Basic Composition Example ==
  
Below is an example of Composite persistence unit definition. The persistence Unit 'compositePu' specifies transaction type and server platform. It contains all persistence units defined in member1.jar and member2.jar files.
+
Below is an example of Composite persistence unit definition. This example assumes two persistence units composed into a single parent unit. In this simple case, there are no relationships between the two units.
  
 
[[Image:Eclipselink_composite-pu_basic.png]]
 
[[Image:Eclipselink_composite-pu_basic.png]]
  
 +
The parent Persistence Unit 'compositePu' specifies transaction type and server platform, and contains a property to define it as the parent PU. It 'contains' all persistence units defined in member1.jar and member2.jar files.
 
<source lang="xml">
 
<source lang="xml">
<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 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">
 
     <persistence-unit name="compositePu" transaction-type="JTA">
 
         <provider>
 
         <provider>
Line 33: Line 35:
 
</source>
 
</source>
  
For more information about Composite persistence units please see [[EclipseLink/DesignDocs/328404_new | the design doc.]]
+
* memberPu1 defined in member1.jar file. As it contains no relationships to other PUs, it can be used independently as well as inside composite persistence unit.  (Note, this pu is mapped to an Oracle DB)
 +
<source lang="xml">
 +
<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="memberPu1" transaction-type="JTA">
 +
        <provider>
 +
            org.eclipse.persistence.jpa.PersistenceProvider
 +
        </provider>
 +
        <jta-data-source>jdbc/OracleJtaDS</jta-data-source>
 +
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
 +
        <properties>
 +
            <property name="eclipselink.target-database" value="org.eclipse.persistence.platform.database.oracle.Oracle11Platform"/>
 +
        </properties>
 +
    </persistence-unit>
 +
</persistence>
 +
</source>
  
 +
* memberPu2 defined in member2.jar file. As with memberPu1, it can be used independently as well as inside composite persistence unit. (Note, this pu is mapped to MySql DB)
 +
<source lang="xml">
 +
<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="memberPu2" transaction-type="JTA">
 +
        <provider>
 +
            org.eclipse.persistence.jpa.PersistenceProvider
 +
        </provider>
 +
        <jta-data-source>jdbc/MySqlJtaDS</jta-data-source>
 +
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
 +
        <properties>
 +
            <property name="eclipselink.target-database" value="org.eclipse.persistence.platform.database.oracle.MySqlPlatform"/>
 +
        </properties>
 +
    </persistence-unit>
 +
</persistence>
 +
</source>
 
== Relationship Example ==
 
== Relationship Example ==
 +
 +
For this example, take the simple example above and add a relationship from a class in Pu1, to a class in Pu2. 
  
 
[[Image:Eclipselink_composite-pu_rel.png]]
 
[[Image:Eclipselink_composite-pu_rel.png]]
 +
 +
The persistence xml files for 'compositePu' and 'memberPu2', stay exactly the same.  However, memberPu1, needs a flag to indicate that it has a relationship to another pu.  This also adds the restriction that memberPu1 can not be used as it's own independent persistence unit.
 +
 +
<source lang="xml">
 +
<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="memberPu1" transaction-type="JTA">
 +
        <provider>
 +
            org.eclipse.persistence.jpa.PersistenceProvider
 +
        </provider>
 +
        <jta-data-source>jdbc/OracleJtaDS</jta-data-source>
 +
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
 +
        <properties>
 +
            <property name="eclipselink.composite-unit.member" value="true"/>
 +
            <property name="eclipselink.target-database" value="org.eclipse.persistence.platform.database.oracle.Oracle11Platform"/>
 +
        </properties>
 +
    </persistence-unit>
 +
</persistence>
 +
</source>
 +
 +
== Using the composite PU ==
 +
The composite PU is used as a normal PU, either through injection:
 +
 +
<source lang="java">
 +
@PersistenceUnit(unitName="compositePu")
 +
EntityManagerFactory entityManagerFactory;
 +
</source>
 +
 +
Or created manually
 +
<source lang="java">
 +
EntityManagerFactory entityManagerFactory = Persistence.createEntityManagerFactory("compositePu", properties);
 +
</source>
 +
 +
Access to the factory is done as per usual, with the reads and writes of classes from different units going to different databases.
 +
 +
For more information about Composite persistence units please see [[EclipseLink/DesignDocs/328404_new | the design doc.]]

Latest revision as of 14:33, 16 June 2011

EclipseLink JPA: Composite Persistence Units Example

Starting with EclipseLink 2.3.0 JPA developers can now combine persistence units together at runtime allowing entities to be stored in different databases. This includes support for relationships between entities in different persistence units (references across databases). For long time users of TopLink/EclipseLink this feature is an upgrade to the native Session Broker functionality to make it easier to use with JPA.

Usage

  • Two or more persistence units could be combined into a single Composite persistence Unit.
  • Each composite members persistence unit keeps mapping its classes to its own database.
    • Therefore Composite persistence unit allows to map different entities to different data bases.

Basic Composition Example

Below is an example of Composite persistence unit definition. This example assumes two persistence units composed into a single parent unit. In this simple case, there are no relationships between the two units.

Eclipselink composite-pu basic.png

The parent Persistence Unit 'compositePu' specifies transaction type and server platform, and contains a property to define it as the parent PU. It 'contains' all persistence units defined in member1.jar and member2.jar files.

<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>
  • memberPu1 defined in member1.jar file. As it contains no relationships to other PUs, it can be used independently as well as inside composite persistence unit. (Note, this pu is mapped to an Oracle DB)
<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="memberPu1" transaction-type="JTA">
        <provider>
            org.eclipse.persistence.jpa.PersistenceProvider
        </provider>
        <jta-data-source>jdbc/OracleJtaDS</jta-data-source>
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
        <properties>
            <property name="eclipselink.target-database" value="org.eclipse.persistence.platform.database.oracle.Oracle11Platform"/>
        </properties>
    </persistence-unit>
</persistence>
  • memberPu2 defined in member2.jar file. As with memberPu1, it can be used independently as well as inside composite persistence unit. (Note, this pu is mapped to MySql DB)
<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="memberPu2" transaction-type="JTA">
        <provider>
            org.eclipse.persistence.jpa.PersistenceProvider
        </provider>
        <jta-data-source>jdbc/MySqlJtaDS</jta-data-source>
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
        <properties>
            <property name="eclipselink.target-database" value="org.eclipse.persistence.platform.database.oracle.MySqlPlatform"/>
        </properties>
    </persistence-unit>
</persistence>

Relationship Example

For this example, take the simple example above and add a relationship from a class in Pu1, to a class in Pu2.

Eclipselink composite-pu rel.png

The persistence xml files for 'compositePu' and 'memberPu2', stay exactly the same. However, memberPu1, needs a flag to indicate that it has a relationship to another pu. This also adds the restriction that memberPu1 can not be used as it's own independent 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="memberPu1" transaction-type="JTA">
        <provider>
            org.eclipse.persistence.jpa.PersistenceProvider
        </provider>
        <jta-data-source>jdbc/OracleJtaDS</jta-data-source>
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
        <properties>
            <property name="eclipselink.composite-unit.member" value="true"/>
            <property name="eclipselink.target-database" value="org.eclipse.persistence.platform.database.oracle.Oracle11Platform"/>
        </properties>
    </persistence-unit>
</persistence>

Using the composite PU

The composite PU is used as a normal PU, either through injection:

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

Or created manually

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

Access to the factory is done as per usual, with the reads and writes of classes from different units going to different databases.

For more information about Composite persistence units please see the design doc.