Revision as of 16:05, 8 April 2011

Design Specification: XML Extensions

ER 339381

Currently, EclipseLink MOXy supports the mapping of Java fields and properties to XML. Said another way; in order to map data to XML, the user must have an existing Java field or property to map.

To support multi-tenancy, we will be allowing the user to add additional mappings at runtime. Because these new mappings would not have existing fields / properties on the Java class to map to, we will introduce the concept of "extensions", where we can instead map the elements of a Java Map to the desired XML.

Requirements

1. Users must be able to add new mappings at runtime through EclipseLink OXM
2. Users should be able to add any type of MOXy mapping as an extension
3. Users must be able to annotate a field on their Java objects to hold extensions
   1. The Java field must be of type Map<String, Object>
4. Users must be able to specify a field in EclipseLink OXM to hold extensions

Configuration

In order to use this feature, the user will have to have defined a field on their Java object to be an extensions holder. This can be done either with an annotation in the Java class, or through EclipseLink OXM.

There can be at most one extensions holder on any given Java class. Attempting to define multiple extensions holders should result in a validation error.

Annotations

The user can specify a field on their Java object to hold extensions by using the @XmlExtensions annotation.

@Target({TYPE}) 
@Retention(RUNTIME)
public @interface XmlExtensible {
 
   String getMethodName default "get";
   String setMethodName default "set";
 
   XmlExtensibleSchema schemaGenerationPolicy default XmlExtensibleSchema.ELEMENTS;
 
}
 
---
 
public enum XmlExtensibleSchema {
    /**
     * XML Extensions are written to the schema as individual elements (default).
     */
    ELEMENTS,
 
    /**
     * An XML <any> element will be written to the schema to represent all
     * of the defined Extensions.
     */
    ANY
 
}

OXM Metadata

To indicate an extensions field in EclipseLink OXM, the user can specify an xml-extensible element in their metadata file:

eclipselink_oxm_2_3.xsd:

...
<xs:element name="java-type">
   <xs:complexType>
      <xs:all>
         ...
         <xs:element ref="xml-extensible" minOccurs="0"/>
         ...
 
...
<xs:element name="xml-extensible">
   <xs:complexType>
      <xs:attribute name="getMethodName" type="xs:string" default="get" />
      <xs:attribute name="setMethodName" type="xs:string" default="set" />
      <xs:attribute name="schema" type="xs:string" default="ELEMENTS" />
   </xs:complexType>
</xs:element>
...

Example

The following domain class is annotated with @XmlExtensible, indicating that it has special accessor methods to handle additional mappings. EclipseLink's default behaviour will look for the methods public Object get(String) and public void set(String, Object) to be the accessors of the extensions map.

@XmlRootElement
@XmlExtensible
@XmlAccessorType(AccessType.PROPERTY)
public class Customer {
 
   private int id;
 
   private String name;
 
   private Map<String, Object> extensions;
 
   public Object get(String name) {
      if (extensions == null) {
         extensions = new HashMap<String, Object>();
      }
      return extensions.get(name);
   }
 
   public void set(String name, Object value) {
      if (extensions == null) {
         extensions = new HashMap<String, Object>();
      }
      extensions.put(name, value);
   }
 
   @XmlAttribute
   public int getId() {
   ...
 
}

The class above can be expressed in EclipseLink OXM metadata as follows:

...
<java-types>
   <java-type name="Customer" xml>
      <java-attributes>
         <xml-attribute java-attribute="name" type="java.lang.String" />
      </java-attributes>
   </java-type>
...

In a secondary metadata file, we will define additional mappings that we would like to add to Customer:

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

(Note that there is no special configuration needed for additional mappings; they are specified in the same way as "normal" mappings.)

To set the values for these additional mappings, we will add values into the extensions Map, using the property name as the Map key:

InputStream oxm = classLoader.getResourceAsStream("eclipselink-oxm.xml");
Map<String, Object> properties = new HashMap<String, Object>();
properties.put(JAXBContextFactory.ECLIPSELINK_OXM_XML_KEY, oxm);
 
Class[] classes = new Class[] { Customer.class };
JAXBContext ctx = JAXBContext.newInstance(classes, properties);
 
Customer c = new Customer();
c.setName("Dan Swano");
c.set("discountCode", "SIUB372JS7G2IUDS7");
 
ctx.createMarshaller().marshal(e, System.out);

This will produce the following XML:

<customer name="Dan Swano">
   <discount-code>SIUB372JS7G2IUDS7</discount-code>
</customer>

Config Options

XmlAccessorType and XmlTransient

If you are using an @XmlAccessorType other than AccessType.PROPERTY, you will need to mark your extensions Map attribute to be @XmlTransient, to prevent the Map itself from being bound to XML.

@XmlRootElement
@XmlExtensible
@XmlAccessorType(AccessType.FIELD)
public class Customer {
 
   @XmlTransient
   private Map<String, Object> extensions;
   ...

Specifying Alternate Accessor Methods

To use different method names as your extensions accessors, specify them using the getMethodName and setMethodName attributes on @XmlExtensible:

@XmlRootElement
@XmlExtensible(getMethodName = "getCustomProps", setMethodName = "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);
   }
 
}

Schema Generation Options

If the user generates an XML Schema from the JAXBContext after extensions 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 extensions should appear in future generated schemas, use the schemaGenerationPolicy attribute on @XmlExtensible.

Extensions as individual Elements

This is EclipseLink's default behaviour, or can be specified explicitly as an override as follows:

@XmlRootElement
@XmlExtensible(schemaGenerationPolicy = XmlExtensibleSchema.ELEMENTS)
@XmlAccessorType(AccessType.FIELD)
public class Customer {
 
   ...

For example:

Original Customer Schema:

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

Generated Schema after adding middle-initial and phone-number:

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

All Extensions in an <any> Element

EclipseLink can also use an <any> element to hold all of the extensions in one node:

@XmlRootElement
@XmlExtensible(schemaGenerationPolicy = XmlExtensibleSchema.ANY)
@XmlAccessorType(AccessType.FIELD)
public class Customer {
 
   ...

Taking the example from above, a newly generated schema using this approach would look like:

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

Design

• org.eclipse.persistence.jaxb.compiler.Property
  • A Property will now know if it is an extensions holder
• org.eclipse.persistence.jaxb.compiler.TypeInfo
  • A TypeInfo can now have an extensions Property
• org.eclipse.persistence.internal.jaxb.XmlExtensionsAttributeAccessor
  • New AttributeAccessor to handle getting/setting values from the extensions Map.
• org.eclipse.persistence.jaxb.compiler.XMLProcessor
  • When processing an OXM file, if a Property is encountered (e.g. "foo") that does not have a corresponding property in Java:
    • If the TypeInfo has an extensions Property, then create a new "foo" Property, and setup an XmlExtensionsAttributeAccessor for its mapping
    • If the TypeInfo does not have an extensions Property, a "No such property exists" exception will be thrown

Document History