EclipseLink/DesignDocs/293925/MOXyExtensions/XmlTransformationMapping

XMLTransformationMapping

Requirements

Provide support for XML transformation mapping configuration via XML metadata file.

The following should be supported:

• Get/set method names
• Attribute Method
• Attribute Transformer
• Field transformer
• Field transformations
• Read only
• Write only
• Mutable

XML Schema

Following is the proposed schema change required to support Xml transformation mappings:

<xs:element name="xml-transformation" substitutionGroup="java-attribute">
    <xs:complexType>
        <xs:complexContent>
            <xs:extension base="java-attribute">
                <xs:all>
                    <xs:element ref="xml-access-methods" minOccurs="0" />
                    <xs:element name="field-transformations" minOccurs="0">
                        <xs:complexType>
                            <xs:sequence>
                                <xs:element name="field-transformation" maxOccurs="unbounded">
                                    <xs:complexType>
                                        <xs:attribute name="xml-path" type="xs:string" />
                                        <xs:attribute name="method-name" type="xs:string" />
                                    </xs:complexType>
                                </xs:element>
                            </xs:sequence>
                        </xs:complexType>
                    </xs:element>
                    <xs:element name="field-transformers" minOccurs="0">
                        <xs:complexType>
                            <xs:sequence>
                                <xs:element name="field-transformer" maxOccurs="unbounded">
                                    <xs:complexType>
                                        <xs:attribute name="xml-path" type="xs:string" />
                                        <xs:attribute name="transformer-class" type="xs:string" />
                                    </xs:complexType>
                                </xs:element>
                            </xs:sequence>
                        </xs:complexType>
                    </xs:element>
                </xs:all>
                <xs:attribute name="attribute-method" type="xs:string" />
                <xs:attribute name="attribute-transformer" type="xs:string" />
                <xs:attribute name="mutable" type="xs:boolean" default="false" />
                <xs:attribute name="read-only" type="xs:boolean" default="false" />
                <xs:attribute name="write-only" type="xs:boolean" default="false" />
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
</xs:element>

Example

The follow demonstrates how an XML transformation mapping can be configured via XML metadata:

org.example.Employee.java

package org.example;
 
import org.eclipse.persistence.oxm.annotations.FieldTransformation;
import org.eclipse.persistence.oxm.annotations.FieldTransformer;
import org.eclipse.persistence.oxm.annotations.XmlAccessMethods;
import org.eclipse.persistence.oxm.annotations.XmlTransformation;
 
public class Employee {
 
    @XmlTransformation(attribute-method="buildNameAttribute",
        field-transformations = {
            @FieldTransformation(xml-path="name/text()", method-name="buildNameField")
        }
    )*
    @XmlAccessMethods(get-method="getName", set-method="setName")*
    protected String name;
 
    @XmlTransformation(attribute-transformer="org.example.NormalHoursAttributeTransformer",
        field-transformers = {
            @FieldTransformer(xml-path="normal-hours/start-time/text()", 
                     transformer-class="org.example.StartTimeTransformer"),
            @FieldTransformer(xml-path="normal-hours/end-time/text()", 
                     transformer-class="org.example.EndTimeTransformer"),
        }
    )*
    @XmlAccessMethods(get-method="getNormalHours", set-method="setNormalHours")*
    protected String[] normalHours;
}

• Note that the XmlTransformation, FieldTransformation, XmlAccessMethods, and FieldTransformer annotations do not exist and are intended for example purposes only.

org\example\employee-oxm.xml

<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm" 
              xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <java-types>
        <java-type name="org.example.Employee">
            <java-attributes>
                <xml-transformation java-attribute="name" attribute-method="buildNameAttribute">
                    <field-transformations>
                        <field-transformation xml-path="name/text()" method-name="buildNameField" />
                    </field-transformations>
                    <xml-access-methods get-method="getName" set-method="setName" />
                </xml-transformation>
                <xml-transformation java-attribute="normalHours" attribute-transformer="org.example.NormalHoursAttributeTransformer">
                    <field-transformers>
                        <field-transformer xml-path="normal-hours/start-time/text()", transformer-class="org.example.StartTimeTransformer" />
                        <field-transformer xml-path="normal-hours/end-time/text()", transformer-class="org.example.EndTimeTransformer" />
                    </field-transformers>
                    <xml-access-methods get-method="getNormalHours" set-method="setNormalHours" />
                </xml-transformation>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

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