EclipseLink/DesignDocs/293925/Phase7

Phase 7 - Schema Customization

Allow customized mapping to an XML Schema built in type.

Annotations

The following annotations will be targetted in this phase:

Annotation	XML Metadata Tag	Package	Type	Field	Method
XmlSchemaType	xml-schema-type	X		X	X
XmlSchemaTypes	xml-schema-types	X

Example: XmlSchemaType Annotation - Package Level

Java Metadata

The following example will demonstrate how the XmlSchemaType annotation can be applied at the package level:

org.example.package-info.java

@javax.xml.bind.annotation.XmlSchemaType(name="date", type=java.util.GregorianCalendar.class)
package org.example;

org.example.Employee.java

package org.example;
 
@javax.xml.bind.annotation.XmlRootElement
public class Employee {
    @javax.xml.bind.annotation.XmlElement
    public java.util.GregorianCalendar hireDate;
}

XML Metadata

xml-schema-type

If this is present in XML, an existing Java type to simple schema built-in type mapping (from @XmlSchemaTypes/@XmlSchemaType annotation or xml-schema-type metadata) with a matching type class name will be replaced. Otherwise, the value/type pair defined in XML will be mapped in addition to any existing mappings.

org/example/eclipselink-oxm.xml

This XML file represents metadata overrides for the "org.example.Employee" class.

<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
    <xml-schema-type name="date" type="java.util.GregorianCalendar" />
    <java-types>
        <java-type name="org.example.Employee">
            <xml-root-element name="employee" />
            <java-attributes>
                <xml-element java-attribute="hireDate" />
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

Example: XmlSchemaType Annotation - Property Level

Java Metadata

The following example will demonstrate how the XmlSchemaType annotation can be applied at the property level:

org.example.Employee.java

package org.example;
 
@javax.xml.bind.annotation.XmlRootElement
public class Employee {
    @javax.xml.bind.annotation.XmlElement
    @javax.xml.bind.annotation.XmlSchemaType(name="date")
    public java.util.GregorianCalendar hireDate;
}

XML Metadata

xml-schema-type

If this is present in XML, the corresponding annotation will be completely replaced.

org/example/eclipselink-oxm.xml

This XML file represents metadata overrides for the "org.example.Employee" class.

<?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">
            <xml-root-element name="employee" />
            <java-attributes>
                <xml-element java-attribute="hireDate">
                    <xml-schema-type name="date" />
                </xml-element>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

Example: XmlSchemaTypes Annotation

Java Metadata

The following example will demonstrate how the XmlSchemaTypes annotation can be applied:

org.example.package-info.java

@javax.xml.bind.annotation.XmlSchemaTypes({
    @javax.xml.bind.annotation.XmlSchemaType(name="date", type=java.util.GregorianCalendar.class),
    @javax.xml.bind.annotation.XmlSchemaType(name="int", type=java.math.BigDecimal.class)
})
package org.example;
}

org.example.Employee.java

package org.example;
 
@javax.xml.bind.annotation.XmlRootElement
public class Employee {
    public java.util.GregorianCalendar hireDate;
    public java.math.BigDecimal lengthOfEmployment;
}

XML Metadata

xml-schema-types

If this is present in XML, any existing Java type to simple schema built-in type mappings (from @XmlSchemaTypes/@XmlSchemaType annotation) with matching type class names will be replaced. Otherwise, each value/type pair defined in XML will be mapped in addition to any defined via annotations.

org/example/eclipselink-oxm.xml

This XML file represents metadata overrides for the "org.example.Employee" class.

<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
    <xml-schema-types>
        <xml-schema-type name="date" type="java.util.GregorianCalendar" />
        <xml-schema-type name="int" type="java.math.BigDecimal" />
    </xml-schema-types>
    <java-types>
        <java-type name="org.example.Employee">
            <xml-root-element name="employee" />
        </java-type>
    </java-types>
</xml-bindings>