EclipseLink Solutions Guide for EclipseLink
Release 2.4
  Go To Table Of Contents

Beta Draft: 2012-12-13

Using an External Metadata Source

With EclipseLink, you can store your mapping information in a metadata source that is external to the running application. Because the mapping information is retrieved when the application creates the persistence unit, you can dynamically override or extend mappings in a deployed application.

Using the eclipselink-orm.xml File Externally

With EclipseLink, you can use the eclipselink-orm.xml file to support advanced mapping types and options. This file can override the standard JPA orm.xml mapping configuration file.

Main Tasks

To use an external metadata source for your mapping information, perform the following tasks:

Task 1: Configure the Persistence Unit

You can configure your persistence unit to use the external metadata by:

Accessing a Fixed Location

The easiest way to access an external file, such as the eclipselink-orm.xml file with additional mapping information, is by making the file available from a fixed URL on the web server.

Use the eclipselink.metadata-source.xml.url property, as shown in Example 10-15, to specify the location.

Example 10-15 Fixed Location

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

Accessing an Application Context-Based Location

For more complex requirements, such as providing tenant-specific extensions in a multi-tenant application, you can specify the location of the external metadata based on the application context.

Implement the MetadataSource interface, as shown in Example 10-16, to specify the location.

Example 10-16 Fixed Location

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

Example 10-17 illustrates how to return a specific mapping file, based on the tenant.

Example 10-17 Tenant-specific Mapping File

public class AdminMetadataSource extends XMLMetadataSource {
    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://myserverlocation/rest/" + leagueId + "/orm");
        return super.getEntityMappings(properties, classLoader, log);

Task 2: Configure the Server

To access the metadata file, the server must provide URL access to the mapping file by using any of the following:

  • Static file serving

  • A server-based solution with its own mapping file or a mapping file built on-demand from stored mapping information

  • some other web technology.

Additional Resources

See the following resources for more information about the technologies and tools used to implement the solutions in this chapter:

For additional information about JPA deployment, see the following sections of the JPA Specification (

  • Section 7.2, "Bootstrapping in Java SE Environments"

  • Chapter 7, "Container and Provider Contracts for Deployment and Bootstrapping"

Related Javadoc

For more information, see the following APIs in Oracle Fusion Middleware Java API Reference for EclipseLink:

  • PersistenceUnitProperties class