blob: dd03348e69bdde9a52d976028817a1b264c7ba3e [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>Building and Using the Persistence Layer | EclipseLink 2.5.x Understanding EclipseLink</title>
<meta name="generator" content="Oracle DARB XHTML Converter (Mode = document) - Version 1.0.17" />
<meta name="date" content="2013-10-03T10:37:14Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="Building and Using the Persistence Layer" />
<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="app_dev002.htm" title="Previous" type="text/html" />
<link rel="next" href="app_dev004.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="app_dev002.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="app_dev004.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="BABCCAHJ" name="BABCCAHJ"></a><a id="OTLCG91175" name="OTLCG91175"></a>
<div class="sect1"><!-- infolevel="all" infotype="General" -->
<h1 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">Building and Using the Persistence Layer</font></h1>
<p>EclipseLink requires that classes must meet certain minimum requirements before they can become persistent. EclipseLink also provides alternatives to most requirements. EclipseLink uses a nonintrusive approach by employing a metadata architecture that allows for minimal object model intrusions.</p>
<p>This section includes the following information:</p>
<ul>
<li>
<p><a href="#BABBGDHH">Implementation Options</a></p>
</li>
<li>
<p><a href="#BABDHDIA">Persistent Class Requirements</a></p>
</li>
<li>
<p><a href="#BABCCJCC">Persistence Layer Components</a></p>
</li>
</ul>
<a id="BABBGDHH" name="BABBGDHH"></a><a id="OTLCG91176" name="OTLCG91176"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Implementation Options</font></h2>
<p>When implementing your persistence layer using EclipseLink, consider the following options:</p>
<ul>
<li>
<p><a href="#CCHGEJEA">Using EclipseLink JPA Metatdata, Annotations, and XML</a></p>
</li>
<li>
<p><a href="#CCHHEIFG">Using EclipseLink Metadata Java API</a></p>
</li>
<li>
<p><a href="#CCHJBHDG">Using Method and Direct Field Access</a></p>
</li>
<li>
<p><a href="#CCHGGAGE">Using Java Byte-code Weaving</a></p>
</li>
</ul>
<a id="CCHGEJEA" name="CCHGEJEA"></a><a id="OTLCG91177" name="OTLCG91177"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Using EclipseLink JPA Metatdata, Annotations, and XML</font></h3>
<p>When using JPA, you can specify persistence layer components using any combination of standard JPA annotations and <code>persistence.xml</code>, EclipseLink JPA annotation extensions, and EclipseLink JPA <code>persistence.xml</code> extensions.</p>
<p>For more information, see <a href="blocks001.htm#CHDIEIFJ">About Configuration Basics</a>.</p>
</div>
<!-- class="sect3" -->
<a id="CCHHEIFG" name="CCHHEIFG"></a><a id="OTLCG91179" name="OTLCG91179"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Using EclipseLink Metadata Java API</font></h3>
<p>Persistence layer components may be coded or generated as Java. To use Java code, you must manually write code for each element of the project including: project, login, platform, descriptors, and mappings. This may be more efficient if your application is model-based and relies heavily on code generation.</p>
</div>
<!-- class="sect3" -->
<a id="CCHJBHDG" name="CCHJBHDG"></a><a id="OTLCG91180" name="OTLCG91180"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Using Method and Direct Field Access</font></h3>
<p>You can access the fields (data members) of a class by using a getter/setter method (also known as property access) or by accessing the field itself directly.</p>
<p>When to use method or direct field access depends on your application design. Consider the following guidelines:</p>
<ul>
<li>
<p>Use method access outside of a class.</p>
<p>This is the natural public API of the class. The getter/setter methods handle any necessary side-effects and the client need not know anything about those details.</p>
</li>
<li>
<p>Use direct field access within a class to improve performance.</p>
<p>In this case, you are responsible for taking into consideration any side-effects not invoked by bypassing the getter/setter methods.</p>
</li>
</ul>
<p>When considering using method or direct field access, consider the following limitations.</p>
<p>If you enable change tracking on a getter/setter method (for example, you decorate method <code>setPhone</code> with <code>@ChangeTracking</code>), then EclipseLink tracks changes accordingly when a client modifies the field (<code>phone</code>) using the getter/setter methods.</p>
<p>Similarly, if you enable change tracking on a field (for example, you decorate field <code>phone</code> with <code>@ChangeTracking</code>), then EclipseLink tracks changes accordingly when a client modifies the field (<code>phone</code>) directly.</p>
<p>However, if you enable change tracking on a getter/setter method (for example, you decorate method <code>setPhone</code> with <code>@ChangeTracking</code>) and a client accesses the field (<code>phone</code>) directly, EclipseLink does not detect the change. If you choose to code in this style of field access within a class for performance and method access outside of a class, then be aware of this limitation.</p>
<p>For more information, see the description of the <code>@ChangeTracking</code> annotation in <em>Java Persistence API (JPA) Extensions Reference for EclipseLink</em></p>
</div>
<!-- class="sect3" -->
<a id="CCHGGAGE" name="CCHGGAGE"></a><a id="OTLCG91181" name="OTLCG91181"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Using Java Byte-code Weaving</font></h3>
<p>Weaving is a technique of manipulating the byte-code of compiled Java classes.</p>
<p>Weaving is used to enhance both JPA entities and Plain Old Java Object (POJO) classes for such things as lazy loading, change tracking, fetch groups, and internal optimizations.</p>
<p>For more information, see <a href="app_dev007.htm#CCHJEDFH">About Weaving</a>.</p>
</div>
<!-- class="sect3" --></div>
<!-- class="sect2" -->
<a id="BABDHDIA" name="BABDHDIA"></a><a id="OTLCG91182" name="OTLCG91182"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Persistent Class Requirements</font></h2>
<p>When you create persistent Java objects, use direct access on private or protected attributes.</p>
<p>If you are using weaving, the <code>ValueHolderInterface</code> is not required. For more information, see <a href="app_dev007.htm#CCHJEDFH">About Weaving.</a> See <a href="mappingintro002.htm#CHDJAHDC">Indirection (Lazy Loading)</a> for more information on indirection and transparent indirection.</p>
</div>
<!-- class="sect2" -->
<a id="BABCCJCC" name="BABCCJCC"></a><a id="OTLCG91183" name="OTLCG91183"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Persistence Layer Components</font></h2>
<p>The purpose of your application's persistence layer is to use a session at run time to associate mapping metadata and a data source (see <a href="data_access.htm#CHDJBDEA">Chapter 8, "Understanding Data Access"</a>) to create, read, update, and delete persistent objects using the EclipseLink cache, queries and expressions, and transactions.</p>
<p>Typically, the EclipseLink persistence layer contains the following components:</p>
<ul>
<li>
<p><a href="#BABFEEGF">Mapping Metadata</a></p>
</li>
<li>
<p><a href="#BABBGFHF">Cache</a></p>
</li>
<li>
<p><a href="#BABJDGGH">Queries and Expressions</a></p>
</li>
</ul>
<a id="BABFEEGF" name="BABFEEGF"></a><a id="OTLCG91184" name="OTLCG91184"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Mapping Metadata</font></h3>
<p>The EclipseLink application metadata model is based on the project. The project includes descriptors, mappings, and various policies that customize the run-time capabilities. You associate this mapping and configuration information with a particular data source and application by referencing the project from a session.</p>
<p>For more information, see the following:</p>
<ul>
<li>
<p><a href="app_dev006.htm#BABEECEF">Creating Project Metadata</a></p>
</li>
<li>
<p><a href="descriptors.htm#CHECEAAE">Chapter 6, "Understanding Descriptors"</a></p>
</li>
<li>
<p><a href="mappingintro.htm#CHDFEJIJ">Chapter 7, "Understanding Mappings"</a></p>
</li>
</ul>
</div>
<!-- class="sect3" -->
<a id="BABBGFHF" name="BABBGFHF"></a><a id="OTLCG91186" name="OTLCG91186"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Cache</font></h3>
<p>By default, EclipseLink sessions provide an object-level cache that guarantees object identity and enhances performance by reducing the number of times the application needs to access the data source. EclipseLink provides a variety of cache options, including locking, refresh, invalidation, isolation, and coordination. Using cache coordination, you can configure EclipseLink to synchronize changes with other instances of the deployed application. You configure most cache options at the persistence unit or entity level. You can also configure cache options on a per-query basis or on a descriptor to apply to all queries on the reference class.</p>
<p>For more information, see <a href="cache.htm#CDEFHHEH">Chapter 9, "Understanding Caching."</a></p>
</div>
<!-- class="sect3" -->
<a id="BABJDGGH" name="BABJDGGH"></a><a id="OTLCG91187" name="OTLCG91187"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Queries and Expressions</font></h3>
<p>For Object-relational architectures, EclipseLink provides several object and data query types, and offers flexible options for query selection criteria, including the following:</p>
<ul>
<li>
<p>EclipseLink expressions</p>
</li>
<li>
<p>JPQL (Java Persistence Query Language)</p>
</li>
<li>
<p>SQL</p>
</li>
<li>
<p>Stored procedures</p>
</li>
<li>
<p>Query by example</p>
</li>
</ul>
<p>With these options, you can build any type of query. Oracle recommends using named queries to define application queries. Named queries are held in the project metadata and referenced by name. This simplifies application development and encapsulates the queries to reduce maintenance costs.</p>
<p>For Object-relational architectures, you are free to use any of the query options regardless of the persistent entity type. Alternatively, you can build queries in code, using the EclipseLink API.</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>These query techniques cannot be used with Object-XML (OXM, JAXB) mapping. However you can perform queries when using legacy EIS XML projects.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
<p>For more information, see <a href="queries.htm#CHDGGCJB">Chapter 10, "Understanding Queries"</a> and <a href="expressions.htm#CHDCAIGD">Chapter 11, "Understanding EclipseLink Expressions."</a></p>
</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="app_dev002.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="app_dev004.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>