Revision as of 10:18, 20 July 2011

EclipseLink
Website
Download
Community
Mailing List • Forums • IRC • mattermost
Issues
Open • Help Wanted • Bug Day
Contribute
Browse Source

Key API

• [EntityManagerProperties]

Examples

• [Composite Persistence Units Example]

Composite Persistence Units

New in version 2.3.

Multiple persistence units with unique sets of entity types can be exposed as a single persistence context by using a composite persistence unit. A persistent unit that is part of a composite persistent unit is called a composite member persistent unit.

With composite persistence units:

• Mapping relationships can be established among any of the entities in the composite.
• The persistence context can access entities stored in different data sources.
• Queries and transactions can be performed transparently across the complete set of entities.

For example, you could persist data from a single context into different data sources, as shown below:

em.persist(new A(..));
em.persist(new Z(..));
// Insert A into database1; insert Z into database2:
// the two databases can be from different vendors.
em.flush();

Configuring Composite Persistence and Composite Member Persistence Units

Both composite persistence units and their member persistence units are regular persistence units, each of them must have persistence.xml.

Configuring Composite Persistent Units in persistence.xml

• Use the <property name="eclipselink.composite-unit" value="true"/> property to identify persistence unit as a composite. (Note: If this property is passed to the createEntityManagerFactory method or if it is set in system properties, it is ignored.)

• 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.

• The transaction type may be specified in the composite persistence unit (otherwise default transaction type is used). Transaction types of composite members are ignored.
• Persistence Unit Properties That Can Be Set on Composite Persistence Units (like "eclipselink.target-server") may be specified in composite pu persistence.xml (these properties ignored if specified by composite members).
• Don't specify any classes in composite persistence unit - all the classes should be specified in composite members.

Example

The composite persistence unit compositePu specifies the transaction type and the server platform. It will contain 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>

Configuring Composite Member Persistent Units in persistence.xml

• Data sources may be specified in composite member persistence units. Those specified in the composite are ignored.
• Persistence Unit Properties That Can Be Set on Composite Member Persistence Units (like "eclipselink.target-database") may be specified in composite members pu persistence.xml (these properties ignored if specified by the composite pu).
• Normally composite member pu could also be used as stand alone pu (independent from the composite). However if a member pu has dependencies of another member(s) (for instance a class defined in memberPu2 has a reference to a class defined in memberPu1) then such pu can no longer be used as a stand alone - only as a member of the composite.
  • To indicate that a member pu must be a member of a composite pu <property name="eclipselink.composite-unit.member" value="true"/> should be specified in its persistence.xml. (Note: If this property is passed to the createEntityManagerFactory method or if it is set in system properties, it is ignored.)
    • Attempt to create an EntityManagerFactory for such pu will still succeed (that's required by application servers), however attempt to create an EntityManager from the factory would fail

Example

Composite member persistence unit memberPu1 is defined in the member1.jar file. It can be used independently as well as inside composite persistence unit. Note that transaction type and server platform will be ignored if memberPu1 used as a composite member pu, but they will be used if memberPu1 is used stand alone (as a regular 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>
        <mapping-file>META-INF/advanced-entity-mappings1.xml</mapping-file>
        <jta-data-source>jdbc/OracleJtaDS</jta-data-source>
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
        <properties>
            <property name="eclipselink.target-server" value="WebLogic_10"/>
            <property name="eclipselink.target-database" value="org.eclipse.persistence.platform.database.oracle.Oracle11Platform"/>
        </properties>
    </persistence-unit>
</persistence>

Composite member persistence unit memberPu2 is defined in the member2.jar file. It has dependency on a class defined in member1.jar and cannot be used independently.

<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">
        <provider>
            org.eclipse.persistence.jpa.PersistenceProvider
        </provider>
        <mapping-file>META-INF/advanced-entity-mappings2.xml</mapping-file>
        <jta-data-source>jdbc/MySqlJtaDS</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.MySQLPlatform"/>
        </properties>
    </persistence-unit>
</persistence>

Persistence Unit Properties

As always, Persistence Unit properties could be either defined in persistence.xml or passed to createEntityManagerFactory method (the latter properties overriding the former).

Example

Property "eclipselink.logging.level" passed to the composite persistence unit, connection properties passed to the member persistence units through "eclipselink.composite-unit.properties" property.

Map props1 = new HashMap();
 
   props1.put("javax.persistence.jdbc.user", "user1");
   props1.put("javax.persistence.jdbc.password", "password1");
   props1.put("javax.persistence.jdbc.driver", "oracle.jdbc.OracleDriver");
   props1.put("javax.persistence.jdbc.url", "jdbc:oracle:thin:@oracle_db_url:1521:db");
 
Map props2 = new HashMap();
 
   props2.put("javax.persistence.jdbc.user", "user2");
   props2.put("javax.persistence.jdbc.password", "password2");
   props2.put("javax.persistence.jdbc.driver", "com.mysql.jdbc.Driver");
   props2.put("javax.persistence.jdbc.url", " jdbc:mysql://my_sql_db_url:3306/user2");
 
Map memberProps = new HashMap();
   memberProps.put("memberPu1", props1);
   memberProps.put("memberPu2", props2);
 
Map props = new HashMap();
   props.put("eclipselink.logging.level", "FINEST");
   props.put("eclipselink.composite-unit.properties", memberProps);
 
EntityManagerFactory emf = Persistence.createEntityManagerFactory("compositePu", props);

The following tables show where to set properties: on the composite persistence unit or on the composite member persistence unit.

• Persistence Unit Properties That Can Be Set on Composite Persistence Units should be used only by the composite persistence unit.
• Persistence Unit Properties That Can Be Set on Composite Member Persistence Units should be used only by composite member persistence units.
• Composite pu member property used assigned to composite pu (or composite property assigned to composite member pu) is ignored.

For complete PersistenceUnitProperties reference documentation, see [|PersistenceUnitProperties].

Persistence Unit Properties That Can Be Set on Composite Persistence Units

You can set the following persistence unit properties on composite persistence units. All other properties will be ignored.

Persistence Unit Properties That Can Be Set on Composite Member Persistence Units

You can set the following persistence unit properties on composite member persistence units. All other properties will be ignored.

Entity Manager Properties

As always, Entity Manager properties can be set either through either createEntityManager() method on the factory or to the setProperty method on the EntityManager.

Example

Property ""eclipselink.jdbc.exclusive-connection.mode"" passed to the composite persistence unit, connection properties passed to the member persistence units through "eclipselink.composite-unit.properties" property.

Map props1 = new HashMap();
 
   props1.put("javax.persistence.jdbc.user", "user1");
   props1.put("javax.persistence.jdbc.password", "password1");
   props1.put("javax.persistence.jdbc.driver", "oracle.jdbc.OracleDriver");
   props1.put("javax.persistence.jdbc.url", "jdbc:oracle:thin:@oracle_db_url:1521:db");
 
Map props2 = new HashMap();
 
   props2.put("javax.persistence.jdbc.user", "user2");
   props2.put("javax.persistence.jdbc.password", "password2");
   props2.put("javax.persistence.jdbc.driver", "com.mysql.jdbc.Driver");
   props2.put("javax.persistence.jdbc.url", " jdbc:mysql://my_sql_db_url:3306/user2");
 
Map memberProps = new HashMap();
   memberProps.put("memberPu1", props1);
   memberProps.put("memberPu2", props2);
 
Map props = new HashMap();
   props.put("eclipselink.jdbc.exclusive-connection.mode", "Always");
   props.put("eclipselink.composite-unit.properties", memberProps);
 
EntityManager em = emf.createEntityManager(props);

The following tables show where to set properties: on the composite persistence unit or on the composite member persistence unit.

• Entity Manager Properties That Can Be Set On Composite Persistence Units should be used only by the composite persistence unit.
• Entity Manager Properties That Can Be Set On Composite Member Persistence Units should be used only by composite member persistence units.
• Composite pu member property used assigned to composite pu (or composite property assigned to composite member pu) is ignored.

For complete PersistenceUnitProperties reference documentation, see [|EntityManagerProperties].

Entity Manager Properties That Can Be Set On Composite Persistence Units

You can set the following entity manager properties on composite persistence units. All other properties will be ignored.

Entity Manager Properties That Can Be Set On Composite Member Persistence Units

You can set the following entity manager properties on composite member persistence units. All other properties will be ignored.

Deploying and Accessing a Composite Persistence Unit

All the jars – the composite and the members – should be deployed on the same class loader. If they are deployed to an application server, the jars should be packed in an ear file. If they run standalone, the jars should be added to the class path.

A composite persistence unit can be accessed as any other persistence unit.

• Container managed composite persistence unit could be accessed using injection:

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

• Application managed composite persistence unit - using [Persistence.createEntityManagerFactory ]:

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

Limitations

Composite members persistence units' names must be unique in the composite.

Joins across tables in different data sources are not supported. This limitation affects mapping, query execution, and optimizations. For example:

• Entities mapped in different composite members cannot be joined in a query.
• If deleting an entity causes deletion from a table that is mapped by another composite member, then a "delete all" query cannot be performed. Therefore a delete all cannot be used if an entity:
  • has ElementCollection mapped in another composite member,
  • owns bidirectional relationship with a JoinTable with the target mapped in another composite member,
  • has any reference mapping that is privately owned with the target mapped in another composite member.

The inheritance hierarchy cannot be shared between different composite members.

If the target of a reference mapping is defined in a different composite member and JoinTable is used, the join table must belong to the target composite member. Such mappings must be unidirectional: the "invert" mapping cannot use mappedBy. That is because JoinTable must be defined in the same composite member with the target entity. Master mapping requires it to be in slave's member, slave mapping - in master's.You can work around this limitation by defining independent invert mapping with its own JoinTable. If you maintain both sides of the relationship, the two join tables will be in sync.

A native query created without a result class must specify the target composite member persistence unit, for example:

em.createNativeQuery("SELECT F_NAME FROM MBR2_EMPLOYEE").setHint(QueryHints.COMPOSITE_UNIT_MEMBER, "composite-advanced-member_2").getResultList();

Extensions

You can specify ElementCollection with primitive type target values with CollectionTable defined in a different composite member persistence unit, using annotations or eclipselink-orm.xml as described below:

• Annotations

@ElementCollection()
@CollectionTable(name = "MBR1_RESPONS", joinColumns=@JoinColumn(name="EMP_ID"))
@CompositeMember("composite-advanced-member_1")
@Column(name = "DESCRIPTION")
public Collection<String> getResponsibilities() {
    return responsibilities;
}

• eclipselink-orm.xml

<element-collection name="responsibilities" composite-member="xml-composite-advanced-member_3">
    <column name="DESCRIPTION"/>
    <collection-table name="XML_MBR3_RESPONS">
        <join-column name="EMP_ID"/>
    </collection-table>
</element-collection>

No @CompositeMember annotation (or composite-member attribute) is required if CollectionTable is defined in the same composite member persistence unit as the source.