EclipseLink/UserGuide/JPA/Advanced JPA Development/External Mappings

EclipseLink JPA

• EclipseLink Destinations:
• Documentation
• FAQ
• Examples
• Development

Key API

• [MetadataSource]
• [METADATA_SOURCE]
• [METADATA_SOURCE_XML_FILE]
• [METADATA_SOURCE_XML_URL]

Examples

• Extensible Entities
• MySports Example

This page is under construction

External Mappings

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