blob: d6dbb6ba9ea3572ad8fb98773d1c3e0e2f9ca702 [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>Common 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="Common 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="mappingintro.htm" title="Previous" type="text/html" />
<link rel="next" href="mappingintro002.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="mappingintro.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="mappingintro002.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="CHDGIHEJ" name="CHDGIHEJ"></a><a id="OTLCG75016" name="OTLCG75016"></a>
<div class="sect1"><!-- infolevel="all" infotype="General" -->
<h1 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">Common Mapping Concepts</font></h1>
<p>This section describes concepts for relational and nonrelational mappings that are unique to EclipseLink:</p>
<ul>
<li>
<p><a href="#CHDEDGDF">Mapping Architecture</a></p>
</li>
<li>
<p><a href="#CHDGGFCH">Mapping Examples</a></p>
</li>
<li>
<p><a href="#CHDJJHJD">Mapping Converters and Transformers</a></p>
<ul>
<li>
<p><a href="#BABHCBJA">Serialized Object Converter</a></p>
</li>
<li>
<p><a href="#BABEHFGH">Type Conversion Converter</a></p>
</li>
<li>
<p><a href="#BABBCAIH">Object Type Converter</a></p>
</li>
<li>
<p><a href="#CHDIHCJF">Transformation Mappings</a></p>
</li>
</ul>
</li>
</ul>
<a id="CHDEDGDF" name="CHDEDGDF"></a><a id="OTLCG92097" name="OTLCG92097"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Mapping Architecture</font></h2>
<p>To define a mapping, you draw upon the following components:</p>
<ul>
<li>
<p>The data representation specific to the data source (such as a relational database table or schema-defined XML element) in which you store the object's data.</p>
</li>
<li>
<p>A descriptor for a particular object class.</p>
</li>
<li>
<p>An object class to map.</p>
</li>
</ul>
<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>A mapping is the same regardless of whether your project is persistent or nonpersistent.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" -->
<p>For an example of a typical EclipseLink mapping, see <a href="#CHDGGFCH">Mapping Examples</a>.</p>
<p>The type of data source you define in your project determines the type of mappings you can use and how you configure them. In a persistent project, you use mappings to persist to a data source. In a nonpersistent project, you use mappings simply to transform between the object format and some other data representation (such as XML).</p>
<p>A descriptor represents a particular domain object: it describes the object's class. A descriptor also owns the mappings: one mapping for each of the class data members that you intend to persist or transform in memory.</p>
<p>For more information about descriptors, see <a href="descriptors.htm#CHECEAAE">Chapter 6, "Understanding Descriptors"</a>.</p>
</div>
<!-- class="sect2" -->
<a id="CHDGGFCH" name="CHDGGFCH"></a><a id="OTLCG92098" name="OTLCG92098"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Mapping Examples</font></h2>
<p>Although EclipseLink supports more complex mappings, most EclipseLink classes map to a single database table or XML element that defines the type of information available in the class. Each object instance of a given class maps to a single row comprising the object's attributes, plus an identifier (the primary key) that uniquely identifies the object.</p>
<p><a href="#CHDHADEG">Figure 7-1</a> illustrates the simplest database mapping case in which:</p>
<ul>
<li>
<p><strong>Table_X</strong> in the database represents <strong>Class_X</strong>.</p>
</li>
<li>
<p><strong>Object_X1</strong> and <strong>Object_X2</strong> are instances of <strong>Class_X</strong>.</p>
</li>
<li>
<p>Individual rows in <strong>Table_X</strong> represent <strong>Object_X1</strong> and <strong>Object_X2</strong>, as well as any other instances of <strong>Class_X</strong>.</p>
</li>
</ul>
<div class="figure"><a id="CHDHADEG" name="CHDHADEG"></a><a id="OTLCG92099" name="OTLCG92099"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Figure 7-1 How Classes and Objects Map to a Database Table</font></em></strong></p>
<img src="img/example_map1.gif" alt="Description of Figure 7-1 follows" title="Description of Figure 7-1 follows" longdesc="img_text/example_map1.htm" /><br />
<a id="sthref37" name="sthref37" href="img_text/example_map1.htm">Description of "Figure 7-1 How Classes and Objects Map to a Database Table"</a><br />
<br /></div>
<!-- class="figure" -->
<p>EclipseLink provides you with the tools to build these mappings, from the simple mappings illustrated in <a href="#CHDHADEG">Figure 7-1</a>, to complex mappings.</p>
<p>For an additional example of a relational mapping, see <a href="#i1025794">Figure 7-2, "Serialized Object Converter (relational)"</a>.</p>
</div>
<!-- class="sect2" -->
<a id="CEGBCJAG" name="CEGBCJAG"></a><a id="OTLCG94303" name="OTLCG94303"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Using Lazy Loading</font></h2>
<p>JPA specifies that lazy loading is a hint to the persistence provider that data should be fetched lazily when it is first accessed, if possible. If you are developing your application in a Java EE environment, set fetch to <code>javax.persistence.FetchType.LAZY</code>, and the persistence provider supplies all the necessary functionality.</p>
<p>When using a one-to-one or many-to-one mapping in a Java SE environment, use either dynamic or static weaving to perform lazy loading when the <code>fetch</code> attribute is set to <code>FetchType.LAZY</code>.</p>
<p>When using a one-to-one or many-to-one mapping in a Java SE environment and the environment does not permit the use of <code>-javaagent</code> on the JVM command line, use static weaving to perform lazy loading when the <code>fetch</code> attribute is set to <code>FetchType.LAZY</code>.</p>
<p><a href="#CEGCJEHD">Table 7-1</a> lists support for lazy loading by mapping type.</p>
<div class="tblformal"><a id="OTLCG94304" name="OTLCG94304"></a><a id="sthref38" name="sthref38"></a><a id="CEGCJEHD" name="CEGCJEHD"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Table 7-1 Support for Lazy Loading by Mapping Type</font></em></strong></p>
<table class="Formal" title="Support for Lazy Loading by Mapping Type" summary="Support for Lazy Loading by Mapping Type" dir="ltr" border="1" width="100%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
<col width="18%" />
<col width="41%" />
<col width="*" />
<thead>
<tr align="left" valign="top">
<th align="left" valign="bottom" id="r1c1-t3"><font face="Arial, Helvetica, sans-serif"><strong>Mapping</strong></font></th>
<th align="left" valign="bottom" id="r1c2-t3"><font face="Arial, Helvetica, sans-serif"><strong>Java EE</strong></font></th>
<th align="left" valign="bottom" id="r1c3-t3"><font face="Arial, Helvetica, sans-serif"><strong>Java SE</strong></font></th>
</tr>
</thead>
<tbody>
<tr align="left" valign="top">
<td align="left" id="r2c1-t3" headers="r1c1-t3">
<p>Many-to-many</p>
</td>
<td align="left" headers="r2c1-t3 r1c2-t3">
<p>Lazy loading is performed when the <code>fetch</code> attribute is set to <code>javax.persistence.FetchType.LAZY</code> (default).</p>
</td>
<td align="left" headers="r2c1-t3 r1c3-t3">
<p>Lazy loading is performed when the <code>fetch</code> attribute is set to <code>javax.persistence.FetchType.LAZY</code> (default).</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r3c1-t3" headers="r1c1-t3">
<p>One-to-many</p>
</td>
<td align="left" headers="r3c1-t3 r1c2-t3">
<p>Lazy loading is performed when the <code>fetch</code> attribute is set to <code>javax.persistence.FetchType.LAZY</code> (default).</p>
</td>
<td align="left" headers="r3c1-t3 r1c3-t3">
<p>Lazy loading is performed when the <code>fetch</code> attribute is set to <code>javax.persistence.FetchType.LAZY</code> (default).</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r4c1-t3" headers="r1c1-t3">
<p>One-to-one</p>
</td>
<td align="left" headers="r4c1-t3 r1c2-t3">
<p>Lazy loading is performed when the <code>fetch</code> attribute is set to <code>javax.persistence.FetchType.LAZY</code>.</p>
</td>
<td align="left" headers="r4c1-t3 r1c3-t3">
<p>The <code>fetch</code> attribute is ignored and default <code>javax.persistence.FetchType.EAGER</code> applies.</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r5c1-t3" headers="r1c1-t3">
<p>Many-to-one</p>
</td>
<td align="left" headers="r5c1-t3 r1c2-t3">
<p>Lazy loading is performed when the <code>fetch</code> attribute is set to <code>javax.persistence.FetchType.LAZY</code>.</p>
</td>
<td align="left" headers="r5c1-t3 r1c3-t3">
<p>The <code>fetch</code> attribute is ignored and default <code>javax.persistence.FetchType.EAGER</code> applies</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r6c1-t3" headers="r1c1-t3">
<p>Basic</p>
</td>
<td align="left" headers="r6c1-t3 r1c2-t3">
<p>Lazy loading is performed when the <code>fetch</code> attribute is set to <code>javax.persistence.FetchType.LAZY</code>.</p>
</td>
<td align="left" headers="r6c1-t3 r1c3-t3">
<p>The <code>fetch</code> attribute is ignored and default <code>javax.persistence.FetchType.EAGER</code> applies</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="tblformal" --></div>
<!-- class="sect2" -->
<a id="CHDJJHJD" name="CHDJJHJD"></a><a id="OTLCG92121" name="OTLCG92121"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Mapping Converters and Transformers</font></h2>
<p>If existing EclipseLink mappings do not meet your needs, you can create custom mappings using mapping extensions. These extensions include the following:</p>
<ul>
<li>
<p><a href="#BABHCBJA">Serialized Object Converter</a></p>
</li>
<li>
<p><a href="#BABEHFGH">Type Conversion Converter</a></p>
</li>
<li>
<p><a href="#BABBCAIH">Object Type Converter</a></p>
</li>
<li>
<p><a href="#CHDIHCJF">Transformation Mappings</a></p>
</li>
</ul>
<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>Except for simple type translation, you can use the mapping converters and transformers regardless of whether your data source is relational or nonrelational. Simple type translation is applicable only to XML projects.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
<a id="BABHCBJA" name="BABHCBJA"></a><a id="OTLCG00042" name="OTLCG00042"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Serialized Object Converter</font></h3>
<p>The serialized object converter can be used with direct and direct collection mappings, allowing you to map complex objects into binary fields through Java object serialization. Serialized objects are normally stored in <code>RAW</code> or Binary Large Object (<code>BLOB)</code> fields in the database, or <code>HEX</code> or <code>BASE64</code> elements in an XML document.</p>
<p><a href="#i1025794">Figure 7-2</a> shows an example of a direct-to-field mappings that uses a serialized object converter. The attribute <code>jobDescription</code> contains a formatted text document that is stored in the <code>JOB_DESC</code> field of the database.</p>
<div class="figure"><a id="i1025794" name="i1025794"></a><a id="OTLCG92122" name="OTLCG92122"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Figure 7-2 Serialized Object Converter (relational)</font></em></strong></p>
<img src="img/serobjfg.gif" alt="Description of Figure 7-2 follows" title="Description of Figure 7-2 follows" longdesc="img_text/serobjfg.htm" /><br />
<a id="sthref39" name="sthref39" href="img_text/serobjfg.htm">Description of "Figure 7-2 Serialized Object Converter (relational)"</a><br />
<br /></div>
<!-- class="figure" -->
<p><a href="#CEGGDDEC">Figure 7-3</a> demonstrates an example of a nonrelational mapping that uses a serialized object converter. The attribute <code>jobDescription</code> contains a formatted text document that EclipseLink stores in the <code>JOB DESCRIPTION</code> element of an XML schema.</p>
<div class="figure"><a id="CEGGDDEC" name="CEGGDDEC"></a><a id="OTLCG92123" name="OTLCG92123"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Figure 7-3 Serialized Object Converter (nonrelational)</font></em></strong></p>
<img src="img/otlcg_dt_002.png" alt="Description of Figure 7-3 follows" title="Description of Figure 7-3 follows" longdesc="img_text/otlcg_dt_002.htm" /><br />
<a id="sthref40" name="sthref40" href="img_text/otlcg_dt_002.htm">Description of "Figure 7-3 Serialized Object Converter (nonrelational)"</a><br />
<br /></div>
<!-- class="figure" -->
<p>The serialized object converter relies on the Java serializer. Before you map a domain object with the serialized object converter, ensure that the domain object implements the <code>java.io.Serializable</code> interface (or inherits that implementation) and marks all nonserializable fields transient.</p>
</div>
<!-- class="sect3" -->
<a id="BABEHFGH" name="BABEHFGH"></a><a id="OTLCG00043" name="OTLCG00043"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Type Conversion Converter</font></h3>
<p>The type conversion converter can be used with direct and direct collection mappings, allowing you to map complex objects into binary fields. For example, a <code>Number</code> in the data source can be mapped to a <code>String</code> in Java, or a <code>java.util.Date</code> in Java can be mapped to a <code>java.sql.Date</code> in the data source.</p>
<p><a href="#i1054818">Figure 7-4</a> illustrates a type conversion mapping (relational). Because the <code>java.util.Date</code> class is stored by default as a <code>Timestamp</code> in the database, it must first be converted to an explicit database type such as <code>java.sql.Date</code> (required only for DB2&ndash;most other databases have a single date data type that can store any date or time).</p>
<div class="figure"><a id="i1054818" name="i1054818"></a><a id="OTLCG92124" name="OTLCG92124"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Figure 7-4 Type Conversion Mapping (relational)</font></em></strong></p>
<img src="img/tcmapfig.gif" alt="Description of Figure 7-4 follows" title="Description of Figure 7-4 follows" longdesc="img_text/tcmapfig.htm" /><br />
<a id="sthref41" name="sthref41" href="img_text/tcmapfig.htm">Description of "Figure 7-4 Type Conversion Mapping (relational) "</a><br />
<br /></div>
<!-- class="figure" -->
<p><a href="#CHDBJHEI">Figure 7-5</a> illustrates a type conversion mapping (nonrelational). <code>java.util.Date</code> object is mapped to a String in a XML schema.</p>
<div class="figure"><a id="CHDBJHEI" name="CHDBJHEI"></a><a id="OTLCG92125" name="OTLCG92125"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Figure 7-5 Type Conversion Mapping (nonrelational)</font></em></strong></p>
<img src="img/tcmapxml.gif" alt="Description of Figure 7-5 follows" title="Description of Figure 7-5 follows" longdesc="img_text/tcmapxml.htm" /><br />
<a id="sthref42" name="sthref42" href="img_text/tcmapxml.htm">Description of "Figure 7-5 Type Conversion Mapping (nonrelational)"</a><br />
<br /></div>
<!-- class="figure" -->
<p>You can use a type conversion converter to specify the specific database type when that type must be handled specially for the database. This includes support for the special Oracle JDBC binding options required for <code>NCHAR</code>, <code>NVARCHAR2</code>, and <code>NCLOB</code> fields as well as the special Oracle Thin JDBC insert and update requirements for handling <code>BLOB</code> and <code>CLOB</code> fields greater than 5K.</p>
<p>EclipseLink uses the <code>NCharacter</code>, <code>NClob</code> and <code>NString</code> types in the <code>org.eclipse.persistence.platform.database.oracle</code> package as the converter data type to support the <code>NCHAR</code>, <code>NCLOB</code> and <code>NVARCHAR2</code> types. EclipseLink uses the <code>java.sql.Blob</code> and <code>Clob</code> types as the converter data type to support <code>BLOB</code> and <code>CLOB</code> values greater than 5K.</p>
<p>You can configure a type conversion converter to map a data source time type (such as <code>TIMESTAMP</code>) to a <code>java.lang.String</code> provided that the String value conforms to the following formats:</p>
<ul>
<li>
<p><code>YYYY/MM/DD HH:MM:SS</code></p>
</li>
<li>
<p><code>YY/MM/DD HH:MM:SS</code></p>
</li>
<li>
<p><code>YYYY-MM-DD HH:MM:SS</code></p>
</li>
<li>
<p><code>YY-MM-DD HH:MM:SS</code></p>
</li>
</ul>
<p>For more complex <code>String</code> to <code>TIMESTAMP</code> type conversion, consider a transformation mapping (see <a href="#CHDIHCJF">Transformation Mappings</a>).</p>
</div>
<!-- class="sect3" -->
<a id="BABBCAIH" name="BABBCAIH"></a><a id="OTLCG00044" name="OTLCG00044"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Object Type Converter</font></h3>
<p>The object type converter can be used with direct and direct collection mappings allowing you to match a fixed number of values to Java objects. Use this converter when the values in the schema differ from those in Java.</p>
<p><a href="#CHDJBFJH">Figure 7-6</a> illustrates an object type conversion between the <code>Employee</code> attribute <code>gender</code> and the XML element <code>gender</code>. If the value of the Java object attribute is <code>Female</code>, EclipseLink stores it in the XML element as <code>F</code>.</p>
<div class="figure"><a id="CHDJBFJH" name="CHDJBFJH"></a><a id="OTLCG92126" name="OTLCG92126"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Figure 7-6 Object Type XML Converter</font></em></strong></p>
<img src="img/obxmlfig.gif" alt="Description of Figure 7-6 follows" title="Description of Figure 7-6 follows" longdesc="img_text/obxmlfig.htm" /><br />
<a id="sthref43" name="sthref43" href="img_text/obxmlfig.htm">Description of "Figure 7-6 Object Type XML Converter"</a><br />
<br /></div>
<!-- class="figure" --></div>
<!-- class="sect3" -->
<a id="CHDIHCJF" name="CHDIHCJF"></a><a id="OTLCG00046" name="OTLCG00046"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Transformation Mappings</font></h3>
<p>In some special circumstances, existing mapping types and their default Java to data source type handling may be insufficient. In these special cases, you can consider using a transformation mapping to perform specialized translations between how a value is represented in Java and in the data source.</p>
<p>A transformation mapping is made up of the following two components:</p>
<ul>
<li>
<p>attribute transformer: performs the object attribute transformation at read time</p>
</li>
<li>
<p>field transformer: performs the object attribute-to-field transformation at write time</p>
</li>
</ul>
<p>You can implement a transformer as either a separate class or as a method on your domain object.</p>
<p>Within your implementation of the attribute and field transformer, you can take whatever actions are necessary to transform your application data to suit your data source, and vise versa.</p>
<p>For more information, see <a href="#CHDDBJJJ">Transformation Mapping</a>.</p>
</div>
<!-- class="sect3" --></div>
<!-- class="sect2" -->
<a id="CHDDBJJJ" name="CHDDBJJJ"></a><a id="OTLCG00040" name="OTLCG00040"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Transformation Mapping</font></h2>
<p>Use transformation mappings for specialized translations for how a value is represented in Java and how it is represented in the database.</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><font face="arial, helvetica, sans-serif"><strong><strong>Tip</strong>:</strong></font></p>
<p>Because of the complexity of transformation mappings, it is often easier to perform the transformation with a converter or getter and setter methods of a direct-to-field mapping.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
<p><a href="#i1054846">Figure 7-7</a> illustrates a transformation mapping. The values from the <code>B_DATE</code> and <code>B_TIME</code> fields are used to create a <code>java.util.Date</code> to be stored in the <code>birthDate</code> attribute.</p>
<div class="figure"><a id="i1054846" name="i1054846"></a><a id="OTLCG92423" name="OTLCG92423"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Figure 7-7 Transformation Mappings</font></em></strong></p>
<img src="img/trmapfig.gif" alt="Description of Figure 7-7 follows" title="Description of Figure 7-7 follows" longdesc="img_text/trmapfig.htm" /><br />
<a id="sthref44" name="sthref44" href="img_text/trmapfig.htm">Description of "Figure 7-7 Transformation Mappings"</a><br />
<br /></div>
<!-- class="figure" -->
<p>Often, a transformation mapping is appropriate when values from multiple fields are used to create an object. This type of mapping requires that you provide an <em>attribute transformation</em> that is invoked when reading the object from the database. This must have at least one parameter that is an instance of <code>Record</code>. In your attribute transformation, you can use <code>Record</code> method <code>get</code> to retrieve the value in a specific column. Your attribute transformation can optionally specify a second parameter, an instance of <code>Session</code>. The <code>Session</code> performs queries on the database to get additional values needed in the transformation. The transformation should <em>return</em> the value to be stored in the attribute.</p>
<p>Transformation mappings also require a <em>field transformation</em> for each field, to be written to the database when the object is saved. The transformation returns the value to be stored in that field.</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="mappingintro.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="mappingintro002.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>