View source for EclipseLink/Examples/JPA/EclipseLink-ORM.XML

[[Category:EclipseLink/Example/JPA|EclipseLink-ORM.XML]]
{{EclipseLink_DocWiki|link=EclipseLink/UserGuide/JPA/Basic_JPA_Development/Configuration/JPA/eclipselink-orm.xml}}EclipseLink supports an extended JPA orm.xml mapping configuration file called '''eclipselink-orm.xml'''. This mapping file can be used in place of JPA's standard mapping file or can be used to override a JPA mapping file. In additional to allowing all of the standard JPA mapping capabilities it also includes advanced mapping types and options.


'''Note: Usage of this mapping file will enable many advanced features but may prevent the persistence unit from being portable to other JPA implementations'''

== XML Configuration ==

The [http://www.eclipse.org/eclipselink/xsds/eclipselink_orm_2_1.xsd EclipseLink ORM schema (eclipselink_orm_2_1.xsd)] can be used with the following header to define JPA and EclipseLink's advanced mappings.

<source lang="xml">
<?xml version="1.0"?>
<entity-mappings
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/orm"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.eclipse.org/eclipselink/xsds/persistence/orm http://www.eclipse.org/eclipselink/xsds/eclipselink_orm_2_1.xsd"
	version="2.1">
</entity-mappings>
</source>

EclipseLink automatically resolves the xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/orm" to its internally packages schema. The following header will not cause the parser to attempt to access the XSD from the web. Using this however will require you to add the eclipselink_orm_2_0.xsd to your IDE's catalog in order to have XML completion available.

<source lang="xml">
<?xml version="1.0"?>
<entity-mappings
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/orm"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	version="2.1">
</entity-mappings>
</source>

== Configuring usage in persistence.xml ==

A persistence unit can use one or more of these mapping files in the same way a standard JPA ORM mapping XML file can be used. The default location of <code>/META-INF/orm.xml</code> will automatically be picked up and used by any persistence unit. 

If you want to use a different name for this mapping file or provide multiple mapping files they must be listed in the peristence.xml as:

<source lang="xml">
<mapping-file>META-INF/additional-orm.xml</mapping-file>
</source>

== Employee JPA Example using eclipselink-orm.xml ==

The [[EclipseLink/Examples/JPA/EmployeeXML | Employee JPA Example using XML]] illustrates how XML can be used exclusively (no annotations) to configure JPA usage. This example includes the usage of this EclipseLink specific JPA mapping XML file (see Employee example [http://dev.eclipse.org/svnroot/rt/org.eclipse.persistence/trunk/examples/org.eclipse.persistence.example.jpa.employee.xml/src/META-INF/eclipselink-orm.xml eclipselink-orm.xml]).

= EclipseLink ORM Features =

In addition to supporting all capabilities of JPA's orm.xml mapping file with similarly named elements and attributes the EclipseLink mapping file also offers many additional configuration capabilities.


== <entity-mappings> ==

Within the entity-mappings section of the mapping file EclipseLink supports additional configurations applicable to the persistence unit and all mapped entities.

===<exclude-default-mappings/>===

Within the persistence-unit-metadata section of JPA's orm.xml there is support for indicating <xml-mapping-metadata-complete/>. This indicates that the mappings provided are complete and no additional annotation processing should be performed for the entities mapped in this file. It does not however prevent the JPA provider from automatically mapping additional attributes that exist on the class but are not mapped. To avoid having additional attributes auto-mapped EclipseLink supports this additional configuration.

<source lang="xml">
<persistence-unit-metadata>
	<xml-mapping-metadata-complete/>
	<exclude-default-mappings/>
</persistence-unit-metadata>
</source>

===<access> and <access-methods>===

In addition to supporting FIELD and PROPERTY access EclipseLink also supports VIRTUAL. The VIRTUAL access types is generally used with [[EclipseLink/Examples/JPA/DynamicPersistence | Dynamic Persistence]] so that generic get/set or get/put access methods can be used. With VIRTUAL access the methods additionally take the attribute name as their first parameter.

The <access-methods> allows default access methods names to be specified. This is generally only used with Dynamic Persistence but could be applied to any attribute where map style access is used instead of direct access to the field or a pair of property specific access methods.

Both of these configurations can be made within the entity-mappings section of the document to apply to all of the mappings in this file or can be specified to be the default for the entire persistence unit.

<source lang="xml">
<persistence-unit-metadata>
	<xml-mapping-metadata-complete/>
	<exclude-default-mappings/>
	<persistence-unit-defaults>
		<access>VIRTUAL</access>
		<access-methods set-method="get" get-method="set"/>
	</persistence-unit-defaults>
</persistence-unit-metadata>
</source>

=== Converters ===
====<converter>====
====<type-converter>====
{{EclipseLink_DocWiki
|link=EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters/ObjectTypeConverter
}}
====<object-type-converter>====
<source lang="xml">
<object-type-converter name="gender-converter"
	object-type="model.Gender" data-type="java.lang.String">
	<conversion-value object-value="Male" data-value="M" />
	<conversion-value object-value="Female" data-value="F" />
</object-type-converter>
</source>

====<struct-converter>====

===<named-stored-procedure-query>===

== Entity Features ==

* [[#.3Caccess.3E_and_.3Caccess-methods.3E|<access-methods>]]

=== <customizer> ===

A DescriptorCustomizer can be configured for an entity which will cause the provided customizer class to be invoked after the metadata is processed but before the persistence context (Server Session) is intialized.

=== <change-tracking> ===

: Change Tracking Type Values
* ATTRIBUTE
* OBJECT
* DEFERRED
* AUTO (default)

===<primary-key>===
The PrimaryKey annotation allows advanced configuration of the Id. A validation policy can be given that allows specifying if zero is a valid id value. The set of primary key columns can also be specified precisely.

===<class-extractor>===
A ClassExtractor allows for a user defined class indicator in place of providing a discriminator column. The class has the following restrictions:

* It must extend the org.eclipse.persistence.descriptors.ClassExtractor class and implement the extractClassFromRow(Record, Session) method. 
* That method must take a database row (a Record/Map) as an argument and must return the class to use for that row. 

This method will be used to decide which class to instantiate when reading from the database. It is the application's responsibility to populate any typing information in the database required to determine the class from the row.

The ClassExtractor must only be set on the root of an entity class or sub-hierarchy in which a different inheritance strategy is applied. The ClassExtractor can only be used with the SINGLE_TABLE and JOINED inheritance 

===<optimistic-locking>===

=== Cache Configuration ===
{{EclipseLink_DocWiki|link=EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Type_and_Size}}EclipseLink's caching can be configured 

==== <cache> ====

<source lang="xml">
<cache type="SOFT_WEAK" 
	   size="1000" 
	   shared="true"
	   always-refresh="false" 
	   refresh-only-if-newer="true" 
	   disable-hits="false" 
	   coordination-type="INVALIDATE_CHANGED_OBJECTS">
	<expiry-time-of-day hour="0" minute="0" />
</cache>
</source>

:Cache Type Values
* FULL
* WEAK
* SOFT
* SOFT_WEAK (default)
* HARD_WEAK
* CACHE
* NONE

:Coordination Values
* SEND_OBJECT_CHANGES (default)
* INVALIDATE_CHANGED_OBJECTS
* SEND_NEW_OBJECTS_WITH_CHANGES
* NONE
:''Note: Cache Coordination configuration on individual entities is only used when Cache Coordination is enabled for the persistence unit.

==== <cache-interceptor> ====

===<fetch-group>===
TODO

===Converters===
Converters can also be configured within an <entity> in the same way they are supported within <entity-mappings>. [[#Converters]]

===<copy-policy>===
TODO

===<instantiation-copy-policy>===
TODO

===<clone-copy-policy>===
TODO

===<named-stored-procedure-query>===
A named stored procedure query can be defined within <entity> in the same way it is with <entity-mappings>. The name of the query is still global to the persistence unit.

===<query-redirectors>===
TODO

===<property>===
TODO?

===<parent-class>===
TODO

===<read-only>===
TODO

===<existence-checking>===
TODO

===<exclude-default-mappings>===

===<embeddable> Type===
* <access-methods>
* <customizer>
* <change-tracking>
* Converters
*: Converters can also be configured within an <embeddable> in the same way they are supported within <entity-mappings>. ([[#Converters|see Converters]])
* <copy-policy>
* <instantiation-copy-policy>
* <clone-copy-policy>
* <property>
* <exclude-default-mappings>

== Mappings: <attributes> ==

Within the <attributes> section of <entity> mappings can be configured. The following are the EclipseLink ORM extensions.

===<basic>===

Within the <basic> mapping the following additional options are supported:

* <convert>
* <mutable>
* <attribute-type>
*: By default EclipseLink will look at the class to determine the attribute type. In some cases a user may want to force a different type to be used if the class define attribute is too generic or in the case of VIRTUAL access where no attribute exists to get the type from the type must be provided. If this is specified it will be trusted during metadata processing and may only fail at runtime if the type specified and the actual type of the field or access methods is not compatible.

===<basic-collection>===
TODO - deprecated

===<basic-map>===
TODO - deprecated

===<variable-one-to-one>===
TODO

===<transformation>===
TODO - recommend converters

=== <element-collection>===

The <element-collection> mapping can be extended with the following options:

*<map-key-convert>====
*<map-key-association-override>====
*<convert>
*:can be specified within the <element-collection>'s <column> to specify a converter that should be used on all element values.
*<join-fetch>
*<batch-fetch>
*<property>
*<access-methods>
*<attribute-type>

===<embedded> Mapping===
* <property>
* <access-methods>
* <attribute-type>

===<embedded-id>===
====<property>====
====<access-methods>====
====<attribute-type>====

===<id> Mapping===
*<convert>
*<property>
*<access-methods>
*<mutable>
*<attribute-type>

===<many-to-many>===
*<map-key-convert>
*<map-key-association-override>
*Converters
*:Converters can be defined within a mapping in the same way they can be defined in <entity-mappings>. The name of the converter is global to the persistence unit. - ([[#Converters|see Converters]])
<join-fetch>
<batch-fetch>
<property>
<access-methods>
<attribute-type>

===<many-to-one> Mapping ===
* <join-fetch>
* <batch-fetch>
* <property>
* <access-methods>



===<one-to-many> Mapping===
*<map-key-convert>
*<map-key-association-override>
*Converters
*:Converters can be defined within a mapping in the same way they can be defined in <entity-mappings>. The name of the converter is global to the persistence unit. - ([[#Converters|see Converters]])
*<private-owned>
*<join-fetch>
*<batch-fetch>
*<property>
*<access-methods>
*<attribute-type>

===<one-to-one> Mapping===

The 1:1 mapping configured in the <one-to-one> element has the additional ability to configure:
*<private-owned>
*<join-fetch>
*<batch-fetch>
*<property>
*<access-methods>

===<version> Mapping ===
*Converters
*:Converters can be defined within a mapping in the same way they can be defined in <entity-mappings>. The name of the converter is global to the persistence unit. - ([[#Converters|see Converters]])
*<property>
*<access-methods>
*<mutable>
*<attribute-type>

===<mapped-superclass>===
* <access-methods>
* <customizer>
* <change-tracking>
* <primary-key>
* <optimistic-locking>
* <cache>
* <cache-interceptor>
* <fetch-group>
* Converters
*:Converters can be defined within a mapped superclass in the same way they can be defined in <entity-mappings>. The name of the converter is global to the persistence unit. - ([[#Converters|see Converters]])
* <copy-policy>
* <instantiation-copy-policy>
* <clone-copy-policy>
* <named-stored-procedure-query>
* <query-redirectors>
* <property>
* <attribute-override>
* <association-override>
* <parent-class>
* <cacheable>
* <read-only>
* <existence-checking>
* <exclude-default-mappings/>