Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/JPA/Advanced JPA Development/Composite Persistence Units"

m
m
 
(23 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
----
 +
 +
 +
'''[[Image:Elug_draft_icon.png|Warning]] This page is now obsolete. '''
 +
 +
For current information, please see "Using Multiple Databases with a Composite Persistence Unit" in the ''EclipseLink Solutions Guide'':
 +
http://www.eclipse.org/eclipselink/documentation/latest/solutions/usingmultipledbs.htm
 +
 +
 +
----
 +
 
{{EclipseLink_UserGuide  
 
{{EclipseLink_UserGuide  
 
|info=y
 
|info=y
Line 11: Line 22:
 
*[[http://wiki.eclipse.org/EclipseLink/Examples/JPA/Composite Composite Persistence Units Example]]
 
*[[http://wiki.eclipse.org/EclipseLink/Examples/JPA/Composite Composite Persistence Units Example]]
 
}}
 
}}
===******SANDBOX VERSION******===
+
 
''This page is under development''
+
 
= Composite Persistence Units=
 
= Composite Persistence Units=
  
Line 40: Line 50:
 
==Configuring Composite Persistence and Composite Member Persistence Units ==
 
==Configuring Composite Persistence and Composite Member Persistence Units ==
  
Composite persistence units and their member persistence units are configured in the same way as regular persistence units, and with some additional properties specific to composite 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.
 
+
Certain properties must be defined on the composite persistence unit; certain properties must be defined on composite member persistence units; and other properties may be defined on either.
+
* The transaction type must be specified in the composite persistence unit. Transaction types of composite members are ignored.
+
* Data sources must be specified in composite member persistence units. Those specified in the composite are ignored.
+
* The <tt>eclipselink.composite-unit</tt> property must be set on the composite persistent unit.
+
* The <tt>eclipselink.composite-unit.member</tt> property can only be set on composite member persitent units.
+
 
+
The [[#Persistence Unit Properties| Persistence Unit Properties]] table and the [[#Entity Manager Properties| Entity Manager Properties]] tables, below, show how those and other  properties are processed, depending on whether they are set on the composite or on the member persistent unit.
+
  
 
===Configuring Composite Persistent Units in persistence.xml ===
 
===Configuring Composite Persistent Units in persistence.xml ===
  
A minimal configuration of a composite persistent unit in <tt>persistence.xml</tt> requires the following:
+
* Use the <tt><property name="eclipselink.composite-unit" value="true"/></tt> property to identify persistence unit as a composite. ('''Note:''' If this property is passed to the <tt>createEntityManagerFactory</tt> method or if it is set in system properties, it is ignored.)  
 
+
* Use the <tt>eclipselink.composite-unit</tt> property to specify that it is a composite persistence unit. ('''Note:''' If this property is passed to the <tt>createEntityManagerFactory</tt> method or if it is set in system properties, it is ignored.)  
+
  
 
* Use the <tt><jar-file></tt> 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.  
 
* Use the <tt><jar-file></tt> 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.  
  
For example,
+
* 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| 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.
  
<source lang="xml">
+
====Example====
...
+
The composite persistence unit <tt>compositePu</tt> specifies the transaction type and the server platform. It will contain all persistence units defined in <tt>member1.jar</tt> and <tt>member2.jar</tt> files.
<jar-file>member1.jar</jar-file>
+
<jar-file>member2.jar</jar-file>
+
<properties>
+
    <property name="eclipselink.composite-unit" value="true"/>
+
</properties>
+
...
+
</source>
+
 
+
===Configuring Composite Member Persistent Units in persistence.xml ===
+
 
+
Use the <tt>eclipselink.composite-unit.member</tt> property to specify whether or not a persistent unit should be a member of a composite persistence unit:
+
 
+
* <tt>true</tt> specifies that the persistent unit ''must'' be a member of a composite persistence unit.
+
 
+
* <tt>false</tt> specifies that the persistent unit ''cannot'' be a member of a composite persistence unit (if, for example, it has dependencies on other persistence unit(s)).
+
 
+
For example,
+
 
+
<source lang="xml">
+
...
+
<properties>
+
    <property name="eclipselink.composite-unit.member" value="true"/>
+
</properties>
+
...
+
</source>
+
 
+
The <tt>eclipselink.composite-unit.member</tt> property is not required and defaults to <tt>false</tt> if not specified.
+
 
+
'''Note:''' If <tt>eclipselink.composite-unit.member</tt> is passed to the <tt>createEntityManagerFactory</tt> method or if it is set in system properties, it is ignored.
+
 
+
<!---//REVIEWERS: Design doc also says "If this property is set to true, the EntityManagerFactory can still be created, but it cannot be connected." I don't understand, as true is perfectly valid, no?// //ANDREI: true is perfectly valid. That means persistence unit can only be used as a member of composite - cannot be used as an independent persistence unit. Motivation: persistence unit that has dependency on classes in other persistence unit(s) - impossible to use standalone, still possible to use as a member of composite, of course the persistence unit(s) on which it depends should also be members in the same composite. Logically I would prefer to fail when the factory is created - but that would be a problem with application servers, so the next best solution is to fail on attempt to actually use the factory - createEntityManager// -->
+
 
+
 
+
=== Passing EntityManagerFactory Properties to Composite Member Persistent Units ===
+
 
+
While creating a composite persistent unit, <tt>EntityManagerFactory</tt> properties can be passed to composite member persistent units, as shown in the following example.  The value is a map of properties, and the key is a member persistence unit's name. The map of properties is passed to that persistence unit.
+
 
+
'''''//REVIEWERS: I don't completely understand this part. I have these general questions:
+
# '''''When (why) would one want to do this? That is, why do you want to use this instead of persistence.xml? '''''
+
# '''''I think this part of the [[EclipseLink/DesignDocs/328404_new|design doc (search for "While creating Composite PU EntityManagerFactory")]] says that you define the properties on the composite and then pass them to the members. Is that correct? But why not define them on the members directly? '''''
+
# '''''If I got item 2, above, correct, are there times when you want to define the properties directly on the composite? directly on the members? '''''
+
 
+
'''''//REVIEWERS: '''''
+
 
+
'''''The design doc (quoting the Javadoc) says this: '''''
+
 
+
'''''
+
<source lang="java">
+
"eclipselink.composite-unit.properties" -> (
+
  ("memberPu1" -> (  "javax.persistence.jdbc.user" -> "user1",
+
                          "javax.persistence.jdbc.password" -> "password1",
+
                          "javax.persistence.jdbc.driver" -> "oracle.jdbc.OracleDriver",
+
                          "javax.persistence.jdbc.url" -> "jdbc:oracle:thin:@oracle_db_url:1521:db",
+
                    ) ,
+
  ("memberPu2" -> (  "javax.persistence.jdbc.user" -> "user2",
+
                          "javax.persistence.jdbc.password" -> "password2"
+
                          "javax.persistence.jdbc.driver" -> "com.mysql.jdbc.Driver",
+
                          "javax.persistence.jdbc.url" -> "jdbc:mysql://my_sql_db_url:3306/user2",
+
                    )
+
</source>
+
'''''
+
 
+
'''''I tried to convert to code, below, but I know this isn't quite right. I think it just shows how to set the properties directly on the members (does it?). I'm not sure how to use <tt>eclipselink.composite-unit.properties</tt> itself. Please correct, as needed.
+
//'''''
+
 
+
<source lang="java">
+
eclipselink.composite-unit.properties
+
 
+
Map props1 = new HashMap();
+
 
+
  props.put(PersistenceUnitProperties.JDBC_USER, "user1");
+
  props.put(PersistenceUnitProperties.JDBC_PASSWORD, "password1");
+
  props.put(PersistenceUnitProperties.JDBC_DRIVER, "oracle.jdbc.OracleDriver");
+
  props.put(PersistenceUnitProperties.JDBC_URL, "jdbc:oracle:thin:@oracle_db_url:1521:db");
+
 
+
EntityManagerFactory emf = Persistence.createEntityManagerFactory("memberPU1 ", props1);
+
 
+
Map props2 = new HashMap();
+
 
+
  props.put(PersistenceUnitProperties.JDBC_USER, "user2");
+
  props.put(PersistenceUnitProperties.JDBC_PASSWORD, "password2");
+
  props.put(PersistenceUnitProperties.JDBC_DRIVER, "oracle.mysql.OracleDriver");
+
  props.put(PersistenceUnitProperties.JDBC_URL, " jdbc:mysql:@oracle_sql_url:3306/user2");
+
 
+
EntityManagerFactory emf = Persistence.createEntityManagerFactory("memberPU2", props2);
+
 
+
</source>
+
 
+
=== Examples ===
+
In the following example, the composite persistence unit <tt>compositePU</tt> specifies the transaction type and the server platform. It will contain all persistence units defined in <tt>member1.jar</tt> and <tt>member2.jar</tt> files.
+
  
 
<source lang="xml">
 
<source lang="xml">
Line 171: Line 83:
 
</source>
 
</source>
  
In the following example, the composite member persistence unit <tt>memberPu1</tt> is defined in the <tt>member1.jar</tt> file. It can be used independently as well as inside composite persistence unit.
+
===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| 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 <tt>createEntityManagerFactory</tt> 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 <tt>memberPu1</tt> is defined in the <tt>member1.jar</tt> 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).
 
<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">
Line 190: Line 110:
 
</source>
 
</source>
  
In the following example, the composite member persistence unit <tt>memberPu2</tt> is defined in the <tt>member2.jar</tt> file. It has dependency on a class defined in member1.jar and cannotbe used independently.
+
Composite member persistence unit <tt>memberPu2</tt> is defined in the <tt>member2.jar</tt> file. It has dependency on a class defined in member1.jar and cannot be used independently.
  
 
<source lang="xml">
 
<source lang="xml">
Line 209: Line 129:
 
</source>
 
</source>
  
==Deploying and Accessing a Composite Persistence Unit==
+
<!---//REVIEWERS: Design doc also says "If this property is set to true, the EntityManagerFactory can still be created, but it cannot be connected." I don't understand, as true is perfectly valid, no?// //ANDREI: true is perfectly valid. That means persistence unit can only be used as a member of composite - cannot be used as an independent persistence unit. Motivation: persistence unit that has dependency on classes in other persistence unit(s) - impossible to use standalone, still possible to use as a member of composite, of course the persistence unit(s) on which it depends should also be members in the same composite. Logically I would prefer to fail when the factory is created - but that would be a problem with application servers, so the next best solution is to fail on attempt to actually use the factory - createEntityManager// -->
  
All three jars – the composite and the two 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.
+
== 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).
  
A composite persistence unit can be accessed as with any other persistence unit.  
+
===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.
 +
<source lang="java">
 +
Map props1 = new HashMap();
  
* It can be accessed using injection, for example:
+
  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");
  
<source lang="java">
+
Map props2 = new HashMap();
@PersistenceUnit(unitName="compositePu")
+
EntityManagerFactory entityManagerFactory;
+
@PersistenceUnit(unitName="compositePu")
+
EntityManager entityManager;
+
</source>
+
  
* Or it can be created manually, using  [[http://www.eclipse.org/eclipselink/api/latest/javax/persistence/Persistence.html <tt>Persistence.createEntityManagerFactory </tt>]], as shown in the following example:
+
  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);
  
<source lang="java">
 
EntityManagerFactory entityManagerFactory = Persistence.createEntityManagerFactory("compositePu", properties);
 
 
</source>
 
</source>
  
== Persistence Unit Properties ==
+
The following tables show where to set properties: on the composite persistence unit or on the composite member persistence unit.
  
Persistence unit properties can be set on the <tt>EntityManagerFactory</tt> as follow:
+
* [[#Persistence Unit Properties That Can Be Set on Composite Persistence Units| 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| 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.
  
* Composite persistence unit properties can be specified either in the composite persistence unit's <tt>persistence.xml</tt> file or passed to the its <tt>createEntityManagerFactory()</tt> method.
+
For complete <tt>PersistenceUnitProperties</tt> reference documentation, see [[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/PersistenceUnitProperties.html |PersistenceUnitProperties]].
* Composite member persistence unit properties can either be specified in the composite member persistence unit's <tt>persistence.xml</tt> file or passed to the composite persistence unit's <tt>createEntityManagerFactory()</tt> method through the <tt>eclipselink.composite.properties</tt> property.
+
  
'''''//REVIEWERS: Can't the properties also be passed to <tt>createEntityManager()</tt>? If so, why would you do that instead of using <tt>createEntityManagerFactory()</tt>?//'''''
+
===Persistence Unit Properties That Can Be Set on Composite Persistence Units===
  
The following table shows how properties set on a composite persistence unit and its members are handled when properties are set on both. '''''//REVIEWERS: Is that correct?//''''' For complete <tt>PersistenceUnitProperties</tt>> reference documentation, see [[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/PersistenceUnitProperties.html |PersistenceUnitProperties]].
+
You can set the following persistence unit properties on composite persistence units. All other properties will be ignored.
  
 
{|{{BMTableStyle}}
 
{|{{BMTableStyle}}
 
|-{{BMTableCaptionStyle
 
|-{{BMTableCaptionStyle
|caption=Persistence Unit Properties}}
+
|caption=Persistence Unit Properties Set on Composite Persistence Units}}
 
|-{{BMTHStyle}}
 
|-{{BMTHStyle}}
 
| PersistenceUnitProperties.
 
| PersistenceUnitProperties.
| property name
+
| Property Name
| composite pu
+
| composite member pu
+
 
| comment
 
| comment
 
|-  
 
|-  
 
| COMPOSITE_UNIT
 
| COMPOSITE_UNIT
 
| eclipselink.composite-unit
 
| eclipselink.composite-unit
| Processed
+
| Must be specified in persistence.xml of a composite persistence unit with the value "true". Advanced usage: This property can also be set on a composite member persistence unit that is itself a composite persistence unit. In that case, the composite is substituted by its own members.  
| Advanced
+
| If specified by member then the member is substituted for its own members. '''''//REVIEWERS: I think this means "If specified by a composite member persistence unit ..." But what does the rest of the sentence mean?'''''
+
 
+
'''''Also, what does "Advanced" mean?//'''''
+
|-
+
| COMPOSITE_UNIT_MEMBER
+
| eclipselink.composite-unit.member
+
| Advanced
+
| Processed
+
| if specified by composite persistence unit, the composite must be member of another composite persistence unit. '''''//REVIEWERS: This suggests that composite PUs can be composite member PUs of other composite PUs. Is that correct? Any limitations?//'''''
+
 
|-  
 
|-  
 
| COMPOSITE_PROPERTIES
 
| COMPOSITE_PROPERTIES
 
| eclipselink.composite.properties
 
| eclipselink.composite.properties
| Processed
 
| Ignored
 
 
|  
 
|  
 
|-  
 
|-  
 
| TRANSACTION_TYPE
 
| TRANSACTION_TYPE
 
| javax.persistence.transactionType
 
| javax.persistence.transactionType
| Processed
 
| Ignored
 
 
|  
 
|  
 
|-  
 
|-  
 
| TARGET_SERVER
 
| TARGET_SERVER
 
| eclipselink.target-server
 
| eclipselink.target-server
| Processed
 
| Ignored
 
 
|  
 
|  
 
|-  
 
|-  
 
| LOGGING_*
 
| LOGGING_*
 
| eclipselink.logging.*
 
| eclipselink.logging.*
| Processed
 
| Ignored
 
 
|  
 
|  
 
|-  
 
|-  
 
| PROFILER
 
| PROFILER
 
| eclipselink.profiler
 
| eclipselink.profiler
| Processed
 
| Ignored
 
 
|  
 
|  
 
|-  
 
|-  
 
| COORDINATION_*
 
| COORDINATION_*
 
| eclipselink.cache.coordination.*
 
| eclipselink.cache.coordination.*
| Processed
 
| Ignored
 
 
|  
 
|  
 
|-  
 
|-  
 
| SESSION_NAME
 
| SESSION_NAME
 
| eclipselink.session-name
 
| eclipselink.session-name
| Processed
+
| This property can also be set on a composite member persistence unit . The member session name is used to read the session from <tt>sessions.xml</tt>, but the deployed session always has the same name as the member persistence unit (as it is defined in <tt>memberPuInfo.getPersistenceUnitName()</tt>)
| Advanced
+
| The member session name is used to read the session from <tt>sessions.xml</tt>, but the deployed session always has the same name as the member persistence unit (as it is defined in <tt>memberPuInfo.getPersistenceUnitName()</tt>)
+
 
|-  
 
|-  
 
| DEPLOY_ON_STARTUP
 
| DEPLOY_ON_STARTUP
 
| eclipselink.deploy-on-startup
 
| eclipselink.deploy-on-startup
| Processed
 
| Ignored
 
 
|  
 
|  
 
|-  
 
|-  
 
| VALIDATION_ONLY_PROPERTY
 
| VALIDATION_ONLY_PROPERTY
 
| eclipselink.validation-only
 
| eclipselink.validation-only
| Processed
+
| In 2.3: This property is also processed if set on a composite member persistence unit, but that is a known bug ({{bug|348815}}). This property '''should''' be processed by the composite only and ignored by member persistence units. To work around this bug, specify the property in the composite and in all its members. THIS IS FIXED IN 2.3.1: it's ignored by members.
| ''processed''
+
| '''''//REVIEWERS: {{bug|348815}}: WRONG BEHAVIOUR, should be processed by composite only, ignored by member persistence unit. Workaround for now: specify the property in the composite and in all its members.//'''''
+
 
|-  
 
|-  
 
| VALIDATION_*
 
| VALIDATION_*
 
| eclipselink.validation.*
 
| eclipselink.validation.*
| Processed
 
| Ignored
 
 
|
 
|
 
|-  
 
|-  
 
| CLASSLOADER
 
| CLASSLOADER
 
| eclipselink.classloader
 
| eclipselink.classloader
| Processed
 
| Ignored
 
 
|
 
|
 
|-
 
|-
 
| THROW_EXCEPTIONS
 
| THROW_EXCEPTIONS
 
| eclipselink.orm.throw.exceptions
 
| eclipselink.orm.throw.exceptions
| Processed
 
| Ignored
 
 
|  
 
|  
 
|-
 
|-
 
| FLUSH_CLEAR_CACHE
 
| FLUSH_CLEAR_CACHE
 
| eclipselink.flush-clear.cache
 
| eclipselink.flush-clear.cache
| Processed
 
| Ignored
 
 
|  
 
|  
 
|-
 
|-
 
| VALIDATE_EXISTENCE
 
| VALIDATE_EXISTENCE
 
| eclipselink.validate-existence
 
| eclipselink.validate-existence
| Processed
 
| Ignored
 
 
|  
 
|  
 
|-
 
|-
 
| JOIN_EXISTING_TRANSACTION
 
| JOIN_EXISTING_TRANSACTION
 
| eclipselink.transaction.join-existing
 
| eclipselink.transaction.join-existing
| Processed
 
| Ignored
 
 
|  
 
|  
 
|-
 
|-
 
| PERSISTENCE_CONTEXT_*
 
| PERSISTENCE_CONTEXT_*
 
| eclipselink.persistence-context.*
 
| eclipselink.persistence-context.*
| Processed
 
| Ignored
 
 
|  
 
|  
 
|-
 
|-
 
| ALLOW_ZERO_ID
 
| ALLOW_ZERO_ID
 
| eclipselink.allow-zero-id
 
| eclipselink.allow-zero-id
| Processed
 
| Ignored
 
 
|  
 
|  
 
|-
 
|-
 
| SESSION_CUSTOMIZER
 
| SESSION_CUSTOMIZER
 
| eclipselink.session.customizer
 
| eclipselink.session.customizer
| Processed
+
| This property can also be set on a composite member persistence unit. Customizers of member persistence units are processed before the composite persistence unit's customizer.
| Processed
+
|-
| Customizers of member persistence units are processed before the composite persistence unit's customizer.
+
| SESSION_EVENT_LISTENER_CLASS
 +
| eclipselink.session-event-listener
 +
|This property can also be set on a composite member persistence unit. An
 +
<tt>EventListener</tt> defined by a composite member will not receive events raised by a <tt>UnitOfWork</tt>; it will only receive events raised by its member. Also see {{bug|348766}} - FIXED in 2.3.1. An <tt>EventListener<>/tt> specified by a composite will receive all events (raised by either a unit of work or by members).
 +
|-
 +
| Exception_HANDLER_CLASS
 +
| eclipselink.exception-handler
 +
| This property can also be set on a composite member persistence unit. The first <tt>ExceptionHandler</tt> specified by a member handles the exception. If it is not specified or fails, then the composite's <tt>ExceptionHandler</tt> handles the original exception.
 +
|-
 +
| WEAVING
 +
| eclipselink.weaving
 +
| A composite persistent unit switches weaving on and off for all its member persistent units.
 +
|-
 +
|}
 +
 
 +
===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.
 +
 
 +
{|{{BMTableStyle}}
 +
|-{{BMTableCaptionStyle
 +
|caption=Persistence Unit Properties Set on Composite Member Persistence Units}}
 +
|-{{BMTHStyle}}
 +
| PersistenceUnitProperties.
 +
| Property Name
 +
| comment
 +
|-
 +
| COMPOSITE_UNIT
 +
| eclipselink.composite-unit
 +
| Advanced usage: This property can also be set on a composite member persistence unit that is itself a composite persistence unit. In that case, the composite is substituted by its own members. 
 +
|-
 +
| COMPOSITE_UNIT_MEMBER
 +
| eclipselink.composite-unit.member
 +
|The property should be specified with a value "true" in persistence.xml to indicate that the persistence unit cannot be used stand alone (only as a member of a composite).
 +
|-
 +
| SESSION_NAME
 +
| eclipselink.session-name
 +
| This property can also be set on a composite persistence unit. The member session name is used to read the session from <tt>sessions.xml</tt>, but the deployed session always has the same name as the member persistence unit (as it is defined in <tt>memberPuInfo.getPersistenceUnitName()</tt>)
 +
|-
 +
| VALIDATION_ONLY_PROPERTY
 +
| eclipselink.validation-only
 +
| This property is processed if set on a composite member persistence unit, but that is a known bug ({{bug|348815}}). This property '''should''' be processed by the composite only and ignored by member persistence units. To work around this bug, specify the property in the composite and in all its members. FIXED in 2.3.1 - ignored on member.
 +
|-
 +
| VALIDATION_*
 +
| eclipselink.validation.*
 +
|
 +
|-
 +
| CLASSLOADER
 +
| eclipselink.classloader
 +
|
 +
|-
 +
| THROW_EXCEPTIONS
 +
| eclipselink.orm.throw.exceptions
 +
|
 +
|-
 +
| FLUSH_CLEAR_CACHE
 +
| eclipselink.flush-clear.cache
 +
|
 +
|-
 +
| VALIDATE_EXISTENCE
 +
| eclipselink.validate-existence
 +
|
 +
|-
 +
| JOIN_EXISTING_TRANSACTION
 +
| eclipselink.transaction.join-existing
 +
|
 +
|-
 +
| PERSISTENCE_CONTEXT_*
 +
| eclipselink.persistence-context.*
 +
|
 +
|-
 +
| ALLOW_ZERO_ID
 +
| eclipselink.allow-zero-id
 +
|
 +
|-
 +
| SESSION_CUSTOMIZER
 +
| eclipselink.session.customizer
 +
| This property can also be set on a composite persistence unit. Customizers of member persistence units are processed before the composite persistence unit's customizer.
 
|-
 
|-
 
| SESSIONS_XML
 
| SESSIONS_XML
 
| eclipselink.sessions-xml
 
| eclipselink.sessions-xml
| Exception
+
|If this property is set on a composite persistence unit, an exception will be thrown. Composite persitence units cannot be read from <tt>sessions.xml</tt>. Note that a non-composite persistence unit should be able to use a <tt>SessionBroker</tt> defined in <tt>sessions.xml</tt>.
| Processed
+
| Composite persitence units cannot be read from <tt>sessions.xml</tt>. Note that a non-composite persistence unit should be able to use a <tt>SessionBroker</tt> defined in <tt>sessions.xml</tt>.
+
 
|-
 
|-
 
| JTA_DATASOURCE
 
| JTA_DATASOURCE
 
| javax.persistence.jtaDataSource
 
| javax.persistence.jtaDataSource
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| NON_JTA_DATASOURCE
 
| NON_JTA_DATASOURCE
 
| javax.persistence.nonJtaDataSource
 
| javax.persistence.nonJtaDataSource
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| NATIVE_SQL
 
| NATIVE_SQL
 
| eclipselink.jdbc.native-sql
 
| eclipselink.jdbc.native-sql
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| SQL_CAST
 
| SQL_CAST
 
| eclipselink.jdbc.sql-cast
 
| eclipselink.jdbc.sql-cast
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| JDBC_*
 
| JDBC_*
 
| javax.persistence.jdbc.* eclipselink.jdbc.*
 
| javax.persistence.jdbc.* eclipselink.jdbc.*
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| CONNECTION_POOL_*
 
| CONNECTION_POOL_*
 
|  
 
|  
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| PARTITIONING.*
 
| PARTITIONING.*
 
| eclipselink.partitioning.*
 
| eclipselink.partitioning.*
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| EXCLUSIVE_CONNECTION_*
 
| EXCLUSIVE_CONNECTION_*
 
| eclipselink.jdbc.exclusive-connection.*
 
| eclipselink.jdbc.exclusive-connection.*
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| CACHE.*
 
| CACHE.*
 
| eclipselink.cache.*
 
| eclipselink.cache.*
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| TARGET_DATABASE
 
| TARGET_DATABASE
 
| eclipselink.target-database
 
| eclipselink.target-database
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| TABLE_CREATION_SUFFIX
 
| TABLE_CREATION_SUFFIX
 
| eclipselink.ddl-generation.table-creation-suffix
 
| eclipselink.ddl-generation.table-creation-suffix
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| EXCLUDE_ECLIPSELINK_ORM_FILE
 
| EXCLUDE_ECLIPSELINK_ORM_FILE
 
| eclipselink.exclude-eclipselink-orm
 
| eclipselink.exclude-eclipselink-orm
| Ignored
 
| Processed
 
 
|  
 
|  
|-
 
| WEAVING
 
| eclipselink.weaving
 
| Processed
 
| Ignored
 
| A composite persistent unit switches weaving on and off for all its member persistent units.
 
 
|-
 
|-
 
| WEAVING_*
 
| WEAVING_*
 
| eclipselink.weaving.*
 
| eclipselink.weaving.*
| Ignored
 
| Processed
 
 
| If the weaving is on, members use their own weaving properties.
 
| If the weaving is on, members use their own weaving properties.
|-
 
| DESCRIPTOR_CUSTOMIZER_*
 
| eclipselink.descriptor.customizer.*
 
| Ignored
 
| Processed
 
| '''''//REVIEWERS: what about this from design doc: "TODO? Should we follow the same pattern as SessionCustomizer and process composite's DescriptorCustomizers after members' ones?"//'''''
 
 
|-
 
|-
 
| NATIVE_QUERY_UPPERCASE_COLUMNS
 
| NATIVE_QUERY_UPPERCASE_COLUMNS
 
| eclipselink.jdbc.uppercase-columns
 
| eclipselink.jdbc.uppercase-columns
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| UPPERCASE_COLUMN_NAMES
 
| UPPERCASE_COLUMN_NAMES
 
| eclipselink.jpa.uppercase-column-names
 
| eclipselink.jpa.uppercase-column-names
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| BATCH_WRITING.*
 
| BATCH_WRITING.*
 
| eclipselink.jdbc.batch-writing.*
 
| eclipselink.jdbc.batch-writing.*
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| SESSION_EVENT_LISTENER_CLASS
 
| SESSION_EVENT_LISTENER_CLASS
 
| eclipselink.session-event-listener
 
| eclipselink.session-event-listener
| Processed
+
|This property can also be set on a composite persistence unit. An <tt>EventListener</tt> defined by a composite member will not receive events raised by a <tt>UnitOfWork</tt>; it will only receive events raised by its member. Also see {{bug|348766}}. An <tt>EventListener<>/tt> specified by a composite will receive all events (raised by either a unit of work or by members).
| Processed
+
| EventListener defined by a composite member won't receive evens risen by a UnitOfWork - only events risen by it's member. Also see {{bug|348766}}. EventListener specified by composite will receive all event (risen by either unit of work or members).
+
 
|-
 
|-
 
| Exception_HANDLER_CLASS
 
| Exception_HANDLER_CLASS
 
| eclipselink.exception-handler
 
| eclipselink.exception-handler
| Processed
+
| This property can also be set on a composite persistence unit. The first <tt>ExceptionHandler</tt> specified by a member handles the exception. If it is not specified or fails, then the composite's <tt>ExceptionHandler</tt> handles the original exception.
| Processed
+
| First ExceptionHandler specified by member handles exception. If it is not specified or fails then composite's ExceptionHandler handles the original exception.
+
 
|-
 
|-
 
| INCLUDE_DESCRIPTOR_QUERIES
 
| INCLUDE_DESCRIPTOR_QUERIES
 
| eclipselink.session.include.descriptor.queries
 
| eclipselink.session.include.descriptor.queries
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| ID_VALIDATION
 
| ID_VALIDATION
 
| eclipselink.id-validation
 
| eclipselink.id-validation
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| TEMPORAL_MUTABLE
 
| TEMPORAL_MUTABLE
 
| eclipselink.temporal.mutable
 
| eclipselink.temporal.mutable
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| ORM_SCHEMA_VALIDATION
 
| ORM_SCHEMA_VALIDATION
 
| eclipselink.orm.validate.schema
 
| eclipselink.orm.validate.schema
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| DDL_*
 
| DDL_*
 
|  
 
|  
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| PESSIMISTIC_LOCK_TIMEOUT
 
| PESSIMISTIC_LOCK_TIMEOUT
 
| javax.persistence.lock.timeout
 
| javax.persistence.lock.timeout
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| QUERY_TIMEOUT
 
| QUERY_TIMEOUT
 
| javax.persistence.query.timeout
 
| javax.persistence.query.timeout
| Ignored
 
| Processed
 
 
|  
 
|  
 
|-
 
|-
 
| ORACLE_PROXY_TYPE
 
| ORACLE_PROXY_TYPE
 
| eclipselink.oracle.proxy-type
 
| eclipselink.oracle.proxy-type
| Ignored
 
| Processed
 
 
|  
 
|  
 
|}
 
|}
 +
 +
<br>
  
 
== Entity Manager Properties ==
 
== Entity Manager Properties ==
Persistence unit properties can be set on the <tt>EntityManager</tt> as follow:
+
 
* Composite entity manager properties can be passed directly to the <tt>createEntityManager()</tt> method or to the <tt>setProperty</tt> method.
+
As always, Entity Manager properties can be set either through either <tt>createEntityManager()</tt> method on the factory or to the <tt>setProperty</tt> method on the EntityManager.
* Composite member properties can be passed to the same methods through the <tt>eclipselink.composite.properties</tt> property.
+
 
 +
===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.
 +
<source lang="java">
 +
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);
 +
 
 +
</source>
 +
 
 +
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| 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| 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 <tt>PersistenceUnitProperties</tt> reference documentation, see [[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/EntityManagerProperties.html |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.
 +
 
 
{|{{BMTableStyle}}
 
{|{{BMTableStyle}}
 
|-{{BMTHStyle}}
 
|-{{BMTHStyle}}
 
| EntityManagerProperties.
 
| EntityManagerProperties.
| property name
+
| Property Name
| composite pu
+
| composite member pu
+
| comment
+
 
|-  
 
|-  
 
| COMPOSITE_PROPERTIES
 
| COMPOSITE_PROPERTIES
 
| eclipselink.composite.properties
 
| eclipselink.composite.properties
| Processed
 
| Ignored
 
|
 
 
|-
 
|-
 
| FLUSH_CLEAR_CACHE
 
| FLUSH_CLEAR_CACHE
 
| eclipselink.flush-clear.cache
 
| eclipselink.flush-clear.cache
| Processed
 
| Ignored
 
|
 
 
|-
 
|-
 
| VALIDATE_EXISTENCE
 
| VALIDATE_EXISTENCE
 
| eclipselink.validate-existence
 
| eclipselink.validate-existence
| Processed
 
| Ignored
 
|
 
 
|-
 
|-
 
| JOIN_EXISTING_TRANSACTION
 
| JOIN_EXISTING_TRANSACTION
 
| eclipselink.transaction.join-existing
 
| eclipselink.transaction.join-existing
| Processed
 
| Ignored
 
|
 
 
|-
 
|-
 
| PERSISTENCE_CONTEXT_*
 
| PERSISTENCE_CONTEXT_*
 
| eclipselink.persistence-context.*
 
| eclipselink.persistence-context.*
| Processed
 
| Ignored
 
|
 
 
|-
 
|-
 
| ORDER_UPDATES
 
| ORDER_UPDATES
 
| eclipselink.order-updates
 
| eclipselink.order-updates
| Processed
 
| 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.
 +
 +
{|{{BMTableStyle}}
 +
|-{{BMTHStyle}}
 +
| EntityManagerProperties.
 +
| Property Name
 +
|-
 
| EXCLUSIVE_CONNECTION_*
 
| EXCLUSIVE_CONNECTION_*
 
| eclipselink.jdbc.exclusive-connection.*
 
| eclipselink.jdbc.exclusive-connection.*
| Ignored
 
| Processed
 
|
 
 
|-
 
|-
 
| JDBC_DRIVER
 
| JDBC_DRIVER
 
| javax.persistence.jdbc.driver
 
| javax.persistence.jdbc.driver
| Ignored
 
| Processed
 
|
 
 
|-
 
|-
 
| JDBC_URL
 
| JDBC_URL
 
| javax.persistence.jdbc.url
 
| javax.persistence.jdbc.url
| Ignored
 
| Processed
 
|
 
 
|-
 
|-
 
| JDBC_USER
 
| JDBC_USER
 
| javax.persistence.jdbc.user
 
| javax.persistence.jdbc.user
| Ignored
 
| Processed
 
|
 
 
|-
 
|-
 
| JDBC_PASSWORD
 
| JDBC_PASSWORD
 
| javax.persistence.jdbc.password
 
| javax.persistence.jdbc.password
| Ignored
 
| Processed
 
|
 
 
|-
 
|-
 
| JTA_DATASOURCE
 
| JTA_DATASOURCE
 
| javax.persistence.jtaDataSource
 
| javax.persistence.jtaDataSource
| Ignored
 
| Processed
 
|
 
 
|-
 
|-
 
| NON_JTA_DATASOURCE
 
| NON_JTA_DATASOURCE
 
| javax.persistence.nonJtaDataSource
 
| javax.persistence.nonJtaDataSource
| Ignored
 
| Processed
 
|
 
 
|-
 
|-
 
| CONNECTION_POLICY
 
| CONNECTION_POLICY
 
| eclipselink.jdbc.connection-policy
 
| eclipselink.jdbc.connection-policy
| Ignored
 
| Processed
 
|
 
 
|-
 
|-
 
| ORACLE_PROXY_TYPE
 
| ORACLE_PROXY_TYPE
 
| eclipselink.oracle.proxy-type
 
| eclipselink.oracle.proxy-type
| Ignored
 
| Processed
 
|
 
 
|}
 
|}
 +
 +
==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:
 +
 +
<source lang="java">
 +
@PersistenceUnit(unitName="compositePu")
 +
EntityManagerFactory entityManagerFactory;
 +
@PersistenceUnit(unitName="compositePu")
 +
EntityManager entityManager;
 +
</source>
 +
 +
* Application managed composite persistence unit - using  [[http://www.eclipse.org/eclipselink/api/latest/javax/persistence/Persistence.html <tt>Persistence.createEntityManagerFactory </tt>]]:
 +
 +
<source lang="java">
 +
EntityManagerFactory entityManagerFactory = Persistence.createEntityManagerFactory("compositePu", properties);
 +
</source>
  
 
== Limitations ==
 
== 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:
 
Joins across tables in different data sources are not supported. This limitation affects mapping, query execution, and optimizations. For example:

Latest revision as of 07:12, 17 April 2013



Warning This page is now obsolete.

For current information, please see "Using Multiple Databases with a Composite Persistence Unit" in the EclipseLink Solutions Guide: http://www.eclipse.org/eclipselink/documentation/latest/solutions/usingmultipledbs.htm




EclipseLink JPA


Composite Persistence Units

EL NewIn.png 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.

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.

PersistenceUnitProperties. Property Name comment
COMPOSITE_UNIT eclipselink.composite-unit Must be specified in persistence.xml of a composite persistence unit with the value "true". Advanced usage: This property can also be set on a composite member persistence unit that is itself a composite persistence unit. In that case, the composite is substituted by its own members.
COMPOSITE_PROPERTIES eclipselink.composite.properties
TRANSACTION_TYPE javax.persistence.transactionType
TARGET_SERVER eclipselink.target-server
LOGGING_* eclipselink.logging.*
PROFILER eclipselink.profiler
COORDINATION_* eclipselink.cache.coordination.*
SESSION_NAME eclipselink.session-name This property can also be set on a composite member persistence unit . The member session name is used to read the session from sessions.xml, but the deployed session always has the same name as the member persistence unit (as it is defined in memberPuInfo.getPersistenceUnitName())
DEPLOY_ON_STARTUP eclipselink.deploy-on-startup
VALIDATION_ONLY_PROPERTY eclipselink.validation-only In 2.3: This property is also processed if set on a composite member persistence unit, but that is a known bug (bug 348815). This property should be processed by the composite only and ignored by member persistence units. To work around this bug, specify the property in the composite and in all its members. THIS IS FIXED IN 2.3.1: it's ignored by members.
VALIDATION_* eclipselink.validation.*
CLASSLOADER eclipselink.classloader
THROW_EXCEPTIONS eclipselink.orm.throw.exceptions
FLUSH_CLEAR_CACHE eclipselink.flush-clear.cache
VALIDATE_EXISTENCE eclipselink.validate-existence
JOIN_EXISTING_TRANSACTION eclipselink.transaction.join-existing
PERSISTENCE_CONTEXT_* eclipselink.persistence-context.*
ALLOW_ZERO_ID eclipselink.allow-zero-id
SESSION_CUSTOMIZER eclipselink.session.customizer This property can also be set on a composite member persistence unit. Customizers of member persistence units are processed before the composite persistence unit's customizer.
SESSION_EVENT_LISTENER_CLASS eclipselink.session-event-listener This property can also be set on a composite member persistence unit. An

EventListener defined by a composite member will not receive events raised by a UnitOfWork; it will only receive events raised by its member. Also see bug 348766 - FIXED in 2.3.1. An EventListener<>/tt> specified by a composite will receive all events (raised by either a unit of work or by members).

Exception_HANDLER_CLASS eclipselink.exception-handler This property can also be set on a composite member persistence unit. The first <tt>ExceptionHandler specified by a member handles the exception. If it is not specified or fails, then the composite's ExceptionHandler handles the original exception.
WEAVING eclipselink.weaving A composite persistent unit switches weaving on and off for all its member persistent units.

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.

PersistenceUnitProperties. Property Name comment
COMPOSITE_UNIT eclipselink.composite-unit Advanced usage: This property can also be set on a composite member persistence unit that is itself a composite persistence unit. In that case, the composite is substituted by its own members.
COMPOSITE_UNIT_MEMBER eclipselink.composite-unit.member The property should be specified with a value "true" in persistence.xml to indicate that the persistence unit cannot be used stand alone (only as a member of a composite).
SESSION_NAME eclipselink.session-name This property can also be set on a composite persistence unit. The member session name is used to read the session from sessions.xml, but the deployed session always has the same name as the member persistence unit (as it is defined in memberPuInfo.getPersistenceUnitName())
VALIDATION_ONLY_PROPERTY eclipselink.validation-only This property is processed if set on a composite member persistence unit, but that is a known bug (bug 348815). This property should be processed by the composite only and ignored by member persistence units. To work around this bug, specify the property in the composite and in all its members. FIXED in 2.3.1 - ignored on member.
VALIDATION_* eclipselink.validation.*
CLASSLOADER eclipselink.classloader
THROW_EXCEPTIONS eclipselink.orm.throw.exceptions
FLUSH_CLEAR_CACHE eclipselink.flush-clear.cache
VALIDATE_EXISTENCE eclipselink.validate-existence
JOIN_EXISTING_TRANSACTION eclipselink.transaction.join-existing
PERSISTENCE_CONTEXT_* eclipselink.persistence-context.*
ALLOW_ZERO_ID eclipselink.allow-zero-id
SESSION_CUSTOMIZER eclipselink.session.customizer This property can also be set on a composite persistence unit. Customizers of member persistence units are processed before the composite persistence unit's customizer.
SESSIONS_XML eclipselink.sessions-xml If this property is set on a composite persistence unit, an exception will be thrown. Composite persitence units cannot be read from sessions.xml. Note that a non-composite persistence unit should be able to use a SessionBroker defined in sessions.xml.
JTA_DATASOURCE javax.persistence.jtaDataSource
NON_JTA_DATASOURCE javax.persistence.nonJtaDataSource
NATIVE_SQL eclipselink.jdbc.native-sql
SQL_CAST eclipselink.jdbc.sql-cast
JDBC_* javax.persistence.jdbc.* eclipselink.jdbc.*
CONNECTION_POOL_*
PARTITIONING.* eclipselink.partitioning.*
EXCLUSIVE_CONNECTION_* eclipselink.jdbc.exclusive-connection.*
CACHE.* eclipselink.cache.*
TARGET_DATABASE eclipselink.target-database
TABLE_CREATION_SUFFIX eclipselink.ddl-generation.table-creation-suffix
EXCLUDE_ECLIPSELINK_ORM_FILE eclipselink.exclude-eclipselink-orm
WEAVING_* eclipselink.weaving.* If the weaving is on, members use their own weaving properties.
NATIVE_QUERY_UPPERCASE_COLUMNS eclipselink.jdbc.uppercase-columns
UPPERCASE_COLUMN_NAMES eclipselink.jpa.uppercase-column-names
BATCH_WRITING.* eclipselink.jdbc.batch-writing.*
SESSION_EVENT_LISTENER_CLASS eclipselink.session-event-listener This property can also be set on a composite persistence unit. An EventListener defined by a composite member will not receive events raised by a UnitOfWork; it will only receive events raised by its member. Also see bug 348766. An EventListener<>/tt> specified by a composite will receive all events (raised by either a unit of work or by members).
Exception_HANDLER_CLASS eclipselink.exception-handler This property can also be set on a composite persistence unit. The first <tt>ExceptionHandler specified by a member handles the exception. If it is not specified or fails, then the composite's ExceptionHandler handles the original exception.
INCLUDE_DESCRIPTOR_QUERIES eclipselink.session.include.descriptor.queries
ID_VALIDATION eclipselink.id-validation
TEMPORAL_MUTABLE eclipselink.temporal.mutable
ORM_SCHEMA_VALIDATION eclipselink.orm.validate.schema
DDL_*
PESSIMISTIC_LOCK_TIMEOUT javax.persistence.lock.timeout
QUERY_TIMEOUT javax.persistence.query.timeout
ORACLE_PROXY_TYPE eclipselink.oracle.proxy-type


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.

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.

EntityManagerProperties. Property Name
COMPOSITE_PROPERTIES eclipselink.composite.properties
FLUSH_CLEAR_CACHE eclipselink.flush-clear.cache
VALIDATE_EXISTENCE eclipselink.validate-existence
JOIN_EXISTING_TRANSACTION eclipselink.transaction.join-existing
PERSISTENCE_CONTEXT_* eclipselink.persistence-context.*
ORDER_UPDATES eclipselink.order-updates

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.

EntityManagerProperties. Property Name
EXCLUSIVE_CONNECTION_* eclipselink.jdbc.exclusive-connection.*
JDBC_DRIVER javax.persistence.jdbc.driver
JDBC_URL javax.persistence.jdbc.url
JDBC_USER javax.persistence.jdbc.user
JDBC_PASSWORD javax.persistence.jdbc.password
JTA_DATASOURCE javax.persistence.jtaDataSource
NON_JTA_DATASOURCE javax.persistence.nonJtaDataSource
CONNECTION_POLICY eclipselink.jdbc.connection-policy
ORACLE_PROXY_TYPE eclipselink.oracle.proxy-type

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