Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/JPA/Advanced JPA Development/Extensible Entities"

(User-Specified Example)
Line 11: Line 11:
 
*[[EclipseLink/Examples/JPA/Extensibility|Extensible Entities]]
 
*[[EclipseLink/Examples/JPA/Extensibility|Extensible Entities]]
 
}}
 
}}
 +
===******SANDBOX VERSION******===
 
=Extensible Entities=
 
=Extensible Entities=
 
''This feature is new in EclipseLink 2.3.''
 
 
 
''This topic is currently under review.''
 
''This topic is currently under review.''
 +
 +
{{EclipseLink_NewIn
 +
|version=2.3}}
 +
<br><br>.''
  
 
Use the <tt>@VirtualAccessMethods</tt> annotation to specify that an entity is extensible. By using virtual properties in an extensible 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.  
 
Use the <tt>@VirtualAccessMethods</tt> annotation to specify that an entity is extensible. By using virtual properties in an extensible 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.  
Line 28: Line 30:
 
* Provide an additional source of metadata to be used by an application.  
 
* Provide an additional source of metadata to be used by an application.  
  
To configure extensible entities, you must do the following:
+
To create and support an extensible entity,  
#''' add a get(String) method and a set(String, Object) method and the datastructures necessary to support them to your Entity.'''--[[User:Tom.ware.oracle.com|Tom.ware.oracle.com]] 15:47, 28 June 2011 (UTC)
+
 
# Configure the entity with <tt>@VirtualAccessMethods</tt> to specify that the entity is extensible and to define virtual properties. See [[#Configuring the Entity| Configuring the Entity]].  
+
#Configure the entity. See [[#Configuring the Entity| Configuring the Entity]].  
 
# Include flexible columns in the database table to store the additional data. See [[#Designing the Schema| Designing the Schema]].
 
# Include flexible columns in the database table to store the additional data. See [[#Designing the Schema| Designing the Schema]].
 
# Specify extended mappings in the <tt>eclipselink-orm.xml</tt> file. See [[#Providing Additional Mappings| Providing Additional Mappings]]
 
# Specify extended mappings in the <tt>eclipselink-orm.xml</tt> file. See [[#Providing Additional Mappings| Providing Additional Mappings]]
Line 36: Line 38:
  
 
===Configuring the Entity===
 
===Configuring the Entity===
 +
To configure the entity,
 +
 +
# [[#Annotate with @VirtualAccessMethods| Annotate with <tt>@VirtualAccessMethods</tt>]]
 +
#  [[#Add get() and set() Methods| Add <tt>get()</tt> and <tt>set()</tt> methods]]
 +
# [[#Add a Data Structure|Add a data structure]]
 +
 +
====Annotate with @VirtualAccessMethods====
  
Use the <tt>@VirtualAccessMethods</tt> annotation to specify that an entity allows flexible mappings.
+
Annotate the entity with <tt>@VirtualAccessMethods</tt> to specify that it is extensible and to define virtual properties.  
 
{{EclipseLink_AttributeTable
 
{{EclipseLink_AttributeTable
 
|caption=@VirtualAccessMethods Attributes
 
|caption=@VirtualAccessMethods Attributes
Line 45: Line 54:
 
<td> The name of the getter method to use for the virtual property This method must take a single <tt>java.lang.String</tt> parameter and return a <tt>java.lang.Object</tt>. </td>
 
<td> The name of the getter method to use for the virtual property This method must take a single <tt>java.lang.String</tt> parameter and return a <tt>java.lang.Object</tt>. </td>
 
<td><tt>get</tt></td>
 
<td><tt>get</tt></td>
<td>No</td>
+
<td>Yes</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
Line 51: Line 60:
 
<td>The name of the setter method to use for the virtual property This method must take a <tt>java.lang.String</tt> parameter and return a <tt>java.lang.Object</tt> parameter.</td>
 
<td>The name of the setter method to use for the virtual property This method must take a <tt>java.lang.String</tt> parameter and return a <tt>java.lang.Object</tt> parameter.</td>
 
<td><tt>set</tt></td>
 
<td><tt>set</tt></td>
<td>No</td>
+
<td>Yes</td>
 
</tr>
 
</tr>
 
}}
 
}}
 +
<br>
  
*'''We should mention the required signatures of these methods here.  (get(String) and set(String, Object))  Our weaving will not work with other signatures'''--[[User:Tom.ware.oracle.com|Tom.ware.oracle.com]] 15:52, 28 June 2011 (UTC)
+
==== Add get() and set() Methods====
*'''What does "Required: No" mean?'''--[[User:Tom.ware.oracle.com|Tom.ware.oracle.com]] 15:52, 28 June 2011 (UTC)
+
Add <tt>get(String)</tt> and <tt>set(String, Object)</tt> methods to the entity.
  
<br>
+
The <tt>get()</tt> method returns a value by property name and the <tt>set()</tt> method stores a value by property name. The default names for these methods are <tt>get</tt> and <tt>set</tt>, and they can be overridden with the <tt>@VirtualAccessMethods</tt> annotation.  
<br>
+
An extensible entity class must have a <tt>get()</tt> method that returns a value by property name and a <tt>set()</tt> method that stores a value by property name. The default names for these methods are <tt>get()</tt> and <tt>set()</tt>, and they can be overridden with the <tt>@VirtualAccessMethods</tt> annotation.  
+
  
EclipseLink weaves these methods if weaving is enabled, which provides support for lazy loading, change tracking, fetch groups, and internal optimizations.  
+
EclipseLink weaves these methods if weaving is enabled, which provides support for lazy loading, change tracking, fetch groups, and internal optimizations. You must use the the <tt>get(String)</tt> and <tt>set(String, Object)</tt> signatures, or else weaving will not work.
  
 
{{EclipseLink_Note
 
{{EclipseLink_Note
Line 68: Line 76:
 
}}
 
}}
  
An extended entity stores extended attributes in a <tt>Map</tt>, and values from the <tt>Map</tt> are mapped to the database using an <tt>eclipselink-orm.xml</tt> mapping file.
+
==== Add a Data Structure ====
  
Use the <tt>@Transient</tt> annotation to ...
+
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 [[#Providing Additional Mappings| Providing Additional Mappings]].
  
'''''//REVIEWERS: What is the right thing to say about Transient? The MOXy extensibility sample doc says "Use @Transient annotation to prevent the entity from being mapped as an inheritance relationship," but I don't think that is right for JPA> 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? (including, is @Transient ''required'' when specifying virtual properties?) These issues also come up in the explanations for the examples, below, where the design doc says something like " Extensions are mapped in a portable way using Transient ".//'''''
+
A common way to store the virtual mappings is in a <tt>Map</tt> (as shown in the examples in this topic), but you can use other ways, as well. For example you could store the virtual mappings in a directory system.  
  
* '''@Transient is really just something to remind users to keep in mind.  If they are using FIELD based access any underlying data structure they use to store the virtual mappings should be @Transient so that JPA will not try to use that data structure to for another mapping. With PROPERTY access, there is no need for @Transient''' --[[User:Tom.ware.oracle.com|Tom.ware.oracle.com]] 15:56, 28 June 2011 (UTC)
+
When using field-based access, annotate the data structure with <tt>@Transient</tt> so it cannot use it for another mapping. When using property-based access, <tt>@Transient'</tt> is unnecessary.
  
===Example===
+
====Example====
  
'''Add a comment here that indicates this is an Entity that uses PROPERTY access, or maybe just the "id" field I have added below in the source''' --[[User:Tom.ware.oracle.com|Tom.ware.oracle.com]] 17:18, 28 June 2011 (UTC)
+
The following example shows an entity that uses property access.  
  
 
<source lang="java">
 
<source lang="java">
Line 100: Line 108:
 
     }
 
     }
 
</source>
 
</source>
 +
 +
====Using XML====
 +
As an alternative to, or in addition to, using <tt>@VirtualAccessMethods</tt>, you can use the <tt><access></tt> and <tt><access-methods></tt> elements, for example:
 +
 +
<source lang="xml">
 +
<access>VIRTUAL</access>
 +
<access-methods set-method="get" get-method="set"/>
 +
</source>
 +
 +
''''''REVIEWERS: // Is this correct? Is this adequate?//''''''
  
 
===Designing the Schema===
 
===Designing the Schema===
Line 113: Line 131:
  
 
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]].
 
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]].
 +
 
===Providing Additional Mappings===
 
===Providing Additional Mappings===
  
Line 154: Line 173:
 
*Field access is used for non-extension fields.
 
*Field access is used for non-extension fields.
 
*Virtual access is used for extension fields, using defaults <tt>(get(String)</tt> and <tt>set(String, Object))</tt> .
 
*Virtual access is used for extension fields, using defaults <tt>(get(String)</tt> and <tt>set(String, Object))</tt> .
*The <tt>get(String)</tt> and <tt>set(String, Object)</tt> methods will be woven, even if no mappings use them, because of the presence of <tt>@Extensible</tt>.<br>
+
*The <tt>get(String)</tt> and <tt>set(String, Object)</tt> methods will be woven, even if no mappings use them, because of the presence of <tt>@VirtualAccessMethods</tt>.
'''''// REVIEWERS: All the examples make this point about @Extensible, but I don't see @Extensible used elsewhere in this spec, in the Javadoc, or in the [[EclipseLink/Examples/JPA/Extensibility|sample]]; 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?//'''''
+
 
+
* '''Replace "Extensible" with "VirtualAccessMethods".  I'll fix the other doc.'''--[[User:Tom.ware.oracle.com|Tom.ware.oracle.com]] 17:22, 28 June 2011 (UTC)
+
 
+
 
*Extensions are mapped in a portable way by specifying <tt>@Transient</tt>.  
 
*Extensions are mapped in a portable way by specifying <tt>@Transient</tt>.  
'''''// REVIEWERS: See my question earlier about @Transient, under "Configuring the Entity."  In short, what should be said here about using @Transient?//'''''
 
 
* '''Let me know if that is not covered in the original comments'''--[[User:Tom.ware.oracle.com|Tom.ware.oracle.com]] 17:22, 28 June 2011 (UTC)
 
 
  
 
Example 1
 
Example 1
Line 199: Line 210:
 
*Field access is used for non-extension fields.
 
*Field access is used for non-extension fields.
 
* The <tt>@VirtualAccessMethods</tt> annotation overrides methods to be used for getting and setting.  
 
* The <tt>@VirtualAccessMethods</tt> annotation overrides methods to be used for getting and setting.  
* The <tt>getExtension(String)</tt> and <tt>setExtension(String, Object)</tt> methods will be woven, even if no mappings use them, because of the presence of <tt>@Extensible</tt>  
+
*The <tt>get(String)</tt> and <tt>set(String, Object)</tt> methods will be woven, even if no mappings use them, because of the presence of <tt>@VirtualAccessMethods</tt>.<br>
'''''// REVIEWERS: See my question about @Extensible in example 1.//'''''
+
 
*Extensions are mapped in a portable way by specifying <tt>@Transient</tt>.  
 
*Extensions are mapped in a portable way by specifying <tt>@Transient</tt>.  
'''''// REVIEWERS: See my question about @Transient in example 1.//'''''
 
 
* The XML for extended mapping indicates which <tt>get()</tt> and <tt>set()</tt> method to use.
 
* The XML for extended mapping indicates which <tt>get()</tt> and <tt>set()</tt> method to use.
 
  
 
Example 2  
 
Example 2  
Line 246: Line 254:
 
Example 3  illustrates the following:  
 
Example 3  illustrates the following:  
  
* Property access is used for non extension fields.
+
* Property access is used for non-extension fields.
 
*Virtual access is used for extension fields, using defaults <tt>(get(String)</tt> and <tt>set(String, Object)) </tt>  
 
*Virtual access is used for extension fields, using defaults <tt>(get(String)</tt> and <tt>set(String, Object)) </tt>  
* The extensions are mapped in a portable way; no @Transient is required because property access is used.  
+
* The extensions are mapped in a portable way. <tt>@Transient</tt> is not required, because property access is used.  
'''''//REVIEWERS: Why? See also my comments on @Transient in example 1//'''''
+
* The <tt>get(String)</tt> and <tt>set(String, Object)</tt> methods will be woven, even if no mappings use them, because of the presence of <tt>@VirtualAccessMethods</tt>.
* The <tt>get(String)</tt> and <tt>set(String, Object) </tt> methods will be woven, even if no mappings use them, because of the presence of <tt>@Extensible</tt>.
+
<br>
'''''//REVIEWERS: See also comments about <tt>@Extensible</tt> in example 1//'''''
+
  
 
<source lang="java">
 
<source lang="java">
Line 281: Line 288:
 
== Configuring the EntityManagerFactory and the Metadata Repository ==
 
== Configuring the EntityManagerFactory and the Metadata Repository ==
  
'''''//REVIEWERS: I'm not sure about this section. Are these 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. The current release supports XML repositories.
  
* '''I think think this section can be fairly brief.  A quick intro to what the repository does and then an indication that it is possible to provide an overriding class and a pointer to the XML that provides the classname'''--[[User:Tom.ware.oracle.com|Tom.ware.oracle.com]] 17:30, 28 June 2011 (UTC)
+
Specify the class to use and any configuration information for the metadata repository through persistence unit properties. The entity manager factory integrates additional mapping information from the metadata repository into the metadata it uses to bootstrap.  
 
+
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.
+
 
+
* '''There is no "database" at the moment.  I'll fix the other doc'''--[[User:Tom.ware.oracle.com|Tom.ware.oracle.com]] 17:30, 28 June 2011 (UTC)
+
  
 
You can provide your own implementation of the class to access the metadata repository.  
 
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.
 
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?//'''''
 
 
* '''Brief example of how to use the XML.  You can use "User-Specified Example" below. And explain that the propeties that start with "com.foo" are implementer-defined.'''--[[User:Tom.ware.oracle.com|Tom.ware.oracle.com]] 17:30, 28 June 2011 (UTC)
 
 
<property name="eclipselink.metadata-source" value="myPackage.MyClass"/>
 
 
* '''And a note that says you can subclass either org.eclipse.persistence.internal.jpa.extensions.MetadataRepository or org.eclipse.persistence.internal.jpa.extensions.XMLMetadataRepository.''' --[[User:Tom.ware.oracle.com|Tom.ware.oracle.com]] 17:30, 28 June 2011 (UTC)
 
 
 
===Examples ===
 
'''''//REVIEWERS: Can we say something more about these examples to explain them? What? And should all this information be moved up to [[#Configuring persistence.xml|Configuring persistence.xml]]?//'''''
 
 
* '''XML File examples is covered above and could possibly be removed here.'''--[[User:Tom.ware.oracle.com|Tom.ware.oracle.com]] 17:32, 28 June 2011 (UTC)
 
 
====XML File Example====
 
 
<source lang="xml">
 
<property name="eclipselink.metadata-source" value="XML"/>
 
<property name="eclipselink.metadata-source.xml.url" value="foo://bar"/>
 
</source>
 
  
 +
You can subclass either of the following: *<tt>org.eclipse.persistence.internal.jpa.extensions.MetadataRepository</tt> *<tt>org.eclipse.persistence.internal.jpa.extensions.XMLMetadataRepository</tt>
  
====User-Specified Example====
+
====Example====
 +
In the following example, the properties that begin with <tt>com.foo</tt> are defined by the implementor.
  
 
<source lang="xml">
 
<source lang="xml">

Revision as of 08:37, 30 June 2011

EclipseLink JPA

link="http://wiki.eclipse.org/EclipseLink"
EclipseLink
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source

******SANDBOX VERSION******

Extensible Entities

This topic is currently under review.

EL NewIn.png New in version 2.3.



.

Use the @VirtualAccessMethods annotation to specify that an entity is extensible. By using virtual properties in an extensible 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 be used by multiple clients (tenants). Tenants have private access to their own data, as well as to data shared with other tenants. See also Single-Table Multi-Tenancy.

Using extensible 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 create and support an extensible entity,

  1. Configure the entity. 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

To configure the entity,

  1. Annotate with @VirtualAccessMethods
  2. Add get() and set() methods
  3. Add a data structure

Annotate with @VirtualAccessMethods

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

@VirtualAccessMethods Attributes
Attribute Description Default Required?
get The name of the getter method to use for the virtual property This method must take a single java.lang.String parameter and return a java.lang.Object. get Yes
set The name of the setter method to use for the virtual property This method must take a java.lang.String parameter and return a java.lang.Object parameter. set Yes


Add get() and set() Methods

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. You must use the the get(String) and set(String, Object) signatures, or else weaving will not work.

Elug note icon.png

Note: Weaving is not supported when using virtual access methods with OneToOne mappings. If attempted, an exception will be thrown.

Add a Data Structure

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 Providing Additional Mappings.

A common way to store the virtual mappings is in a Map (as shown in the examples in this topic), but you can use other ways, as well. For example you could store the virtual mappings in a directory system.

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

Example

The following example shows an entity 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);
    }

Using XML

As an alternative to, or in addition to, using @VirtualAccessMethods, you can use the <access> and <access-methods> elements, for example:

<access>VIRTUAL</access>
<access-methods set-method="get" get-method="set"/>

'REVIEWERS: // Is this correct? Is this adequate?//'

Designing the Schema

Provide database tables with extra columns for storing flexible mapping data. For example, the following Customer table 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?//

  • I think that part of this will be addressed by anything we do to document using <access-methods> to specify Virtual mappings--Tom.ware.oracle.com 16:04, 28 June 2011 (UTC)
  • The XML file simply gets treated as another XML file in the list of XML files. As long as you obey all the rules related to what can be overridden, you can use any kind of mapping. The challenge in using non-virtual mappings is how to have the data structures that support them make sense when the document is not there. e.g. if you're going to have an extension that uses an instance variable, for the instances of the application that don't use that extension file, how is that instance variable treated - JPA will likely try to use it for a mapping using its defaulting-rules --Tom.ware.oracle.com 16:04, 28 June 2011 (UTC)

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:

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

  • Both persistence unit propeties and persistence.xml are legitimate use cases. We should describe both. persistence.xml allows either a default, or a single-user file that can be changed. persistence unit properties allow specification of the file at runtime and provides a more dynamic experience.--Tom.ware.oracle.com 16:06, 28 June 2011 (UTC)
<property name="eclipselink.metadata-source" value="XML"/>
<property name="eclipselink.metadata-source.xml.url" value="foo://bar"/>

//REVIEWERS What more can be said about these? See my related questions below, under Configuring the EntityManagerFactory and the Metadata Repository.//

  • Maybe the two sections should go together. We could mention that by default we support using a file at a URL, but it is possible to also override how the repository works and then go into details.--Tom.ware.oracle.com 17:20, 28 June 2011 (UTC)

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 @VirtualAccessMethods.
  • Extensions are mapped in a portable way by specifying @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 get(String) and set(String, Object) methods will be woven, even if no mappings use them, because of the presence of @VirtualAccessMethods.
  • Extensions are mapped in a portable way by specifying @Transient.
  • 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. @Transient is not required, because property access is used.
  • The get(String) and set(String, Object) methods will be woven, even if no mappings use them, because of the presence of @VirtualAccessMethods.


@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

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. The current release supports XML repositories.

Specify the class to use and any configuration information for the metadata repository through persistence unit properties. The entity manager factory 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: *org.eclipse.persistence.internal.jpa.extensions.MetadataRepository *org.eclipse.persistence.internal.jpa.extensions.XMLMetadataRepository

Example

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

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

Elug note icon.png

Note: Use [RefreshMetadata()] to refresh the metadata repository.

'''//REVIERWERS: Should that note on refresh metadata be included? Should something more be said about it?//

  • refreshMetadata() is important. We should indicate that if you change the metadata and you want an EntityManager based on the new metadata, you call refreshMetadata on the EntityManagerFactory and then the next EntityManager you get will be based on the new metadata. Additionally, refreshMetadata takes a Map of properties and that map of properties can be used to override the properties previously defined for the metadata-source.--Tom.ware.oracle.com 17:36, 28 June 2011 (UTC)


Eclipselink-logo.gif
Version: DRAFT
Other versions...