Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/JPA/Advanced JPA Development/External Mappings"

m
m
 
(5 intermediate revisions by one other user not shown)
Line 1: Line 1:
{{EclipseLink_UserGuide
+
----
 +
 
 +
 
 +
'''[[Image:Elug_draft_icon.png|Warning]] This page is now obsolete. '''
 +
 
 +
For current information, please see "Using an External MetaData Source" in the ''EclipseLink Solutions Guide'':
 +
http://www.eclipse.org/eclipselink/documentation/latest/solutions/metadatasource.htm
 +
 
 +
 
 +
----
 +
 
 +
 
 +
{{EclipseLink_UserGuide  
 
|info=y
 
|info=y
 
|toc=n
 
|toc=n
 +
|eclipselink=y
 +
|eclipselinktype=JPA
 
|api=y
 
|api=y
 
|apis=
 
|apis=
*[http://www.eclipse.org/eclipselink/api/2.3/org/eclipse/persistence/xxx.html xxx]
+
* [[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/jpa/metadata/MetadataSource.html| MetadataSource]]
 +
* [[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/PersistenceUnitProperties.html#METADATA_SOURCE| METADATA_SOURCE]]
 +
* [[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/PersistenceUnitProperties.html#METADATA_SOURCE_XML_FILE| METADATA_SOURCE_XML_FILE]]
 +
* [[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/PersistenceUnitProperties.html#METADATA_SOURCE_XML_URL| METADATA_SOURCE_XML_URL]]
 
|examples=y
 
|examples=y
 
|example=
 
|example=
 +
*[[EclipseLink/Examples/JPA/Extensibility|Extensible Entities]]
 +
*[[EclipseLink/Examples/MySports|MySports Example]]
 
*[[EclipseLink/Examples/JPA/MetadataSource|MetadataSource]]
 
*[[EclipseLink/Examples/JPA/MetadataSource|MetadataSource]]
}}  
+
}}
  
= Externalized Mappings =
+
''This page has not yet been reviewed''
  
 +
= External Mappings=
  
''This feature is new in EclipseLink 2.3.''
+
{{EclipseLink_NewIn
 +
|version=2.3}}
 +
<br>
 +
<br>
  
''This page is under development.''
+
You can store mapping information using a metadata source external to the running application. This allows you to dynamically integrate mapping overrides and extended mappings into deployed applications. The mapping information is retrieved when the application's persistence unit is being created. This feature can be used for any mapping customization including [[EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Extensible_Entities| Extensible JPA Entities]].
  
You can store mappings using a <tt>MetadataSource</tt> external to the running application so that mapping overrides and extended mappings can be more dynamically integrated into deployed applications.
+
To configure external mapping, you must:
  
{{EclipseLink_JPA
+
# [[# Configuring the Persistence Unit|Configure the client persistence unit]]
|up=     [[EclipseLink/UserGuide/JPA/Advanced_JPA_Development|Advanced JPA Development]]
+
# [[# Configuring the Server|Configure the server]]
}}
+
 
 +
== Configuring the Persistence Unit ==
 +
 
 +
The simplest way to store mappings externally is to make the <tt>eclipselink-orm.xml</tt> file with the additional mapping information available on a Web server as a file. A more \complex way is to establish a server process that stores the mapping information and supports dynamically updating this information.
 +
 
 +
=== Accessing a Mapping File at a Fixed URL ===
 +
 
 +
To access an external mapping file at a fixed URL for a persistence unit, use the <tt>eclipselink.metadata-source</tt> and <tt>eclipselink.metadata-source.xml</tt> properties, for example:
 +
 
 +
<source lang="xml">
 +
<property name="eclipselink.metadata-source" value="XML"/>
 +
<property name="eclipselink.metadata-source.xml.url" value="foo://bar"/>
 +
</source>
 +
 
 +
=== Mapping a Location Based on the Application Context ===
 +
 
 +
For more complex requirement, for example, to provide tenant-specific extensions in a multi-tenant application, you can specify the location of the mapping information based on application context. To do so, implement the <tt>MetadataSource</tt> interface, and set the properties as follows:
 +
 
 +
<source lang="xml">
 +
<property name="eclipselink.metadata-source" value="mypackage.MyMetadataSource"/>
 +
<property name="eclipselink.metadata-source.xml.url" value="foo://bar"/>
 +
</source>
 +
 
 +
In the following example, (from the the [[http://wiki.eclipse.org/EclipseLink/Examples/MySports MySports]] example application), a JAX-RS (RESTful) service is built that returns the mapping file per tenant:
 +
 
 +
<source lang="java">
 +
public class AdminMetadataSource extends XMLMetadataSource {
 +
 
 +
    @Override
 +
    public XMLEntityMappings getEntityMappings(Map<String, Object> properties, ClassLoader classLoader, SessionLog log) {
 +
        String leagueId = (String) properties.get(LEAGUE_CONTEXT);
 +
        properties.put(PersistenceUnitProperties.METADATA_SOURCE_XML_URL, "http://foo.bar/rest/" + leagueId + "/orm");
 +
        return super.getEntityMappings(properties, classLoader, log);
 +
    }
 +
}
 +
</source>
 +
 
 +
==Configuring the Server ==
 +
 
 +
The server must provide URL access to a mapping file. This can be done using a number of Web technologies, including:
 +
* Static file serving
 +
* Server-based solution with its own persistent store of XML files or mapping information stored in a granular form and put together into mapping documents on demand
 +
 
 +
See the [[http://wiki.eclipse.org/EclipseLink/Examples/MySports MySports]] example application for an implementation of a JAX-RS based solution. The mapping extensions are stored as separate JPA entities and combined together on demand to create a tenant-specific mapping override file with that tenant's extension mappings.
 +
 
 +
'''''//Expand this section with actual instructions and examples//'''''

Latest revision as of 07:05, 17 April 2013



Warning This page is now obsolete.

For current information, please see "Using an External MetaData Source" in the EclipseLink Solutions Guide: http://www.eclipse.org/eclipselink/documentation/latest/solutions/metadatasource.htm




EclipseLink JPA


This page has not yet been reviewed

External Mappings

EL NewIn.png New in version 2.3.



You can store mapping information using a metadata source external to the running application. This allows you to dynamically integrate mapping overrides and extended mappings into deployed applications. The mapping information is retrieved when the application's persistence unit is being created. This feature can be used for any mapping customization including Extensible JPA Entities.

To configure external mapping, you must:

  1. Configure the client persistence unit
  2. Configure the server

Configuring the Persistence Unit

The simplest way to store mappings externally is to make the eclipselink-orm.xml file with the additional mapping information available on a Web server as a file. A more \complex way is to establish a server process that stores the mapping information and supports dynamically updating this information.

Accessing a Mapping File at a Fixed URL

To access an external mapping file at a fixed URL for a persistence unit, use the eclipselink.metadata-source and eclipselink.metadata-source.xml properties, for example:

<property name="eclipselink.metadata-source" value="XML"/>
<property name="eclipselink.metadata-source.xml.url" value="foo://bar"/>

Mapping a Location Based on the Application Context

For more complex requirement, for example, to provide tenant-specific extensions in a multi-tenant application, you can specify the location of the mapping information based on application context. To do so, implement the MetadataSource interface, and set the properties as follows:

<property name="eclipselink.metadata-source" value="mypackage.MyMetadataSource"/>
<property name="eclipselink.metadata-source.xml.url" value="foo://bar"/>

In the following example, (from the the [MySports] example application), a JAX-RS (RESTful) service is built that returns the mapping file per tenant:

public class AdminMetadataSource extends XMLMetadataSource {
 
    @Override
    public XMLEntityMappings getEntityMappings(Map<String, Object> properties, ClassLoader classLoader, SessionLog log) {
        String leagueId = (String) properties.get(LEAGUE_CONTEXT);
        properties.put(PersistenceUnitProperties.METADATA_SOURCE_XML_URL, "http://foo.bar/rest/" + leagueId + "/orm");
        return super.getEntityMappings(properties, classLoader, log);
    }
}

Configuring the Server

The server must provide URL access to a mapping file. This can be done using a number of Web technologies, including:

  • Static file serving
  • Server-based solution with its own persistent store of XML files or mapping information stored in a granular form and put together into mapping documents on demand

See the [MySports] example application for an implementation of a JAX-RS based solution. The mapping extensions are stored as separate JPA entities and combined together on demand to create a tenant-specific mapping override file with that tenant's extension mappings.

//Expand this section with actual instructions and examples//