EclipseLink/DesignDocs/322284

Dynamic JAXB: Support For Specifying The Container Type Via XML metadata

This design page will capture design and decisions involving adding support for specifying a container class via XML metadata. This support is required by Dynamic JAXB.

Problem

For Dynamic JAXB, there must be a way of specifying the class of the container being used, such that the underlying dynamic JavaModel can be built correctly. We currently support setting the type via type attribute (based on the corresponding JAXB annotation) as follows:

<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
    <java-types>
        <java-type name="org.example.Employee">
            <java-attributes>
                <xml-element java-attribute="zipCodes" type="java.lang.Integer"/>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

This level of support will NOT allow us to configure, for example, the following dynamically:

package org.example;
 
public class Employee {
    java.util.List<Integer> zipCodes;
}

JPA Metadata

Dynamic JPA allows setting the container class via attribute-type attribute, and the property type via target-entity, as follows:

<one-to-many name="phoneNumbers" mapped-by="owner" target-entity="PhoneNumber" attribute-type="java.util.List" />

Solution

We will add an attribute named container-type that will allow users to declare the type of the container:

<xs:attribute name="container-type" type="xs:string" default="##default" />

The new attribute will be added to the following:

• xml-attribute
• xml-any-attribute
• xml-any-element
• xml-element
• xml-elements
• xml-value

Example

Here is an example of how the container type can be configured via XML metadata:

org/example/eclipselink-oxm.xml

<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
  <java-types>
    <java-type name="org.example.Employee">
      <java-attributes>
        <xml-attribute java-attribute="id" type="java.lang.String" />
        <xml-element java-attribute="name" type="java.lang.String" />
        <xml-element java-attribute="phoneNumbers" type="org.example.PhoneNumber" container-type="java.util.ArrayList" />
      </java-attributes>
    </java-type>
    <java-type name="org.example.PhoneNumber">
      <java-attributes>
        <xml-attribute java-attribute="id" type="java.lang.String" />
        <xml-attribute java-attribute="number" type="java.lang.String" />
      </java-attributes>
    </java-type>
  </java-types>
</xml-bindings>

The generated classes would look like: org.example.Employee.java

package org.example;
 
public class Employee {
    public String id;
    public String name;
    public java.util.ArrayList<PhoneNumber> phoneNumbers
}

org.example.PhoneNumber.java

package org.example;
 
public class PhoneNumber {
    public String id;
    public String number;
}

Open Issues

This section lists the open issues that are still pending that must be decided prior to fully implementing this project's requirements.

Issue #	Owner	Description / Notes

Decisions

This section lists decisions made. These are intended to document the resolution of open issues or constraints added to the project that are important.

Issue #	Description / Notes	Decision
1	For MOXy, the the property type is set via type attribute. Adding an attribute named attribute-type to support setting the container class would be confusing for users. Should a different name be used, and if so, what should it be named?	We will add an attribute named container-type
2	Should the container type be limited to interfaces (Map, List, Set) via enumeration?	No.
3	How will arrays be handled? JPA does the following: attribute-type="java.lang.Integer[]". Can we do the same thing, i.e. container-type="java.lang.Integer[]" or type="java.lang.Integer[]"?	We will not add support for array types at this time. An enhancement request has been opened to track this issue (https://bugs.eclipse.org/bugs/show_bug.cgi?id=326548).