Difference between revisions of "EclipseLink/UserGuide/MOXy/Runtime/Bootstrapping"

From Eclipsepedia

Jump to: navigation, search
m (Replacing page with ''''Warning For the current release, see [http://www.eclipse.org/eclipselink/documentation/2.4/moxy Developing JAXB Applications Using EclipseLink ...')
 
(One intermediate revision by one user not shown)
Line 1: Line 1:
{{EclipseLink_UserGuide
+
'''[[Image:Elug_draft_icon.png|Warning]] For the current release, see [http://www.eclipse.org/eclipselink/documentation/2.4/moxy Developing JAXB Applications Using EclipseLink MOXy, EclipseLink 2.4]
|eclipselink=y
+
'''
|eclipselinktype=MOXy
+
|info=y
+
|toc=y
+
|api=y
+
|apis= * [http://www.eclipse.org/eclipselink/api/latest/javax/xml/bind/JAXBContext.html JAXBContext]
+
}}
+
  
= Bootstrapping =
+
http://www.eclipse.org/eclipselink/documentation/2.4/moxy/runtime002.htm
 
+
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 XML Bindings documents defining the mappings for your Java classes
+
* A combination of classes and XML Bindings
+
* 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:
+
 
+
<source lang="java">
+
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
+
</source>
+
 
+
* '''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 [[EclipseLink/UserGuide/MOXy/Runtime/Specifying the EclipseLink Runtime|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:
+
 
+
<source lang="java">
+
JAXBContext context = JAXBContext.newInstance(Company.class, Employee.class);
+
</source>
+
 
+
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:
+
 
+
<source lang="java">
+
JAXBContext context = JAXBContext.newInstance("example");
+
</source>
+
 
+
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''':
+
 
+
<tt>src/example/jaxb.index</tt>:
+
<source lang="text">
+
Employee
+
PhoneNumber
+
</source>
+
 
+
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.
+
 
+
<tt>src/example/ObjectFactory.java</tt>:
+
<source lang="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);
+
    }
+
 
+
}
+
</source>
+
 
+
=== 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'''.
+
 
+
<source lang="java">
+
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);
+
 
+
}
+
</source>
+
 
+
 
+
For information on using a '''MetadataSource''', see:
+
 
+
* [[EclipseLink/UserGuide/MOXy/Runtime/MetadataSource|MetadataSource]]
+
 
+
 
+
== Bootstrapping from EclipseLink XML Bindings ==
+
 
+
If you would like to have more control over how your classes will be mapped to XML, you can instead bootstrap from an EclipseLink XML Bindings document. 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 documents are passed in via the '''properties''' parameter, using a special key, '''JAXBContextFactory.ECLIPSELINK_OXM_XML_KEY''':
+
 
+
<source lang="java">
+
InputStream iStream = myClassLoader.getResourceAsStream("example/xml-bindings.xml");
+
+
Map<String, Object> properties = new HashMap<String, Object>();
+
properties.put(JAXBContextFactory.ECLIPSELINK_OXM_XML_KEY, iStream);
+
+
JAXBContext context = JAXBContext.newInstance(new Class[]{ Customer.class }, properties);
+
</source>
+
 
+
 
+
For more information on the XML Bindings format, see:
+
 
+
* [[EclipseLink/UserGuide/MOXy/Runtime/XML_Bindings|XML Bindings]]
+
 
+
 
+
== Combining Annotated Classes and XML Bindings ==
+
 
+
When bootstrapping from annotated classes, additional mapping information can be provided with an EclipseLink XML Bindings document.  For instance, you might annotate your model classes with JAXB-spec-only annotations, and put your EclipseLink-specific mapping customizations into an XML Bindings document (negating the need to import EclipseLink annotations in your model classes).
+
 
+
For example, note the annotated '''Employee''' class below:
+
 
+
<source lang="java">
+
package example;
+
 
+
import javax.xml.bind.annotation.*;
+
 
+
@XmlRootElement
+
@XmlAccessorType(XmlAccessType.FIELD)
+
public class Employee {
+
  @XmlElement(name="phone-number")
+
  private PhoneNumber phoneNumber;
+
 
+
  ...
+
}
+
</source>
+
 
+
We could customize our '''Employee''' to use an EclipseLink '''XMLAdapter''' for marshalling/unmarshalling '''PhoneNumbers''' using the following XML Bindings:
+
 
+
<source lang="xml">
+
<?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>
+
</source>
+
 
+
Finally, we pass both the list of annotated classes and the link to the XML Bindings to the '''JAXBContext''':
+
 
+
<source lang="java">
+
InputStream iStream = myClassLoader.getResourceAsStream("example/xml-bindings.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);
+
</source>
+

Latest revision as of 16:26, 6 November 2012

Warning For the current release, see Developing JAXB Applications Using EclipseLink MOXy, EclipseLink 2.4

http://www.eclipse.org/eclipselink/documentation/2.4/moxy/runtime002.htm