Making JPA Entities Extensible

Annotate the Entity Class with @VirtualAccessMethods

Annotate the entity with @VirtualAccessMethods to specify that it is extensible and to define virtual properties.

Table 12-1 describes the attributes available to the @VirtualAccessMethods annotation.

Add get and set Methods to the Entity

Add get(String) and set(String, Object) methods to the entity. The get() method returns a value by property name and the set() method stores a value by property name. The default names for these methods are get and set, and they can be overridden with the @VirtualAccessMethods annotation.

EclipseLink weaves these methods if weaving is enabled, which provides support for lazy loading, change tracking, fetch groups, and internal optimizations.

Define Virtual Attribute Storage

Add a data structure to store the extended attributes and values, that is, the virtual mappings. These can then be mapped to the database. See Task 3: Provide Additional Mappings.

A common way to store the virtual mappings is in a Map object (as shown in Example 12-1), but you can also use other strategies.

When using field-based access, annotate the data structure with @Transient so the structure cannot be used for another mapping. When using property-based access, @Transient is unnecessary.

Example 12-1 illustrates an entity class that uses property access.

@Entity
@VirtualAccessMethods
public class Customer{
 
    @Id
    private int id;
    ...
 
    @Transient
    private Map<String, Object> extensions;
 
    public <T> T get(String name) {
        return (T) extentions.get(name);
    }
 
    public Object set(String name, Object value) {
        return extensions.put(name, value);
    }

Use XML

As an alternative to, or in addition to, using the @VirtualAccessMethods annotation, you can use an access="VIRTUAL" attribute on a mapping element (such as <basic>), for example:

<basic name="idNumber" access="VIRTUAL" attribute-type="String">
    <column name="FLEX_COL1"/>
</basic>

To set virtual access methods as the defaults for the persistence unit, use the <access> and <access-methods> elements, for example:

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

Configure the persistence.xml File

In the persistence.xml file, use the eclipselink.metadata-source property to use the default eclipselink-orm.xml file. Use the eclipselink.metadata-source.xml.url property to use a different file at the specified location, for example:

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

Configure EntityManagerFactory and the Metadata Repository

Extensions are added at bootstrap time through access to a metadata repository. The metadata repository is accessed through a class that provides methods to retrieve the metadata it holds. EclipseLink includes a metadata repository implementation that supports XML repositories.

Specify the class to use and any configuration information for the metadata repository through persistence unit properties. The EntityManagerFactory interface integrates additional mapping information from the metadata repository into the metadata it uses to bootstrap.

You can provide your own implementation of the class to access the metadata repository. Each metadata repository access class must specify an individual set of properties to use to connect to the repository.

You can subclass either of the following classes:

• org.eclipse.persistence.internal.jpa.extensions.MetadataRepository

• org.eclipse.persistence.internal.jpa.extensions.XMLMetadataRepository

In the following example, the properties that begin with com.foo are subclasses defined by the developer.

<property name="eclipselink.metadata-source" value="com.foo.MetadataRepository"/>
<property name="com.foo.MetadataRepository.location" value="foo://bar"/>
<property name="com.foo.MetadataRepository.extra-data" value="foo-bar"/>

Refresh the Metadata Repository

If you change the metadata and you want an EntityManager instance based on the new metadata, you must call the refreshMetadata() method on the EntityManagerFactory interface to refresh the data. The next EntityManager instance will be based on the new metadata.

The refreshMetadata() method takes a map of properties that can be used to override the properties previously defined for the metadata-source element.