EclipseLink/DesignDocs/277920/Phase5

Phase 5 (page under construction)

Provide support for high level metadata.

Annotations

The following annotations will be targetted in this phase:

Annotation	Package	Type	Field	Method
XmlAnyAttribute			X	X
XmlMixed			X	X
XmlID			X	X
XmlIDREF			X	X
XmlBidirectional			X	X

Example: XmlID and XmlIDREF annotations

Java Metadata

The following example will demonstrate how the XmlID and XmlIDREF annotations can be applied:

org.example.Employee.java

package org.example;
 
@javax.xml.bind.annotation.XmlRootElement
public class Employee {
    public String name;
 
    @javax.xml.bind.annotation.XmlIDREF
    @javax.xml.bind.annotation.XmlElement(name="address-id")
    public Address address;
}

org.example.Address.java

package org.example;
 
@javax.xml.bind.annotation.XmlRootElement
public class Address {
    @javax.xml.bind.annotation.XmlID
    @javax.xml.bind.annotation.XmlAttribute(required=true)
    public String id;
 
    public String city;
}

XML Metadata

xml-id

If this is present in the XML then the associated property will be treated as an ID. To unset an @XmlID annotated property via xml, xml-element or xml-attribute can be used with an xml-id="false" entry, or none (the default is false).

xml-idref

If this is present in the XML then the associated property will be treated as an IDREF. To unset an @XmlIDREF annotated property via xml, xml-element or xml-attribute can be used with an xml-idref="false" entry, or none (the default is false).

org/example/eclipselink-oxm.xml

This XML file represents metadata overrides for the "org.example.Employee" and "org.example.Address" classes.

<?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="address" name="address-id" xml-idref="true" />
            </java-attributes>
        </java-type>
        <java-type name="org.example.Address">
            <xml-root-element name="address" />
            <java-attributes>
                <xml-attribute java-attribute="id" xml-id="true" required="true" />
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

Example: Unset XmlID via XML Metadata

Java Metadata

The following example will demonstrate how the XmlID annotation can be unset via XML metadata:

org.example.Address.java

package org.example;
 
@javax.xml.bind.annotation.XmlRootElement
public class Address {
    @javax.xml.bind.annotation.XmlID
    public String id;
 
    public String street;
    public String city;
    public String zip;
}

XML Metadata

xml-id

If this is present in the XML then the associated property will be treated as an ID. To unset an @XmlID annotated property via xml, xml-element or xml-attribute can be used with an xml-id="false" entry, or none (the default is false).

org/example/eclipselink-oxm.xml

This XML file represents metadata overrides for the "org.example.Address" class. Here, the @XmlID annotated property [id] will be unset.

<?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.Address">
            <xml-root-element name="address" />
            <java-attributes>
                <xml-attribute java-attribute="id" xml-id="false" />
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>

Example: XmlBidirectional annotation

Java Metadata

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

org.example.Employee.java

package org.example;
 
@javax.xml.bind.annotation.XmlRootElement
public class Employee {
    public String name;
 
    @javax.xml.bind.annotation.XmlIDREF
    @javax.xml.bind.annotation.XmlAttribute(name="address-id")
    @org.eclipse.persistence.oxm.annotations.XmlBidirectional(targetAttribute = "emp")
    public Address address;
}

org.example.Address.java

package org.example;
 
@javax.xml.bind.annotation.XmlRootElement
public class Address {
    @javax.xml.bind.annotation.XmlID
    @javax.xml.bind.annotation.XmlAttribute(required=true)
    public String id;
 
    @javax.xml.bind.annotation.XmlTransient
    public Employee emp;
}

XML Metadata

xml-bidirectional

Use this to indicate the name of a transient property on the target object of this property that refers back to the owning object.

org/example/eclipselink-oxm.xml

This XML file represents metadata overrides for the "org.example.Employee" and "org.example.Address" classes.

<?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-attribute java-attribute="address" name="address-id" xml-idref="true" xml-bidirectional="emp" />
            </java-attributes>
        </java-type>
        <java-type name="org.example.Address">
            <xml-root-element name="address" />
            <java-attributes>
                <xml-attribute java-attribute="id" xml-id="true" required="true" />
                <xml-transient java-attribute="emp"/>
            </java-attributes>
        </java-type>
    </java-types>
</xml-bindings>