Using the eclispelink-orm.xml File

EclipseLink-ORM.XML

Use the eclipselink-orm.xml file to override the JPA native orm.xml file. The eclipselink-orm.xsd (http://www.eclipse.org/eclipselink/xsds/eclipselink_orm_1_0.xsd) defines the schema used by this configuration file.

Default Location

Normally, you should place the eclipselink-orm.xml file in the default META-INF/ location. You can also reference the eclipselink-orm.xml file from the persistence unit mapping file (persistence.xml) or sessions configuration file (sessions.xml). The eclipselink-orm.xml file can co-exist with the JPA META-INF/orm.xml file and can be used anywhere the JPA orm.xml file is used.

Overrding and Merging

Normally, when multiple mapping files are used, the last file read will be read will be used. The order of the files in the persistence.xml does not guarantee the processing order. Regardless, whenever a META-INF/eclipselink-orm.xml file is defined, it will always be used to override any other defined mappings.

For example, using the following mapping files:

• META-INF/orm.xml: Defines Entity A with mappings B and C
• META-INF/some-other-mapping-fle.xml: Defines Entity B with mappings A and B
• META-INF/eclipselink-orm.xml: Defines Entity A with mappings C and D, and Entity B with mappings B and C

will result in the following:

• Entity A will contain mapping B (from orm.xml), mappings C and D (from eclipselink-orm.xml)
• Entity B will contain mapping A (from some-other-mapping-file.xml), mappings B and C (from eclipselink-orm.xml).

Persistence Unit Metadata

Any persistence unit metadata defined in the eclipselink-orm.xml file will be merged with, or override, the perisitence unit metadata defined elsewhere, as shown in the following table:

entity-mappings/persistence-unit-metadata	Rule	Comments
xml-mapping-metadata-complete	Full override	An xml-mapping-unit-metadata setting will override an existing setting (non-set that is) and set one. And the functionality remains as defined in the JPA spec. If specified then the complete set of mapping metadata for the persistence unit is contained in the XML mapping files for the persistence unit.
persistence-unit-defaults/schema	Full override	A schema setting will override an existing setting or set one
persistence-unit-defaults/catalog	Full override	A catalog setting will override an existing setting or set one
persistence-unit-defaults/access	Full override	An access setting will override an existing setting or set one
entity-mappings/persistence-unit-metadata/persistence-unit-defaults/cascade-persist	Full override	A cascade-persist setting will override an existing setting or set one
entity-mappings/persistence-unit-metadata/persistence-unit-defaults/entity-listeners	Full override	Any listeners defined here will override existing listeners and add new ones

Entity Mappings

Any Entity, Embeddable Entity, or Mapped Superclass defined in the eclipselink-orm.xml file will be added to (or merged and overridden) the persistence unit, as shown in the following table:

entity-mappings/	Rule	Comments
package	None	The package element specifies the package of the classes listed within the sub-elements and attributes of the same mapping file only. That is, will only apply to those entities that are fully defined within the EclipseLink-ORM.XML file, otherwise its usage remains local and the same as described in the JPA spec.
catalog	None	The catalog element applies only to the sub-elements and attributes listed within the EclipseLink-ORM.XML file that are NOT an extension to another mapping file. Otherwise, the use of the catalog element within the EclipseLink-ORM.XML file remains local and the same as described in the JPA spec.
schema	None	The schema element applies only to the sub-elements and attributes listed within the EclipseLink-ORM.XML file that are NOT an extension to another mapping file. Otherwise, the use of the schema element within the EclipseLink-ORM.XML file remains local and the same as described in the JPA spec.
access	None	The access element applies only to the sub-elements and attributes listed within the EclipseLink-ORM.XML file that are NOT an extension to another mapping file. Otherwise, the use of the access element within the EclipseLink-ORM.XML file remains local and the same as described in the JPA spec.
sequence-generator	Full override	A sequence-generator is unique by name. A sequence-generator with the same named defined in another mapping file will be completely overridden by this sequence-generator. Two sequence-generator's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
table-generator	Full override	A table-generator is unique by name. A table-generator with the same named defined in another mapping file will be completely overridden by this table-generator. Two table-generator's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
named-query	Full override	A named-query is unique by name. A named-query with the same named defined in another mapping file will be completely overridden by this named-query. Two named-query's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
named-native-query	Full override	A named-native-query is unique by name. A named-native-query with the same named defined in another mapping file will be completely overridden by this named-native-query. Two named-native-query's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
sql-result-set-mapping	Full override	A sql-result-set-mapping is unique by name. A sql-result-set-mapping with the same named defined in another mapping file will be completely overridden by this sql-result-set-mapping. Two sql-result-set-mapping's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.

Entity Merging

Because an Entity may be defined wholly or extend to an entity from another mapping file, the metadata for an entity defined in the eclipselink-orm.xml file will be merged as shown in the following table:

entity-mappings/entity	Rule	Comments
table	Full override	A table definition will override any other table setting (with the same name) for this entity. There will be no merging of individual table values.
secondary-table	Full override	A secondary-table definition will override another secondary-table setting (with the same name) for this entity. There will be no merging of individual secondary-table(s) values. New secondary-table's will be added.
primary-key-join-column	Full override	A primary-key-join-column(s) definition will override any other primary-key-join-column(s) setting for this entity. There will be no merging of the primary-key-join-column(s). That is, the specification is assumed to be complete and these primary-key-join-columns are the source of truth.
id-class	Full override	An id-class setting will override an existing setting or set one.
inheritance	Full override	An inheritance setting will override an existing setting or set one.
discriminator-value	Full override	A discriminator-value setting will override an existing setting or set one.
discriminator-column	Full override	A discriminator-column setting will override an existing setting or set one.
sequence-generator	Full override	A sequence-generator is unique by name. A sequence-generator with the same named defined in another mapping file will be completely overridden by this sequence-generator. Two sequence-generator's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
table-generator	Full override	A table-generator is unique by name. A table-generator with the same named defined in another mapping file will be completely overridden by this table-generator. Two table-generator's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
named-query	Full override	A named-query is unique by name. A named-query with the same named defined in another mapping file will be completely overridden by this named-query. Two named-query's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
named-native-query	Full override	A named-native-query is unique by name. A named-native-query with the same named defined in another mapping file will be completely overridden by this named-native-query. Two named-native-query's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
sql-result-set-mapping	Full override	A sql-result-set-mapping is unique by name. A sql-result-set-mapping with the same named defined in another mapping file will be completely overridden by this sql-result-set-mapping. Two sql-result-set-mapping's with the same name defined in the EclipseLink-ORM.XML file, or any other mapping file, will cause an exception to be thrown.
exclude-default-listeners	Full override	An exclude-default-listeners setting will override an existing setting or set one.
exclude-superclass-listeners	Full override	An exclude-superclass-listeners setting will override an existing setting or set one.
entity-listeners	Full override	Any listeners defined here will override existing listeners and add new ones. The class name of the listener will be the key to identify the override. All the lifecycle methods of that listener will be overridden.
pre-persist	Full override	A pre-persist setting will override an existing setting or set one.
post-persist	Full override	A post-persist setting will override an existing setting or set one.
pre-remove	Full override	A pre-remove setting will override an existing setting or set one.
post-remove	Full override	A post-remove setting will override an existing setting or set one.
pre-update	Full override	A pre-update setting will override an existing setting or set one.
post-update	Full override	A post-update setting will override an existing setting or set one.
post-load	Full override	A post-load setting will override an existing setting or set one.
attributes	Merge and mapping level override	All attributes will be overriden at the mapping level (id, embedded-id, basic, version, many-to-one, one-to-many, one-to-one, many-to-many, embedded, transient) and new attributes will be added.
association-override	Merge and full override	Any association-overide defined here will override an existing association-override and add new ones.
name	Full override	An name setting will override an existing setting or set one.
class	None
access	Full override	An access setting will override an existing setting or set one. It will override the default class setting.
metadata-complete	Full override	A metadata-complete setting will override an existing setting or set one.

Mapped Superclass Merging

Because a Mapped Superclass may be defined wholly or extend to a mapped superclass from another mapping file, the metadata for a mapped superclass defined in the eclipselink-orm.xml file will be merged as shown in the following table:

entity-mappings/mapped-superclass	Rule	Comments
id-class	Full override	An id-class setting will override an existing setting or set one.
exclude-default-listeners	Full override	An exclude-default-listeners setting will override an existing setting or set one.
exclude-superclass-listeners	Full override	An exclude-superclass-listeners setting will override an existing setting or set one.
entity-listeners	Full override	Any listeners defined here will override existing listeners and add new ones. The class name of the listener will be the key to identify the override. All the lifecycle methods of that listener will be overridden.
pre-persist	Full override	A pre-persist setting will override an existing setting or set one.
post-persist	Full override	A post-persist setting will override an existing setting or set one.
pre-remove	Full override	A pre-remove setting will override an existing setting or set one.
post-remove	Full override	A post-remove setting will override an existing setting or set one.
pre-update	Full override	A pre-update setting will override an existing setting or set one.
post-update	Full override	A post-update setting will override an existing setting or set one.
post-load	Full override	A post-load setting will override an existing setting or set one.
attributes	Merge and mapping level override	All attributes will be overridden at the mapping level (id, embedded-id, basic, version, many-to-one, one-to-many, one-to-one, many-to-many, embedded, transient) and new attributes will be added.
class	None
access	Full override	An access setting will override an existing setting or set one. It will override the default class setting.
metadata-complete	Full override	A metadata-complete setting will override an existing setting or set one.

Embeddable Merging

Because an Embeddable Entity may be defined wholly or extend to an embeddable entity from another mapping file, the metadata for an embeddable entity defined in the eclipselink-orm.xml file will be merged as shown in the following table:

entity-mappings/embeddable	Rule	Comments
attributes	Override and merge	At the mapping level (id, embedded-id, basic, version, many-to-one, one-to-many, one-to-one, many-to-many, embedded, transient)
class	None
access	Full override	An access setting will override an existing setting or set one. It will override the default class setting.
metadata-complete	Full override	A metadata-complete setting will override an existing setting or set one.