EclipseLink/DesignDocs/317962/Phase2.1

Phase 2 - Additional MOXy annotation/xml metadata support

This phase of development involves providing additional MOXy annotations and XML metadata support that will allow configuration similar to that of deployment XML

Annotations/XML Metadata

The following MOXy annotations/XML metadata will be targeted in this phase:

MOXy Annotation	XML Metadata Tag	Package	Type	Field	Method
XmlProperties	xml-properties		X	X	X
XmlProperty	xml-property		X	X	X
XmlTransformation	xml-transformation			X	X
XmlReadTransformer	xml-read-transformer			X	X
XmlWriteTransformer	xml-write-transformer			X	X
XmlClassExtractor	xml-class-extractor		X

xml-properties

Purpose

The xml-properties element will be used as a grouping element to wrap one or more xml-property elements. See below for additional information and examples of use.

xml-property

Purpose

The xml-property element provides a means to set a property on a mapping or descriptor. Any annotations set on a property will be completely replaced by XML. Any annotations set on a type will be merged with XML, with XML taking precedence in the case of a conflict.

XML Schema

Since there can be multiple properties on a mapping or descriptor, and <xs:all> doesn't allow maxOccurs="unbounded", we will wrap xml-property in xml-properties. Following are the proposed schema changes:

<xs:element name="xml-properties" type="xml-properties" />
<xs:complexType name="xml-properties">
    <xs:sequence>
        <xs:element name="xml-property" minOccurs="0" maxOccurs="unbounded" >
            <xs:complexType>
                <xs:attribute name="name" type="xs:string" use="required" />
                <xs:attribute name="value" type="xs:string" use="required" />
                <xs:attribute name="value-type" type="xs:string" default="java.lang.String" />
            </xs:complexType>
        </xs:element>
    </xs:sequence>
</xs:complexType>

An element ref to the new global xml-properties element will be added to the following:

• java-type
• xml-any-attribute
• xml-attribute
• xml-any-element
• xml-element
• xml-elements
• xml-element-ref
• xml-element-refs
• xml-inverse-reference
• xml-value
• xml-transformation

Example: type-level xml-property

The following example will demonstrate how a type-level xml-property can be applied.

Setting xml-property on a type via EclipseLink XML metadata can be accomplished as follows:

<java-type name="org.example.Employee">
    <xml-properties>
        <xml-property name="identifier" value="101" value-type="Integer.class" />
        <xml-property name="isTrue" value="false" value-type="Boolean.class" />
    </xml-properties>
</java-type>

Example: property-level xml-property

The following example will demonstrate how a property-level xml-property can be applied.

Setting xml-property on a property via EclipseLink XML metadata can be accomplished as follows:

<java-type name="org.example.Employee">
    <java-attributes>
        <xml-element java-attribute="myelement">
            <xml-properties>
                <xml-property name="isAttribute" value="false" value-type="Boolean.class" />
                <xml-property name="comment" value="this is an element" />
            </xml-properties>
        </xml-element>
    </java-attributes>
</java-type>

Testing

Tests for xml-property and xml-properties will be added to the direct mapping test suite in the org.eclipse.persistence.testing.jaxb.externalizedmetadata.mappings.direct package.

xml-transformation

Purpose

The xml-transformation element is used to configure an org.eclipse.persistence.oxm.mappings.XMLTransformationMapping. Transformation mappings are used to create a custom mapping where one or more XML nodes can be used to create the object to be stored in a Java class's attribute.

XML Schema

Following is the proposed schema structure for xml-transformation:

<xs:element name="xml-transformation" substitutionGroup="java-attribute">
    <xs:complexType>
        <xs:complexContent>
            <xs:extension base="java-attribute">
                <xs:all>
                    <xs:element name="xml-access-methods" type="xml-access-methods" minOccurs="0"/>
                    <!-- xs:element name="xml-accessor-type" type="xml-access-type" minOccurs="0"/ -->
                    <xs:element name="xml-properties" minOccurs="0">
                        <xs:complexType>
                            <xs:sequence>
                                <xs:element ref="xml-property" minOccurs="0" maxOccurs="unbounded" />
                            </xs:sequence>
                        </xs:complexType>
                    </xs:element>
                    <xs:element name="xml-read-transformer">
                        <xs:complexType>
                            <xs:attribute name="method" type="xs:string" />
                            <xs:attribute name="transformer-class" type="xs:string" />
                        </xs:complexType>
                    </xs:element>
                    <xs:element name="xml-write-transformer" minOccurs="0" maxOccurs="unbounded">
                        <xs:complexType>
                            <xs:attribute name="method" type="xs:string" />
                            <xs:attribute name="xml-path" type="xs:string" />
                            <xs:attribute name="transformer-class" type="xs:string" />
                        </xs:complexType>
                    </xs:element>
                </xs:all>
                <xs:attribute name="attribute-type" type="xs:string" />
                <!-- xs:attribute name="fetch" type="orm:fetch-type"/ -->
                <xs:attribute name="mutable" type="xs:boolean" default="false"/>
                <xs:attribute name="name" type="xs:string" use="required"/>
                <xs:attribute name="optional" type="xs:boolean" default="false"/>
                <xs:attribute name="xml-accessor-type" type="xml-access-type" minOccurs="0" default="PUBLIC_MEMBER"/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
</xs:element>

Example

The following example will demonstrate how xml-transformation can be applied.

Setting xml-transformation via EclipseLink XML metadata can be accomplished as follows:

<java-type name="org.example.Employee">
    <java-attributes>
        <xml-transformation java-attribute="hours" optional="true">
            <xml-read-transformer transformer-class="org.example.NormalHoursTransformer" />
            <xml-write-transformer xml-path="normal-hours/start-time/text()" transformer-class="org.example.StartTimeTransformer"/>
            <xml-write-transformer xml-path="normal-hours/end-time/text()" transformer-class="org.example.EndTimeTransformer"/>
            <xml-access-methods get-method="getNormalHours" set-method="setNormalHours" />
        </xml-transformation>
    </java-attributes>
</java-type>

XmlClassExtractor

Purpose

A class extractor provides a means for complex inheritance support. A ClassExtractor instance is registered with the descriptor to override the default inheritance mechanism. This allows for a user defined class indicator in place of providing an explicit class indicator field. The instance registered must extend the org.eclipse.persistence.descriptors.ClassExtractor class and implement the extractClassFromRow(Record, Session) method; this method is used to determine which class to instantiate when unmarshalling.

Java Metadata

@XmlClassExtractor

The following is the proposed source code for the XmlClassExtractor annotation:

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlClassExtractor {
    /**
     * (Required) Defines the name of the class extractor that should be 
     * applied to this entity's descriptor.
     */
    Class value(); 
}

XML Metadata

XML Schema

Following is the proposed schema structure for xml-class-extractor - a global element/complex type pair will be added, and a ref will be added to java-type:

<xs:element name="xml-class-extractor" type="xml-class-extractor" />
<xs:complexType name="xml-class-extractor">
    <xs:attribute name="class" type="xs:string" use="required"/>
</xs:complexType>

Example

The following example will demonstrate how a class extractor can be applied.

Setting xml-class-extractor via EclipseLink XML metadata can be accomplished as follows:

<java-type name="org.example.Person">
    <xml-class-extractor class="org.example.MyClassExtractor" />
</java-type>

Setting the Class Extractor via Annotations would be accomplished as follows: org.example.Person.java

package org.example;
 
@XmlClassExtractor(MyClassExtactor.class)
class Person {
    String name;
}

org.example.Employee.java

package org.example;
 
class Employee extends Person {
    String id;
}

org.example.MyClassExtractor.java

package org.example;
 
class MyClassExtractor extends org.eclipse.persistence.descriptors.ClassExtractor {
    /**
     * This method simply returns Employee.class.  Typically, the class to be 
     * returned would be based on the given Record.
     */
    public static Class extractClassFromRow(Record databaseRow, Session session) {
        return Employee.class;
    }
}

Testing

A new suite of tests will be added in the org.eclipse.persistence.testing.jaxb.externalizedmetadata.xmlclassextractor package to test the XML metadata portion of this feature.

Annotation/XML Metadata	Package
xml-class-extractor	org.eclipse.persistence.testing.jaxb.externalizedmetadata.xmlclassextractor
XmlClassExtractor

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	xml-class-extraction-method	We will not provide support for setting a class extraction method name on the InheritancePolicy. Please refer to this bug for additional information.