blob: c86c643d9955229f6f87cbae1171cca53dbea3ad [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>Object-XML Mapping Concepts | 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:15Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="Object-XML Mapping Concepts" />
<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="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>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="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">Object-XML Mapping Concepts</font></h1>
<p>This section describes concepts for nonrelational mappings that are unique to EclipseLink:</p>
<a id="BABGAAIA" name="BABGAAIA"></a><a id="OTLCG00045" name="OTLCG00045"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Simple Type Translation</font></h2>
<p>The simple type translation can be used with direct and direct collection mappings, allowing you to automatically translate an XML element value to an appropriate Java type based on the element's <code>&lt;type&gt;</code> attribute as defined in your XML schema.</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>Simple type translation is applicable only for XML projects.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
<p>In code, this is set up when building a mapping using the <code>setIsTypedTextField</code> method on <code>XMLField</code>, for example:</p>
<pre xml:space="preserve" class="oac_no_warn">
XMLDirectMapping mapping = new XMLDirectMapping();
XMLField tef = new XMLField();
tef.setIsTypedTextField(true);
tef.setXPath("NUMBER/text()");
mapping.setField(tef);
mapping.setAttributeName("number");
xmlDescriptor.addMapping(mapping);
</pre>
<p>You can use simple type translation only when the mapping's XPath goes to a text node. You cannot use a simple type translation if the mapping's XPath goes to an attribute.</p>
<p>Using simple type translation, you can make the XML document preserve type information. This is useful when your object model specifies generic object attributes such as <code>java.lang.Object</code> and <code>java.io.Serializable</code>, since they do not trigger specific type conversions in EclipseLink as do specific object attributes such as <code>java.lang.Integer</code> or <code>java.util.Calendar</code>.</p>
<p><a href="#BABFGEFJ">Figure 7-12</a> illustrates a type translation XML mapping for the <code>number</code> attribute of the <code>PhoneNumber</code> class. Notice that the Java attribute is not specific enough to preserve the typing. Simple type translation adds the type information to the resulting document to preserve the typing.</p>
<div class="figure"><a id="BABFGEFJ" name="BABFGEFJ"></a><a id="OTLCG92127" name="OTLCG92127"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Figure 7-12 Simple Type Translation</font></em></strong></p>
<img src="img/tcxmlfig.gif" alt="Description of Figure 7-12 follows" title="Description of Figure 7-12 follows" longdesc="img_text/tcxmlfig.htm" /><br />
<a id="sthref49" name="sthref49" href="img_text/tcxmlfig.htm">Description of "Figure 7-12 Simple Type Translation"</a><br />
<br /></div>
<!-- class="figure" -->
<p>By default, EclipseLink uses built-in read and write conversion pairs (see <a href="#BABFEHDE">Default Read Conversions</a> and <a href="#BABEEDGD">Default Write Conversions</a>).</p>
<p>You can override this behavior by specifying and configuring your own simple type translation, for example, to write XML binary data as <code>Base64</code>.</p>
<a id="BABFEHDE" name="BABFEHDE"></a><a id="OTLCG92128" name="OTLCG92128"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Default Read Conversions</font></h3>
<p><a href="#BABJJIIB">Table 7-2</a> lists the built-in conversion pairs for reading XML elements. When the schema <code>&lt;type&gt;</code> attribute is specified and simple type translation is enabled, the value read is converted to the corresponding Java type.</p>
<div class="tblhruleformal"><a id="OTLCG92129" name="OTLCG92129"></a><a id="sthref50" name="sthref50"></a><a id="BABJJIIB" name="BABJJIIB"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Table 7-2 Simple Type Translation Read Conversions</font></em></strong></p>
<table class="HRuleFormal" title="Simple Type Translation Read Conversions" summary="This table lists the built-in conversion pairs for writing XML. When the schema type&gt; attribute is specified and simple type translator is enabled, the value read will be converted to the corresponding Java type" dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
<col width="*" />
<col width="42%" />
<thead>
<tr align="left" valign="top">
<th align="left" valign="bottom" id="r1c1-t8"><font face="Arial, Helvetica, sans-serif"><strong>Schema Type</strong></font></th>
<th align="left" valign="bottom" id="r1c2-t8"><font face="Arial, Helvetica, sans-serif"><strong>Java Type</strong></font></th>
</tr>
</thead>
<tbody>
<tr align="left" valign="top">
<td align="left" id="r2c1-t8" headers="r1c1-t8">
<p>base64Binary</p>
</td>
<td align="left" headers="r2c1-t8 r1c2-t8">
<p>Byte[]</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r3c1-t8" headers="r1c1-t8">
<p>boolean</p>
</td>
<td align="left" headers="r3c1-t8 r1c2-t8">
<p>Boolean</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r4c1-t8" headers="r1c1-t8">
<p>byte</p>
</td>
<td align="left" headers="r4c1-t8 r1c2-t8">
<p>Byte</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r5c1-t8" headers="r1c1-t8">
<p>date</p>
</td>
<td align="left" headers="r5c1-t8 r1c2-t8">
<p>Calendar</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r6c1-t8" headers="r1c1-t8">
<p>dateTime</p>
</td>
<td align="left" headers="r6c1-t8 r1c2-t8">
<p>Calendar</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r7c1-t8" headers="r1c1-t8">
<p>double</p>
</td>
<td align="left" headers="r7c1-t8 r1c2-t8">
<p>Double</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r8c1-t8" headers="r1c1-t8">
<p>float</p>
</td>
<td align="left" headers="r8c1-t8 r1c2-t8">
<p>Float</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r9c1-t8" headers="r1c1-t8">
<p>hexBinary</p>
</td>
<td align="left" headers="r9c1-t8 r1c2-t8">
<p>Byte[]</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r10c1-t8" headers="r1c1-t8">
<p>int</p>
</td>
<td align="left" headers="r10c1-t8 r1c2-t8">
<p>int</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r11c1-t8" headers="r1c1-t8">
<p>integer</p>
</td>
<td align="left" headers="r11c1-t8 r1c2-t8">
<p>BigInteger</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r12c1-t8" headers="r1c1-t8">
<p>long</p>
</td>
<td align="left" headers="r12c1-t8 r1c2-t8">
<p>Long</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r13c1-t8" headers="r1c1-t8">
<p>short</p>
</td>
<td align="left" headers="r13c1-t8 r1c2-t8">
<p>Short</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r14c1-t8" headers="r1c1-t8">
<p>string</p>
</td>
<td align="left" headers="r14c1-t8 r1c2-t8">
<p>String</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r15c1-t8" headers="r1c1-t8">
<p>time</p>
</td>
<td align="left" headers="r15c1-t8 r1c2-t8">
<p>Calendar</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r16c1-t8" headers="r1c1-t8">
<p>unsignedByte</p>
</td>
<td align="left" headers="r16c1-t8 r1c2-t8">
<p>Short</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r17c1-t8" headers="r1c1-t8">
<p>unsignedInt</p>
</td>
<td align="left" headers="r17c1-t8 r1c2-t8">
<p>Long</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r18c1-t8" headers="r1c1-t8">
<p>unsignedShort</p>
</td>
<td align="left" headers="r18c1-t8 r1c2-t8">
<p>Integer</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="tblhruleformal" --></div>
<!-- class="sect3" -->
<a id="BABEEDGD" name="BABEEDGD"></a><a id="OTLCG92130" name="OTLCG92130"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Default Write Conversions</font></h3>
<p><a href="#BABEFAGA">Table 7-3</a> lists the built-in conversion pairs for writing XML. When a Java class attribute is of a type in <a href="#BABEFAGA">Table 7-3</a> and the simple type translation is enabled, the corresponding schema type is specified on the element written.</p>
<div class="tblhruleformal"><a id="OTLCG92131" name="OTLCG92131"></a><a id="sthref51" name="sthref51"></a><a id="BABEFAGA" name="BABEFAGA"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Table 7-3 Simple Type Translation Write Conversions</font></em></strong></p>
<table class="HRuleFormal" title="Simple Type Translation Write Conversions" summary="This table lists the built-in conversion pairs for writing XML. When a Java class attribute is of a type in the table below and simple type translator is enabled, the corresponding schema type will be specified on the element." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
<col width="*" />
<col width="42%" />
<thead>
<tr align="left" valign="top">
<th align="left" valign="bottom" id="r1c1-t9"><font face="Arial, Helvetica, sans-serif"><strong>Java Type</strong></font></th>
<th align="left" valign="bottom" id="r1c2-t9"><font face="Arial, Helvetica, sans-serif"><strong>Schema Type</strong></font></th>
</tr>
</thead>
<tbody>
<tr align="left" valign="top">
<td align="left" id="r2c1-t9" headers="r1c1-t9">
<p>Byte[]</p>
</td>
<td align="left" headers="r2c1-t9 r1c2-t9">
<p>hexBinary</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r3c1-t9" headers="r1c1-t9">
<p>BigInteger</p>
</td>
<td align="left" headers="r3c1-t9 r1c2-t9">
<p>integer</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r4c1-t9" headers="r1c1-t9">
<p>Boolean</p>
</td>
<td align="left" headers="r4c1-t9 r1c2-t9">
<p>boolean</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r5c1-t9" headers="r1c1-t9">
<p>Byte</p>
</td>
<td align="left" headers="r5c1-t9 r1c2-t9">
<p>byte</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r6c1-t9" headers="r1c1-t9">
<p>Calendar</p>
</td>
<td align="left" headers="r6c1-t9 r1c2-t9">
<p>dateTime</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r7c1-t9" headers="r1c1-t9">
<p>GregorianCalendar</p>
</td>
<td align="left" headers="r7c1-t9 r1c2-t9">
<p>dateTime</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r8c1-t9" headers="r1c1-t9">
<p>Double</p>
</td>
<td align="left" headers="r8c1-t9 r1c2-t9">
<p>double</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r9c1-t9" headers="r1c1-t9">
<p>Float</p>
</td>
<td align="left" headers="r9c1-t9 r1c2-t9">
<p>float</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r10c1-t9" headers="r1c1-t9">
<p>Integer</p>
</td>
<td align="left" headers="r10c1-t9 r1c2-t9">
<p>int</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r11c1-t9" headers="r1c1-t9">
<p>Long</p>
</td>
<td align="left" headers="r11c1-t9 r1c2-t9">
<p>long</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r12c1-t9" headers="r1c1-t9">
<p>int</p>
</td>
<td align="left" headers="r12c1-t9 r1c2-t9">
<p>int</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r13c1-t9" headers="r1c1-t9">
<p>short</p>
</td>
<td align="left" headers="r13c1-t9 r1c2-t9">
<p>short</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r14c1-t9" headers="r1c1-t9">
<p>String</p>
</td>
<td align="left" headers="r14c1-t9 r1c2-t9">
<p>string</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="tblhruleformal" --></div>
<!-- class="sect3" --></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>