Skip to main content

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.

Jump to: navigation, search

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

m (Replacing page with ''''Warning For the current release, see [http://www.eclipse.org/eclipselink/documentation/2.4/moxy Developing JAXB Applications Using EclipseLink ...')
 
(26 intermediate revisions by 2 users 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 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 of '''JAXBContexts''':
+
 
+
<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 that contain mapped classes.
+
* '''classLoader''' - The class loader used to locate the mapped classes.
+
* '''properties''' - A map of additional properties.
+
 
+
 
+
== 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>
+
 
+
 
+
== 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.  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>
+
 
+
=== 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 XSD-to-Java Compiler (xjc), 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>
+
 
+
=== sessions.xml ===
+
 
+
EclipseLink MOXy also allows you to specify your mapping information in EclipseLink's legacy '''session.xml''' file.  In this case, the context path will be a colon-delimited list of EclipseLink '''Session''' names.
+
 
+
<tt>sessions.xml</tt>
+
<source lang="xml">
+
<?xml version="1.0" encoding="US-ASCII"?>
+
<sessions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="file://xsd/eclipselink_sessions_1.0.xsd" version="0">
+
    <session xsi:type="database-session">
+
        <name>example.moxy.project</name>
+
        <primary-project xsi:type="class">example.mappings.EclipseLinkProject</primary-project>
+
    </session>
+
</sessions>
+
 
+
</source>
+
 
+
== 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'''.
+
 
+
<source lang="java">
+
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);
+
</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

Back to the top