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.

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.

−

'''''//ANDREI: Changed "must" to "should" in the next two bullets'''''

* The transaction type should be specified in the composite persistence unit (otherwise default transaction type is used). Transaction types of composite members are ignored.

* The transaction type should be specified in the composite persistence unit (otherwise default transaction type is used). Transaction types of composite members are ignored.

* Data sources should be specified in composite member persistence units. Those specified in the composite are ignored.

* Data sources should 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</tt> property can only be set on the composite persistent unit. This is an advanced feature. Setting this properry to <tt>true</tt> specifies that the persistence unit should '''not''' be used as an independent persistence unit, but only as a member of a composite. The property should be specified if the persistence unit has a dependency on another member persistence unit. An independent persistence unit cannot have dependencies on other persistence units.

−

* '''''//ANDREI I would remove that - seems confusing here. This property is defined for an advanced case - it should be specified (with value "true") if the persistence unit should NOT be used as an independent persistence unit, but only as a member of a composite. The property should be specified if the persistence unit has dependency on another member persistence unit. An independent pu can'tr have dependencies on other pus'''''The <tt>eclipselink.composite-unit.member</tt> property can only be set on composite member persistent 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.

'''''//ANDREI The only goal of these tables is to show which property should be defined where. For instance, I have to specify "eclipselink.target-server" property - where should I define it? On the composite? Or on all the composite members? That should be communicated as clearly as possible'''''

+

===Configuring Composite Persistent Units in persistence.xml ===

===Configuring Composite Persistent Units in persistence.xml ===

Line 77:

Line 74:

* <tt>true</tt> specifies that the persistent unit ''must'' 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.

−

* '''''//ANDREI this statement is wrong. "false" value is equivalent to not specifying the property at all (so there is no reason to specify it with value "false") - that's the common case: pu may be both used independently and as a member of a composite'''''<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)).

+

* <tt>false</tt> is equivalent to not specifying the property at all (and therefore there is no reason to specify the property with value <tt>false</tt>)). This is the common case, where the persistence unit can be used independently and as a member of a composite.

For example,

For example,

Line 95:

Line 92:

<!---//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// -->

<!---//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// -->

As with regular persistence unit you can override properties specified in <tt>persistence.xml</tt> with new ones passed to the <tt>createEntityManagerFactory</tt> method. Therefore, you can change some properties at runtime, for example connection parameters. Do do this with composite member persistence units, use the <tt>eclipselink.composite-unit.properties</tt> property. The value is a <tt>Map</tt> that is keyed on composite member persistence unit names; the value is a <tt>Map</tt> that contains all properties to be passed to this member persistence unit. For example,

+

As with regular persistence units, you can override properties specified in <tt>persistence.xml</tt> with new ones passed to the <tt>createEntityManagerFactory</tt> method. Therefore, you can change some properties at runtime, for example connection parameters. To do this with composite member persistence units, use the <tt>eclipselink.composite-unit.properties</tt> property. The value is a <tt>Map</tt> that is keyed on composite member persistence unit names; the value is a <tt>Map</tt> that contains all properties to be passed to this member persistence unit. For example,

<source lang="java">

<source lang="java">

Line 123:

Line 120:

</source>

</source>

−

'''''//ANDREI: May be also to mention that: a) only Persistence Unit properties that processed by composite member (as indicated in the table) should be passed to member - other properties will be ignored. (Or is it self evident already?); b) the same rule applies for createEntityManager method - in the same manner Entity Manager Properties could be passed to members, only those Entity Manager properties that processed on member (as indicated in Entity Manager Properties table) should be passed - other properties will be ignored'''''

+

Only persistence unit properties that are processed by composite members (as indicated in the [[#Persistence Unit Properties| Persistence Unit Properties]] table, below) should be passed to a member. Other properties are ignored. The same rule applies for the <tt>createEntityManager</tt> method; only those entity manager properties that are processed on members (as indeicated in the [[#Entity Manager Properties| Entity Manager Properties]] table) should be passed. Other properties are ignored.

=== Examples ===

=== Examples ===

Line 212:

Line 209:

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

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

−

'''''ANDREI: let's scrap the next sentence and provide something a bit more clear instead. For instance: Only pass to composite the properties that are processed on composite (as per table below) - all other properties will be ignored. Only pass to composite member (through "eclipselink.composite.properties") the properties that marked in the table as processed on member - all other properties will be ignored. May be it would be more clear instead of the table just provide to lists of properties: one would contain the properties that may be passed to composite; another - the properties that may be passed (through "eclipselink.composite.properties") to member?'''''

+

The following table shows where to set properties: on the composite persistence unit or on the composite member persistence unit. You should only pass properties to a composite or to a member that can be processed by the composite or the member. That is,

−

The following table shows how properties set on a composite persistence unit and its members are handled when properties are set on both.

+

+

*Only pass to a composite persistence unit those properties that are processed on composite persistence units. All other properties are ignored.

+

*Only pass to a composite persistence unit member (through <tt>eclipselink.composite.properties</tt>) the properties that are processed on composite member persistence units. All other properties are ignored.

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();

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.

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 should be specified in the composite persistence unit (otherwise default transaction type is used). Transaction types of composite members are ignored.

Data sources should be specified in composite member persistence units. Those specified in the composite are ignored.

The eclipselink.composite-unit property can only be set on the composite persistent unit. This is an advanced feature. Setting this properry to true specifies that the persistence unit should not be used as an independent persistence unit, but only as a member of a composite. The property should be specified if the persistence unit has a dependency on another member persistence unit. An independent persistence unit cannot have dependencies on other persistence units.

Configuring Composite Persistent Units in persistence.xml

A minimal configuration of a composite persistent unit in persistence.xml requires the following:

Use the eclipselink.composite-unit property to specify that it is a composite persistence unit. (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.

Configuring Composite Member Persistent Units in persistence.xml

Use the eclipselink.composite-unit.member property to specify whether or not a persistent unit should be a member of a composite persistence unit:

true specifies that the persistent unit must be a member of a composite persistence unit.

false is equivalent to not specifying the property at all (and therefore there is no reason to specify the property with value false)). This is the common case, where the persistence unit can be used independently and as a member of a composite.

As with regular persistence units, you can override properties specified in persistence.xml with new ones passed to the createEntityManagerFactory method. Therefore, you can change some properties at runtime, for example connection parameters. To do this with composite member persistence units, use the eclipselink.composite-unit.properties property. The value is a Map that is keyed on composite member persistence unit names; the value is a Map that contains all properties to be passed to this member persistence unit. For example,

Only persistence unit properties that are processed by composite members (as indicated in the Persistence Unit Properties table, below) should be passed to a member. Other properties are ignored. The same rule applies for the createEntityManager method; only those entity manager properties that are processed on members (as indeicated in the Entity Manager Properties table) should be passed. Other properties are ignored.

Examples

In the following 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.

Deploying and Accessing a Composite Persistence Unit

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.

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

Persistence Unit Properties

Persistence unit properties can be set on the EntityManagerFactory as follows:

Composite persistence unit properties can be specified either in the composite persistence unit's persistence.xml file or passed to the its createEntityManagerFactory() method.

Composite member persistence unit properties can either be specified in the composite member persistence unit's persistence.xml file or passed to the composite persistence unit's createEntityManagerFactory() method through the eclipselink.composite.properties property.

The following table shows where to set properties: on the composite persistence unit or on the composite member persistence unit. You should only pass properties to a composite or to a member that can be processed by the composite or the member. That is,

Only pass to a composite persistence unit those properties that are processed on composite persistence units. All other properties are ignored.

Only pass to a composite persistence unit member (through eclipselink.composite.properties) the properties that are processed on composite member persistence units. All other properties are ignored.

If specified by a composite member persistence unit that is itself a composite persistence unit, then it is substituted by its own members.

COMPOSITE_UNIT_MEMBER

eclipselink.composite-unit.member

Advanced feature

Processed

If specified by a composite persistence unit, the composite must be member of another composite persistence unit. All the persistence units in this case must have unique names.

COMPOSITE_PROPERTIES

eclipselink.composite.properties

Processed

Ignored

TRANSACTION_TYPE

javax.persistence.transactionType

Processed

Ignored

TARGET_SERVER

eclipselink.target-server

Processed

Ignored

LOGGING_*

eclipselink.logging.*

Processed

Ignored

PROFILER

eclipselink.profiler

Processed

Ignored

COORDINATION_*

eclipselink.cache.coordination.*

Processed

Ignored

SESSION_NAME

eclipselink.session-name

Processed

Advanced

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

Processed

Ignored

VALIDATION_ONLY_PROPERTY

eclipselink.validation-only

Processed

Processed

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

VALIDATION_*

eclipselink.validation.*

Processed

Ignored

CLASSLOADER

eclipselink.classloader

Processed

Ignored

THROW_EXCEPTIONS

eclipselink.orm.throw.exceptions

Processed

Ignored

FLUSH_CLEAR_CACHE

eclipselink.flush-clear.cache

Processed

Ignored

VALIDATE_EXISTENCE

eclipselink.validate-existence

Processed

Ignored

JOIN_EXISTING_TRANSACTION

eclipselink.transaction.join-existing

Processed

Ignored

PERSISTENCE_CONTEXT_*

eclipselink.persistence-context.*

Processed

Ignored

ALLOW_ZERO_ID

eclipselink.allow-zero-id

Processed

Ignored

SESSION_CUSTOMIZER

eclipselink.session.customizer

Processed

Processed

Customizers of member persistence units are processed before the composite persistence unit's customizer.

SESSIONS_XML

eclipselink.sessions-xml

Exception

Processed

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

Ignored

Processed

NON_JTA_DATASOURCE

javax.persistence.nonJtaDataSource

Ignored

Processed

NATIVE_SQL

eclipselink.jdbc.native-sql

Ignored

Processed

SQL_CAST

eclipselink.jdbc.sql-cast

Ignored

Processed

JDBC_*

javax.persistence.jdbc.* eclipselink.jdbc.*

Ignored

Processed

CONNECTION_POOL_*

Ignored

Processed

PARTITIONING.*

eclipselink.partitioning.*

Ignored

Processed

EXCLUSIVE_CONNECTION_*

eclipselink.jdbc.exclusive-connection.*

Ignored

Processed

CACHE.*

eclipselink.cache.*

Ignored

Processed

TARGET_DATABASE

eclipselink.target-database

Ignored

Processed

TABLE_CREATION_SUFFIX

eclipselink.ddl-generation.table-creation-suffix

Ignored

Processed

EXCLUDE_ECLIPSELINK_ORM_FILE

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_*

eclipselink.weaving.*

Ignored

Processed

If the weaving is on, members use their own weaving properties.

NATIVE_QUERY_UPPERCASE_COLUMNS

eclipselink.jdbc.uppercase-columns

Ignored

Processed

UPPERCASE_COLUMN_NAMES

eclipselink.jpa.uppercase-column-names

Ignored

Processed

BATCH_WRITING.*

eclipselink.jdbc.batch-writing.*

Ignored

Processed

SESSION_EVENT_LISTENER_CLASS

eclipselink.session-event-listener

Processed

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

eclipselink.exception-handler

Processed

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

eclipselink.session.include.descriptor.queries

Ignored

Processed

ID_VALIDATION

eclipselink.id-validation

Ignored

Processed

TEMPORAL_MUTABLE

eclipselink.temporal.mutable

Ignored

Processed

ORM_SCHEMA_VALIDATION

eclipselink.orm.validate.schema

Ignored

Processed

DDL_*

Ignored

Processed

PESSIMISTIC_LOCK_TIMEOUT

javax.persistence.lock.timeout

Ignored

Processed

QUERY_TIMEOUT

javax.persistence.query.timeout

Ignored

Processed

ORACLE_PROXY_TYPE

eclipselink.oracle.proxy-type

Ignored

Processed

Entity Manager Properties

Persistence unit properties can be set on the EntityManager as follows:

Composite entity manager properties can be passed directly to the createEntityManager() method or to the setProperty method.

Composite member properties can be passed to the same methods through the eclipselink.composite.properties property.

EntityManagerProperties.

property name

composite pu

composite member pu

comment

COMPOSITE_PROPERTIES

eclipselink.composite.properties

Processed

Ignored

FLUSH_CLEAR_CACHE

eclipselink.flush-clear.cache

Processed

Ignored

VALIDATE_EXISTENCE

eclipselink.validate-existence

Processed

Ignored

JOIN_EXISTING_TRANSACTION

eclipselink.transaction.join-existing

Processed

Ignored

PERSISTENCE_CONTEXT_*

eclipselink.persistence-context.*

Processed

Ignored

ORDER_UPDATES

eclipselink.order-updates

Processed

Ignored

EXCLUSIVE_CONNECTION_*

eclipselink.jdbc.exclusive-connection.*

Ignored

Processed

JDBC_DRIVER

javax.persistence.jdbc.driver

Ignored

Processed

JDBC_URL

javax.persistence.jdbc.url

Ignored

Processed

JDBC_USER

javax.persistence.jdbc.user

Ignored

Processed

JDBC_PASSWORD

javax.persistence.jdbc.password

Ignored

Processed

JTA_DATASOURCE

javax.persistence.jtaDataSource

Ignored

Processed

NON_JTA_DATASOURCE

javax.persistence.nonJtaDataSource

Ignored

Processed

CONNECTION_POLICY

eclipselink.jdbc.connection-policy

Ignored

Processed

ORACLE_PROXY_TYPE

eclipselink.oracle.proxy-type

Ignored

Processed

Limitations

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:

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: