Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Configuration/JPA/Overriding and Merging"

Line 3: Line 3:
 
|toc=n
 
|toc=n
 
|eclipselink=y
 
|eclipselink=y
|eclipselinktype=JPA}}
+
|eclipselinktype=JPA}}  
=Overriding and Merging XML=
+
 
You can use EclipseLink’s native metadata xml file, [[EclipseLink/UserGuide/JPA/Basic JPA Development/Configuration/JPA/eclipselink-orm.xml|<tt>eclipselink-orm.xml</tt>]], to override mappings defined in JPA’s configuration file <tt>[[EclipseLink/UserGuide/JPA/Basic JPA Development/Configuration/JPA/orm.xml|orm.xml]]</tt> and provide EclipseLink with extended ORM features.
+
= Overriding and Merging XML =
{{EclipseLink_Spec
+
 
 +
You can use EclipseLink’s native metadata xml file, [[EclipseLink/UserGuide/JPA/Basic JPA Development/Configuration/JPA/eclipselink-orm.xml|<tt>eclipselink-orm.xml</tt>]], to override mappings defined in JPA’s configuration file <tt>[[EclipseLink/UserGuide/JPA/Basic JPA Development/Configuration/JPA/orm.xml|orm.xml]]</tt> and provide EclipseLink with extended ORM features. {{EclipseLink_Spec
 
|link=http://jcp.org/en/jsr/detail?id=220
 
|link=http://jcp.org/en/jsr/detail?id=220
 
|section=Section 12.2 "XML Overriding Rules"
 
|section=Section 12.2 "XML Overriding Rules"
}}
+
}}  
  
When both <tt>orm.xml</tt> and <tt>eclipselink-orm.xml</tt> are specified in a project, the contents of <tt>eclipselink-orm.xml</tt> override <tt>orm.xml</tt> and any other JPA mapping file specified in the persistence unit. If there are overlapping specifications in multiple ORM files, the files are merged if there are no conflicting entities.
+
When both <tt>orm.xml</tt> and <tt>eclipselink-orm.xml</tt> are specified in a project, the contents of <tt>eclipselink-orm.xml</tt> override <tt>orm.xml</tt> and any other JPA mapping file specified in the persistence unit. If there are overlapping specifications in multiple ORM files, the files are merged if there are no conflicting entities. {{EclipseLink_Note
{{EclipseLink_Note
+
|note=The order of files defined in <tt>persistence.xml</tt> does not define the order of their processing. The files are processed, merged, and overidden as required. For more information, see [[#Overriding and Merging Examples|Overriding and Merging Examples]].}}  
|note=The order of files defined in <tt>persistence.xml</tt> does not define the order of their processing. The files are processed, merged, and overidden as required. For more information, see [[#Overriding and Merging Examples|Overriding and Merging Examples]].}}
+
  
The EclipseLink-ORM.XML file can be referenced for inclusion in a persistence unit’s metadata through any of the following files or methods:
+
The eclipselink-orm.xml file can be referenced for inclusion in a persistence unit’s metadata through any of the following files or methods:  
{|{{BMTableStyle}}
+
 
|-{{BMTHStyle}}
+
{|
! File/Method
+
|-
 +
! File/Method  
 
! Description
 
! Description
|-  
+
|-
| <tt>META-INF/eclipselink-orm.xml</tt>
+
| <tt>META-INF/eclipselink-orm.xml</tt>  
| Provides mapping overriding capabilities.  
+
| Provides mapping overriding capabilities.
|-  
+
|-
| <tt>META-INF/orm.xml</tt>
+
| <tt>META-INF/orm.xml</tt>  
 
| The default ORM file provided with JPA.
 
| The default ORM file provided with JPA.
|-
+
|-
| Referenced as persistence unit mapping file in <tt>persistence.xml</tt>
+
| Referenced as persistence unit mapping file in <tt>persistence.xml</tt>  
 
| Does not provide mapping overriding capability, but can be used for merging mapping files.
 
| Does not provide mapping overriding capability, but can be used for merging mapping files.
 
|}
 
|}
  
==Overriding and Merging Examples==
+
== Overriding and Merging Examples ==
  
'''''Example 1'''''
+
'''''Example 1'''''  
* <tt>META-INF/orm.xml</tt> - defines Entity A with the mappings b and c.
+
* <tt>META-INF/eclipselink-orm.xml</tt> - defines Entity A with the mappings for c and d.
+
* Result - Entity A will contain the mapping b (from <tt>orm.xml</tt>), mapping c and d (from <tt>eclipselink-orm.xml</tt>)
+
  
'''''Example 2'''''
+
*<tt>META-INF/orm.xml</tt> - defines Entity A with the mappings b and c.  
* <tt>META-INF/orm.xml</tt> - defines Entity A with the mappings b and c
+
*<tt>META-INF/eclipselink-orm.xml</tt> - defines Entity A with the mappings for c and d.
* <tt>META-INF/some-other-mapping-file.xml</tt> - defines Entity B with mappings a and b
+
*Result - Entity A will contain the mapping b (from <tt>orm.xml</tt>), mapping c and d (from <tt>eclipselink-orm.xml</tt>)
* <tt>META-INF/eclipselink-orm.xml</tt> - defines Entity A with the mappings for c and d and Entity B with the mapping b and c
+
* Result
+
** Entity A will contain the mapping b (from <tt>orm.xml</tt>), mapping c and d (from <tt>eclipselink-orm.xml</tt>)
+
** Entity B will contain the mapping a (from <tt>some-other-mapping-file</tt>), mappings b and c (from <tt>eclipselink-orm.xml</tt>)  
+
  
'''''Example 3'''''
+
'''''Example 2'''''  
* <tt>META-INF/orm.xml</tt> - defines Entity A with the mappings b and c.
+
* <tt>META-INF/eclipselink-orm.xml</tt> - defines Entity A with the mappings c and d.
+
* <tt>META-INF/some-other-mapping-file.xml</tt> - defines Entity A with the mapping x.
+
* Result - Entity A will contain the mapping b (from <tt>orm.xml</tt>), mapping c and d (from <tt>eclipselink-orm.xml</tt>) and mapping x (from some-other-mapping-file)
+
+
'''''Example 4'''''
+
* <tt>META-INF/orm.xml</tt> - defines Entity A with the mappings b and c.
+
* <tt>META-INF/extensions/eclipselink-orm.xml</tt> - defines defines Entity A with the mappings c and d. <br> '''Note:''' This file is added through a <mapping-file> tag in the <tt>persistence.xml</tt>
+
* Result -  Exception generated for conficting specifications for mapping c.
+
  
'''''Example 5'''''
+
*<tt>META-INF/orm.xml</tt> - defines Entity A with the mappings b and c  
* <tt>META-INF/orm.xml</tt> - defines Entity A with the mappings b and c.
+
*<tt>META-INF/some-other-mapping-file.xml</tt> - defines Entity B with mappings a and b
* <tt>META-INF/jpa-mapping-file.xml</tt> - defines Entity A with the mappings a and d.
+
*<tt>META-INF/eclipselink-orm.xml</tt> - defines Entity A with the mappings for c and d and Entity B with the mapping b and c
* <tt>META-INF/extensions/eclipse-mapping-file.xml</tt> - defines defines Entity A with the mappings c and d.
+
*Result  
* Result - Exception generated for conficting specifications for mapping c or d (which ever is processed first).
+
**Entity A will contain the mapping b (from <tt>orm.xml</tt>), mapping c and d (from <tt>eclipselink-orm.xml</tt>)  
 +
**Entity B will contain the mapping a (from <tt>some-other-mapping-file</tt>), mappings b and c (from <tt>eclipselink-orm.xml</tt>)
  
==Overriding and Merging Rules==
+
'''''Example 3'''''
The following sections outlines elements defined in <tt>orm.xml</tt> and their specific overriding in greater detail.
+
  
===Persistence Unit Metadata===
+
*<tt>META-INF/orm.xml</tt> - defines Entity A with the mappings b and c.
In EclipseLink-ORM.XML, a persistence-unit-metadata specification merges or overrides the values of existing persistence-unit-metadata specification.
+
*<tt>META-INF/eclipselink-orm.xml</tt> - defines Entity A with the mappings c and d.
 +
*<tt>META-INF/some-other-mapping-file.xml</tt> - defines Entity A with the mapping x.
 +
*Result - Entity A will contain the mapping b (from <tt>orm.xml</tt>), mapping c and d (from <tt>eclipselink-orm.xml</tt>) and mapping x (from some-other-mapping-file)
  
{|{{BMTableStyle}}
+
'''''Example 4'''''
|-{{BMTHStyle}}
+
 
! entity-mappings/persistence-unit-metadata
+
*<tt>META-INF/orm.xml</tt> - defines Entity A with the mappings b and c.
! Rule
+
*<tt>META-INF/extensions/eclipselink-orm.xml</tt> - defines defines Entity A with the mappings c and d. <br> '''Note:''' This file is added through a &lt;mapping-file&gt; tag in the <tt>persistence.xml</tt>
 +
*Result - Exception generated for conficting specifications for mapping c.
 +
 
 +
'''''Example 5'''''
 +
 
 +
*<tt>META-INF/orm.xml</tt> - defines Entity A with the mappings b and c.
 +
*<tt>META-INF/jpa-mapping-file.xml</tt> - defines Entity A with the mappings a and d.
 +
*<tt>META-INF/extensions/eclipse-mapping-file.xml</tt> - defines defines Entity A with the mappings c and d.
 +
*Result - Exception generated for conficting specifications for mapping c or d (which ever is processed first).
 +
 
 +
== Overriding and Merging Rules ==
 +
 
 +
The following sections outlines elements defined in <tt>orm.xml</tt> and their specific overriding in greater detail.
 +
 
 +
=== Persistence Unit Metadata ===
 +
 
 +
In eclipselink-orm.xml, a persistence-unit-metadata specification merges or overrides the values of existing persistence-unit-metadata specification.
 +
 
 +
{|
 +
|-
 +
! entity-mappings/persistence-unit-metadata  
 +
! Rule  
 
! Description
 
! Description
|-  
+
|-
| xml-mapping-metadata-complete
+
| xml-mapping-metadata-complete  
| Full override
+
| Full override  
| If specified, the complete set of mapping metadata for the persistence unit is contained in the XML mapping files for the persistence unit.  
+
| If specified, 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
+
| persistence-unit-defaults/schema  
| Full override
+
| Full override  
| If a schema setting exists, then the EclipseLink-ORM.XML's schema setting overrides the existing setting, or creates a new schema setting.
+
| If a schema setting exists, then the eclipselink-orm.xml's schema setting overrides the existing setting, or creates a new schema setting.
|-  
+
|-
| persistence-unit-defaults/catalog
+
| persistence-unit-defaults/catalog  
| Full override
+
| Full override  
| If a catalog setting exists, then the EclipseLink-ORM.XML's catalog setting overrides the existing setting, or creates a new catalog setting  
+
| If a catalog setting exists, then the eclipselink-orm.xml's catalog setting overrides the existing setting, or creates a new catalog setting
|-  
+
|-
| persistence-unit-defaults/access
+
| persistence-unit-defaults/access  
| Full override
+
| Full override  
| If an access setting exists, then the EclipseLink-ORM.XML's access setting overrides the existing setting, or creates a new access setting.  
+
| If an access setting exists, then the eclipselink-orm.xml's access setting overrides the existing setting, or creates a new access setting.
|-  
+
|-
| entity-mappings/persistence-unit-metadata/persistence-unit-defaults/cascade-persist
+
| entity-mappings/persistence-unit-metadata/persistence-unit-defaults/cascade-persist  
| Full override
+
| Full override  
| If a cascade-persist setting exists, then the EclipseLink-ORM.XML's cascade-persist setting overrides the existing setting, or creates a new cascade-persist setting.  
+
| If a cascade-persist setting exists, then the eclipselink-orm.xml's cascade-persist setting overrides the existing setting, or creates a new cascade-persist setting.
|-  
+
|-
| entity-mappings/persistence-unit-metadata/persistence-unit-defaults/entity-listeners
+
| entity-mappings/persistence-unit-metadata/persistence-unit-defaults/entity-listeners  
| Merge
+
| Merge  
| If an entity-listeners exists, then the EclipseLink-ORM.XML's entity-listeners will be merged with the list of all entity-listeners from the persistence unit.
+
| If an entity-listeners exists, then the eclipselink-orm.xml's entity-listeners will be merged with the list of all entity-listeners from the persistence unit.
 
|}
 
|}
  
===Entity Mappings===
+
=== Entity Mappings ===
Entities, embeddables and mapped superclasses are defined within entity-mappings. EclipseLink-ORM.XML's entities, embeddables and mapped superclasses are added to the persistence unit. The following table describes the top-level elements of the entity-mappings sections:
+
  
{|{{BMTableStyle}}
+
Entities, embeddables and mapped superclasses are defined within entity-mappings. eclipselink-orm.xml's entities, embeddables and mapped superclasses are added to the persistence unit. The following table describes the top-level elements of the entity-mappings sections:
|-{{BMTHStyle}}
+
 
! entity-mappings/
+
{|
! Rule
+
|-
 +
! entity-mappings/  
 +
! Rule  
 
! Description
 
! Description
 
|-
 
|-
| package
+
| package  
| None
+
| None  
| The package element specifies the package of the classes listed within the subelements and attributes of the same mapping file only. It is only applicable to those entities that are fully defined within the EclipseLink-ORM.XML file, else its usage remains local and is same as described in the JPA specification.  
+
| The package element specifies the package of the classes listed within the subelements and attributes of the same mapping file only. It is only applicable to those entities that are fully defined within the eclipselink-orm.xml file, else its usage remains local and is same as described in the JPA specification.
 
|-
 
|-
| catalog
+
| catalog  
| None
+
| None  
| The catalog element applies only to the subelements 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 is same as described in the JPA specification.  
+
| The catalog element applies only to the subelements 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 is same as described in the JPA specification.
 
|-
 
|-
| schema
+
| schema  
| None
+
| None  
| The schema element applies only to the subelements 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 is same as described in the JPA specification.  
+
| The schema element applies only to the subelements 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 is same as described in the JPA specification.
 
|-
 
|-
| access
+
| access  
| None
+
| None  
| The access element applies only to the subelements 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 is same as described in the JPA specification.  
+
| The access element applies only to the subelements 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 is same as described in the JPA specification.
 
|-
 
|-
| sequence-generator
+
| sequence-generator  
| Full override
+
| Full override  
| A sequence-generator is unique by name. The sequence-generator defined in the EclipseLink-ORM.XML will override a sequence-generator of the same name defined in another mapping file. Outside of the overriding case, an exception is thrown if two or more sequence-generators with the same name are defined in one or across multiple mapping files.  
+
| A sequence-generator is unique by name. The sequence-generator defined in the eclipselink-orm.xml will override a sequence-generator of the same name defined in another mapping file. Outside of the overriding case, an exception is thrown if two or more sequence-generators with the same name are defined in one or across multiple mapping files.
 
|-
 
|-
| table-generator
+
| table-generator  
| Full override
+
| Full override  
| A table-generator is unique by name. The table-generator defined in the EclipseLink-ORM.XML will override a table-generator of the same name defined in another mapping file. Outside of the overriding case, an exception is thrown if two or more table-generators with the same name are defined in one or across multiple mapping files.  
+
| A table-generator is unique by name. The table-generator defined in the eclipselink-orm.xml will override a table-generator of the same name defined in another mapping file. Outside of the overriding case, an exception is thrown if two or more table-generators with the same name are defined in one or across multiple mapping files.
 
|-
 
|-
| named-query
+
| named-query  
| Full override
+
| Full override  
| A named-query is unique by name. The named-query defined in the EclipseLink-ORM.XML will override a named-query of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more named-querys with the same name are defined in one or across multiple mapping file.  
+
| A named-query is unique by name. The named-query defined in the eclipselink-orm.xml will override a named-query of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more named-querys with the same name are defined in one or across multiple mapping file.
 
|-
 
|-
| named-native-query
+
| named-native-query  
| Full override
+
| Full override  
| A named-native-query is unique by name. The named-native-query defined in the EclipseLink-ORM.XML will override a named-native-query of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more named-native-querys with the same name are defined in one or across multiple mapping files.  
+
| A named-native-query is unique by name. The named-native-query defined in the eclipselink-orm.xml will override a named-native-query of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more named-native-querys with the same name are defined in one or across multiple mapping files.
 
|-
 
|-
| sql-result-set-mapping
+
| sql-result-set-mapping  
| Full override
+
| Full override  
| A sql-result-set-mapping is unique by name. The sql-result-set-mapping defined in the EclipseLink-ORM.XML will override a sql-result-set-mapping of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more sql-result-set-mapping entities with the same name are defined in one or across multiple mapping files.  
+
| A sql-result-set-mapping is unique by name. The sql-result-set-mapping defined in the eclipselink-orm.xml will override a sql-result-set-mapping of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more sql-result-set-mapping entities with the same name are defined in one or across multiple mapping files.
 
|}
 
|}
  
===Mapped Superclass===
+
=== Mapped Superclass ===
A mapped-superclass can be defined completely, or with specific elements to provide extensions to a mapped-superclass from another mapping file.  The following table lists individual override and merging rules:
+
  
{|{{BMTableStyle}}
+
A mapped-superclass can be defined completely, or with specific elements to provide extensions to a mapped-superclass from another mapping file. The following table lists individual override and merging rules:
|-{{BMTHStyle}}
+
 
! entity-mappings/mapped-superclass
+
{|
! Rule
+
|-
 +
! entity-mappings/mapped-superclass  
 +
! Rule  
 
! Description
 
! Description
 
|-
 
|-
| id-class
+
| id-class  
| Full override
+
| Full override  
| If an id-class setting exists, then the EclipseLink-ORM.XML's id-class setting overrides the existing setting, or creates a new id-class setting.  
+
| If an id-class setting exists, then the eclipselink-orm.xml's id-class setting overrides the existing setting, or creates a new id-class setting.
 
|-
 
|-
| exclude-default-listeners
+
| exclude-default-listeners  
| Full override
+
| Full override  
| If an exclude-default-listeners setting exists, then the EclipseLink-ORM.XML's exclude-default-listeners setting will be applied. If the exclude-default-listeners setting is not specified, it will not override an existing setting, that is essentially turning it off.
+
| If an exclude-default-listeners setting exists, then the eclipselink-orm.xml's exclude-default-listeners setting will be applied. If the exclude-default-listeners setting is not specified, it will not override an existing setting, that is essentially turning it off.
 
|-
 
|-
| exclude-superclass-listeners
+
| exclude-superclass-listeners  
| Full override
+
| Full override  
| If an exclude-superclass-listeners setting exists, then the EclipseLink-ORM.XML's exclude-superclass-listeners setting will be applied. If exclude-superclass-listeners setting is not specified, it will not override an existing setting, that is essentially turning it off.
+
| If an exclude-superclass-listeners setting exists, then the eclipselink-orm.xml's exclude-superclass-listeners setting will be applied. If exclude-superclass-listeners setting is not specified, it will not override an existing setting, that is essentially turning it off.
 
|-
 
|-
| entity-listeners
+
| entity-listeners  
| Merge and full override
+
| Merge and full override  
| If an entity-listeners setting exists, then the EclipseLink-ORM.XML's entity-listeners setting will override and merge with an existing setting, or creates a new entity-listeners setting all together. <br>{{EclipseLink_Note|note=An entity listener override must be complete. All lifecycle methods of that listener must be specified and no merging of individual lifecycle methods of an entity listener is allowed.  The class name of the listener is the key to identify the override.}}
+
| If an entity-listeners setting exists, then the eclipselink-orm.xml's entity-listeners setting will override and merge with an existing setting, or creates a new entity-listeners setting all together. <br>{{EclipseLink_Note|note=An entity listener override must be complete. All lifecycle methods of that listener must be specified and no merging of individual lifecycle methods of an entity listener is allowed.  The class name of the listener is the key to identify the override.}}
 
|-
 
|-
| pre-persist
+
| pre-persist  
| Full override
+
| Full override  
| If a pre-persist setting exists, then the EclipseLink-ORM.XML's pre-persist setting overrides the existing setting, or creates a new pre-persist setting.  
+
| If a pre-persist setting exists, then the eclipselink-orm.xml's pre-persist setting overrides the existing setting, or creates a new pre-persist setting.
 
|-
 
|-
| post-persist
+
| post-persist  
| Full override
+
| Full override  
| If a post-persist setting exists, then the EclipseLink-ORM.XML's post-persist setting overrides the existing setting, or creates a new post-persist setting.  
+
| If a post-persist setting exists, then the eclipselink-orm.xml's post-persist setting overrides the existing setting, or creates a new post-persist setting.
 
|-
 
|-
| pre-remove
+
| pre-remove  
| Full override
+
| Full override  
| If a pre-remove setting exists, then the EclipseLink-ORM.XML's pre-remove setting overrides the existing setting, or creates a new pre-remove setting.
+
| If a pre-remove setting exists, then the eclipselink-orm.xml's pre-remove setting overrides the existing setting, or creates a new pre-remove setting.
 
|-
 
|-
| post-remove
+
| post-remove  
| Full override
+
| Full override  
| If a post-remove setting exists, then the EclipseLink-ORM.XML's post-remove setting overrides the existing setting, or creates a new post-remove setting.  
+
| If a post-remove setting exists, then the eclipselink-orm.xml's post-remove setting overrides the existing setting, or creates a new post-remove setting.
 
|-
 
|-
| pre-update
+
| pre-update  
| Full override
+
| Full override  
| If a pre-update setting exists, then the EclipseLink-ORM.XML's pre-update setting overrides the existing setting, or creates a new pre-update setting.  
+
| If a pre-update setting exists, then the eclipselink-orm.xml's pre-update setting overrides the existing setting, or creates a new pre-update setting.
 
|-
 
|-
| post-update
+
| post-update  
| Full override
+
| Full override  
| If a post-update setting exists, then the EclipseLink-ORM.XML's post-update setting overrides the existing setting, or creates a new post-update setting.  
+
| If a post-update setting exists, then the eclipselink-orm.xml's post-update setting overrides the existing setting, or creates a new post-update setting.
 
|-
 
|-
| post-load
+
| post-load  
| Full override
+
| Full override  
| If a post-load setting exists, then the EclipseLink-ORM.XML's post-load setting overrides the existing setting, or creates a new post-load setting.
+
| If a post-load setting exists, then the eclipselink-orm.xml's post-load setting overrides the existing setting, or creates a new post-load setting.
 
|-
 
|-
| attributes
+
| attributes  
 
| Merge and mapping level override  
 
| Merge and mapping level override  
| If the attribute settings (id, embedded-id, basic, version, many-to-one, one-to-many, one-to-one, many-to-many, embedded, transient) exist at the mapping level, then the EclipseLink-ORM.XML's attributes merges or overrides the existing settings, else creates new attributes.
+
| If the attribute settings (id, embedded-id, basic, version, many-to-one, one-to-many, one-to-one, many-to-many, embedded, transient) exist at the mapping level, then the eclipselink-orm.xml's attributes merges or overrides the existing settings, else creates new attributes.
 
|-
 
|-
| class
+
| class  
| None
+
| None  
 
|  
 
|  
 
|-
 
|-
| access
+
| access  
| Full override
+
| Full override  
| If an access setting exists, then the EclipseLink-ORM.XML's access setting overrides the existing setting, or creates a new access setting. It also overrides the default class setting.  
+
| If an access setting exists, then the eclipselink-orm.xml's access setting overrides the existing setting, or creates a new access setting. It also overrides the default class setting.
 
|-
 
|-
| metadata-complete
+
| metadata-complete  
| Full override
+
| Full override  
| If a metadata-complete setting exists, then the EclipseLink-ORM.XML's metadata-complete setting will be applied. If metadata-complete setting is not specified, it will not override an existing setting, that is essentially turning it off.
+
| If a metadata-complete setting exists, then the eclipselink-orm.xml's metadata-complete setting will be applied. If metadata-complete setting is not specified, it will not override an existing setting, that is essentially turning it off.
 
|}
 
|}
  
===Entity override and merging rules===
+
=== Entity override and merging rules ===
An entity can be defined completely, or with specific elements to provide extensions to an entity from another mapping file. The following table lists individual override and merging rules: 
+
  
{|{{BMTableStyle}}
+
An entity can be defined completely, or with specific elements to provide extensions to an entity from another mapping file. The following table lists individual override and merging rules:
|-{{BMTHStyle}}
+
 
! entity-mappings/entity
+
{|
! Rule
+
|-
 +
! entity-mappings/entity  
 +
! Rule  
 
! Comments
 
! Comments
 
|-
 
|-
| table
+
| table  
| Full override
+
| Full override  
| The table definition overrides any other table setting (with the same name) for this entity. There is no merging of individual table values.  
+
| The table definition overrides any other table setting (with the same name) for this entity. There is no merging of individual table values.
 
|-
 
|-
| secondary-table
+
| secondary-table  
| Full override
+
| Full override  
| The secondary-table definition overrides another secondary-table setting (with the same name) for this entity. There is no merging of individual secondary-table(s) values.
+
| The secondary-table definition overrides another secondary-table setting (with the same name) for this entity. There is no merging of individual secondary-table(s) values.
 
|-
 
|-
| primary-key-join-column
+
| primary-key-join-column  
| Full override
+
| Full override  
| The primary-key-join-column(s) definition overrides any other primary-key-join-column(s) setting for this entity. There is no merging of the primary-key-join-column(s). The specification is assumed to be complete and these primary-key-join-columns are the source of truth.  
+
| The primary-key-join-column(s) definition overrides any other primary-key-join-column(s) setting for this entity. There is no merging of the primary-key-join-column(s). The specification is assumed to be complete and these primary-key-join-columns are the source of truth.
 
|-
 
|-
| id-class
+
| id-class  
| Full override
+
| Full override  
| If an id-class setting exists, then the EclipseLink-ORM.XML's id-class setting overrides the existing setting, or creates a new id-class setting.  
+
| If an id-class setting exists, then the eclipselink-orm.xml's id-class setting overrides the existing setting, or creates a new id-class setting.
 
|-
 
|-
| inheritance
+
| inheritance  
| Full override
+
| Full override  
| If an inheritance setting exists, then the EclipseLink-ORM.XML's inheritance setting overrides the existing setting, or creates a new inheritance setting.  
+
| If an inheritance setting exists, then the eclipselink-orm.xml's inheritance setting overrides the existing setting, or creates a new inheritance setting.
 
|-
 
|-
| discriminator-value
+
| discriminator-value  
| Full override
+
| Full override  
| If a discriminator-value setting exists, then the EclipseLink-ORM.XML's discriminator-value setting overrides the existing setting, or creates a new discriminator-value setting.  
+
| If a discriminator-value setting exists, then the eclipselink-orm.xml's discriminator-value setting overrides the existing setting, or creates a new discriminator-value setting.
 
|-
 
|-
| discriminator-column
+
| discriminator-column  
| Full override
+
| Full override  
| If a discriminator-column setting exists, then the EclipseLink-ORM.XML's discriminator-column setting overrides the existing setting, or creates a new discriminator-column setting.
+
| If a discriminator-column setting exists, then the eclipselink-orm.xml's discriminator-column setting overrides the existing setting, or creates a new discriminator-column setting.
 
|-
 
|-
| sequence-generator
+
| sequence-generator  
| Full override
+
| Full override  
| A sequence-generator is unique by name. The sequence-generator defined in EclipseLink-ORM.XML overrides sequence-generator of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more sequence-generators with the same name are defined in one or across multiple mapping files.  
+
| A sequence-generator is unique by name. The sequence-generator defined in eclipselink-orm.xml overrides sequence-generator of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more sequence-generators with the same name are defined in one or across multiple mapping files.
 
|-
 
|-
| table-generator
+
| table-generator  
| Full override
+
| Full override  
| A table-generator is unique by name. The table-generator defined in EclipseLink-ORM.XML overrides table-generator of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more table-generators with the same name are defined in one or across multiple mapping files.  
+
| A table-generator is unique by name. The table-generator defined in eclipselink-orm.xml overrides table-generator of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more table-generators with the same name are defined in one or across multiple mapping files.
 
|-
 
|-
| named-query
+
| named-query  
| Merge and full override
+
| Merge and full override  
| A named-query is unique by name. The named-query defined in EclipseLink-ORM.XML overrides named-query of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more named-query elements with the same name are defined in one or across multiple mapping files.  
+
| A named-query is unique by name. The named-query defined in eclipselink-orm.xml overrides named-query of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more named-query elements with the same name are defined in one or across multiple mapping files.
 
|-
 
|-
| named-native-query
+
| named-native-query  
| Merge and full override
+
| Merge and full override  
| A named-native-query is unique by name. The named-native-query defined in EclipseLink-ORM.XML overrides named-native-query of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more named-native-query elements with the same name are defined in one or across multiple mapping files.  
+
| A named-native-query is unique by name. The named-native-query defined in eclipselink-orm.xml overrides named-native-query of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more named-native-query elements with the same name are defined in one or across multiple mapping files.
 
|-
 
|-
| sql-result-set-mapping
+
| sql-result-set-mapping  
| Merge and full override
+
| Merge and full override  
| A sql-result-set-mapping is unique by name. The sql-result-set-mapping defined in EclipseLink-ORM.XML overrides sql-result-set-mapping of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more sql-result-set-mapping elements with the same name are defined in one or across multiple mapping files.  
+
| A sql-result-set-mapping is unique by name. The sql-result-set-mapping defined in eclipselink-orm.xml overrides sql-result-set-mapping of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more sql-result-set-mapping elements with the same name are defined in one or across multiple mapping files.
 
|-
 
|-
| exclude-default-listeners
+
| exclude-default-listeners  
| Full override
+
| Full override  
| If an exclude-default-listeners setting exists, then the EclipseLink-ORM.XML's exclude-default-listeners setting will be applied. If an exclude-default-listeners setting is not specified, it will not override an existing setting, that is essentially turning it off.  
+
| If an exclude-default-listeners setting exists, then the eclipselink-orm.xml's exclude-default-listeners setting will be applied. If an exclude-default-listeners setting is not specified, it will not override an existing setting, that is essentially turning it off.
 
|-
 
|-
| exclude-superclass-listeners
+
| exclude-superclass-listeners  
| Full override
+
| Full override  
| If an exclude-superclass-listeners setting exists, then the EclipseLink-ORM.XML's exclude-superclass-listeners setting will be applied. If an exclude-superclass-listeners setting is not specified, it will not override an existing setting, that is essentially turning it off.
+
| If an exclude-superclass-listeners setting exists, then the eclipselink-orm.xml's exclude-superclass-listeners setting will be applied. If an exclude-superclass-listeners setting is not specified, it will not override an existing setting, that is essentially turning it off.
 
|-
 
|-
| entity-listeners
+
| entity-listeners  
| Full override
+
| Full override  
| If an entity-listeners setting exists, then the EclipseLink-ORM.XML's entity-listeners setting will override and merge with an existing setting, or creates a new entity-listeners setting all together. <br> {{EclipseLink_Note|note=An entity listener override must be complete. All lifecycle methods of that listener must be specified and no merging of individual lifecycle methods of an entity listener is allowed.  The class name of the listener is the key to identify the override.}}
+
| If an entity-listeners setting exists, then the eclipselink-orm.xml's entity-listeners setting will override and merge with an existing setting, or creates a new entity-listeners setting all together. <br> {{EclipseLink_Note|note=An entity listener override must be complete. All lifecycle methods of that listener must be specified and no merging of individual lifecycle methods of an entity listener is allowed.  The class name of the listener is the key to identify the override.}}
 
|-
 
|-
| pre-persist
+
| pre-persist  
| Full override
+
| Full override  
| If a pre-persist setting exists, then the EclipseLink-ORM.XML's pre-persist setting overrides the existing setting, or creates a new pre-persist setting.  
+
| If a pre-persist setting exists, then the eclipselink-orm.xml's pre-persist setting overrides the existing setting, or creates a new pre-persist setting.
 
|-
 
|-
| post-persist
+
| post-persist  
| Full override
+
| Full override  
| If a post-persist setting exists, then the EclipseLink-ORM.XML's post-persist setting overrides the existing setting, or creates a new post-persist setting.  
+
| If a post-persist setting exists, then the eclipselink-orm.xml's post-persist setting overrides the existing setting, or creates a new post-persist setting.
 
|-
 
|-
| pre-remove
+
| pre-remove  
| Full override
+
| Full override  
| If a pre-remove setting exists, then the EclipseLink-ORM.XML's pre-remove setting overrides the existing setting, or creates a new pre-remove setting.
+
| If a pre-remove setting exists, then the eclipselink-orm.xml's pre-remove setting overrides the existing setting, or creates a new pre-remove setting.
 
|-
 
|-
| post-remove
+
| post-remove  
| Full override
+
| Full override  
| If a post-remove setting exists, then the EclipseLink-ORM.XML's post-remove setting overrides the existing setting, or creates a new post-remove setting.  
+
| If a post-remove setting exists, then the eclipselink-orm.xml's post-remove setting overrides the existing setting, or creates a new post-remove setting.
 
|-
 
|-
| pre-update
+
| pre-update  
| Full override
+
| Full override  
| If a pre-update setting exists, then the EclipseLink-ORM.XML's pre-update setting overrides the existing setting, or creates a new pre-update setting.  
+
| If a pre-update setting exists, then the eclipselink-orm.xml's pre-update setting overrides the existing setting, or creates a new pre-update setting.
 
|-
 
|-
| post-update
+
| post-update  
| Full override
+
| Full override  
| If a post-update setting exists, then the EclipseLink-ORM.XML's post-update setting overrides the existing setting, or creates a new post-update setting.  
+
| If a post-update setting exists, then the eclipselink-orm.xml's post-update setting overrides the existing setting, or creates a new post-update setting.
 
|-
 
|-
| post-load
+
| post-load  
| Full override
+
| Full override  
| If a post-load setting exists, then the EclipseLink-ORM.XML's post-load setting overrides the existing setting, or creates a new post-load setting.  
+
| If a post-load setting exists, then the eclipselink-orm.xml's post-load setting overrides the existing setting, or creates a new post-load setting.
 
|-
 
|-
| attributes
+
| attributes  
| Merge and mapping level override
+
| Merge and mapping level override  
| If the attribute settings (id, embedded-id, basic, version, many-to-one, one-to-many, one-to-one, many-to-many, embedded, transient) exist at the mapping level, then the EclipseLink-ORM.XML's attributes merges or overrides the existing settings, else creates new attributes.  
+
| If the attribute settings (id, embedded-id, basic, version, many-to-one, one-to-many, one-to-one, many-to-many, embedded, transient) exist at the mapping level, then the eclipselink-orm.xml's attributes merges or overrides the existing settings, else creates new attributes.
 
|-
 
|-
| association-override
+
| association-override  
| Merge and full override
+
| Merge and full override  
| If an association-override setting exists, then the EclipseLink-ORM.XML's association-override setting overrides the existing setting, or creates a new association-override setting.
+
| If an association-override setting exists, then the eclipselink-orm.xml's association-override setting overrides the existing setting, or creates a new association-override setting.
 
|-
 
|-
| name
+
| name  
| Full override
+
| Full override  
| If a name setting exists, then the EclipseLink-ORM.XML's name setting overrides the existing setting, or creates a new name setting.  
+
| If a name setting exists, then the eclipselink-orm.xml's name setting overrides the existing setting, or creates a new name setting.
 
|-
 
|-
| class
+
| class  
| None
+
| None  
 
|  
 
|  
 
|-
 
|-
| access
+
| access  
| Full override
+
| Full override  
| If an access setting exists, then the EclipseLink-ORM.XML's access setting overrides the existing setting, or creates a new access setting. It also overrides the default class setting.  
+
| If an access setting exists, then the eclipselink-orm.xml's access setting overrides the existing setting, or creates a new access setting. It also overrides the default class setting.
 
|-
 
|-
| metadata-complete
+
| metadata-complete  
| Full override
+
| Full override  
| If a metadata-complete setting exists, then the EclipseLink-ORM.XML's metadata-complete setting will be applied. If a metadata-complete setting is not specified, it will not override an existing setting, that is essentially turning it off.  
+
| If a metadata-complete setting exists, then the eclipselink-orm.xml's metadata-complete setting will be applied. If a metadata-complete setting is not specified, it will not override an existing setting, that is essentially turning it off.
 
|}
 
|}
  
===Embeddable===
+
=== Embeddable ===
 +
 
 
An embeddable can be defined wholely or may be defined so as to provide extensions to an embeddeable from another mapping file. Therefore, we will allow the merging of that classes metadata. The individual override rules for that metadata is tabled below.  
 
An embeddable can be defined wholely or may be defined so as to provide extensions to an embeddeable from another mapping file. Therefore, we will allow the merging of that classes metadata. The individual override rules for that metadata is tabled below.  
  
{|{{BMTableStyle}}
+
{|
|-{{BMTHStyle}}
+
|-
! entity-mappings/embeddable
+
! entity-mappings/embeddable  
! Rule
+
! Rule  
 
! Description
 
! Description
 
|-
 
|-
| attributes
+
| attributes  
| Override and merge
+
| Override and merge  
| If the attribute settings (id, embedded-id, basic, version, many-to-one, one-to-many, one-to-one, many-to-many, embedded, transient) exist at the mapping level, then the EclipseLink-ORM.XML's attributes merges or overrides the existing settings, or creates new attributes.  
+
| If the attribute settings (id, embedded-id, basic, version, many-to-one, one-to-many, one-to-one, many-to-many, embedded, transient) exist at the mapping level, then the eclipselink-orm.xml's attributes merges or overrides the existing settings, or creates new attributes.
 
|-
 
|-
| class
+
| class  
| None
+
| None  
 
|  
 
|  
 
|-
 
|-
| access
+
| access  
| Full override
+
| Full override  
| If an access setting exists, then the EclipseLink-ORM.XML's access setting overrides the existing setting, or creates a new access setting. It also overrides the default class setting.  
+
| If an access setting exists, then the eclipselink-orm.xml's access setting overrides the existing setting, or creates a new access setting. It also overrides the default class setting.
 
|-
 
|-
| metadata-complete
+
| metadata-complete  
| Full override
+
| Full override  
| If a metadata-complete setting exists, then the EclipseLink-ORM.XML's metadata-complete setting will be applied. If a metadata-complete setting is not specified, it will not override an existing setting, that is essentially turning it off.
+
| If a metadata-complete setting exists, then the eclipselink-orm.xml's metadata-complete setting will be applied. If a metadata-complete setting is not specified, it will not override an existing setting, that is essentially turning it off.
 
|}
 
|}
  
 
+
<br>
  
 
{{EclipseLink_JPA
 
{{EclipseLink_JPA

Revision as of 14:11, 21 March 2011

EclipseLink JPA

link="http://wiki.eclipse.org/EclipseLink"
EclipseLink
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source


Overriding and Merging XML

You can use EclipseLink’s native metadata xml file, eclipselink-orm.xml, to override mappings defined in JPA’s configuration file orm.xml and provide EclipseLink with extended ORM features.
Elug javaspec icon.gif

For more information, see Section 12.2 "XML Overriding Rules" in the JPA Specification.

When both orm.xml and eclipselink-orm.xml are specified in a project, the contents of eclipselink-orm.xml override orm.xml and any other JPA mapping file specified in the persistence unit. If there are overlapping specifications in multiple ORM files, the files are merged if there are no conflicting entities.

Elug note icon.png

Note: The order of files defined in persistence.xml does not define the order of their processing. The files are processed, merged, and overidden as required. For more information, see Overriding and Merging Examples.

The eclipselink-orm.xml file can be referenced for inclusion in a persistence unit’s metadata through any of the following files or methods:

File/Method Description
META-INF/eclipselink-orm.xml Provides mapping overriding capabilities.
META-INF/orm.xml The default ORM file provided with JPA.
Referenced as persistence unit mapping file in persistence.xml Does not provide mapping overriding capability, but can be used for merging mapping files.

Overriding and Merging Examples

Example 1

  • META-INF/orm.xml - defines Entity A with the mappings b and c.
  • META-INF/eclipselink-orm.xml - defines Entity A with the mappings for c and d.
  • Result - Entity A will contain the mapping b (from orm.xml), mapping c and d (from eclipselink-orm.xml)

Example 2

  • META-INF/orm.xml - defines Entity A with the mappings b and c
  • META-INF/some-other-mapping-file.xml - defines Entity B with mappings a and b
  • META-INF/eclipselink-orm.xml - defines Entity A with the mappings for c and d and Entity B with the mapping b and c
  • Result
    • Entity A will contain the mapping b (from orm.xml), mapping c and d (from eclipselink-orm.xml)
    • Entity B will contain the mapping a (from some-other-mapping-file), mappings b and c (from eclipselink-orm.xml)

Example 3

  • META-INF/orm.xml - defines Entity A with the mappings b and c.
  • META-INF/eclipselink-orm.xml - defines Entity A with the mappings c and d.
  • META-INF/some-other-mapping-file.xml - defines Entity A with the mapping x.
  • Result - Entity A will contain the mapping b (from orm.xml), mapping c and d (from eclipselink-orm.xml) and mapping x (from some-other-mapping-file)

Example 4

  • META-INF/orm.xml - defines Entity A with the mappings b and c.
  • META-INF/extensions/eclipselink-orm.xml - defines defines Entity A with the mappings c and d.
    Note: This file is added through a <mapping-file> tag in the persistence.xml
  • Result - Exception generated for conficting specifications for mapping c.

Example 5

  • META-INF/orm.xml - defines Entity A with the mappings b and c.
  • META-INF/jpa-mapping-file.xml - defines Entity A with the mappings a and d.
  • META-INF/extensions/eclipse-mapping-file.xml - defines defines Entity A with the mappings c and d.
  • Result - Exception generated for conficting specifications for mapping c or d (which ever is processed first).

Overriding and Merging Rules

The following sections outlines elements defined in orm.xml and their specific overriding in greater detail.

Persistence Unit Metadata

In eclipselink-orm.xml, a persistence-unit-metadata specification merges or overrides the values of existing persistence-unit-metadata specification.

entity-mappings/persistence-unit-metadata Rule Description
xml-mapping-metadata-complete Full override If specified, 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 If a schema setting exists, then the eclipselink-orm.xml's schema setting overrides the existing setting, or creates a new schema setting.
persistence-unit-defaults/catalog Full override If a catalog setting exists, then the eclipselink-orm.xml's catalog setting overrides the existing setting, or creates a new catalog setting
persistence-unit-defaults/access Full override If an access setting exists, then the eclipselink-orm.xml's access setting overrides the existing setting, or creates a new access setting.
entity-mappings/persistence-unit-metadata/persistence-unit-defaults/cascade-persist Full override If a cascade-persist setting exists, then the eclipselink-orm.xml's cascade-persist setting overrides the existing setting, or creates a new cascade-persist setting.
entity-mappings/persistence-unit-metadata/persistence-unit-defaults/entity-listeners Merge If an entity-listeners exists, then the eclipselink-orm.xml's entity-listeners will be merged with the list of all entity-listeners from the persistence unit.

Entity Mappings

Entities, embeddables and mapped superclasses are defined within entity-mappings. eclipselink-orm.xml's entities, embeddables and mapped superclasses are added to the persistence unit. The following table describes the top-level elements of the entity-mappings sections:

entity-mappings/ Rule Description
package None The package element specifies the package of the classes listed within the subelements and attributes of the same mapping file only. It is only applicable to those entities that are fully defined within the eclipselink-orm.xml file, else its usage remains local and is same as described in the JPA specification.
catalog None The catalog element applies only to the subelements 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 is same as described in the JPA specification.
schema None The schema element applies only to the subelements 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 is same as described in the JPA specification.
access None The access element applies only to the subelements 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 is same as described in the JPA specification.
sequence-generator Full override A sequence-generator is unique by name. The sequence-generator defined in the eclipselink-orm.xml will override a sequence-generator of the same name defined in another mapping file. Outside of the overriding case, an exception is thrown if two or more sequence-generators with the same name are defined in one or across multiple mapping files.
table-generator Full override A table-generator is unique by name. The table-generator defined in the eclipselink-orm.xml will override a table-generator of the same name defined in another mapping file. Outside of the overriding case, an exception is thrown if two or more table-generators with the same name are defined in one or across multiple mapping files.
named-query Full override A named-query is unique by name. The named-query defined in the eclipselink-orm.xml will override a named-query of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more named-querys with the same name are defined in one or across multiple mapping file.
named-native-query Full override A named-native-query is unique by name. The named-native-query defined in the eclipselink-orm.xml will override a named-native-query of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more named-native-querys with the same name are defined in one or across multiple mapping files.
sql-result-set-mapping Full override A sql-result-set-mapping is unique by name. The sql-result-set-mapping defined in the eclipselink-orm.xml will override a sql-result-set-mapping of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more sql-result-set-mapping entities with the same name are defined in one or across multiple mapping files.

Mapped Superclass

A mapped-superclass can be defined completely, or with specific elements to provide extensions to a mapped-superclass from another mapping file. The following table lists individual override and merging rules:

entity-mappings/mapped-superclass Rule Description
id-class Full override If an id-class setting exists, then the eclipselink-orm.xml's id-class setting overrides the existing setting, or creates a new id-class setting.
exclude-default-listeners Full override If an exclude-default-listeners setting exists, then the eclipselink-orm.xml's exclude-default-listeners setting will be applied. If the exclude-default-listeners setting is not specified, it will not override an existing setting, that is essentially turning it off.
exclude-superclass-listeners Full override If an exclude-superclass-listeners setting exists, then the eclipselink-orm.xml's exclude-superclass-listeners setting will be applied. If exclude-superclass-listeners setting is not specified, it will not override an existing setting, that is essentially turning it off.
entity-listeners Merge and full override If an entity-listeners setting exists, then the eclipselink-orm.xml's entity-listeners setting will override and merge with an existing setting, or creates a new entity-listeners setting all together.

Elug note icon.png

Note: An entity listener override must be complete. All lifecycle methods of that listener must be specified and no merging of individual lifecycle methods of an entity listener is allowed. The class name of the listener is the key to identify the override.

pre-persist Full override If a pre-persist setting exists, then the eclipselink-orm.xml's pre-persist setting overrides the existing setting, or creates a new pre-persist setting.
post-persist Full override If a post-persist setting exists, then the eclipselink-orm.xml's post-persist setting overrides the existing setting, or creates a new post-persist setting.
pre-remove Full override If a pre-remove setting exists, then the eclipselink-orm.xml's pre-remove setting overrides the existing setting, or creates a new pre-remove setting.
post-remove Full override If a post-remove setting exists, then the eclipselink-orm.xml's post-remove setting overrides the existing setting, or creates a new post-remove setting.
pre-update Full override If a pre-update setting exists, then the eclipselink-orm.xml's pre-update setting overrides the existing setting, or creates a new pre-update setting.
post-update Full override If a post-update setting exists, then the eclipselink-orm.xml's post-update setting overrides the existing setting, or creates a new post-update setting.
post-load Full override If a post-load setting exists, then the eclipselink-orm.xml's post-load setting overrides the existing setting, or creates a new post-load setting.
attributes Merge and mapping level override If the attribute settings (id, embedded-id, basic, version, many-to-one, one-to-many, one-to-one, many-to-many, embedded, transient) exist at the mapping level, then the eclipselink-orm.xml's attributes merges or overrides the existing settings, else creates new attributes.
class None
access Full override If an access setting exists, then the eclipselink-orm.xml's access setting overrides the existing setting, or creates a new access setting. It also overrides the default class setting.
metadata-complete Full override If a metadata-complete setting exists, then the eclipselink-orm.xml's metadata-complete setting will be applied. If metadata-complete setting is not specified, it will not override an existing setting, that is essentially turning it off.

Entity override and merging rules

An entity can be defined completely, or with specific elements to provide extensions to an entity from another mapping file. The following table lists individual override and merging rules:

entity-mappings/entity Rule Comments
table Full override The table definition overrides any other table setting (with the same name) for this entity. There is no merging of individual table values.
secondary-table Full override The secondary-table definition overrides another secondary-table setting (with the same name) for this entity. There is no merging of individual secondary-table(s) values.
primary-key-join-column Full override The primary-key-join-column(s) definition overrides any other primary-key-join-column(s) setting for this entity. There is no merging of the primary-key-join-column(s). The specification is assumed to be complete and these primary-key-join-columns are the source of truth.
id-class Full override If an id-class setting exists, then the eclipselink-orm.xml's id-class setting overrides the existing setting, or creates a new id-class setting.
inheritance Full override If an inheritance setting exists, then the eclipselink-orm.xml's inheritance setting overrides the existing setting, or creates a new inheritance setting.
discriminator-value Full override If a discriminator-value setting exists, then the eclipselink-orm.xml's discriminator-value setting overrides the existing setting, or creates a new discriminator-value setting.
discriminator-column Full override If a discriminator-column setting exists, then the eclipselink-orm.xml's discriminator-column setting overrides the existing setting, or creates a new discriminator-column setting.
sequence-generator Full override A sequence-generator is unique by name. The sequence-generator defined in eclipselink-orm.xml overrides sequence-generator of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more sequence-generators with the same name are defined in one or across multiple mapping files.
table-generator Full override A table-generator is unique by name. The table-generator defined in eclipselink-orm.xml overrides table-generator of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more table-generators with the same name are defined in one or across multiple mapping files.
named-query Merge and full override A named-query is unique by name. The named-query defined in eclipselink-orm.xml overrides named-query of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more named-query elements with the same name are defined in one or across multiple mapping files.
named-native-query Merge and full override A named-native-query is unique by name. The named-native-query defined in eclipselink-orm.xml overrides named-native-query of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more named-native-query elements with the same name are defined in one or across multiple mapping files.
sql-result-set-mapping Merge and full override A sql-result-set-mapping is unique by name. The sql-result-set-mapping defined in eclipselink-orm.xml overrides sql-result-set-mapping of the same name defined in other mapping files. Outside of the overriding case, an exception is thrown if two or more sql-result-set-mapping elements with the same name are defined in one or across multiple mapping files.
exclude-default-listeners Full override If an exclude-default-listeners setting exists, then the eclipselink-orm.xml's exclude-default-listeners setting will be applied. If an exclude-default-listeners setting is not specified, it will not override an existing setting, that is essentially turning it off.
exclude-superclass-listeners Full override If an exclude-superclass-listeners setting exists, then the eclipselink-orm.xml's exclude-superclass-listeners setting will be applied. If an exclude-superclass-listeners setting is not specified, it will not override an existing setting, that is essentially turning it off.
entity-listeners Full override If an entity-listeners setting exists, then the eclipselink-orm.xml's entity-listeners setting will override and merge with an existing setting, or creates a new entity-listeners setting all together.

Elug note icon.png

Note: An entity listener override must be complete. All lifecycle methods of that listener must be specified and no merging of individual lifecycle methods of an entity listener is allowed. The class name of the listener is the key to identify the override.

pre-persist Full override If a pre-persist setting exists, then the eclipselink-orm.xml's pre-persist setting overrides the existing setting, or creates a new pre-persist setting.
post-persist Full override If a post-persist setting exists, then the eclipselink-orm.xml's post-persist setting overrides the existing setting, or creates a new post-persist setting.
pre-remove Full override If a pre-remove setting exists, then the eclipselink-orm.xml's pre-remove setting overrides the existing setting, or creates a new pre-remove setting.
post-remove Full override If a post-remove setting exists, then the eclipselink-orm.xml's post-remove setting overrides the existing setting, or creates a new post-remove setting.
pre-update Full override If a pre-update setting exists, then the eclipselink-orm.xml's pre-update setting overrides the existing setting, or creates a new pre-update setting.
post-update Full override If a post-update setting exists, then the eclipselink-orm.xml's post-update setting overrides the existing setting, or creates a new post-update setting.
post-load Full override If a post-load setting exists, then the eclipselink-orm.xml's post-load setting overrides the existing setting, or creates a new post-load setting.
attributes Merge and mapping level override If the attribute settings (id, embedded-id, basic, version, many-to-one, one-to-many, one-to-one, many-to-many, embedded, transient) exist at the mapping level, then the eclipselink-orm.xml's attributes merges or overrides the existing settings, else creates new attributes.
association-override Merge and full override If an association-override setting exists, then the eclipselink-orm.xml's association-override setting overrides the existing setting, or creates a new association-override setting.
name Full override If a name setting exists, then the eclipselink-orm.xml's name setting overrides the existing setting, or creates a new name setting.
class None
access Full override If an access setting exists, then the eclipselink-orm.xml's access setting overrides the existing setting, or creates a new access setting. It also overrides the default class setting.
metadata-complete Full override If a metadata-complete setting exists, then the eclipselink-orm.xml's metadata-complete setting will be applied. If a metadata-complete setting is not specified, it will not override an existing setting, that is essentially turning it off.

Embeddable

An embeddable can be defined wholely or may be defined so as to provide extensions to an embeddeable from another mapping file. Therefore, we will allow the merging of that classes metadata. The individual override rules for that metadata is tabled below.

entity-mappings/embeddable Rule Description
attributes Override and merge If the attribute settings (id, embedded-id, basic, version, many-to-one, one-to-many, one-to-one, many-to-many, embedded, transient) exist at the mapping level, then the eclipselink-orm.xml's attributes merges or overrides the existing settings, or creates new attributes.
class None
access Full override If an access setting exists, then the eclipselink-orm.xml's access setting overrides the existing setting, or creates a new access setting. It also overrides the default class setting.
metadata-complete Full override If a metadata-complete setting exists, then the eclipselink-orm.xml's metadata-complete setting will be applied. If a metadata-complete setting is not specified, it will not override an existing setting, that is essentially turning it off.


Eclipselink-logo.gif
Version: 2.2.0 DRAFT
Other versions...