Jump to: navigation, search

EclipseLink/UserGuide/MOXy/Runtime/Bootstrapping

EclipseLink MOXy

link="http://wiki.eclipse.org/EclipseLink"
EclipseLink
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source

Elug api package icon.png Key API

Bootstrapping

EclipseLink MOXy offers several options when creating your JAXBContext. You have the option of bootstrapping from:

  • A list of one or more JAXB-annotated Classes
  • A list of one or more EclipseLink OXM Bindings Files defining the mappings for your Java classes
  • A combination of classes and OXM files
  • A list of context paths
  • A list of Session names, referring to EclipseLink Sessions defined in sessions.xml


JAXBContext API

The following methods on JAXBContext are used to create new instances:

public static JAXBContext newInstance(Class... classesToBeBound) throws JAXBException
 
public static JAXBContext newInstance(Class[] classesToBeBound, Map<String,?> properties) throws JAXBException
 
public static JAXBContext newInstance(String contextPath) throws JAXBException
 
public static JAXBContext newInstance(String contextPath, ClassLoader classLoader) throws JAXBException
 
public static JAXBContext newInstance(String contextPath, ClassLoader classLoader, Map<String,?> properties) throws JAXBException
  • classesToBeBound - List of Java classes to be recognized by the new JAXBContext.
  • contextPath - List of Java package names (or EclipseLink session names) that contain mapped classes.
  • classLoader - The class loader used to locate the mapped classes.
  • properties - A map of additional properties.


The APIs above expect to find a jaxb.properties file in your Java package/context path. For more information see Specifying the EclipseLink Runtime.


Bootstrapping from Classes

If you already have a collection of Java Classes annotated with JAXB annotations, you can provide a list of these Classes directly:

JAXBContext context = JAXBContext.newInstance(Company.class, Employee.class);

Other classes that are reachable from the classes in the array (for example, referenced classes, super class) will automatically be recognized by the JAXBContext. Subclasses or classes marked as @XmlTransient will not be recognized.


Bootstrapping from a Context Path

Another way to bootstrap your JAXBContext is with a String, called the "context path". This is a colon-delimited list of package names containing your mapped classes:

JAXBContext context = JAXBContext.newInstance("example");

Using this approach, there are a few different ways that EclipseLink will discover your model classes:


jaxb.index

The context path could contain a file named jaxb.index, which is a simple text file containing the class names from the current package that will be brought into the JAXBContext:

src/example/jaxb.index:

Employee
PhoneNumber

Other classes that are reachable from the classes in list (for example, referenced classes, super class) will automatically be recognized by the JAXBContext. Subclasses or classes marked as @XmlTransient will not be recognized.


ObjectFactory

The context path could also contain a class called ObjectFactory, which is a special factory class that JAXB will look for. This class contains create() methods for each of the types in your model. Typically the ObjectFactory will be generated by the JAXB Compiler, but one can be written by hand as well.

src/example/ObjectFactory.java:

@XmlRegistry
public class ObjectFactory {
 
    private final static QName _Employee_QNAME = new QName("", "employee");
    private final static QName _PhoneNumber_QNAME = new QName("", "phone-number");
 
    public ObjectFactory() {
    }
 
    public EmployeeType createEmployeeType() {
        return new EmployeeType();
    }
 
    @XmlElementDecl(namespace = "", name = "employee")
    public JAXBElement<EmployeeType> createEmployee(EmployeeType value) {
        return new JAXBElement<EmployeeType>(_Employee_QNAME, EmployeeType.class, null, value);
    }
 
    public PhoneNumberType createPhoneNumberType() {
        return new PhoneNumberType();
    }
 
    @XmlElementDecl(namespace = "", name = "phone-number")
    public JAXBElement<PhoneNumberType> createPhoneNumber(PhoneNumberType value) {
        return new JAXBElement<PhoneNumberType>(_PhoneNumber_QNAME, PhoneNumberType.class, null, value);
    }
 
}

MetadataSource

EclipseLink MOXy also has the ability to retrieve mapping information from an implementation of EclipseLink's MetadataSource. Using this approach, you are responsible for creating your own XmlBindings.

package org.eclipse.persistence.jaxb.metadata;
 
public interface MetadataSource {
 
    /**
     * @param properties - The properties passed in to create the JAXBContext
     * @param classLoader - The ClassLoader passed in to create the JAXBContext
     * 
     * @return the XmlBindings object representing the metadata
     */
    XmlBindings getXmlBindings(Map<String, ?> properties, ClassLoader classLoader);
 
}


Bootstrapping from EclipseLink OXM

If you would like to have more control over how your classes will be mapped to XML, you can instead bootstrap from an EclipseLink OXM bindings file. Using this approach, you can take advantage of EclipseLink's robust mappings framework and customize how each complex type in XML maps to its Java counterpart.

Links to the actual OXM files are passed in via the properties parameter, using a special key, JAXBContextFactory.ECLIPSELINK_OXM_XML_KEY. The value of this key will be a handle to the OXM metadata file, in the form of one of the following:

  • java.io.File
  • java.io.InputStream
  • java.io.Reader
  • java.net.URL
  • javax.xml.stream.XMLEventReader
  • javax.xml.stream.XMLStreamReader
  • javax.xml.transform.Source
  • org.w3c.dom.Node
  • org.xml.sax.InputSource


When bootstrapping from OXM, the package specified by contextPath must contain a jaxb.properties file that specifies the EclipseLink JAXBContextFactory.

InputStream iStream = myClassLoader.getResourceAsStream("example/eclipselink-oxm.xml");
 
Map<String, Object> properties = new HashMap<String, Object>();
properties.put(JAXBContextFactory.ECLIPSELINK_OXM_XML_KEY, iStream);
 
JAXBContext context = JAXBContext.newInstance("example", myClassLoader, properties);


Combining Annotated Classes and EclipseLink OXM

When bootstrapping from annotated classes, additional mapping information can be provided with an EclipseLink OXM file. For instance, you might annotate your model classes with JAXB-spec-only annotations, and put your EclipseLink-specific mapping customizations into an OXM file (negating the need to import EclipseLink annotations in your model classes).

For example, note the annotated Employee class below:

package example;
 
import javax.xml.bind.annotation.*;
 
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Employee {
   @XmlElement(name="phone-number")
   private PhoneNumber phoneNumber;
 
   ...
}

We could customize our Employee to use an EclipseLink XMLAdapter for marshalling/unmarshalling PhoneNumbers using the following OXM file:

<?xml version="1.0" encoding="US-ASCII"?>
<xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm">
  <java-types>
    <java-type name="example.Employee">
      <java-attributes>
        <xml-element java-attribute="phoneNumber">
          <xml-java-type-adapter value="example.util.PhoneNumberProcessor"/>
        </xml-element>
      </java-attributes>
    </java-type>
  </java-types>
</xml-bindings>

Finally, we pass both the list of annotated classes and the link to the OXM file to the JAXBContext:

InputStream iStream = myClassLoader.getResourceAsStream("example/eclipselink-oxm.xml");
 
Map<String, Object> properties = new HashMap<String, Object>();
properties.put(JAXBContextFactory.ECLIPSELINK_OXM_XML_KEY, iStream);
 
Class[] classes = new Class[] { Company.class, Employee.class };
JAXBContext context = JAXBContext.newInstance(classes, properties);

For more information on the OXM file format, see: