Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "EclipseLink/Development/339381"
< EclipseLink | Development
| Line 29: | Line 29: | ||
== Requirements == | == Requirements == | ||
| − | # Users must be able to annotate a field on their Java objects to be a "flex field" | + | # Users must be able to annotate a field on their Java objects to be a "flex field" holder |
| − | # Users must be able to specify a field in EclipseLink OXM to be a "flex field" | + | # Users must be able to specify a field in EclipseLink OXM to be a "flex field" holder |
# Users must be able to add new mappings at runtime through EclipseLink OXM | # Users must be able to add new mappings at runtime through EclipseLink OXM | ||
# Users should be able to add any type of MOXy mapping into a flex field | # Users should be able to add any type of MOXy mapping into a flex field | ||
| Line 38: | Line 38: | ||
=== Annotations === | === Annotations === | ||
| − | The user can specify a field on their Java object to be a flex field by using the <tt>@ | + | The user can specify a field on their Java object to be a flex field by using the <tt>@XmlFlexFields</tt> annotation: |
<div style="width:700px"> | <div style="width:700px"> | ||
| Line 44: | Line 44: | ||
@Target({METHOD, FIELD}) | @Target({METHOD, FIELD}) | ||
@Retention(RUNTIME) | @Retention(RUNTIME) | ||
| − | public @interface | + | public @interface XmlFlexFields {} |
</source> | </source> | ||
</div> | </div> | ||
| Line 57: | Line 57: | ||
<xs:complexType> | <xs:complexType> | ||
... | ... | ||
| − | <xs:attribute name="flex- | + | <xs:attribute name="flex-fields" type="xs:boolean" default="false" /> |
</source> | </source> | ||
</div> | </div> | ||
| Line 73: | Line 73: | ||
private String name; | private String name; | ||
| − | @ | + | @XmlFlexFields |
private Map<String, Object> flexField; | private Map<String, Object> flexField; | ||
| Line 114: | Line 114: | ||
Customer c = new Customer(); | Customer c = new Customer(); | ||
c.setName("Dan Swano"); | c.setName("Dan Swano"); | ||
| − | c. | + | c.getFlexFields().put("discountCode", "SIUB372JS7G2IUDS7"); |
ctx.createMarshaller().marshal(e, System.out); | ctx.createMarshaller().marshal(e, System.out); | ||
| Line 132: | Line 132: | ||
== Work Items == | == Work Items == | ||
| − | * '''Error Handling''' - throw an Exception / log a Warning / fire an Event if we try to marshal a | + | * '''Error Handling''' - throw an Exception / log a Warning / fire an Event if we try to marshal a flex field that was never specified? |
Revision as of 13:09, 29 March 2011
Design Specification: XML Flex Fields
Document History
| Date | Author | Version Description & Notes |
|---|---|---|
| 110323 | Rick Barkhouse | 1.00 |
| 110329 | Rick Barkhouse | 1.01 : Input from Doug, added Work Items |
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
- Users must be able to annotate a field on their Java objects to be a "flex field" holder
- Users must be able to specify a field in EclipseLink OXM to be a "flex field" holder
- Users must be able to add new mappings at runtime through EclipseLink OXM
- 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-field="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>
Work Items
- Error Handling - throw an Exception / log a Warning / fire an Event if we try to marshal a flex field that was never specified?