blob: d6872dda47fc46ccd83c5c6c558d0f79a4447348 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<title>Bootstrapping | EclipseLink 2.7 EclipseLink MOXy</title>
<meta name="generator" content="Oracle DARB XHTML Converter (Mode = document) - Version 1.0.22 Build 1" />
<meta name="date" content="2014-06-10T10:25:31Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="Bootstrapping" />
<meta name="relnum" content="Release 2.7" />
<meta name="partnum" content="" />
<link rel="stylesheet" type="text/css" href="../../dcommon/style.css" media="screen" />
<link rel="copyright" href="../../dcommon/html/cpyr.htm" title="Copyright" type="text/html" />
<link rel="start" href="../../index.htm" title="Home" type="text/html" />
<link rel="contents" href="toc.htm" title="Contents" type="text/html" />
<link rel="prev" href="runtime001.htm" title="Previous" type="text/html" />
<link rel="next" href="runtime003.htm" title="Next" type="text/html" />
<!-- START: Disqus --><script type="text/javascript"> var disqus_developer = 0; </script><!-- END: Disqus --><!-- START: Sharethis --><script type="text/javascript">var switchTo5x=true;</script><script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script><script type="text/javascript" src="http://s.sharethis.com/loader.js"></script> <!-- END: Sharethis --></head>
<body bgcolor="#FFFFFF"><iframe id="docheader" frameborder="0" framemargin="0" scrolling="no" src="../../dcommon/header.html"></iframe><script src="http://www.google.com/jsapi" type="text/javascript"></script><script type="text/javascript"> google.load('search', '1', {language : 'en'}); google.setOnLoadCallback(function() { var customSearchOptions = {}; var googleAnalyticsOptions = {}; googleAnalyticsOptions['queryParameter'] = 'q'; googleAnalyticsOptions['categoryParameter'] = ''; customSearchOptions['googleAnalyticsOptions'] = googleAnalyticsOptions; var customSearchControl = new google.search.CustomSearchControl( '016171230611334810008:1hjujor5_fg', customSearchOptions); customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET); var options = new google.search.DrawOptions(); options.setSearchFormRoot('cse-search-form'); customSearchControl.draw('cse', options); }, true);</script><link rel="stylesheet" href="http://www.google.com/cse/style/look/default.css" type="text/css" /><div id="cse" style="width:100%;"></div>
<div class="header"><a id="top" name="top"></a>
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td align="left" valign="top"><div class="booktitle">Developing JAXB Applications Using EclipseLink MOXy,
<b>Release 2.7</b><br /></font></td>
<td valign="bottom" align="right" width="144">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
</td><td>&nbsp;</td><td align="center"><a href="../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../eclipselink_moxy.pdf" title="PDF" target="_blank"><img src="../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td>
</tr>
</table>
</td>
</tr>
</table>
<hr />
<table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
<tr>
<td align="center"><a href="runtime001.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="runtime003.htm"><img src="../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
<td>&nbsp;</td>
</tr>
</table>
</div>
<!-- class="header" -->
<div class="ind"><!-- End Header --><a id="CACEJGAI" name="CACEJGAI"></a><a id="TLJAX119" name="TLJAX119"></a>
<div class="sect1"><!-- infolevel="all" infotype="General" -->
<h1 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">Bootstrapping</font></h1>
<p>EclipseLink MOXy offers several options when creating your <code>JAXBContext</code>. You have the option of bootstrapping from:</p>
<ul>
<li>
<p>A list of one or more JAXB-annotated classes</p>
</li>
<li>
<p>A list of one or more EclipseLink XML bindings documents defining the mappings for your Java classes</p>
</li>
<li>
<p>A combination of classes and XML bindings</p>
</li>
<li>
<p>A list of context paths</p>
</li>
<li>
<p>A list of session names, referring to EclipseLink sessions defined in <code>sessions.xml</code></p>
</li>
</ul>
<a id="TLJAX120" name="TLJAX120"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref11" name="sthref11"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Using the JAXBContext API</font></h2>
<p>The methods on <code>JAXBContext</code> (shown in <a href="#CACIIJCH">Example 2-1</a>) are used to create new instances.</p>
<div class="example"><a id="CACIIJCH" name="CACIIJCH"></a><a id="TLJAX121" name="TLJAX121"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-1 JAXBContext Methods</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
public static JAXBContext newInstance(Class... <strong>classesToBeBound</strong>) throws JAXBException
public static JAXBContext newInstance(Class[] <strong>classesToBeBound</strong>, Map&lt;String,?&gt; properties) throws JAXBException
public static JAXBContext newInstance(String <strong>contextPath</strong>) throws JAXBException
public static JAXBContext newInstance(String <strong>contextPath</strong>, ClassLoader <strong>classLoader</strong>) throws JAXBException
public static JAXBContext newInstance(String <strong>contextPath</strong>, ClassLoader <strong>classLoader</strong>, Map&lt;String,?&gt; <strong>properties</strong>) throws JAXBException
</pre></div>
<!-- class="example" -->
<p><code>JAXBContext</code> accepts the following options:</p>
<ul>
<li>
<p><strong>classesToBeBound</strong> &ndash; List of Java classes to be recognized by the new <code>JAXBContext</code></p>
</li>
<li>
<p><strong>contextPath</strong> &ndash; List of Java package names (or EclipseLink session names) that contain mapped classes</p>
</li>
<li>
<p><strong>classLoader</strong> &ndash; The class loader used to locate the mapped classes</p>
</li>
<li>
<p><strong>properties</strong> &ndash; A map of additional properties.</p>
</li>
</ul>
<p>The APIs in <a href="#CACIIJCH">Example 2-1</a> expect to find a <code>jaxb.properties</code> file in your Java package/context path. For more information see <a href="runtime001.htm#CACFEGHC">"Specifying the EclipseLink Runtime"</a>.</p>
</div>
<!-- class="sect2" -->
<a id="CACGJHHB" name="CACGJHHB"></a><a id="TLJAX122" name="TLJAX122"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Bootstrapping from Classes</font></h2>
<p>If you have a collection of Java classes annotated with JAXB annotations, you can provide a list of these classes directly:</p>
<pre xml:space="preserve" class="oac_no_warn">
JAXBContext context = JAXBContext.newInstance(Company.class, Employee.class);
</pre>
<p>Other classes that are reachable from the classes in the array (for example, referenced classes, super class) will automatically be recognized by the <code>JAXBContext</code>. Subclasses or classes marked as <code>@</code><code>XmlTransient</code> will not be recognized.</p>
</div>
<!-- class="sect2" -->
<a id="CACGGBJG" name="CACGGBJG"></a><a id="TLJAX123" name="TLJAX123"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Bootstrapping from a Context Path</font></h2>
<p>Another way to bootstrap your <code>JAXBContext</code> is with a <code>String</code>, called the <em>context path</em>. This is a colon-delimited list of package names containing your mapped classes:</p>
<pre xml:space="preserve" class="oac_no_warn">
JAXBContext context = JAXBContext.newInstance("example");
</pre>
<p>Using this approach, there are a few different ways that EclipseLink will discover your model classes:</p>
<ul>
<li>
<p><a href="#CACJBEFE">Using a <code>jaxb.index</code> File</a></p>
</li>
<li>
<p><a href="#CACGECEG">Using an ObjectFactory</a></p>
</li>
<li>
<p><a href="#CACHAFIB">Using MetadataSource</a></p>
</li>
</ul>
<a id="CACJBEFE" name="CACJBEFE"></a><a id="TLJAX124" name="TLJAX124"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Using a <code>jaxb.index</code> File</font></h3>
<p>The context path could contain a file named <code>jaxb.index</code>, which is a simple text file containing the class names from the current package that will be brought into the <code>JAXBContext</code>:</p>
<pre xml:space="preserve" class="oac_no_warn">
src/example/jaxb.index:
</pre>
<div class="example"><a id="TLJAX125" name="TLJAX125"></a><a id="sthref12" name="sthref12"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-2 Sample jaxb.index File</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
Employee
PhoneNumber
</pre></div>
<!-- class="example" -->
<p>Other classes that are reachable from the classes in list (for example, referenced classes, super class) will automatically be recognized by the <code>JAXBContext</code>. Subclasses or classes marked as <code>@XmlTransient</code> will not be recognized.</p>
</div>
<!-- class="sect3" -->
<a id="CACGECEG" name="CACGECEG"></a><a id="TLJAX126" name="TLJAX126"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Using an ObjectFactory</font></h3>
<p>The context path could also contain a class called <code>ObjectFactory</code>, which is a special factory class that JAXB will look for. This class contains <code>create()</code> methods for each of the types in your model. Typically the <code>ObjectFactory</code> will be generated by the JAXB compiler, but one can be written by hand as well.</p>
<pre xml:space="preserve" class="oac_no_warn">
src/example/ObjectFactory.java:
</pre>
<div class="example"><a id="TLJAX127" name="TLJAX127"></a><a id="sthref13" name="sthref13"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-3 Sample ObjectFactory</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
@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 <strong>createEmployeeType</strong>() {
return new EmployeeType();
}
@XmlElementDecl(namespace = "", name = "employee")
public JAXBElement&lt;EmployeeType&gt; createEmployee(EmployeeType value) {
return new JAXBElement&lt;EmployeeType&gt;(_Employee_QNAME, EmployeeType.class, null, value);
}
public PhoneNumberType <strong>createPhoneNumberType</strong>() {
return new PhoneNumberType();
}
@XmlElementDecl(namespace = "", name = "phone-number")
public JAXBElement&lt;PhoneNumberType&gt; <strong>createPhoneNumber</strong>(PhoneNumberType value) {
return new JAXBElement&lt;PhoneNumberType&gt;(_PhoneNumber_QNAME, PhoneNumberType.class, null, value);
}
}
</pre></div>
<!-- class="example" --></div>
<!-- class="sect3" -->
<a id="CACHAFIB" name="CACHAFIB"></a><a id="TLJAX128" name="TLJAX128"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Using MetadataSource</font></h3>
<p>EclipseLink MOXy also has the ability to retrieve mapping information from an implementation of EclipseLink's <code>MetadataSource</code>. Using this approach, you are responsible for creating your own <code>XmlBindings</code>.</p>
<div class="example"><a id="TLJAX129" name="TLJAX129"></a><a id="sthref14" name="sthref14"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-4 Sample Metadata Source</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
package org.eclipse.persistence.jaxb.metadata;
public interface MetadataSource {
/**
* @param properties &ndash; The properties passed in to create the JAXBContext
* @param classLoader &ndash; The ClassLoader passed in to create the JAXBContext
*
* @return the XmlBindings object representing the metadata
*/
<strong>XmlBindings</strong> getXmlBindings(Map&lt;String, ?&gt; properties, ClassLoader classLoader);
}
</pre></div>
<!-- class="example" -->
<p>For information on using a MetadataSource, see <a href="runtime004.htm#CACDDJHJ">"Using MetadataSource"</a>.</p>
</div>
<!-- class="sect3" --></div>
<!-- class="sect2" -->
<a id="CACFIEIB" name="CACFIEIB"></a><a id="TLJAX130" name="TLJAX130"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Bootstrapping from EclipseLink XML Bindings</font></h2>
<p>To have more control over how your classes will be mapped to XML, you can 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.</p>
<p>Links to the actual documents are passed in via the <strong>properties</strong> parameter, using a special key, <code>JAXBContextProperties.OXM_METADATA_SOURCE</code>:</p>
<div class="example"><a id="TLJAX131" name="TLJAX131"></a><a id="sthref15" name="sthref15"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-5 Using an EclipseLink Bindings Document</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
InputStream iStream = myClassLoader.getResourceAsStream("example/xml-bindings.xml");
Map&lt;String, Object&gt; properties = new HashMap&lt;String, Object&gt;();
properties.put(<strong>JAXBContextProperties.OXM_METADATA_SOURCE</strong>, iStream);
JAXBContext context = JAXBContext.newInstance(new Class[]{ Customer.class }, properties);
</pre></div>
<!-- class="example" -->
<p>For more information on the XML Bindings format, see <a href="runtime003.htm#CACHCHAE">"Using XML Bindings"</a>.</p>
</div>
<!-- class="sect2" -->
<a id="TLJAX132" name="TLJAX132"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref16" name="sthref16"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Combining Annotated Classes and XML Bindings</font></h2>
<p>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).</p>
<p>For example, review the annotated <code>Employee</code> class in <a href="#CACHBAEJ">Example 2-6</a>.</p>
<div class="example"><a id="CACHBAEJ" name="CACHBAEJ"></a><a id="TLJAX133" name="TLJAX133"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-6 Sample Java Class</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
package example;
import javax.xml.bind.annotation.*;
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Employee {
@XmlElement(name="phone-number")
private PhoneNumber phoneNumber;
...
}
</pre></div>
<!-- class="example" -->
<p>You can customize the <code>Employee</code> to use an EclipseLink XMLAdapter for marshalling/unmarshalling <code>PhoneNumbers</code> by using the XML Bindings in <a href="#CACJCGHC">Example 2-7</a>.</p>
<div class="example"><a id="CACJCGHC" name="CACJCGHC"></a><a id="TLJAX134" name="TLJAX134"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-7 Using an XML Bindings Document</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;?xml version="1.0" encoding="US-ASCII"?&gt;
&lt;xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm"&gt;
&lt;java-types&gt;
&lt;java-type name="example.Employee"&gt;
&lt;java-attributes&gt;
&lt;xml-element java-attribute="phoneNumber"&gt;
&lt;xml-java-type-adapter value="example.util.PhoneNumberProcessor"/&gt;
&lt;/xml-element&gt;
&lt;/java-attributes&gt;
&lt;/java-type&gt;
&lt;/java-types&gt;
&lt;/xml-bindings&gt;
</pre></div>
<!-- class="example" -->
<p>Finally, pass both the list of annotated classes and the link to the XML Bindings to the <code>JAXBContext</code>, as shown in <a href="#CACDDFDF">Example 2-8</a>.</p>
<div class="example"><a id="CACDDFDF" name="CACDDFDF"></a><a id="TLJAX135" name="TLJAX135"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-8 Sample Application Code</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
InputStream iStream = myClassLoader.getResourceAsStream("example/xml-bindings.xml");
Map&lt;String, Object&gt; properties = new HashMap&lt;String, Object&gt;();
properties.put(JAXBContextProperties.OXM_METADATA_SOURCE, iStream);
Class[] classes = new Class[] { Company.class, Employee.class };
JAXBContext context = JAXBContext.newInstance(classes, properties);
</pre></div>
<!-- class="example" --></div>
<!-- class="sect2" --></div>
<!-- class="sect1" --></div>
<!-- class="ind" -->
<!-- Start Footer -->
<div class="footer">
<hr />
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<col width="33%" />
<col width="*" />
<col width="33%" />
<tr>
<td valign="bottom">
<table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
<col width="*" />
<col width="48%" />
<col width="48%" />
<tr>
<td>&nbsp;</td>
<td align="center"><a href="runtime001.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="runtime003.htm"><img src="../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
</tr>
</table>
</td>
<td align="center" width="34%"><a href="http://www.eclipse.org/eclipselink/" title="EclipseLink home"><img src="../../dcommon/images/ellogo.png" alt="EclipseLink" width="150" border="0" /></a><br />
<td valign="bottom" align="right">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="225">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
</td><td>&nbsp;</td><td align="center"><a href="../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../eclipselink_moxy.pdf" title="PDF" target="_blank"><img src="../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td>
</tr>
</table>
</td>
</tr>
</table>
</div>
<!-- class="footer" -->
<div id="copyright">Copyright &copy; 2013 by The Eclipse Foundation under the <a href="http://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License (EPL)</a><br /> <script type="text/javascript">var LastUpdated = document.lastModified;document.writeln ("Updated: " + LastUpdated);</script> </div><!-- START: Analytics --><script type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-1608008-2']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script><!-- END: Analytics --><!-- START: Sharethis --><script>var options={ "publisher": "e2fe9e07-fab6-4f84-83ea-0991b429842c", "position": "right", "ad": { "visible": false, "openDelay": 5, "closeDelay": 0}};var st_hover_widget = new sharethis.widgets.hoverbuttons(options);</script><!-- END: Sharethis --></body>
</html>