|
|
| (338 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | {{EclipseLink_UserGuide
| |
| − | |eclipselink=y
| |
| − | |eclipselinktype=MOXy
| |
| − | |info=y
| |
| − | |api=y
| |
| − | |apis= * [http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/oxm/annotations/XmlVirtualAccessMethods.html XmlVirtualAccessMethods]
| |
| − | |toc=y
| |
| − | }}
| |
| | | | |
| − | = Virtual Access Methods =
| |
| − |
| |
| − | In addition to the standard JAXB access methods (public member, field, property, etc.), EclipseLink MOXy 2.3 introduces the concept of virtual properties and virtual access methods, which instead rely on special '''get()''' and '''set()''' methods to maintain mapping data. For example, you might want to use a '''HashMap''' as the underlying structure to hold data for certain mappings. The mappings that use virtual method access must be defined in EclipseLink OXM metadata.
| |
| − |
| |
| − | In order to add virtual properties to an entity:
| |
| − |
| |
| − | * the Java class must be marked with an <tt>@XmlVirtualAccessMethods</tt> annotation, or <tt><xml-virtual-access-methods></tt> element in OXM
| |
| − | * the Java class must contain getter and setter methods to access virtual property values
| |
| − | ** <tt>public Object get(String propertyName)</tt>
| |
| − | ** <tt>public void set(String propertyName, Object value)</tt>
| |
| − | ** method names are configurable but must have the same method signatures as above
| |
| − |
| |
| − |
| |
| − | <div style="width:800px">
| |
| − | {{tip||By default, EclipseLink will look for methods named "set" and "get". To customize accessor method names, see [[#Specifying Alternate Accessor Methods|Specifying Alternate Accessor Methods]].}}
| |
| − | </div>
| |
| − |
| |
| − |
| |
| − | == Example ==
| |
| − |
| |
| − | For this example we will use the following '''Employee''' class. In addition to some conventional JAXB mappings, we also specify that this class contains virtual access methods by including the '''@XmlVirtualAccessMethods''' annotation.
| |
| − |
| |
| − | === Using Annotations ===
| |
| − |
| |
| − | <div style="width:700px">
| |
| − | <source lang="java">
| |
| − | package example;
| |
| − |
| |
| − | @XmlRootElement
| |
| − | @XmlVirtualAccessMethods
| |
| − | @XmlAccessorType(AccessType.PROPERTY)
| |
| − | public class Customer {
| |
| − |
| |
| − | private int id;
| |
| − |
| |
| − | private String name;
| |
| − |
| |
| − | private Map<String, Object> extensions = new HashMap<String, Object>();
| |
| − |
| |
| − | public Object get(String name) {
| |
| − | return extensions.get(name);
| |
| − | }
| |
| − |
| |
| − | public void set(String name, Object value) {
| |
| − | extensions.put(name, value);
| |
| − | }
| |
| − |
| |
| − | @XmlAttribute
| |
| − | public int getId() {
| |
| − | ...
| |
| − |
| |
| − | }
| |
| − | </source>
| |
| − | </div>
| |
| − |
| |
| − | === Using EclipseLink OXM ===
| |
| − |
| |
| − | Virtual Access Methods can be specified in OXM as follows:
| |
| − |
| |
| − | <div style="width:700px">
| |
| − | <source lang="xml">
| |
| − | ...
| |
| − | <java-types>
| |
| − | <java-type name="Customer">
| |
| − | <xml-virtual-access-methods />
| |
| − | <java-attributes>
| |
| − | <xml-attribute java-attribute="id"/>
| |
| − | <xml-element java-attribute="name"/>
| |
| − | </java-attributes>
| |
| − | </java-type>
| |
| − | ...
| |
| − | </source>
| |
| − | </div>
| |
| − |
| |
| − | Next, we define our virtual mappings in their own EclipseLink OXM file. Any property encountered in this file that does not have a corresponding Java attribute will be considered a virtual property and will be accessed through the virtual access methods.
| |
| − |
| |
| − | <div style="width:700px">
| |
| − | <source lang="xml">
| |
| − | ...
| |
| − | <java-types>
| |
| − | <java-type name="Customer">
| |
| − | <java-attributes>
| |
| − | <xml-element java-attribute="discountCode" name="discount-code"
| |
| − | type="java.lang.String" />
| |
| − | </java-attributes>
| |
| − | </java-type>
| |
| − | </java-types>
| |
| − | ...
| |
| − | </source>
| |
| − | </div>
| |
| − |
| |
| − |
| |
| − | == XmlAccessorType and XmlTransient ==
| |
| − |
| |
| − | If you are using an <tt>@XmlAccessorType</tt> other than <tt>AccessType.PROPERTY</tt>, you will need to mark your virtual properties Map attribute to be <tt>@XmlTransient</tt>, to prevent the Map itself from being bound to XML.
| |
| − |
| |
| − | <div style="width:700px">
| |
| − | <source lang="java">
| |
| − | package example;
| |
| − |
| |
| − | @XmlRootElement
| |
| − | @XmlVirtualAccessMethods
| |
| − | @XmlAccessorType(AccessType.FIELD)
| |
| − | public class Customer {
| |
| − |
| |
| − | @XmlTransient
| |
| − | private Map<String, Object> extensions;
| |
| − | ...
| |
| − | </source>
| |
| − | </div>
| |
| − |
| |
| − |
| |
| − | == Config Options ==
| |
| − |
| |
| − |
| |
| − | === Specifying Alternate Accessor Methods ===
| |
| − |
| |
| − | To use different method names as your extensions accessors, specify them using the <tt>getMethodName</tt> and <tt>setMethodName</tt> attributes on <tt>@XmlExtensible</tt>:
| |
| − |
| |
| − | <div style="width:700px">
| |
| − | <source lang="java">
| |
| − | package example;
| |
| − |
| |
| − | @XmlRootElement
| |
| − | @XmlVirtualAccessMethods(getMethod = "getCustomProps", setMethod = "putCustomProps")
| |
| − | @XmlAccessorType(AccessType.FIELD)
| |
| − | public class Customer {
| |
| − |
| |
| − | @XmlAttribute
| |
| − | private int id;
| |
| − |
| |
| − | private String name;
| |
| − |
| |
| − | @XmlTransient
| |
| − | private Map<String, Object> extensions;
| |
| − |
| |
| − | public Object getCustomProps(String name) {
| |
| − | if (extensions == null) {
| |
| − | extensions = new HashMap<String, Object>();
| |
| − | }
| |
| − | return extensions.get(name);
| |
| − | }
| |
| − |
| |
| − | public void putCustomProps(String name, Object value) {
| |
| − | if (extensions == null) {
| |
| − | extensions = new HashMap<String, Object>();
| |
| − | }
| |
| − | extensions.put(name, value);
| |
| − | }
| |
| − |
| |
| − | }
| |
| − | </source>
| |
| − | </div>
| |
| − |
| |
| − | In OXM:
| |
| − |
| |
| − | <div style="width:800px">
| |
| − | <source lang="xml">
| |
| − | ...
| |
| − | <java-types>
| |
| − | <java-type name="Customer">
| |
| − | <xml-virtual-access-methods get-method="getCustomProps" set-method="putCustomProps" />
| |
| − | <java-attributes>
| |
| − | <xml-attribute java-attribute="id" type="java.lang.Integer" />
| |
| − | <xml-element java-attribute="name" type="java.lang.String" />
| |
| − | </java-attributes>
| |
| − | </java-type>
| |
| − | ...
| |
| − | </source>
| |
| − | </div>
| |
| − |
| |
| − |
| |
| − | === Schema Generation Options ===
| |
| − |
| |
| − | If the user generates an XML Schema from the <tt>JAXBContext</tt> after virtual properties have been added, then the resulting schema will obviously be different from any Schema that may have been used to generate the initial domain objects.
| |
| − |
| |
| − | To configure how these new properties should appear in future generated schemas, use the <tt>schema</tt> attribute on <tt>@XmlVirtualAccessMethods</tt>.
| |
| − |
| |
| − |
| |
| − | '''Virtual Properties as individual Nodes'''
| |
| − |
| |
| − | This is EclipseLink's default behaviour, or can be specified explicitly as an override as follows:
| |
| − |
| |
| − | <div style="width:700px">
| |
| − | <source lang="java">
| |
| − | package example;
| |
| − |
| |
| − | @XmlRootElement
| |
| − | @XmlVirtualAccessMethods(schema = XmlVirtualAccessMethodsSchema.NODES)
| |
| − | @XmlAccessorType(AccessType.FIELD)
| |
| − | public class Customer {
| |
| − |
| |
| − | ...
| |
| − | </source>
| |
| − | </div>
| |
| − |
| |
| − | For example:
| |
| − |
| |
| − | Original <tt>Customer</tt> Schema:
| |
| − |
| |
| − | <div style="width:700px">
| |
| − | <source lang="xml">
| |
| − | <xs:schema ...>
| |
| − |
| |
| − | <xs:element name="customer">
| |
| − | <xs:complexType>
| |
| − | <xs:sequence>
| |
| − | <xs:element name="first-name" type="xs:string" />
| |
| − | <xs:element name="last-name" type="xs:string" />
| |
| − | </xs:sequence>
| |
| − | </xs:complexType>
| |
| − | </xs:element>
| |
| − |
| |
| − | </xs:schema>
| |
| − | </source>
| |
| − | </div>
| |
| − |
| |
| − | Generated Schema after adding <tt>middle-initial</tt> and <tt>phone-number</tt>:
| |
| − |
| |
| − | <div style="width:700px">
| |
| − | <source lang="xml">
| |
| − | <xs:schema ...>
| |
| − |
| |
| − | <xs:element name="customer">
| |
| − | <xs:complexType>
| |
| − | <xs:sequence>
| |
| − | <xs:element name="first-name" type="xs:string" />
| |
| − | <xs:element name="last-name" type="xs:string" />
| |
| − | <xs:element name="middle-initial" type="xs:string" />
| |
| − | <xs:element name="phone-number" type="xs:string" />
| |
| − | </xs:sequence>
| |
| − | </xs:complexType>
| |
| − | </xs:element>
| |
| − |
| |
| − | </xs:schema>
| |
| − | </source>
| |
| − | </div>
| |
| − |
| |
| − |
| |
| − | '''Virtual Properties in an <any> Element'''
| |
| − |
| |
| − | EclipseLink can also use an <tt><any></tt> element to hold all of the virtual properties in one node:
| |
| − |
| |
| − | <div style="width:700px">
| |
| − | <source lang="java">
| |
| − | package example;
| |
| − |
| |
| − | @XmlRootElement
| |
| − | @XmlVirtualAccessMethods(schema = XmlVirtualAccessMethodsSchema.ANY)
| |
| − | @XmlAccessorType(AccessType.FIELD)
| |
| − | public class Customer {
| |
| − |
| |
| − | ...
| |
| − | </source>
| |
| − | </div>
| |
| − |
| |
| − | Taking the example from above, a newly generated schema using this approach would look like:
| |
| − |
| |
| − | <div style="width:700px">
| |
| − | <source lang="xml">
| |
| − | <xs:schema ...>
| |
| − |
| |
| − | <xs:element name="customer">
| |
| − | <xs:complexType>
| |
| − | <xs:sequence>
| |
| − | <xs:element name="first-name" type="xs:string" />
| |
| − | <xs:element name="last-name" type="xs:string" />
| |
| − | <xs:any minOccurs="0" />
| |
| − | </xs:sequence>
| |
| − | </xs:complexType>
| |
| − | </xs:element>
| |
| − |
| |
| − | </xs:schema>
| |
| − | </source>
| |
| − | </div>
| |
