blob: 096e483db05623ed62815dfed350eb1c30e097fa [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>About Object-XML Mapping | EclipseLink 2.5.x Understanding EclipseLink</title>
<meta name="generator" content="Oracle DARB XHTML Converter (Mode = document) - Version 1.0.17" />
<meta name="date" content="2013-10-03T10:37:14Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="About Object-XML Mapping" />
<meta name="relnum" content="2.5" />
<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="blocks001.htm" title="Previous" type="text/html" />
<link rel="next" href="app_dev.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:mdbgdwjv8zu', 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">Understanding EclipseLink,
<b>2.5</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_otlcg.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="blocks001.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="app_dev.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="CHDJGIEF" name="CHDJGIEF"></a><a id="OTLCG155" name="OTLCG155"></a>
<div class="sect1"><!-- infolevel="all" infotype="General" -->
<h1 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">About Object-XML Mapping</font></h1>
<p>The Object-XML component, supplied by EclipseLink, enables you to efficiently bind Java classes to XML schemas. Object-XML implements JAXB, enabling you to provide your mapping information through annotations and providing support for storing the mappings in XML format.</p>
<p>JAXB (Java Architecture for XML Binding&mdash;JSR 222) is the standard for XML Binding in Java. JAXB covers 100 percent of XML Schema concepts. EclipseLink provides a JAXB implementation with many extensions.</p>
<p>When using EclipseLink Object-XML as the JAXB provider, no metadata is required to convert your existing object model to XML. You can supply metadata (using annotations or XML) if you want to fine-tune the XML representation.</p>
<p>Object-XML includes many advanced mappings that let you handle complex XML structures without having to mirror the schema in your Java class model.</p>
<p>For more information, see <em>Developing JAXB Applications Using EclipseLink MOXy</em>.</p>
<p>The following sections describe many of these features.</p>
<ul>
<li>
<p><a href="#CHDBGGJD">Using EclipseLink Object-XML as the JAXB Provider</a></p>
</li>
<li>
<p><a href="#CHDBDFCI">Understanding Object-XML Architecture</a></p>
</li>
<li>
<p><a href="#CHDIJADI">Serving Metadata for Object-XML</a></p>
</li>
<li>
<p><a href="#CHDCHHHI">About XML Bindings</a></p>
</li>
<li>
<p><a href="#CHDIJFAC">Specifying EclipseLink Object-XML Mappings Using eclipselink-oxm.xml</a></p>
</li>
<li>
<p><a href="#CHDDHJAJ">Querying Objects by XPath</a></p>
</li>
</ul>
<a id="CHDBGGJD" name="CHDBGGJD"></a><a id="OTLCG156" name="OTLCG156"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Using EclipseLink Object-XML as the JAXB Provider</font></h2>
<p>To use Object-XML as your JAXB provider, you must identify the entry point to the JAXB runtime. This entry point is the EclipseLink <code>JAXBContextFactory</code> class.</p>
<p>Create a text file called <code>jaxb.properties</code> and enter the path to the <code>JAXBContextFactory</code> class as the value of the <code>javax.xml.bind.context.factory</code> context parameter, for example:</p>
<pre xml:space="preserve" class="oac_no_warn">
javax.xml.bind.context.factory=org.eclipse.persistence.jaxb.JAXBContextFactory
</pre>
<p>The <code>jaxb.properties</code> file must appear in the same package as the domain classes.</p>
</div>
<!-- class="sect2" -->
<a id="CHDBDFCI" name="CHDBDFCI"></a><a id="OTLCG157" name="OTLCG157"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Understanding Object-XML Architecture</font></h2>
<p>In the sample Object-XML architecture illustrated in <a href="#CHDCBEEE">Figure 2-2</a>, the starting point is an XML schema. A binding compiler binds the source schema to a set of schema-derived program classes and interfaces. JAXB-annotated classes within the application are generated either by a schema compiler or the result of a developer adding JAXB annotations to existing Java classes. The application can either marshal data to an XML document or unmarshal the data to a tree of content objects. Each content object is an instance of either a schema derived or an existing program element mapped by the schema generator and corresponds to an instance in the XML.</p>
<div class="figure"><a id="CHDCBEEE" name="CHDCBEEE"></a><a id="OTLCG158" name="OTLCG158"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Figure 2-2 A Sample Object-XML Architecture</font></em></strong></p>
<img src="img/jaxb_overview.png" alt="Process in an Object-XML project." title="Process in an Object-XML project." longdesc="img_text/jaxb_overview.htm" /><br />
<a id="sthref26" name="sthref26" href="img_text/jaxb_overview.htm">Description of "Figure 2-2 A Sample Object-XML Architecture"</a><br />
<br /></div>
<!-- class="figure" -->
<a id="CHDDHHEI" name="CHDDHHEI"></a><a id="OTLCG159" name="OTLCG159"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">JAXB Contexts and JAXB Context Factories</font></h3>
<p>The <code>JAXBContextFactory</code> class is the entry point into the EclipseLink JAXB runtime. It provides the required factory methods and can create new instances of <code>JAXBContext</code> objects.</p>
<p>The <code>JAXBContextFactory</code> class has the ability to:</p>
<ul>
<li>
<p>Create a <code>JAXBContext</code> object from an array of classes and a properties object</p>
</li>
<li>
<p>Create a <code>JAXBContext</code> object from a context path and a classloader</p>
</li>
</ul>
<p>The <code>JAXBContext</code> class provides the client's entry point to the JAXB API. The <code>JAXBContext</code> class is responsible for interpreting the metadata, generating schema files, and for creating instances of these JAXB objects: <code>Marshaller</code>, <code>Unmarshaller</code>, <code>Binder</code>, <code>Introspector</code>, and <code>Validator</code>.</p>
<p>Object-XML offers several options when creating the <code>JAXBContext</code> object. You have the option of booting 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>
</div>
<!-- class="sect3" --></div>
<!-- class="sect2" -->
<a id="CHDIJADI" name="CHDIJADI"></a><a id="OTLCG160" name="OTLCG160"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Serving Metadata for Object-XML</font></h2>
<p>In addition to the input options described in <a href="#CHDDHHEI">JAXB Contexts and JAXB Context Factories,</a> Object-XML provides the concept of a <code>MetadataSource</code> object. This object lets you to store mapping information outside of your application and retrieve it when the application's <code>JAXBContext</code> object is being created or refreshed. For information on implementing <code>MetadataSource</code>, see <em>Developing JAXB Applications Using EclipseLink MOXy</em>.</p>
</div>
<!-- class="sect2" -->
<a id="CHDCHHHI" name="CHDCHHHI"></a><a id="OTLCG161" name="OTLCG161"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">About XML Bindings</font></h2>
<p>EclipseLink enables you to use all of the standard JAXB annotations. In addition to the standard annotations, EclipseLink offers another way of expressing your metadata&mdash;the EclipseLink XML Bindings document. Not only can XML Bindings separate your mapping information from your actual Java class, it can also be used for more advanced metadata tasks such as:</p>
<ul>
<li>
<p>Augmenting or overriding existing annotations with additional mapping information.</p>
</li>
<li>
<p>Specifying all mappings information externally, without using Java annotations.</p>
</li>
<li>
<p>Defining your mappings across multiple Bindings documents.</p>
</li>
<li>
<p>Specifying virtual mappings that do not correspond to concrete Java fields.</p>
</li>
</ul>
<p>For more information, see <em>Developing JAXB Applications Using EclipseLink MOXy</em>.</p>
<a id="CHDIJFAC" name="CHDIJFAC"></a><a id="OTLCG162" name="OTLCG162"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Specifying EclipseLink Object-XML Mappings Using eclipselink-oxm.xml</font></h3>
<p>You can use Java annotations to specify JAXB features in your projects. In addition to Java annotations, EclipseLink provides an XML mapping configuration file called <code>eclipselink-oxm.xml</code>. This mapping file contains the standard JAXB mappings and configuration options for advanced mapping types. You can use the <code>eclipselink-oxm.xml</code> file in place of or to override JAXB annotations in source code.</p>
<div align="center">
<div class="inftblnote"><br />
<table class="Note oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
<tbody>
<tr>
<td align="left">
<p class="note"><img src="../../dcommon/images/note_icon.png" width="16" height="16" alt="Note" style="vertical-align:middle;padding-right:5px;" />Note:</p>
<p>Using this mapping file will enable many advanced features but it can prevent the model from being portable to other JAXB implementations.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
</div>
<!-- class="sect3" --></div>
<!-- class="sect2" -->
<a id="CHDDFBIG" name="CHDDFBIG"></a><a id="OTLCG131" name="OTLCG131"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">About Object-XML Data Type Mappings</font></h2>
<p>XML mappings transform object data members to the XML elements of an XML document whose structure is defined by an XML Schema Document (XSD). You can map the attributes of a Java object to a combination of XML simple and complex types using a wide variety of XML mapping types.</p>
<p>Classes are mapped to complex types, object relationships map to XML elements, and simple attributes map to text nodes and XML attributes. The real power in using Object-XML is that when mapping an object attribute to an XML document, XPath statements are used to specify the location of the XML data.</p>
<p>EclipseLink stores XML mappings for each class in the class descriptor. EclipseLink uses the descriptor to instantiate objects mapped from an XML document and to store new or modified objects as XML documents.</p>
<p>EclipseLink provides XML mappings that are not defined in the JAXB specification. Some of the Object-XML extensions are available through EclipseLink annotations; others require programmatic changes to the underlying metadata.</p>
<p>For more information on these mappings, see <em>Developing JAXB Applications Using EclipseLink MOXy</em>.</p>
</div>
<!-- class="sect2" -->
<a id="CHDDHJAJ" name="CHDDHJAJ"></a><a id="OTLCG163" name="OTLCG163"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Querying Objects by XPath</font></h2>
<p>In addition to using conventional Java access methods to get and set your object's values, EclipseLink Object-XML also lets you access values using an XPath statement. There are special APIs on EclipseLink's <code>JAXBContext</code> object that enable you to get and set values by XPath. For more information, see <em>Developing JAXB Applications Using EclipseLink MOXy</em>.</p>
</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="blocks001.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="app_dev.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_otlcg.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; 2012 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>