blob: df62ccf331a14bb14a6cda7f37a1dc9f05362080 [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>MOXy Mapping Concepts | EclipseLink 3.0.x Understanding EclipseLink</title>
<meta name="generator" content="Oracle DARB XHTML Converter (Mode = document) - Version 1.0.22 Build 1" />
<meta name="date" content="2014-06-10T10:39:53Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="MOXy Mapping Concepts" />
<meta name="relnum" content="3.0" />
<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="mappingintro002.htm" title="Previous" type="text/html" />
<link rel="next" href="mappingintro004.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>3.0</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="mappingintro002.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="mappingintro004.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="CEGEJJGJ" name="CEGEJJGJ"></a>
<div class="sect1"><!-- infolevel="all" infotype="General" -->
<h1 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">MOXy Mapping Concepts</font></h1>
<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 MOXy 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 MOXy extensions are available through EclipseLink annotations; others require programmatic changes to the underlying metadata.</p>
<p>Mapping concepts for MOXy are described in <em>Developing JAXB Applications EclipseLink MOXy</em>. See the following chapters:</p>
<p>"EclipseLink MOXy Runtime" describes:</p>
<ul>
<li>
<p>the EclipseLink XML Bindings document, which is an alternative to the JAXB annotations. Not only can XML Bindings separate your mapping information from your actual Java class, it can also be used for more advanced metadata</p>
</li>
<li>
<p>the several different bootstrapping options that you can use when creating your <code>JAXBContext</code>.</p>
</li>
<li>
<p>the <code>MetadataSource</code> interface, which is responsible for serving up EclipseLink metadata. Providing an implementation of this interface allows you to store mapping information outside of your application and have it retrieved when the application's <code>JAXBContext</code> is being created or refreshed.</p>
</li>
<li>
<p>schema generation and validation.</p>
</li>
<li>
<p>the several mechanisms by which you can get event callbacks during the marshalling and unmarshalling processes. You can specify callback methods directly on your mapped objects, or define separate <code>Listener</code> classes and register them with the JAXB runtime</p>
</li>
<li>
<p>querying objects by XPath. This is an alternative to using conventional Java access methods to get and set your object's values. EclipseLink MOXy allows you to access values using an XPath statement. There are special APIs on EclipseLink's <code>JAXBContext</code> to allow you to get and set values by XPath.</p>
</li>
<li>
<p>the use of the JAXB <code>Binder</code> interface, which allows you to preserve an entire XML document, even if only some of the items are mapped.</p>
</li>
</ul>
<p>"Mapping Type Levels" describes the initial tasks of setting up a mapping in MOXy:</p>
<ul>
<li>
<p>the default root element, which tells EclipseLink what the top-level root of your XML document will be.</p>
</li>
<li>
<p>namespace information for the Java class, and that all of the elements must be qualified for the namespace. You can namespace-qualify the elements on the package, type, or field/property level.</p>
</li>
<li>
<p>the ways in which you can specify inheritance hierarchy in XML by using <code>xsi:type</code> attribute, substitution groups, or the MOXY-specific <code>@XmlDiscriminatorNode</code> and <code>@XmlDiscriminatorValue</code> annotations</p>
</li>
</ul>
<p>"Mapping Simple Values" and "Mapping Special Schema Types" describes how Java values can be mapped to XML in several different ways:</p>
<ul>
<li>
<p>Java values can be mapped to XML attributes, text nodes, schema types, or simple type translators</p>
</li>
<li>
<p>collections of simple Java values can be mapped to text nodes, text nodes within a grouping element, list elements, or a collection of <code>XmlAttributes</code> or <code>XmlValues</code></p>
</li>
<li>
<p>multiple Java mappings can be created for a single property using OXM metadata, with the caveat that at most one mapping will be readable (the rest will be "write-only")</p>
</li>
<li>
<p>Java <code>enums</code> can be mapped to XML using the <code>@XmlEnum</code> and <code>@XmlEnumValue</code> annotations</p>
</li>
<li>
<p>dates and time: EclipseLink MOXy supports the following types which are not covered in the JAXB specification: <code>java.sql.Date</code> <code>java.sql.Time</code> , and <code>java.sql.Timestamp</code>.</p>
</li>
<li>
<p>union files: When EclipseLink unmarshalls the XML document, such as an XML Schema Union, it tries each of the union types until it can make a successful conversion. Currently, EclipseLink does not support the mapping of Unions using Annotations or OXM Metadata. However, an EclipseLink XML Customizer can be used to create the mapping.</p>
</li>
<li>
<p>binary types: EclipseLink supports marshalling and unmarshalling binary data in two different representation formats: <code>base64Binary</code> (default) and <code>hexBinary</code>. You can specify the desired binary format using the <code>@XmlSchemaType</code> annotation, or <code>&lt;xml-schema-type&gt;</code> element in EclipseLink OXM.</p>
</li>
</ul>
<div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref52" name="sthref52"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Understanding an XML Data Representation</font></h2>
<p>Annotations are not always the most effective way to map JPA to XML. For example, you would not use JAXB if:</p>
<ul>
<li>
<p>You want to specify metadata for a third-party class but do not have access to the source.</p>
</li>
<li>
<p>You want to map an object model to multiple XML schemas, because JAXB rules preclude applying more than one mapping by using annotations.</p>
</li>
<li>
<p>Your object model already contains too many annotations&mdash;for example, from such services as JPA, Spring, JSR-303, and so on&mdash;and you want to specify the metadata elsewhere.</p>
</li>
</ul>
<p>Under these and similar circumstances, you can use an XML data representation by exposing the <code>eclipselink_oxm.xml</code> file.</p>
<p>XML metadata works in two modes:</p>
<ul>
<li>
<p>It adds to the metadata supplied by annotations. This is useful when:</p>
<ul>
<li>
<p>Annotations define version one of the XML representation, and you use XML metadata to tweak the metadata for future versions.</p>
</li>
<li>
<p>You use the standard JAXB annotations, and use the XML metadata for the MOXy extensions. In this way you don't introduce new compile time dependencies in the object model.</p>
</li>
</ul>
</li>
<li>
<p>It completely replaces the annotation metadata, which is useful when you want to map to different XML representations.</p>
</li>
</ul>
</div>
<!-- class="sect2" -->
<div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref53" name="sthref53"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Mapping Values</font></h2>
<p>There are several ways to map simple Java values and collections of simple values directly to XML text nodes. You can map to attributes, text nodes, or schema types. You can also use simple type translators to map types of nodes that are not defined in your XML schema. These techniques are described in "Mapping Simple Values" in <em>Developing JAXB Applications 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="mappingintro002.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="mappingintro004.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>