Revision as of 09:43, 27 June 2011

EclipseLink
Website
Download
Community
Mailing List • Forums • IRC • mattermost
Issues
Open • Help Wanted • Bug Day
Contribute
Browse Source

Key API

• @VirtualAccessMethods

Examples

• Extensible Entities

Extensible Entities

This feature is new in EclipseLink 2.3.

Use the @VirtualAccessMethods annotation to specify that an entity is extensible. By using virtual properties in the entity, you can specify mappings external to the entity. This allows you to modify the mappings without modifying the entity source file and without redeploying the entity's persistence unit.

Extensible entities are useful in a multi-tenant (or Software-as-a-Service) environment where a shared, generic application can used by multiple clients (tenants), and each tenant can have access to their own, private data, as well as to data shared with other tenants.

Using extended entities, you can:

• Build an application where some mappings are common to all users and some mappings are user-specific.
• Add mappings to an application after it is made available to a customer (even post-deployment).
• Use the same EntityManagerFactory to work with data after mappings have changed
• Provide an additional source of metadata to be used by an application.

To extend the entities and take advantage of flexible columns, you must do the following:

1. Configure the entity with @VirtualAccessMethods to specify that the entity is extensible and to define virtual properties. See Configuring the Entity.
2. Include flexible columns in the database table to store the additional data. See Designing the Schema.
3. Specify extended mappings in the eclipselink-orm.xml file. See Providing Additional Mappings
4. Configure persistence.xml. See Configuring persistence.xml.

Configuring the Entity

Use the @VirtualAccessMethods annotation to specify that an entity allows flexible mappings.

An extended entity stores extended attributes in a Map, and values from the Map are mapped to the database using an eclipselink-orm.xml mapping file.

An extensible entity class must have a get() method that returns a value by property name and a set() method that 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.

Use the @Transient annotation to prevent the entity from being mapped as an inheritance relationship.

//REVIEWERS: Can that be right? I stole that phrase from the MOXy extensibility sample doc, but my understanding of transient in JPA is that it means a property or field isn't persisted. So what should be said here about transient? Is it required when specifying virtual properties? These issues also come up in the explanations for the examples, below.//

Example

@Entity
  @VirtualAccessMethods
  public class Customer{
 
...
 
    @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);
    }

Designing the Schema

Provide database tables with extra columns for storing store determines how the persistence provider accesses the state of an entity or embedded object.

When you design your schema, provide enough extra columns in the tables to accommodate the number of flexible mappings to allow. For example, the following Customer table that includes two predefined columns, ID and NAME, and three flexible columns, FLEX_COL1, FLEX_COL2, FLEX_COL3:

• CUSTOMER
  • INTEGER ID
  • VARCHAR NAME
  • VARCHAR FLEX_COL1
  • VARCHAR FLEX_COL2
  • VARCHAR FLEX_CO31

You can then specify which of those flex columns should be used to persist an extended attribute, as described below, in Providing Additional Mappings.

Providing Additional Mappings

To provide additional mappings, add the mappings to the eclipselink-orm.xml file, for example:

<basic name="idNumber" attribute-type="String">
  <column name="FLEX_COL1"/>
  <access-methods get-method="get" set-method="set"/>
</basic>

REVIEWERS: Are there any limitations on the types of mappings that support flexible mappings? Also, do you think anything more should be said about what you have to do in eclipselink-orm.xml?

Configuring persistence.xml

Configure persistence unit properties in persistence.xml to indicate that the application should retrieve the flexible mappings from the eclipselink-orm.xml file,. For example:

“Did I get that intro right? Would different wording be better here? The design doc said “Use persistence unit properties to get your application to use the file:”

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

Examples

The following examples illustrate variations on configuring extensible entities.

Example 1

Example 1 illustrates the following:

• Field access is used for non-extension fields.
• Virtual access is used for extension fields, using defaults (get(String) and set(String, Object))
• The get(String) and set(String, Object) methods will be woven, even if no mappings use them, because of the presence of @Extensible
  

// REVIEWERS: All the examples make this point, but I don't see @Extensible used elsewhere in this spec, in the Javadoc, in the sample on available from Samples area, and I don't see <extensible> in eclipselink-orm.xsd. Does it exist? If it does not exist, should this bullet be rewritten to say something new about weaving, or should I delete it?//

• Extensions are mapped in a portable way by specifying @Transient.

// REVIEWERS: See my question earlier about @Transient, under "Configuring the Entity." In short, what should be said here about using @Transient?//

Example 1

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

Example 2

Example 2 illustrates the following:

• Field access is used for non-extension fields.
• The @VirtualAccessMethods annotation overrides methods to be used for getting and setting.
• The getExtension(String) and setExtension(String, Object) methods will be woven, even if no mappings use them, because of the presence of @Extensible << I don't see @Extensible
• Extensions are mapped in a portable way by specifying @Transient.

// REVIEWERS: See my in example 1?//

• The XML for extended mapping indicates which get() and set() method to use.

Example 2

@Entity
  @VirtualAccessMethods(get="getExtension", set="setExtension")
  public class Address {
 
    @Id
    private int id;
 
    @Transient
    private Map<String, Object> extensions;
 
    public int getId(){
        return id;
    }
 
    public <T> T getExtension(String name) {
        return (T) extensions.get(name);
    }
 
    public Object setExtension(String name, Object value) {
        return extensions.put(name, value);
    }
 
...

<basic name="name" attribute-type="String">
      <column name="FLEX_1"/>
      <access-methods get-method="getExtension" set-method="setExtension"/>
    </basic>

Example 3

Example 3 illustrates the following:

• Property access is used for non extension fields.
• Virtual access is used for extension fields, using defaults (get(String) and set(String, Object))
• The extensions are mapped in a portable way; no @Transient is required because property access is used.

//REVIEWERS: Why? See also my comments on @Transient in example 1//

• The get(String) and set(String, Object) methods will be woven, even if no mappings use them, because of the presence of @Extensible

//REVIEWERS: See also comments about @Extensible in example 1//

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

Configuring the EntityManagerFactory and the Metadata Repository

//I'm not sure about this section. Is this really mostly implementation details whose user-facing information is already discussed above? Or should we retain this section to delve deeper into these subjects? If so, please advise what to say here.//

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.

Specify the class to use and any configuration information for the metadata repository through persistence unit properties. The entity manager factory checks the metadata repository while bootstrapping for additional mapping information. If additional mapping information is found, the entity manager factory integrates the into the metadata it uses to bootstrap.

Two types of metadata repository are supported: XML and database.

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. //REVIEWERS: Should we provide an example here?//

Examples

//REVIEWERS: Can we say something more about these examples to explain them? What? And should all this information be moved up to [[#Configuring persitence.xml} Configuring persitence.xml ]]?}//

XML File Example

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

User-Specified Example

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

{{EclipseLink_Note note=Use RefreshMetadata() to refresh the metadata repository. }}

[[]]	[[]]	[[]]
EclipseLink Home JPA User Guide: Table of Contents, Search
How to contribute to this guide...