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

NOTE: Changes Required

The XML Schema and Annotations suggested below will need to be reworked to be inline with JPA. Essentially, we will want to use read/write transformers instead of field/attribute, and create applicable element/attribute schema components as per the following (from eclipselink-orm.xml):

  <xsd:complexType name="transformation">
    <xsd:sequence>
      <xsd:element name="read-transformer" type="orm:read-transformer"/>
      <xsd:element name="write-transformer" type="orm:write-transformer" minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="access" type="orm:access-type" minOccurs="0"/>
      <xsd:element name="property" type="orm:property" minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="access-methods" type="orm:access-methods" minOccurs="0" maxOccurs="1"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="fetch" type="orm:fetch-type"/>
    <xsd:attribute name="optional" type="xsd:boolean"/>
    <xsd:attribute name="access" type="orm:access-type"/>
    <xsd:attribute name="mutable" type="xsd:boolean"/>
    <xsd:attribute name="attribute-type" type="xsd:string"/>
  </xsd:complexType>
 
  <xsd:complexType name="read-transformer">
    <xsd:attribute name="transformer-class" type="xsd:string"/>
    <xsd:attribute name="method" type="xsd:string"/>
  </xsd:complexType>
 
  <xsd:complexType name="write-transformer">
    <xsd:sequence>
      <xsd:element name="column" type="orm:column"/>
    </xsd:sequence>
    <xsd:attribute name="transformer-class" type="xsd:string"/>
    <xsd:attribute name="method" type="xsd:string"/>
  </xsd:complexType>
 
  <xsd:simpleType name="access-type">
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="PROPERTY"/>
      <xsd:enumeration value="FIELD"/>
      <xsd:enumeration value="VIRTUAL"/>
    </xsd:restriction>
  </xsd:simpleType>
 
  <xsd:complexType name="property">
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="value" type="xsd:string" use="required"/>
    <xsd:attribute name="value-type" type="xsd:string"/>
  </xsd:complexType>
 
  <xsd:simpleType name="fetch-type">
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="LAZY"/>
      <xsd:enumeration value="EAGER"/>
    </xsd:restriction>
  </xsd:simpleType>
 
  <xsd:complexType name="column">
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="unique" type="xsd:boolean"/>
    <xsd:attribute name="nullable" type="xsd:boolean"/>
    <xsd:attribute name="insertable" type="xsd:boolean"/>
    <xsd:attribute name="updatable" type="xsd:boolean"/>
    <xsd:attribute name="column-definition" type="xsd:string"/>
    <xsd:attribute name="table" type="xsd:string"/>
    <xsd:attribute name="length" type="xsd:int"/>
    <xsd:attribute name="precision" type="xsd:int"/>
    <xsd:attribute name="scale" type="xsd:int"/>
  </xsd:complexType>
 
  <xsd:complexType name="access-methods">
    <xsd:attribute name="get-method" type="xsd:string" use="required"/>
    <xsd:attribute name="set-method" type="xsd:string" use="required"/>
  </xsd:complexType>

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