EclipseLink/Development/339381

Design Specification: XML Flex Fields

ER 339381

Feature Overview

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 a "flex field", 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 field" holder
2. Users must be able to specify a field in EclipseLink OXM to be a "flex field" 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 field

Configuration

Annotations

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

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

OXM Metadata

To indicate a flex field in EclipseLink OXM, the user can use the flex-fields="true" attribute in their xml-element:

   <xs:element name="xml-element" substitutionGroup="java-attribute">
      <xs:complexType>
      ...
         <xs:attribute name="flex-fields" type="xs:boolean" default="false" />

Example

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

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

In an eclipselink-oxm.xml 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>
...

To set the values for these additional mappings, we will add elements into the flexField 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.getFlexFields().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