blob: c507cffd9c5ec6f1ac160f46f4b8f80304ea82ba [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-Relational 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:52Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="Object-Relational 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="mappingintro001.htm" title="Previous" type="text/html" />
<link rel="next" href="mappingintro003.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="mappingintro001.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="mappingintro003.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="CEGDCCDH" name="CEGDCCDH"></a>
<div class="sect1"><!-- infolevel="all" infotype="General" -->
<h1 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">Object-Relational Mapping Concepts</font></h1>
<p>This section describes concepts for relational mappings that are unique to EclipseLink:</p>
<ul>
<li>
<p><a href="#CHDJAHDC">Indirection (Lazy Loading)</a></p>
</li>
<li>
<p><a href="#CHDEEIBD">Indirection, Serialization, and Detachment</a></p>
</li>
<li>
<p><a href="#CEGHBHEA">Value Holder Indirection</a></p>
</li>
<li>
<p><a href="#CEGGCCGA">Transparent Indirection</a></p>
</li>
<li>
<p><a href="#CEGDCAIG">Proxy Indirection</a></p>
</li>
<li>
<p><a href="#CHDBJGII">Weaved Indirection</a></p>
</li>
<li>
<p><a href="#A7964325">About JPA Mapping Types</a></p>
</li>
</ul>
<a id="CHDJAHDC" name="CHDJAHDC"></a><a id="OTLCG00083" name="OTLCG00083"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Indirection (Lazy Loading)</font></h2>
<p>By default, when EclipseLink retrieves a persistent object, it retrieves all of the dependent objects to which it refers. When you configure indirection (also known as lazy reading, lazy loading, and just-in-time reading) for an attribute mapped with a relationship mapping, EclipseLink uses an indirection object as a place holder for the referenced object: EclipseLink defers reading the dependent object until you access that specific attribute. This can result in a significant performance improvement, especially if the application is interested only in the contents of the retrieved object, rather than the objects to which it is related.</p>
<p>Oracle strongly recommends using indirection for all relationship mappings. Not only does this lets you optimize data source access, but it also allows EclipseLink to optimize the persistence unit processing, cache access, and concurrency.</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>Notes:</strong></font></p>
<ul>
<li>
<p>The use of indirection is especially important for providing a proper maintenance of bidirectional relationships. In this case, you must use indirection. If you are operating with collections, you must use transparent indirection (see <a href="#CEGGCCGA">Transparent Indirection</a>).</p>
</li>
<li>
<p>The implementation of indirection (lazy loading) is vendor-specific. Serializing entities and merging those entities back into a persistence context may not be interoperable across vendors when lazy properties or fields and/or relationships are used.</p>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
<p><a href="#i1102721">Figure 6-8</a> shows an indirection example. Without indirection, reading the <code>Order</code> object also reads the dependent collection of <code>LineItem</code> objects. With indirection, reading the <code>Order</code> object does not read the dependent collection of <code>LineItem</code> objects: the <code>lineItems</code> attribute refers to an indirection object. You can access other attributes (such as <code>customerId</code>), but EclipseLink reads the dependent <code>LineItem</code> objects only if and when you access the <code>lineItems</code> attribute.</p>
<div class="figure"><a id="i1102721" name="i1102721"></a><a id="OTLCG92106" name="OTLCG92106"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Figure 6-8 EclipseLink Indirection</font></em></strong></p>
<img src="img/indirctn.gif" alt="Description of Figure 6-8 follows" title="Description of Figure 6-8 follows" longdesc="img_text/indirctn.htm" /><br />
<a id="sthref41" name="sthref41" href="img_text/indirctn.htm">Description of "Figure 6-8 EclipseLink Indirection"</a><br />
<br /></div>
<!-- class="figure" -->
<p>EclipseLink supports the following types of indirection:</p>
<ul>
<li>
<p><a href="#CEGHBHEA">Value Holder Indirection</a></p>
</li>
<li>
<p><a href="#CEGGCCGA">Transparent Indirection</a></p>
</li>
<li>
<p><a href="#CEGDCAIG">Proxy Indirection</a></p>
</li>
</ul>
<p>When using indirection with an object that your application serializes, you must consider the effect of any untriggered indirection objects at deserialization time. See <a href="#CHDEEIBD">Indirection, Serialization, and Detachment</a>.</p>
</div>
<!-- class="sect2" -->
<a id="CHDEEIBD" name="CHDEEIBD"></a><a id="OTLCG92119" name="OTLCG92119"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Indirection, Serialization, and Detachment</font></h2>
<p>When using indirection (lazy loading), it is likely that a graph of persistent objects will contain untriggered indirection objects. Because indirection objects are transient and do not survive serialization between one JVM and another, untriggered indirection objects will trigger an error if the relationship is accessed after deserialization.</p>
<p>The application must ensure that any indirect relationships that will be required after deserialization have been instantiated before serialization. This can be done through accessing the get method for any relationship using <code>ValueHolder</code> or weaved indirection, and by calling the <code>size</code> method to any relationship using transparent indirection. If the application desired the relationships to be always instantiated on serialization, you could overwrite the serialization <code>writeObject</code> method in the persistent class to first instantiate the desired relationships. Use caution for objects with many or deep relationships to avoid serializing large object graphs: ideally, only the relationships required by the client should be instantiated.</p>
<p>When serializing JPA entities, any lazy relationships that have not been instantiated prior to serialization will trigger errors if they are accessed. If weaving is used on the server, and the entities are serialized to a client, the same weaved classes must exist on the client, either through static weaving of the jar, or through launching the client JVM using the EclipseLink agent.</p>
<p>For more information, see <a href="app_dev002.htm#CCHGGAGE">Using Java Byte-code Weaving</a>.</p>
</div>
<!-- class="sect2" -->
<a id="CEGHBHEA" name="CEGHBHEA"></a><a id="OTLCG92107" name="OTLCG92107"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Value Holder Indirection</font></h2>
<p>Persistent classes that use indirection must replace relationship attributes with value holder attributes. A value holder is an instance of a class that implements the <code>ValueHolderInterface</code> interface, such as <code>ValueHolder</code>. This object stores the information necessary to retrieve the object it is replacing from the database. If the application does not access the value holder, the replaced object is never read from the database.</p>
<p>To obtain the object that the value holder replaces, use the <code>getValue</code> and <code>setValue</code> methods of the <code>ValueHolderInterface</code>. A convenient way of using these methods is to hide the <code>getValue</code> and <code>setValue</code> methods of the <code>ValueHolderInterface</code> inside <code>get</code> and <code>set</code> methods, as shown in the following illustrations.</p>
<p><a href="#i1102743">Figure 6-9</a> shows the <code>Employee</code> object being read from the database. The <code>Address</code> object is not read and will not be created unless it is accessed.</p>
<div class="figure"><a id="i1102743" name="i1102743"></a><a id="OTLCG92108" name="OTLCG92108"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Figure 6-9 Address Object Not Read</font></em></strong></p>
<img src="img/vhstep1.gif" alt="Description of Figure 6-9 follows" title="Description of Figure 6-9 follows" longdesc="img_text/vhstep1.htm" /><br />
<a id="sthref42" name="sthref42" href="img_text/vhstep1.htm">Description of "Figure 6-9 Address Object Not Read"</a><br />
<br /></div>
<!-- class="figure" -->
<p>The first time the address is accessed, as in <a href="#i1102751">Figure 6-10</a>, the <code>ValueHolder</code> reads and returns the <code>Address</code> object.</p>
<div class="figure"><a id="i1102751" name="i1102751"></a><a id="OTLCG92109" name="OTLCG92109"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Figure 6-10 Initial Request</font></em></strong></p>
<img src="img/vhstep2.gif" alt="Description of Figure 6-10 follows" title="Description of Figure 6-10 follows" longdesc="img_text/vhstep2.htm" /><br />
<a id="sthref43" name="sthref43" href="img_text/vhstep2.htm">Description of "Figure 6-10 Initial Request"</a><br />
<br /></div>
<!-- class="figure" -->
<p>Subsequent requests for the address do not access the database, as shown in <a href="#i1102759">Figure 6-11</a>.</p>
<div class="figure"><a id="i1102759" name="i1102759"></a><a id="OTLCG92110" name="OTLCG92110"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Figure 6-11 Subsequent Requests</font></em></strong></p>
<img src="img/vhstep3.gif" alt="Description of Figure 6-11 follows" title="Description of Figure 6-11 follows" longdesc="img_text/vhstep3.htm" /><br />
<a id="sthref44" name="sthref44" href="img_text/vhstep3.htm">Description of "Figure 6-11 Subsequent Requests"</a><br />
<br /></div>
<!-- class="figure" -->
<p>If you are using method access, the get and set methods specified in the mapping must access the instance of <code>ValueHolderInterface</code>, rather than the object referenced by the value holder. The application should not use these getter and setter, but use the getter and setter that hide the usage of value holders.</p>
</div>
<!-- class="sect2" -->
<a id="CEGGCCGA" name="CEGGCCGA"></a><a id="OTLCG92112" name="OTLCG92112"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Transparent Indirection</font></h2>
<p>Transparent indirection lets you declare any relationship attribute of a persistent class that holds a collection of related objects as any of the following Java objects:</p>
<ul>
<li>
<p><code>java.util.Collection</code></p>
</li>
<li>
<p><code>java.util.Hastable</code></p>
</li>
<li>
<p><code>java.util.List</code></p>
</li>
<li>
<p><code>java.util.Map</code></p>
</li>
<li>
<p><code>java.util.Set</code></p>
</li>
<li>
<p><code>java.util.Vector</code></p>
</li>
</ul>
<p>EclipseLink will use an indirection object that implements the appropriate interface and also performs just-in-time reading of the related objects. When using transparent indirection, you do not have to declare the attributes as <code>ValueHolderInterface</code>.</p>
<p>Newly created collection mappings use transparent indirection by default if their attribute <em>is not</em> a <code>ValueHolderInterface</code>.</p>
<p>You can configure EclipseLink to automatically weave transparent indirect container indirection for JPA entities and Plain Old Java Object (POJO) classes. For more information, see <a href="app_dev002.htm#CCHGGAGE">Using Java Byte-code Weaving</a> and <a href="app_dev005.htm#CCHJEDFH">About Weaving.</a></p>
</div>
<!-- class="sect2" -->
<a id="CEGDCAIG" name="CEGDCAIG"></a><a id="OTLCG92114" name="OTLCG92114"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Proxy Indirection</font></h2>
<p>The Java class <code>Proxy</code> lets you use dynamic proxy objects as place-holders for a defined interface. Certain EclipseLink mappings can be configured to use proxy indirection, which gives you the benefits of indirection without the need to include EclipseLink classes in your domain model. Proxy indirection is to one-to-one relationship mappings as indirect containers are to collection mappings.</p>
<p>To use proxy indirection, your domain model must satisfy all of the following criteria:</p>
<ul>
<li>
<p>The target class of the one-to-one relationship must implement a public interface.</p>
</li>
<li>
<p>The one-to-one attribute on the source class must be of the <code>interface</code> type.</p>
</li>
<li>
<p>If you employ method accessing, then the getter and setter methods must use the interface.</p>
</li>
</ul>
<p>Before using proxy indirection, be aware of the restrictions it places on how you use the persistence unit (see <a href="#CEGGDDJB">Proxy Indirection Restrictions</a>).</p>
<p>To configure proxy indirection, you can use JDeveloper or Java in an amendment method.</p>
<a id="CEGGDDJB" name="CEGGDDJB"></a><a id="OTLCG92115" name="OTLCG92115"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Proxy Indirection Restrictions</font></h3>
<p>Proxy objects in Java are only able to intercept messages sent. If a primitive operation such as <code>==</code>, <code>instanceof</code>, or <code>getClass</code> is used on a proxy, it will not be intercepted. This limitation can require the application to be somewhat aware of the usage of proxy objects.</p>
<p>You cannot register the target of a proxy indirection implementation with a persistence unit. Instead, first register the source object with the persistence unit. This lets you retrieve a target object clone with a call to a getter on the source object clone.</p>
</div>
<!-- class="sect3" --></div>
<!-- class="sect2" -->
<a id="CHDBJGII" name="CHDBJGII"></a><a id="OTLCG92116" name="OTLCG92116"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Weaved Indirection</font></h2>
<p>For JPA entities or POJO classes that you configure for weaving, EclipseLink weaves value holder indirection for one-to-one mappings. If you want EclipseLink to weave change tracking and your application includes collection mappings (one-to-many or many-to-many), then you must configure all collection mappings to use transparent indirect container indirection only (you may not configure your collection mappings to use eager loading nor value holder indirection).</p>
<p>For more information, see <a href="app_dev002.htm#CCHGGAGE">Using Java Byte-code Weaving</a>.</p>
</div>
<!-- class="sect2" -->
<a id="A7964325" name="A7964325"></a><a id="OTLCG94305" name="OTLCG94305"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">About JPA Mapping Types</font></h2>
<p>To map entity classes to relational tables you must configure a mapping per persistent field. The following sections describe EclipeLink's JPA mapping types:</p>
<ul>
<li>
<p><a href="#CEGGDAJJ">Basic Mappings</a></p>
</li>
<li>
<p><a href="#CEGJFEAH">Default Conversions and Converters</a></p>
</li>
<li>
<p><a href="#CEGGABIA">Collection Mappings</a></p>
</li>
<li>
<p><a href="#CEGDIIIB">Using Optimistic Locking</a></p>
</li>
</ul>
<a id="CEGGDAJJ" name="CEGGDAJJ"></a><a id="OTLCG94306" name="OTLCG94306"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Basic Mappings</font></h3>
<p>Simple Java types are mapped as part of the immediate state of an entity in its fields or properties. Mappings of simple Java types are called basic mappings.</p>
<p>By default, the EclipseLink persistence provider automatically configures a basic mapping for simple types.</p>
<p>Use the following annotations to fine-tune how your application implements these mappings:</p>
<ul>
<li>
<p><code>@Basic</code></p>
</li>
<li>
<p><code>@Enumerated</code></p>
</li>
<li>
<p><code>@Temporal</code></p>
</li>
<li>
<p><code>@Lob</code></p>
</li>
<li>
<p><code>@Transient</code></p>
</li>
<li>
<p><code>@Column</code></p>
</li>
<li>
<p>Lazy Basics (See <a href="#CEGBCJAG">Using Indirection with Collections</a>)</p>
</li>
</ul>
<p>For all mapping types there are a common set of options:</p>
<ul>
<li>
<p>Read-Only: Specifies that the mapping should populate the value on read and copy. Required when multiple mappings share the same database column.</p>
</li>
<li>
<p>Converters: Allows custom data types and data conversions to be used with most mapping types</p>
<ul>
<li>
<p>Annotations: <code>@Converter</code>, <code>@TypeConverter</code>, <code>@ObjectTypeConverter</code>, <code>@StructConverter</code>, <code>@Convert</code></p>
</li>
<li>
<p>External Metadata: <code>&lt;converter&gt;</code>, <code>&lt;type-converter&gt;</code>, <code>&lt;object-type-converter&gt;</code>, <code>&lt;struct-converter&gt;</code>, <code>&lt;convert&gt;</code></p>
</li>
</ul>
</li>
</ul>
<p>For more information on these annotations, see <em>Jakarta Persistence API (JPA) Extensions Reference for EclipseLink</em>.</p>
</div>
<!-- class="sect3" -->
<a id="CEGJFEAH" name="CEGJFEAH"></a><a id="OTLCG94307" name="OTLCG94307"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Default Conversions and Converters</font></h3>
<p>The section "Converter Annotations" in <em>Jakarta Persistence API (JPA) Extensions Reference for EclipseLink</em> provides a list of the converter annotation extensions defined by EclipseLink and links to their descriptions.</p>
<p>See the individual converter annotations in <em>Jakarta Persistence API (JPA) Extensions Reference for EclipseLink</em> for descriptions of the following:</p>
<ul>
<li>
<p>the order in which the EclipseLink persistence provider searches the converter annotations</p>
</li>
<li>
<p>the types of classes for which you can specify converters (you can define converters at the class, field and property level)</p>
</li>
<li>
<p>the mappings with which you can use converters</p>
</li>
</ul>
</div>
<!-- class="sect3" -->
<a id="CEGGABIA" name="CEGGABIA"></a><a id="OTLCG94308" name="OTLCG94308"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Collection Mappings</font></h3>
<p>You can access additional advanced mappings and mapping options through the EclipseLink descriptor and mapping API using a <code>DescriptorCustomizer</code> class.</p>
<ul>
<li>
<p><a href="#CEGIGCIJ">One-to-Many Mapping</a></p>
</li>
<li>
<p><a href="#CEGJCHEB">Many-to-Many Mapping</a></p>
</li>
<li>
<p><a href="#CEGBCJAG">Using Indirection with Collections</a></p>
</li>
</ul>
<a id="CEGIGCIJ" name="CEGIGCIJ"></a><a id="OTLCG94309" name="OTLCG94309"></a>
<div class="sect4">
<h4 class="sect4"><font face="arial, helvetica, sans-serif" color="#330099">One-to-Many Mapping</font></h4>
<p>One-to-many mappings are used to represent the relationship between a single source object and a collection of target objects. They are a good example of something that is simple to implement in Java using a Collection (or other collection types) of target objects, but difficult to implement using relational databases.</p>
<p>In a Java Collection, the owner references its parts. In a relational database, the parts reference their owner. Relational databases use this implementation to make querying more efficient.</p>
<div class="figure"><a id="OTLCG94310" name="OTLCG94310"></a><a id="sthref45" name="sthref45"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Figure 6-12 One-to-Many Relationships</font></em></strong></p>
<img src="img/onetomany_map_fig.gif" alt="This figure illustrates the one-to-many relationship." title="This figure illustrates the one-to-many relationship." longdesc="img_text/onetomany_map_fig.htm" /><br />
<a id="sthref46" name="sthref46" href="img_text/onetomany_map_fig.htm">Description of "Figure 6-12 One-to-Many Relationships"</a><br />
<br /></div>
<!-- class="figure" -->
<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>The phone attribute shown in the One-to-Many Relationships is of type Vector. You can use a Collection interface (or any class that implements the Collection interface) for declaring the collection attribute.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
<a id="OTLCG94311" name="OTLCG94311"></a>
<div class="sect4"><a id="sthref47" name="sthref47"></a>
<h4 class="sect4"><font face="arial, helvetica, sans-serif" color="#330099">JPA Mapping</font></h4>
<p>By default, JPA automatically defines a OneToMany mapping for a many-valued association with one-to-many multiplicity.</p>
<p>Use the <code>@OneToMany</code> annotation to do the following:</p>
<ul>
<li>
<p>configure the fetch type to <code>EAGER</code></p>
</li>
<li>
<p>configure the associated target entity, because the Collection used is not defined using generics</p>
</li>
<li>
<p>configure the operations that must be cascaded to the target of the association: for example, if the owning entity is removed, ensure that the target of the association is also removed</p>
</li>
<li>
<p>configure the details of the join table used by the persistence provider for unidirectional one-to-many relationships. For a one-to-many using a <code>mappedBy</code> or <code>JoinColumn</code>, the deletion of the related objects is cascaded on the database. For a one-to-many using a <code>JoinTable</code>, the deletion of the join table is cascaded on the database (target objects cannot be cascaded even if private because of constraint direction).</p>
</li>
</ul>
<p>For more information, see Section 11.1.23 "JoinTable Annotation" in the JPA Specification.</p>
<p><code><a href="http://jcp.org/en/jsr/detail?id=338">http://jcp.org/en/jsr/detail?id=338</a></code></p>
</div>
<!-- class="sect4" --></div>
<!-- class="sect4" -->
<a id="CEGJCHEB" name="CEGJCHEB"></a><a id="OTLCG94312" name="OTLCG94312"></a>
<div class="sect4">
<h4 class="sect4"><font face="arial, helvetica, sans-serif" color="#330099">Many-to-Many Mapping</font></h4>
<p>Many-to-many mappings represent the relationships between a collection of source objects and a collection of target objects. They require the creation of an intermediate table for managing the associations between the source and target records.</p>
<p><a href="#CEGIHDED">Figure 6-13</a> illustrates a many-to-many mapping in Java and in relational database tables.</p>
<div class="figure"><a id="CEGIHDED" name="CEGIHDED"></a><a id="OTLCG94313" name="OTLCG94313"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Figure 6-13 Many-to-Many Relationships</font></em></strong></p>
<img src="img/mmmapfig.gif" alt="Many-to-many Relationships" title="Many-to-many Relationships" longdesc="img_text/mmmapfig.htm" /><br />
<a id="sthref48" name="sthref48" href="img_text/mmmapfig.htm">Description of "Figure 6-13 Many-to-Many Relationships"</a><br />
<br /></div>
<!-- class="figure" -->
<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>For the projects attribute shown in the Many-to-many Relationships you can use a <code>Collection</code> interface (or any class that implements the <code>Collection</code> interface) for declaring the collection attribute.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
<a id="CEGFEIFF" name="CEGFEIFF"></a><a id="OTLCG94314" name="OTLCG94314"></a>
<div class="sect4">
<h4 class="sect4"><font face="arial, helvetica, sans-serif" color="#330099">JPA Mapping</font></h4>
<p>By default, JPA automatically defines a many-to-many mapping for a many-valued association with many-to-many multiplicity.</p>
<p>Use the <code>@ManyToMany</code> annotation to do the following:</p>
<ul>
<li>
<p>configure the <code>FetchType</code> to <code>EAGER</code></p>
</li>
<li>
<p>configure the mapping to forbid null values (for nonprimitive types) in case null values are inappropriate for your application</p>
</li>
<li>
<p>configure the associated target entity because the Collection used is not defined using generics</p>
</li>
<li>
<p>configure the operations that must be cascaded to the target of the association (for example, if the owning entity is removed, ensure that the target of the association is also removed)</p>
</li>
</ul>
<p>For a list of supported attributes for the <code>@ManyToMany</code> annotation, see the Java Persistence specification:</p>
<p><code><a href="http://jcp.org/en/jsr/detail?id=338">http://jcp.org/en/jsr/detail?id=338</a></code></p>
</div>
<!-- class="sect4" --></div>
<!-- class="sect4" -->
<a id="CEGBCJAG" name="CEGBCJAG"></a><a id="OTLCG94303" name="OTLCG94303"></a>
<div class="sect4">
<h4 class="sect4"><font face="arial, helvetica, sans-serif" color="#330099">Using Indirection with Collections</font></h4>
<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 Jakarta EE environment, set fetch to <code>jakarta.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>. Also in the Java SE environment, one-to-many and many-to-many relationships are lazy by default and use transparent indirection, while one-to-one and many-to-one relationships are not lazy.</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>If you set one-to-one or many-to-one relationships to lazy, and you enable weaving, the EclipseLink JPA persistence provider will use weaving to enable value holder indirection for these relationships.</p>
<p>The collection annotations <code>@OneToOne</code>, <code>@OneToMany</code>, <code>@ManyToMany</code>, and <code>@ManyToOne</code> provide a <code>fetch</code> mapping attribute which can be set to <code>lazy</code> or <code>eager</code>. When you set the attribute to <code>lazy</code>, the EclipseLink JPA persistence provider uses indirection.</p>
<p><a href="#CEGCJEHD">Table 6-1</a> lists support for lazy loading by mapping type.</p>
<div class="tblformal"><a id="OTLCG94304" name="OTLCG94304"></a><a id="sthref49" name="sthref49"></a><a id="CEGCJEHD" name="CEGCJEHD"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Table 6-1 Support for Lazy Loading by Mapping Type</font></em></strong></p>
<table class="Formal" title="Support for Lazy Loading by Mapping Type" summary="This table lists and describes support for lazy loading by mapping type (in both Jakarta EE and Java SE)." 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-t8"><font face="Arial, Helvetica, sans-serif"><strong>Mapping</strong></font></th>
<th align="left" valign="bottom" id="r1c2-t8"><font face="Arial, Helvetica, sans-serif"><strong>Jakarta EE</strong></font></th>
<th align="left" valign="bottom" id="r1c3-t8"><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-t8" headers="r1c1-t8">
<p>Many-to-many</p>
</td>
<td align="left" headers="r2c1-t8 r1c2-t8">
<p>Lazy loading is performed when the <code>fetch</code> attribute is set to <code>jakarta.persistence.FetchType.LAZY</code> (default).</p>
</td>
<td align="left" headers="r2c1-t8 r1c3-t8">
<p>Lazy loading is performed when the <code>fetch</code> attribute is set to <code>jakarta.persistence.FetchType.LAZY</code> (default).</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r3c1-t8" headers="r1c1-t8">
<p>One-to-many</p>
</td>
<td align="left" headers="r3c1-t8 r1c2-t8">
<p>Lazy loading is performed when the <code>fetch</code> attribute is set to <code>jakarta.persistence.FetchType.LAZY</code> (default).</p>
</td>
<td align="left" headers="r3c1-t8 r1c3-t8">
<p>Lazy loading is performed when the <code>fetch</code> attribute is set to <code>jakarta.persistence.FetchType.LAZY</code> (default).</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r4c1-t8" headers="r1c1-t8">
<p>One-to-one</p>
</td>
<td align="left" headers="r4c1-t8 r1c2-t8">
<p>Lazy loading is performed when the <code>fetch</code> attribute is set to <code>jakarta.persistence.FetchType.LAZY</code>.</p>
</td>
<td align="left" headers="r4c1-t8 r1c3-t8">
<p>The <code>fetch</code> attribute is ignored and default <code>jakarta.persistence.FetchType.EAGER</code> applies.</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r5c1-t8" headers="r1c1-t8">
<p>Many-to-one</p>
</td>
<td align="left" headers="r5c1-t8 r1c2-t8">
<p>Lazy loading is performed when the <code>fetch</code> attribute is set to <code>jakarta.persistence.FetchType.LAZY</code>.</p>
</td>
<td align="left" headers="r5c1-t8 r1c3-t8">
<p>The <code>fetch</code> attribute is ignored and default <code>jakarta.persistence.FetchType.EAGER</code> applies</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r6c1-t8" headers="r1c1-t8">
<p>Basic</p>
</td>
<td align="left" headers="r6c1-t8 r1c2-t8">
<p>Lazy loading is performed when the <code>fetch</code> attribute is set to <code>jakarta.persistence.FetchType.LAZY</code>.</p>
</td>
<td align="left" headers="r6c1-t8 r1c3-t8">
<p>The <code>fetch</code> attribute is ignored and default <code>jakarta.persistence.FetchType.EAGER</code> applies</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="tblformal" --></div>
<!-- class="sect4" --></div>
<!-- class="sect3" -->
<a id="CEGDIIIB" name="CEGDIIIB"></a><a id="OTLCG94315" name="OTLCG94315"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Using Optimistic Locking</font></h3>
<p>Oracle recommends using optimistic locking. With optimistic locking, all users have read access to the data. When a user attempts to write a change, the application checks to ensure the data has not changed since the user read the data.</p>
<a id="OTLCG94317" name="OTLCG94317"></a>
<div class="sect4"><a id="sthref50" name="sthref50"></a>
<h4 class="sect4"><font face="arial, helvetica, sans-serif" color="#330099">Optimistic Locking in a Stateless Environment</font></h4>
<p>In a stateless environment, take care to avoid processing out-of-date (stale) data. A common strategy for avoiding stale data is to implement optimistic locking, and store the optimistic lock values in the object. This solution requires careful implementation if the stateless application serializes the objects, or sends the contents of the object to the client in an alternative format. In this case, transport the optimistic lock values to the client in the HTTP contents of an edit page. You must then use the returned values in any write transaction to ensure that the data did not change while the client was performing its work.</p>
<p>You can use optimistic version locking or optimistic field locking policies. Oracle recommends using version locking policies.</p>
</div>
<!-- class="sect4" -->
<a id="OTLCG94318" name="OTLCG94318"></a>
<div class="sect4"><a id="sthref51" name="sthref51"></a>
<h4 class="sect4"><font face="arial, helvetica, sans-serif" color="#330099">Optimistic Version Locking</font></h4>
<p>Use the <code>@Version</code> annotation to enable the JPA-managed optimistic locking by specifying the version field or property of an entity class that serves as its optimistic lock value (recommended).</p>
<p>When choosing a version field or property, ensure that the following is true:</p>
<ul>
<li>
<p>there is only one version field or property per entity</p>
</li>
<li>
<p>you choose a property or field persisted to the primary table</p>
</li>
<li>
<p>your application does not modify the version property or field</p>
</li>
</ul>
<p>For more information, see Section 11.1.45 "Table Annotation" in the JPA Specification.</p>
<p><code><a href="http://jcp.org/en/jsr/detail?id=338">http://jcp.org/en/jsr/detail?id=338</a></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>The field or property type must either be a numeric type (such as <code>Number</code>, <code>long</code>, <code>int</code>, <code>BigDecimal</code>, and so on), or a <code>java.sql.Timestamp</code>. EclipseLink recommends using a numeric type.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
<p>The <code>@Version</code> annotation does not have attributes. The <code>@Version</code> annotation allows you to use EclipseLink converters. See <a href="#CEGJFEAH">Default Conversions and Converters.</a></p>
<p>For more information, see Section 11.1.9 "Column Annotation" in the JPA Specification.</p>
<p><code><a href="http://jcp.org/en/jsr/detail?id=338">http://jcp.org/en/jsr/detail?id=338</a></code></p>
</div>
<!-- class="sect4" --></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="mappingintro001.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="mappingintro003.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>