EclipseLink/Development/339381

Design Specification: XML Flex 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 instead introduce the concept of "flex extensions", where we can instead map the elements of a Java Map to the desired XML.

Requirements

1. Users must be able to annotate a field on their Java objects to be a flex extensions holder
2. Users must be able to specify a field in EclipseLink OXM to be a flex extensions holder
3. Users must be able to add new mappings at runtime through EclipseLink OXM
4. Users should be able to add any type of MOXy mapping into a flex extensions holder

Configuration

Annotations

The user can specify a field on their Java object to be a flex extensions holder by using the @XmlFlexExtensions annotation:

@Target({METHOD, FIELD}) 
@Retention(RUNTIME)
public @interface XmlFlexExtensions {}

OXM Metadata

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

eclipselink_oxm_2_3.xsd:

...
<xs:element name="xml-flex-extensions" substitutionGroup="java-attribute">
   <xs:complexType>
      <xs:complexContent>
         <xs:extension base="java-attribute">
      </xs:complexContent>
   </xs:complexType>
</xs:element>
...

Example

The following domain class specifies an @XmlFlexExtensions attribute to hold additional mappings:

@XmlRootElement
public class Customer {
 
   @XmlAttribute
   private String name;
 
   @XmlFlexExtensions
   private Map<String, Object> extensions;
 
   // getters and setters...
 
}

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

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

In an 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 elements into the flexFields Map:

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.getFlexExtensions().put("discountCode", "SIUB372JS7G2IUDS7");
 
ctx.createMarshaller().marshal(e, System.out);

This will produce the following XML:

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

Document History

Date	Author	Version Description & Notes
110323	Rick Barkhouse	1.00
110329	Rick Barkhouse	1.01 : Input from Doug, added Action Items
110331	Rick Barkhouse	1.02 : Moved open items to Discussion page
110404	Rick Barkhouse	1.03 : Changed to "XML Flex Extensions", modified OXM configuration