Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
EclipseLink/DesignDocs/277920/Phase1
Phase 1
Provide support for boot strapping the JAXBContext.
Annotations
The following annotations will be targetted in this phase:
Annotation | Package | Type | Field | Method |
---|---|---|---|---|
XmlNs | ||||
XmlSchema | X | |||
XmlSeeAlso | X | |||
XmlTransient | 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 - Default
When a JAXBContext is created, an eclipselink-oxm.xml file will be looked for in each of the relevant packages.
In this example both org/example/customer/eclipselink-oxm.xml and org/example/employee/eclipselink-oxm.xml will be looked for:
JAXBContext jaxbContext = JAXBContext.newInstance("org.example.customer:org.example.employee");
In this example both org/example/customer/eclipselink-oxm.xml and org/example/employee/eclipselink-oxm.xml will be looked for:
Class[] classes = new Class[2]; classes[0] = org.example.customer.Customer.class; classes[1] = org.example.employee.Employee.class; JAXBContext jaxbContext = JAXBContext.newInstance(classes);
Bootstrapping - Specifying Source of XML Overrides
The source of the XML override metadata can be passed to the JAXBContext at creation time. If an XML override is specified for a package then the default file is not checked. In the example below "org/example/customer/eclipselink-oxm.xml" will not be looked for, but "org/example/employee/eclipselink-oxm.xml" will be:
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.
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>