EclipseLink/DesignDocs/277920/Phase1

Phase 1 - Bootstrapping

Provide support for boot strapping the JAXBContext.

Annotations

The following annotations will be targetted in this phase:

Annotation	XML Metadata Tag	Package	Type	Field	Method
XmlNs	xml-ns
XmlSchema	xml-schema	X
XmlSeeAlso	xml-see-also		X
XmlTransient	xml-transient		X	X	X

Java Metadata

The following example will demonstrate how these annotations can be applied to Java classes:

org.example.customer.package-info.java

@XmlSchema(
        elementFormDefault=XmlNsForm.QUALIFIED,
        attributeFormDefault=XmlNsForm.UNQUALIFIED,
        namespace="urn:customer",
        xmlns={@XmlNs(prefix="ns1", namespaceURI="urn:customer")})
package org.example.customer;
 
import javax.xml.bind.annotation.XmlNs;
import javax.xml.bind.annotation.XmlNsForm;
import javax.xml.bind.annotation.XmlSchema;

org.example.customer.Person

package org.example.customer;
 
import javax.xml.bind.annotation.XmlTransient;
 
@XmlTransient
public abstract class Person {
 
    private int id;
    private String name;
 
    @XmlTransient
    public int getId() {
        return id;
    }
 
    public void setId(int id) {
        this.id = id;
    }
 
    public String getName() {
        return name;
    }
 
    public void setName(String name) {
        this.name = name;
    }
 
}

org.example.customer.Customer

package org.example.customer;
 
import javax.xml.bind.annotation.XmlSeeAlso;
import org.example.employee.Employee;
 
@XmlSeeAlso({Employee.class})
public class Customer extends Person {
 
    private int customerId;
 
    public int getCustomerId() {
        return customerId;
    }
 
    public void setCustomerId(int customerId) {
        this.customerId = customerId;
    }
 
}

org.example.employee.Employee

package org.example.employee;
 
import org.example.customer.Person;
 
public class Employee extends Person {
}

XML Metadata

Bootstrapping - Specifying Source of XML Overrides

The source of the XML override metadata is to be passed to the JAXBContext at creation time.

Map<String, Source> xmlOverrides = new HashMap<String, Source>();
StreamSource customerOverrides = new StreamSource(new File("customer-override.xml"));
xmlOverrides.put("org.example.customer", customerOverrides);
 
Map<String, Object> properties = new HashMap<String, Object>();
properties.put("eclipselink-oxm-xml", xmlOverrides);
 
JAXBContext jaxbContext = JAXBContext.newInstance("org.example.customer:org.example.employee", aClassLoader, properties);

xml-schema & xml-ns

If this is present in the XML then it completely replaces the corresponding annotation.

xml-transient

If this is present in the XML then it completely replaces the corresponding annotation. It can also be used to remove a transient annotation at the type level.

xml-see-also

If this is present in the XML then it completely replaces the corresponding annotation.

org/example/customer/eclipselink-oxm.xml

This XML file represents metadata overrides for classes in the "org.example.customer" package.

<?xml version="1.0" encoding="UTF-8"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
    <xml-schema
        element-form-default="QUALIFIED"
        attribute-form-default="UNQUALIFIED"
        namespace="urn:customer">
        <xml-ns prefix="ns1" namespace-uri="urn:customer" />
    </xml-schema>
    <java-types>
        <java-type name="Person" xml-transient="true">
            <java-attributes>
                <xml-transient java-attribute="id"/>
            </java-attributes>
        </java-type>
        <java-type name="Customer">
            <xml-see-also>org.example.employee.Employee</xml-see-also>
        </java-type>
    </java-types>
</xml-bindings>