documentation/2.7/jpa/extensions/annotations_ref.htm - www.eclipse.org/eclipselink - Git at Google

 <!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>Annotation Extensions Reference | EclipseLink 2.7.x Java Persistence API (JPA) Extensions Reference</title>
 <meta name="generator" content="Oracle DARB XHTML Converter (Mode = document) - Version 1.0.22 Build 1" />
 <meta name="date" content="2014-06-10T10:29:48Z" />
 <meta name="description" content="This chapter includes information on the EclipseLink extensions to the Java Persistence API (JPA) annotations. EclipseLink supports the Java Persistence API (JPA) 2." />
 <meta name="robots" content="noarchive" />
 <meta name="doctitle" content="Annotation Extensions Reference" />
 <meta name="relnum" content="Release 2.7" />
 <link rel="stylesheet" type="text/css" href="../../../dcommon/style.css" media="screen" />
 <link rel="copyright" href="http://www.eclipse.org/org/documents/epl-v10.php" 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="intro.htm" title="Previous" type="text/html" />
 <link rel="next" href="jpql.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:4sqnhke2any', 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">Java Persistence API (JPA) Extensions Reference for EclipseLink,
 Release 2.7</div></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_jpa_extensions.pdf" title="PDF" target="_blank"><img src="../../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td><td align="center"><a href="#disqus_thread" title="Comments""><img src="../../../dcommon/images/comments.png" style="padding-right:5px;border:0" alt="Comments"><br /><span class="mini">Comments</span></a>
 </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="intro.htm"><img src="../../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
 <td align="center"><a href="jpql.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 -->
 <script type="text/javascript" class="oac_no_warn">
 <!-- // <![CDATA[
 window.name='annotations_ref'
 // ]]> -->
 </script> <script type="text/javascript" class="oac_no_warn">
 // <![CDATA[
 function footdisplay(footnum,footnote) {
     var msg = window.open('', 'NewWindow' + footnum,
         'directories=no,height=120,location=no,menubar=no,resizable=yes,' +
         'scrollbars=yes,status=no,toolbar=no,width=598');
     msg.document.open('text/html');
     msg.document.write('<!DOCTYPE html ');
     msg.document.write('PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" ');

     msg.document.write('"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">');
     msg.document.write('<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head><title>');
     msg.document.write('Footnote ' + footnum);
     msg.document.write('<\/title><meta http-equiv="Content-Type" ');
     msg.document.write('content="text/html; charset=utf-8" />');
     msg.document.write('<meta http-equiv="Content-Script-Type" ');
     msg.document.write('content="text/javascript" />');
     msg.document.write('<style type="text/css"> <![CDATA[ ');
     msg.document.write('h1 {text-align: center; font-size: 14pt;}');
     msg.document.write('fieldset {border: none;}');
     msg.document.write('form {text-align: center;}');
     msg.document.write(' ]]\u003e <\/style>');
     msg.document.write('<\/head><body><h1>Footnote ' + footnum + '<\/h1><p>');
     msg.document.write(footnote);
     msg.document.write('<\/p><form action="" method="post"><fieldset>');
     msg.document.write('<input type="button" value="OK" ');
     msg.document.write('onclick="window.close();" />');
     msg.document.write('<\/fieldset><\/form><\/body><\/html>');
     msg.document.close();
     msg.focus();
 }
 // ]]>
 </script> <noscript>
 <p>The script content on this page is for navigation purposes only and does not alter the content in any way.</p>
 </noscript><a id="TLJPA306" name="TLJPA306"></a> <a id="sthref8" name="sthref8"></a>
 <h1 class="chapter"><font face="arial, helvetica, sans-serif" color="#330099"><span class="secnum">2</span> Annotation Extensions Reference</font></h1>
 <a id="TLJPA54053" name="TLJPA54053"></a>
 <p>This chapter includes information on the EclipseLink extensions to the Java Persistence API (JPA) annotations. EclipseLink supports the Java Persistence API (JPA) 2.0 specification. It also includes many enhancements and extensions.</p>
 <p>This chapter includes the following sections:</p>
 <ul>
 <li>
 <p><a href="#CACGDIBI">Functional Listing of Annotation Extensions</a></p>
 </li>
 <li>
 <p><a href="#CACBGBJG">Alphabetical Listing of Annotation Extensions</a></p>
 </li>
 </ul>
 <a id="CACGDIBI" name="CACGDIBI"></a><a id="TLJPA307" name="TLJPA307"></a>
 <div class="sect1">
 <h2 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">Functional Listing of Annotation Extensions</font></h2>
 <p>The following lists the EclipseLink annotation extensions, categorized by function:</p>
 <ul>
 <li>
 <p><a href="#CACFGAIC">Mapping Annotations</a></p>
 </li>
 <li>
 <p><a href="#CACGCEIJ">Entity Annotations</a></p>
 </li>
 <li>
 <p><a href="#CACDIEID">Converter Annotations</a></p>
 </li>
 <li>
 <p><a href="#CACGIACB">Caching Annotations</a></p>
 </li>
 <li>
 <p><a href="#CACJHFEC">Customization and Optimization Annotations</a></p>
 </li>
 <li>
 <p><a href="#CACDCCEG">Copy Policy Annotations</a></p>
 </li>
 <li>
 <p><a href="#CACGFGED">Returning Policy Annotations</a></p>
 </li>
 <li>
 <p><a href="#CACCBFFE">Stored Procedure and Function Annotations</a></p>
 </li>
 <li>
 <p><a href="#CACHIHIB">Partitioning Annotations</a></p>
 </li>
 <li>
 <p><a href="#CACDIHJI">Non-relational (NoSQL) Annotations</a></p>
 </li>
 </ul>
 <a id="CACFGAIC" name="CACFGAIC"></a><a id="TLJPA308" name="TLJPA308"></a>
 <div class="sect2"><!-- infolevel="all" infotype="General" -->
 <h3 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Mapping Annotations</font></h3>
 <p>EclipseLink includes the following annotation extensions for mappings:</p>
 <ul>
 <li>
 <p><a href="#CHDDDDAI">@PrivateOwned</a></p>
 </li>
 <li>
 <p><a href="#CEGFFHHA">@JoinFetch</a></p>
 </li>
 <li>
 <p><a href="#CHDIFIJF">@Mutable</a></p>
 </li>
 <li>
 <p><a href="#BGBCHEDG">@Property</a></p>
 </li>
 <li>
 <p><a href="#BABCJGIG">@Transformation</a></p>
 </li>
 <li>
 <p><a href="#CHDGHHBA">@ReadTransformer</a></p>
 </li>
 <li>
 <p><a href="#BGBGGAEA">@WriteTransformer</a></p>
 </li>
 <li>
 <p><a href="#BCFCCEJF">@WriteTransformers</a></p>
 </li>
 </ul>
 </div>
 <!-- class="sect2" -->
 <a id="CACGCEIJ" name="CACGCEIJ"></a><a id="TLJPA309" name="TLJPA309"></a>
 <div class="sect2"><!-- infolevel="all" infotype="General" -->
 <h3 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Entity Annotations</font></h3>
 <p>EclipseLink includes the following annotation extensions for entities:</p>
 <ul>
 <li>
 <p><a href="#additionalcriteria">@AdditionalCriteria</a></p>
 </li>
 <li>
 <p><a href="#BEICFBDD">@ExcludeDefaultMappings</a></p>
 </li>
 <li>
 <p><a href="#BABIEJGD">@Multitenant</a></p>
 </li>
 <li>
 <p><a href="#BCGIACHD">@OptimisticLocking</a></p>
 </li>
 <li>
 <p><a href="#BGBGEFBD">@ReadOnly</a></p>
 </li>
 <li>
 <p><a href="#CACDCCIA">@SerializedObject</a></p>
 </li>
 <li>
 <p><a href="#CECBEBEA">@TenantDiscriminatorColumns</a></p>
 </li>
 <li>
 <p><a href="#CHECIDGH">@TenantDiscriminatorColumn</a></p>
 </li>
 <li>
 <p><a href="#CHDFJJEC">@TenantTableDiscriminator</a></p>
 </li>
 <li>
 <p><a href="#CBBDCAHG">@Struct</a></p>
 </li>
 </ul>
 </div>
 <!-- class="sect2" -->
 <a id="CACDIEID" name="CACDIEID"></a><a id="TLJPA310" name="TLJPA310"></a>
 <div class="sect2"><!-- infolevel="all" infotype="General" -->
 <h3 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Converter Annotations</font></h3>
 <p>EclipseLink includes the following annotation extensions for converting data:</p>
 <ul>
 <li>
 <p><a href="#BEHGJHCD">@Convert</a></p>
 </li>
 <li>
 <p><a href="#CHDEHJEB">@Converter</a></p>
 </li>
 <li>
 <p><a href="#CIHEBAFB">@Converters</a></p>
 </li>
 <li>
 <p><a href="#CHDHCCJF">@TypeConverter</a></p>
 </li>
 <li>
 <p><a href="#BCFBEIAE">@TypeConverters</a></p>
 </li>
 <li>
 <p><a href="#BGBBDGAI">@ObjectTypeConverter</a></p>
 </li>
 <li>
 <p><a href="#CHDCHJHF">@ObjectTypeConverters</a></p>
 </li>
 <li>
 <p><a href="#BGBJEBBB">@StructConverter</a></p>
 </li>
 <li>
 <p><a href="#CHDCJCDE">@StructConverters</a></p>
 </li>
 </ul>
 </div>
 <!-- class="sect2" -->
 <a id="CACGIACB" name="CACGIACB"></a><a id="TLJPA311" name="TLJPA311"></a>
 <div class="sect2"><!-- infolevel="all" infotype="General" -->
 <h3 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Caching Annotations</font></h3>
 <p>EclipseLink includes the following annotation extensions for caching:</p>
 <ul>
 <li>
 <p><a href="#CHDBBIHE">@Cache</a></p>
 </li>
 <li>
 <p><a href="#CEGFEJCH">@CacheIndex</a></p>
 </li>
 <li>
 <p><a href="#BABIJDDB">@CacheIndexes</a></p>
 </li>
 <li>
 <p><a href="#BABJGDGB">@CacheInterceptor</a></p>
 </li>
 <li>
 <p><a href="#BGBGACHC">@TimeOfDay</a></p>
 </li>
 <li>
 <p><a href="#BABICJEJ">@ExistenceChecking</a></p>
 </li>
 </ul>
 </div>
 <!-- class="sect2" -->
 <a id="CACJHFEC" name="CACJHFEC"></a><a id="TLJPA312" name="TLJPA312"></a>
 <div class="sect2"><!-- infolevel="all" infotype="General" -->
 <h3 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Customization and Optimization Annotations</font></h3>
 <p>EclipseLink includes the following annotation extensions for customization and optimization.</p>
 <ul>
 <li>
 <p><a href="#CHDCCDGC">@Customizer</a></p>
 </li>
 <li>
 <p><a href="#CEGCCCCJ">@ChangeTracking</a></p>
 </li>
 </ul>
 </div>
 <!-- class="sect2" -->
 <a id="CACDCCEG" name="CACDCCEG"></a><a id="TLJPA313" name="TLJPA313"></a>
 <div class="sect2"><!-- infolevel="all" infotype="General" -->
 <h3 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Copy Policy Annotations</font></h3>
 <p>EclipseLink includes the following annotation extensions for copy policies:</p>
 <ul>
 <li>
 <p><a href="#CDDJGFHA">@CloneCopyPolicy</a></p>
 </li>
 <li>
 <p><a href="#BGBDGCDJ">@CopyPolicy</a></p>
 </li>
 <li>
 <p><a href="#CHDCJEIG">@InstantiationCopyPolicy</a></p>
 </li>
 </ul>
 </div>
 <!-- class="sect2" -->
 <a id="CACGFGED" name="CACGFGED"></a><a id="TLJPA314" name="TLJPA314"></a>
 <div class="sect2"><!-- infolevel="all" infotype="General" -->
 <h3 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Returning Policy Annotations</font></h3>
 <p>EclipseLink includes the following annotation extensions for returning policies:</p>
 <ul>
 <li>
 <p><a href="#CIHHEGJE">@ReturnInsert</a></p>
 </li>
 <li>
 <p><a href="#CACHDFCF">@ReturnUpdate</a></p>
 </li>
 </ul>
 </div>
 <!-- class="sect2" -->
 <a id="CACCBFFE" name="CACCBFFE"></a><a id="TLJPA315" name="TLJPA315"></a>
 <div class="sect2"><!-- infolevel="all" infotype="General" -->
 <h3 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Stored Procedure and Function Annotations</font></h3>
 <p>EclipseLink includes the following annotation extensions for stored procedures and stored functions:</p>
 <ul>
 <li>
 <p><a href="#BGBDHGJE">@NamedPLSQLStoredFunctionQueries</a></p>
 </li>
 <li>
 <p><a href="#CHDIAEFF">@NamedPLSQLStoredFunctionQuery</a></p>
 </li>
 <li>
 <p><a href="#BABJCEJH3">@NamedPLSQLStoredProcedureQueries</a></p>
 </li>
 <li>
 <p><a href="#BGBDHGJE2">@NamedPLSQLStoredProcedureQuery</a></p>
 </li>
 <li>
 <p><a href="#CIHJFFDI">@NamedStoredFunctionQueries</a></p>
 </li>
 <li>
 <p><a href="#BABFBIFE">@NamedStoredFunctionQuery</a></p>
 </li>
 <li>
 <p><a href="#BABJCEJH">@NamedStoredProcedureQueries</a></p>
 </li>
 <li>
 <p><a href="#BGBGAEFF">@NamedStoredProcedureQuery</a></p>
 </li>
 <li>
 <p><a href="#CACGHFJB">@OracleArray</a></p>
 </li>
 <li>
 <p><a href="#CACCIBAB">@OracleArrays</a></p>
 </li>
 <li>
 <p><a href="#CACEBEGE">@OracleObject</a></p>
 </li>
 <li>
 <p><a href="#CACFFCEE">@OracleObjects</a></p>
 </li>
 <li>
 <p><a href="#CHDDEBEC">@PLSQLParameter</a></p>
 </li>
 <li>
 <p><a href="#CHDBGAED">@PLSQLRecord</a></p>
 </li>
 <li>
 <p><a href="#CHDBGAED4">@PLSQLRecords</a></p>
 </li>
 <li>
 <p><a href="#CACJBHHF">@PLSQLTable</a></p>
 </li>
 <li>
 <p><a href="#CACCBFBC">@PLSQLTables</a></p>
 </li>
 <li>
 <p><a href="#CHDDEBEC6">@StoredProcedureParameter</a></p>
 </li>
 </ul>
 </div>
 <!-- class="sect2" -->
 <a id="CACHIHIB" name="CACHIHIB"></a><a id="TLJPA316" name="TLJPA316"></a>
 <div class="sect2"><!-- infolevel="all" infotype="General" -->
 <h3 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Partitioning Annotations</font></h3>
 <p>EclipseLink includes the following annotation extensions for using partitions:</p>
 <ul>
 <li>
 <p><a href="#CEGBDBEG">@HashPartitioning</a></p>
 </li>
 <li>
 <p><a href="#CHDDAHEB">@Partitioned</a></p>
 </li>
 <li>
 <p><a href="#CEGDCFDA">@Partitioning</a></p>
 </li>
 <li>
 <p><a href="#BCGIIAFB">@PinnedPartitioning</a></p>
 </li>
 <li>
 <p><a href="#BABCFDAJ">@RangePartition</a></p>
 </li>
 <li>
 <p><a href="#BCGCGEIH">@RangePartitioning</a></p>
 </li>
 <li>
 <p><a href="#BABJEFJH">@ReplicationPartitioning</a></p>
 </li>
 <li>
 <p><a href="#BCGBJGFF">@RoundRobinPartitioning</a></p>
 </li>
 <li>
 <p><a href="#BCGEJFAH">@UnionPartitioning</a></p>
 </li>
 <li>
 <p><a href="#CEGHFJDJ">@ValuePartitioning</a></p>
 </li>
 </ul>
 </div>
 <!-- class="sect2" -->
 <a id="CACDIHJI" name="CACDIHJI"></a><a id="TLJPA54001" name="TLJPA54001"></a>
 <div class="sect2"><!-- infolevel="all" infotype="General" -->
 <h3 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Non-relational (NoSQL) Annotations</font></h3>
 <p>EclipseLink includes the following annotation extensions for non-relational datasources:</p>
 <ul>
 <li>
 <p><a href="#CBHHCHAC">@Field</a></p>
 </li>
 <li>
 <p><a href="#CIHCAFEI">@JoinField</a></p>
 </li>
 <li>
 <p><a href="#BEIFHJJE">@JoinFields</a></p>
 </li>
 <li>
 <p><a href="#BJEIEBHC">@NoSql</a></p>
 </li>
 </ul>
 </div>
 <!-- class="sect2" --></div>
 <!-- class="sect1" -->
 <a id="CACBGBJG" name="CACBGBJG"></a><a id="TLJPA317" name="TLJPA317"></a>
 <div class="sect1">
 <h2 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">Alphabetical Listing of Annotation Extensions</font></h2>
 <p>The following lists the EclipseLink annotation extensions:</p>
 <ul>
 <li>
 <p><a href="#additionalcriteria">@AdditionalCriteria</a></p>
 </li>
 <li>
 <p><a href="#CHDDDFDA">@Array</a></p>
 </li>
 <li>
 <p><a href="#CHDCCIDA">@BatchFetch</a></p>
 </li>
 <li>
 <p><a href="#CHDBBIHE">@Cache</a></p>
 </li>
 <li>
 <p><a href="#CEGFEJCH">@CacheIndex</a></p>
 </li>
 <li>
 <p><a href="#BABIJDDB">@CacheIndexes</a></p>
 </li>
 <li>
 <p><a href="#BABJGDGB">@CacheInterceptor</a></p>
 </li>
 <li>
 <p><a href="#CIABIIEB">@CascadeOnDelete</a></p>
 </li>
 <li>
 <p><a href="#CEGCCCCJ">@ChangeTracking</a></p>
 </li>
 <li>
 <p><a href="#BGBHAADB">@ClassExtractor</a></p>
 </li>
 <li>
 <p><a href="#CDDJGFHA">@CloneCopyPolicy</a></p>
 </li>
 <li>
 <p><a href="#BGBHHCJH">@CompositeMember</a></p>
 </li>
 <li>
 <p><a href="#CBBJAJCH">@ConversionValue</a></p>
 </li>
 <li>
 <p><a href="#BEHGJHCD">@Convert</a></p>
 </li>
 <li>
 <p><a href="#CHDEHJEB">@Converter</a></p>
 </li>
 <li>
 <p><a href="#CIHEBAFB">@Converters</a></p>
 </li>
 <li>
 <p><a href="#BGBDGCDJ">@CopyPolicy</a></p>
 </li>
 <li>
 <p><a href="#CHDCCDGC">@Customizer</a></p>
 </li>
 <li>
 <p><a href="#BABDDGFG">@DeleteAll</a></p>
 </li>
 <li>
 <p><a href="#CIHGDDED">@DiscriminatorClass</a></p>
 </li>
 <li>
 <p><a href="#BEICFBDD">@ExcludeDefaultMappings</a></p>
 </li>
 <li>
 <p><a href="#BABICJEJ">@ExistenceChecking</a></p>
 </li>
 <li>
 <p><a href="#BABCHIGE">@FetchAttribute</a></p>
 </li>
 <li>
 <p><a href="#BABJBDEG">@FetchGroup</a></p>
 </li>
 <li>
 <p><a href="#CHDIEBGG">@FetchGroups</a></p>
 </li>
 <li>
 <p><a href="#CBHHCHAC">@Field</a></p>
 </li>
 <li>
 <p><a href="#CEGBDBEG">@HashPartitioning</a></p>
 </li>
 <li>
 <p><a href="#BABGIFEC">@Index</a></p>
 </li>
 <li>
 <p><a href="#CHDHGAIE">@Indexes</a></p>
 </li>
 <li>
 <p><a href="#CHDCJEIG">@InstantiationCopyPolicy</a></p>
 </li>
 <li>
 <p><a href="#CEGFFHHA">@JoinFetch</a></p>
 </li>
 <li>
 <p><a href="#CIHCAFEI">@JoinField</a></p>
 </li>
 <li>
 <p><a href="#BEIFHJJE">@JoinFields</a></p>
 </li>
 <li>
 <p><a href="#BEHBBCDB">@MapKeyConvert</a></p>
 </li>
 <li>
 <p><a href="#BABIEJGD">@Multitenant</a></p>
 </li>
 <li>
 <p><a href="#CHDIFIJF">@Mutable</a></p>
 </li>
 <li>
 <p><a href="#BGBDHGJE">@NamedPLSQLStoredFunctionQueries</a></p>
 </li>
 <li>
 <p><a href="#BGBDHGJE2">@NamedPLSQLStoredProcedureQuery</a></p>
 </li>
 <li>
 <p><a href="#CIHJFFDI">@NamedStoredFunctionQueries</a></p>
 </li>
 <li>
 <p><a href="#BABFBIFE">@NamedStoredFunctionQuery</a></p>
 </li>
 <li>
 <p><a href="#BABJCEJH">@NamedStoredProcedureQueries</a></p>
 </li>
 <li>
 <p><a href="#BGBGAEFF">@NamedStoredProcedureQuery</a></p>
 </li>
 <li>
 <p><a href="#CHDGEFGD">@Noncacheable</a></p>
 </li>
 <li>
 <p><a href="#BJEIEBHC">@NoSql</a></p>
 </li>
 <li>
 <p><a href="#BGBBDGAI">@ObjectTypeConverter</a></p>
 </li>
 <li>
 <p><a href="#CHDCHJHF">@ObjectTypeConverters</a></p>
 </li>
 <li>
 <p><a href="#BCGIACHD">@OptimisticLocking</a></p>
 </li>
 <li>
 <p><a href="#CACGHFJB">@OracleArray</a></p>
 </li>
 <li>
 <p><a href="#CACCIBAB">@OracleArrays</a></p>
 </li>
 <li>
 <p><a href="#CACEBEGE">@OracleObject</a></p>
 </li>
 <li>
 <p><a href="#CACFFCEE">@OracleObjects</a></p>
 </li>
 <li>
 <p><a href="#CHDDIBJF">@OrderCorrection</a></p>
 </li>
 <li>
 <p><a href="#CHDDAHEB">@Partitioned</a></p>
 </li>
 <li>
 <p><a href="#CEGDCFDA">@Partitioning</a></p>
 </li>
 <li>
 <p><a href="#BCGIIAFB">@PinnedPartitioning</a></p>
 </li>
 <li>
 <p><a href="#CHDDEBEC">@PLSQLParameter</a></p>
 </li>
 <li>
 <p><a href="#CHDBGAED">@PLSQLRecord</a></p>
 </li>
 <li>
 <p><a href="#CHDBGAED4">@PLSQLRecords</a></p>
 </li>
 <li>
 <p><a href="#CACJBHHF">@PLSQLTable</a></p>
 </li>
 <li>
 <p><a href="#CACCBFBC">@PLSQLTables</a></p>
 </li>
 <li>
 <p><a href="#BGEBBFJE">@PrimaryKey</a></p>
 </li>
 <li>
 <p><a href="#CHDDDDAI">@PrivateOwned</a></p>
 </li>
 <li>
 <p><a href="#BABJHAFD">@Properties</a></p>
 </li>
 <li>
 <p><a href="#BGBCHEDG">@Property</a></p>
 </li>
 <li>
 <p><a href="#CIHCGHGA">@QueryRedirectors</a></p>
 </li>
 <li>
 <p><a href="#BABCFDAJ">@RangePartition</a></p>
 </li>
 <li>
 <p><a href="#BCGCGEIH">@RangePartitioning</a></p>
 </li>
 <li>
 <p><a href="#BGBGEFBD">@ReadOnly</a></p>
 </li>
 <li>
 <p><a href="#CHDGHHBA">@ReadTransformer</a></p>
 </li>
 <li>
 <p><a href="#BABJEFJH">@ReplicationPartitioning</a></p>
 </li>
 <li>
 <p><a href="#CIHHEGJE">@ReturnInsert</a></p>
 </li>
 <li>
 <p><a href="#CACHDFCF">@ReturnUpdate</a></p>
 </li>
 <li>
 <p><a href="#BCGBJGFF">@RoundRobinPartitioning</a></p>
 </li>
 <li>
 <p><a href="#CACDCCIA">@SerializedObject</a></p>
 </li>
 <li>
 <p><a href="#CHDDEBEC6">@StoredProcedureParameter</a></p>
 </li>
 <li>
 <p><a href="#CBBDCAHG">@Struct</a></p>
 </li>
 <li>
 <p><a href="#BGBJEBBB">@StructConverter</a></p>
 </li>
 <li>
 <p><a href="#CHDCJCDE">@StructConverters</a></p>
 </li>
 <li>
 <p><a href="#CACIJAFA">@Structure</a></p>
 </li>
 <li>
 <p><a href="#CECBEBEA">@TenantDiscriminatorColumns</a></p>
 </li>
 <li>
 <p><a href="#CHECIDGH">@TenantDiscriminatorColumn</a></p>
 </li>
 <li>
 <p><a href="#CHDFJJEC">@TenantTableDiscriminator</a></p>
 </li>
 <li>
 <p><a href="#BGBGACHC">@TimeOfDay</a></p>
 </li>
 <li>
 <p><a href="#BABCJGIG">@Transformation</a></p>
 </li>
 <li>
 <p><a href="#CHDHCCJF">@TypeConverter</a></p>
 </li>
 <li>
 <p><a href="#BCFBEIAE">@TypeConverters</a></p>
 </li>
 <li>
 <p><a href="#CJHFCGEJ">@ValuePartition</a></p>
 </li>
 <li>
 <p><a href="#CEGHFJDJ">@ValuePartitioning</a></p>
 </li>
 <li>
 <p><a href="#CFAFIIFC">@UuidGenerator</a></p>
 </li>
 <li>
 <p><a href="#BCGEJFAH">@UnionPartitioning</a></p>
 </li>
 <li>
 <p><a href="#CHDDFDGF">@VariableOneToOne</a></p>
 </li>
 <li>
 <p><a href="#CIHFBCFI">@VirtualAccessMethods</a></p>
 </li>
 <li>
 <p><a href="#BGBGGAEA">@WriteTransformer</a></p>
 </li>
 <li>
 <p><a href="#BCFCCEJF">@WriteTransformers</a></p>
 </li>
 </ul>
 </div>
 <!-- class="sect1" -->
 <a id="additionalcriteria" name="additionalcriteria"></a><a id="TLJPA318" name="TLJPA318"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@AdditionalCriteria</font></h2>
 <p>Use <code>@AdditionalCriteria</code> to define parameterized views on data.</p>
 <p>You can define additional criteria on entities or mapped superclass. When specified at the mapped superclass level, the additional criteria definition applies to all inheriting entities, unless those entities define their own additional criteria, in which case those defined for the mapped superclass are ignored.</p>
 <a id="sthref9" name="sthref9"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDGJGDCxx">Table 2-1</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA319" name="TLJPA319"></a><a id="sthref10" name="sthref10"></a><a id="CHDGJGDCxx" name="CHDGJGDCxx"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-1 @AdditionalCriteria Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@AdditionalCriteria Annotation Elements" summary="This table describes the attributes for the @AdditionalCriteria annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="18%" />
 <col width="*" />
 <col width="18%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t2"><font face="Arial, Helvetica, sans-serif"><strong>Attribute</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t2"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t2"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t2" headers="r1c1-t2">
 <p><code>value</code></p>
 </td>
 <td align="left" headers="r2c1-t2 r1c2-t2">
 <p>(Required) The JPQL fragment to use as the additional criteria</p>
 </td>
 <td align="left" headers="r2c1-t2 r1c3-t2"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref11" name="sthref11"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Additional criteria can provide an additional filtering mechanism for queries. This filtering option, for example, allows you to use an existing additional <code>JOIN</code> expression defined for the entity or mapped superclass and allows you to pass parameters to it.</p>
 <p>Set additional criteria parameters through properties on the entity manager factory or on the entity manager. Properties set on the entity manager override identically named properties set on the entity manager factory. Properties must be set on an entity manager before executing a query. Do not change the properties for the lifespan of the entity manager.</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>Additional criteria are not supported with native SQL queries.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref12" name="sthref12"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>Specify additional criteria using the <code>@AdditionalCriteria</code> annotation or the <code>&lt;additional-criteria&gt;</code> element. The additional criteria definition supports any valid JPQL string and must use <code>this</code> as an alias to form the additional criteria. For example:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 @AdditionalCriteria("this.address.city IS NOT NULL")
 </pre>
 <p><a href="#CFHFACAI">Example 2-1</a> shows additional criteria defined for the entity <code>Employee</code> and then shows the parameters for the additional criteria set on the entity manager.</p>
 <div class="example"><a id="CFHFACAI" name="CFHFACAI"></a><a id="TLJPA320" name="TLJPA320"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-1 Using @AdditionalCriteria Annotation</font></em></strong></p>
 <p>Define additional criteria on <code>Employee</code>, as follows:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 package model;

 <strong>@AdditionalCriteria("this.company=:COMPANY")</strong>
 public class Employee {

   ...
 }
 </pre>
 <p>Set the property on the <code>EntityManager</code>. This example returns all employees of <code>MyCompany</code>.</p>
 <pre xml:space="preserve" class="oac_no_warn">
 entityManager.setProperty("COMPANY", "MyCompany");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CFHHBDFE">Example 2-2</a> illustrates the same example as before, but uses the <code>&lt;additional-criteria&gt;</code> element in the <code>eclipselink-orm.xml</code> mapping file.</p>
 <div class="example"><a id="CFHHBDFE" name="CFHHBDFE"></a><a id="TLJPA321" name="TLJPA321"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-2 Using &lt;additional-criteria&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>&lt;additional-criteria&gt;</strong>
   &lt;criteria&gt;this.address.city IS NOT NULL&lt;/criteria&gt;
 <strong>&lt;/additional-criteria&gt;</strong>
 </pre></div>
 <!-- class="example" -->
 <a id="TLJPA322" name="TLJPA322"></a>
 <p><b><font face="arial, helvetica, sans-serif" color="#330099">Uses for Additional Criteria</font></b></p>
 <p>Uses for additional criteria include:</p>
 <ul>
 <li>
 <p><a href="#CHDIFCDI">Multitenancy</a></p>
 </li>
 <li>
 <p><a href="#CHDJGCJG">Soft Delete</a></p>
 </li>
 <li>
 <p><a href="#CHDFJFFA">Data History</a></p>
 </li>
 <li>
 <p><a href="#CHDEGFBA">Temporal Filtering</a></p>
 </li>
 <li>
 <p><a href="#CHDBGJHD">Shared Table</a></p>
 </li>
 </ul>
 <a id="CHDIFCDI" name="CHDIFCDI"></a>
 <p><strong><font face="arial, helvetica, sans-serif" color="#330099">Multitenancy</font></strong></p>
 <p>In a multitenancy environment, tenants (users, clients, organizations, applications) can share database tables, but the views on the data are restricted so that tenants have access only to their own data. You can use additional criteria to configure such restrictions.</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>In most cases, you use the <code><a href="#BABIEJGD">@Multitenant</a></code> annotation in multitenancy environments instead, as shown.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <div class="example"><a id="TLJPA54054" name="TLJPA54054"></a><a id="sthref13" name="sthref13"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-3 Multitenancy Example 1</font></em></strong></p>
 <p>The following example restricts the data for a <strong>Billing</strong> client, such as a billing application or billing organization:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 @AdditionalCriteria("this.tenant = 'Billing'")
 </pre></div>
 <!-- class="example" -->
 <div class="example"><a id="TLJPA54055" name="TLJPA54055"></a><a id="sthref14" name="sthref14"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-4 Multitenancy Example 2</font></em></strong></p>
 <p>The following example could be used in an application used by multiple tenants at the same time. The additional criteria is defined as:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 @AdditionalCriteria("this.tenant = :tenant")

 </pre></div>
 <!-- class="example" -->
 <p>When the tenant acquires its <code>EntityManagerFactory</code> or <code>EntityManager</code>, the persistence/entity manager property tenant is set to the name of the tenant acquiring it. For example,</p>
 <pre xml:space="preserve" class="oac_no_warn">
 Map properties = new HashMap();
 properties.put("tenant", "ACME");
 EntityManagerFactory emf = Persistence.createEntityManagerFactory(properties);
 </pre>
 <p>Or</p>
 <pre xml:space="preserve" class="oac_no_warn">
 Map properties = new HashMap();
 properties.put("tenant", "ACME");
 EntityManager em = factory.createEntityManager(properties);
 </pre>
 <a id="CHDJGCJG" name="CHDJGCJG"></a>
 <p><strong><font face="arial, helvetica, sans-serif" color="#330099">Soft Delete</font></strong></p>
 <p>The following example filters data that is marked as deleted (but which still exists in the table) from a query:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 @AdditionalCriteria("this.isDeleted = false")
 </pre>
 <a id="CHDFJFFA" name="CHDFJFFA"></a>
 <p><strong><font face="arial, helvetica, sans-serif" color="#330099">Data History</font></strong></p>
 <p>The following example returns the current data from a query, thus filtering out any out-of-date data, for example data stored in a history table.</p>
 <pre xml:space="preserve" class="oac_no_warn">
 @AdditionalCriteria("this.endDate is null")
 </pre>
 <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>EclipseLink also provides specific history support, via <code>HistoryPolicy</code> . See Tracking Changes Using History Policy at <code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/History">http://wiki.eclipse.org/EclipseLink/Examples/JPA/History</a></code>.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="CHDEGFBA" name="CHDEGFBA"></a>
 <p><strong><font face="arial, helvetica, sans-serif" color="#330099">Temporal Filtering</font></strong></p>
 <p>The following example filters on a specific date:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 @AdditionalCriteria("this.startDate &lt;= :viewDate and this.endDate &gt;= :viewDate")
 </pre>
 <a id="CHDBGJHD" name="CHDBGJHD"></a>
 <p><strong><font face="arial, helvetica, sans-serif" color="#330099">Shared Table</font></strong></p>
 <p>For a shared table, there may be inheritance in the table but not in the object model. For example, a <code>SavingsAccount</code> class may be mapped to an <code>ACCOUNT</code> table, but the <code>ACCOUNT</code> table contains both savings account data (<code>SAVINGS</code>) and checking account (<code>CHECKING</code>) data. You can use additional criteria to filter out the checking account data.</p>
 <a id="sthref15" name="sthref15"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="jpql.htm#column">"COLUMN"</a></p>
 </li>
 <li>
 <p><a href="#BABIEJGD">"@Multitenant"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDDDFDA" name="CHDDDFDA"></a><a id="TLJPA325" name="TLJPA325"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Array</font></h2>
 <p>Use <code>@Array</code> to define object-relational data types supported by specific databases, such as Oracle <code>VARRAY</code> types or PostgreSQL JDBC <code>Array</code> types.</p>
 <a id="sthref16" name="sthref16"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CBABBAJF">Table 2-2</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA326" name="TLJPA326"></a><a id="sthref17" name="sthref17"></a><a id="CBABBAJF" name="CBABBAJF"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-2 @Array Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Array Annotation Elements" summary="This table describes the attributes for the @Array annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="21%" />
 <col width="*" />
 <col width="25%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t6"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t6"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t6"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t6" headers="r1c1-t6">
 <p><code>databaseType</code></p>
 </td>
 <td align="left" headers="r2c1-t6 r1c2-t6">
 <p>(Required) The name of the database array structure type</p>
 </td>
 <td align="left" headers="r2c1-t6 r1c3-t6"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t6" headers="r1c1-t6">
 <p><code>targetClass</code></p>
 </td>
 <td align="left" headers="r3c1-t6 r1c2-t6">
 <p>(Optional only if the collection field or property is defined using Java generics; otherwise Required) The class (basic or embeddable) that is the element type of the collection</p>
 </td>
 <td align="left" headers="r3c1-t6 r1c3-t6">
 <p>Parameterized type of the collection.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref18" name="sthref18"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Use <code>@Array</code> on a collection attribute that is persisted to an <code>Array</code> type. The collection can be of basic types or embeddable class mapped using a <code>Struct</code>.</p>
 <a id="sthref19" name="sthref19"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CBABHEHD">Example 2-5</a> shows how to use this annotation with an Oracle <code>VARRAY</code> type.</p>
 <div class="example"><a id="CBABHEHD" name="CBABHEHD"></a><a id="TLJPA327" name="TLJPA327"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-5 Using @Array with Oracle VARRAY</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 VARRAY DDL:
 CREATE TYPE TASKS_TYPE AS VARRAY(10) OF VARCHAR(100)
 </pre>
 <pre xml:space="preserve" class="oac_no_warn">
 @Struct
 @Entity
 public class Employee {
     @Id
     private long id;
     @Array(databaseType="TASKS_TYPE")
     private List&lt;String&gt; tasks;
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CBACGBDA">Example 2-6</a> shows how to use this annotation with an PostgreSQL <code>Struct</code> type.</p>
 <div class="example"><a id="CBACGBDA" name="CBACGBDA"></a><a id="TLJPA328" name="TLJPA328"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-6 Using @Array with PostgreSQL Struct</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 DDL:
 CREATE TABLE EMPLOYEE (ID BIGINT, TASKS TEXT[])
 </pre>
 <pre xml:space="preserve" class="oac_no_warn">
 @Struct
 @Entity
 public class Employee {
     @Id
     private long id;
     @Array(databaseType="TEXT")
     private List&lt;String&gt; tasks;
 }
 </pre></div>
 <!-- class="example" -->
 <a id="sthref20" name="sthref20"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see the following:</p>
 <ul>
 <li>
 <p><a href="#CBBDCAHG">"@Struct"</a></p>
 </li>
 <li>
 <p><em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p><em>Solutions Guide for EclispeLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDCCIDA" name="CHDCCIDA"></a><a id="TLJPA329" name="TLJPA329"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@BatchFetch</font></h2>
 <p>Use <code>@BatchFetch</code> to read objects related to a relationship mapping (such as <code>@OneToOne</code>, <code>@OneToMany</code>, <code>@ManyToMany</code>, and <code>@ElementCollection</code>) to be read in a single query.</p>
 <a id="sthref21" name="sthref21"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDJBJBC">Table 2-3</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA330" name="TLJPA330"></a><a id="sthref22" name="sthref22"></a><a id="CHDJBJBC" name="CHDJBJBC"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-3 @BatchFetch Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@BatchFetch Annotation Elements" summary="This table describes the attributes for the @BatchFetch annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="25%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t7"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t7"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t7"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t7" headers="r1c1-t7">
 <p>size</p>
 </td>
 <td align="left" headers="r2c1-t7 r1c2-t7">
 <p>Default size of the batch fetch, used only when <code>BatchFetchType</code>=<code>IN</code> to define the number of keys in each <code>IN</code> clause</p>
 </td>
 <td align="left" headers="r2c1-t7 r1c3-t7">
 <p><code>256</code> or the query's <code>pageSize</code> (for cursor queries)</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t7" headers="r1c1-t7">
 <p>BatchFetchType</p>
 </td>
 <td align="left" headers="r3c1-t7 r1c2-t7">
 <p>(Optional) The type of batch fetch to use:</p>
 <ul>
 <li>
 <p><code>JOIN</code> &#8211; The original query's selection criteria is joined with the batch query</p>
 </li>
 <li>
 <p><code>EXISTS</code> &#8211; Uses an SQL <code>EXISTS</code> clause and a sub-select in the batch query instead of a <code>JOIN</code></p>
 </li>
 <li>
 <p><code>IN</code> &#8211; Uses an SQL <code>IN</code> clause in the batch query, passing in the source object IDs.</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r3c1-t7 r1c3-t7">
 <p><code>JOIN</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref23" name="sthref23"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Batch fetching allows for the optimal loading of a tree. Setting the <code>@BatchFetch</code> annotation on a <em>child</em> relationship of a tree structure causes EclipseLink to use a <em>single</em> SQL statement for each level. For example, consider an object with an <code>EMPLOYEE</code> and <code>PHONE</code> table in which <code>PHONE</code> has a foreign key to <code>EMPLOYEE</code>. By default, reading a list of employees' addresses by default requires <em>n</em> queries, for each employee's address. With batch fetching, you use <em>one query</em> for all the addresses.</p>
 <p>Using <code>BatchFetchType=EXISTS</code> does not require an SQL <code>DISTINCT</code> statement (which may cause issues with LOBs) and may be more efficient for some types of queries or on specific databases.</p>
 <p>When using <code>BatchFetchType=IN</code>, EclipseLink selects only objects not already in the cache. This method may work better with cursors or pagination, or in situations in which you cannot use a <code>JOIN</code>. On some databases, this may only work for singleton IDs.</p>
 <a id="sthref24" name="sthref24"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>The following examples show how to use this annotation (and XML) with different batch fetch types.</p>
 <div class="example"><a id="TLJPA331" name="TLJPA331"></a><a id="sthref25" name="sthref25"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-7 Using JOIN BatchFetch Type</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @OneToOne
 @BatchFetch(BatchFetchType.JOIN)
 private Address address;
 </pre>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;one-to-one name="address"&gt;
     &lt;batch-fetch type="JOIN" /&gt;
 &lt;/one-to-one&gt;


 </pre></div>
 <!-- class="example" -->
 <div class="example"><a id="TLJPA332" name="TLJPA332"></a><a id="sthref26" name="sthref26"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-8 Using EXISTS BatchFetch Type</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @BatchFetch(BatchFetchType.EXISTS)
 @OneToOne
 public Map&lt;String, String&gt; getStringMap() {
 return stringMap;
 }
 </pre>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;one-to-one name="StringMap"&gt;
     &lt;batch-fetch type="EXISTS"/&gt;
 &lt;/one-to-one&gt;
 </pre></div>
 <!-- class="example" -->
 <div class="example"><a id="TLJPA333" name="TLJPA333"></a><a id="sthref27" name="sthref27"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-9 Using IN BatchFetch Type</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @BatchFetch(BatchFetchType.IN, size=50)
 @OneToOne
 public Map&lt;String, String&gt; getStringMap() {
 return stringMap;
 }

 </pre>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;one-to-one name="StringMap"&gt;
     &lt;batch-fetch type="IN" size="50" /&gt;
 &lt;/one-to-one&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref28" name="sthref28"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CEGFFHHA">"@JoinFetch"</a></p>
 </li>
 <li>
 <p><em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p><em>Solutions Guide for EclispeLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDBBIHE" name="CHDBBIHE"></a><a id="TLJPA334" name="TLJPA334"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Cache</font></h2>
 <p>Use <code>@Cache</code> (in place of the JPA <code>@Cachable</code> annotation) to configure the EclipseLink object cache. By default, EclipseLink uses a shared object cache to cache all objects. You can configure the caching type and options on a per class basis to allow optimal caching.</p>
 <a id="sthref29" name="sthref29"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CDEJJHDG">Table 2-4</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA335" name="TLJPA335"></a><a id="sthref30" name="sthref30"></a><a id="CDEJJHDG" name="CDEJJHDG"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-4 @Cache Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Cache Annotation Elements" summary="This table describes the attributes for the @Cache annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="21%" />
 <col width="*" />
 <col width="30%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t8"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t8"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t8"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t8" headers="r1c1-t8">
 <p><code>type</code></p>
 </td>
 <td align="left" headers="r2c1-t8 r1c2-t8">
 <p>(Optional) Set this attribute to the type (<code>org.eclipse.persistence.annotations.CacheType</code> enumerated type) of the cache that you will be using:</p>
 <ul>
 <li>
 <p><code>FULL</code></p>
 </li>
 <li>
 <p><code>WEAK</code></p>
 </li>
 <li>
 <p><code>SOFT</code></p>
 </li>
 <li>
 <p><code>SOFT_WEAK</code></p>
 </li>
 <li>
 <p><code>HARD_WEAK</code></p>
 </li>
 <li>
 <p><code>CACHE</code> (not recommended)</p>
 </li>
 <li>
 <p><code>NONE</code> (not recommended, use <code>isolation=ISOLATED</code> instead)</p>
 </li>
 </ul>
 <p>You can override this attribute with these persistence unit properties:</p>
 <ul>
 <li>
 <p><code>eclipselink.cache.type.&lt;</code><em><code>ENTITY</code></em><code>&gt;</code></p>
 </li>
 <li>
 <p><code>eclipselink.cache.type.default</code></p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r2c1-t8 r1c3-t8">
 <p><code>CacheType.SOFT_WEAK</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t8" headers="r1c1-t8">
 <p><code>size</code></p>
 </td>
 <td align="left" headers="r3c1-t8 r1c2-t8">
 <p>(Optional) Set this attribute to an int value to define the size of cache to use (number of objects).</p>
 </td>
 <td align="left" headers="r3c1-t8 r1c3-t8">
 <p><code>100</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t8" headers="r1c1-t8">
 <p><code>isolation</code></p>
 </td>
 <td align="left" headers="r4c1-t8 r1c2-t8">
 <p>(Optional) The caching level of the Entity:</p>
 <ul>
 <li>
 <p><code>shared</code> &#8211; Entity instances will be cached within the EntityManagerFactory/ServerSession level</p>
 </li>
 <li>
 <p><code>isolated</code> &#8211; The Entity and its data is not stored in the shared cache, but is isolated to the Persistence Context/UnitOfWork or IsolatedClientSession</p>
 </li>
 <li>
 <p><code>protected</code> &#8211; Entity state information will be cached in the shared cache, but Entity instances will not be shared</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r4c1-t8 r1c3-t8">
 <p><code>shared</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t8" headers="r1c1-t8">
 <p><code>expiry</code></p>
 </td>
 <td align="left" headers="r5c1-t8 r1c2-t8">
 <p>(Optional) The <code>int</code> value to enable the expiration of the cached instance after a fixed period of time (milliseconds). Queries executed against the cache after this will be forced back to the database for a refreshed copy.</p>
 </td>
 <td align="left" headers="r5c1-t8 r1c3-t8">
 <p>no expiry</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t8" headers="r1c1-t8">
 <p><code>expiryTimeOfDay</code></p>
 </td>
 <td align="left" headers="r6c1-t8 r1c2-t8">
 <p>(Optional) Specific time of day (<code>org.eclipse.persistence.annotations.TimeOfDay</code>) when the cached instance will expire. Queries executed against the cache after this will be forced back to the database for a refreshed copy.</p>
 </td>
 <td align="left" headers="r6c1-t8 r1c3-t8">
 <p>no expiry</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r7c1-t8" headers="r1c1-t8">
 <p><code>alwaysRefresh</code></p>
 </td>
 <td align="left" headers="r7c1-t8 r1c2-t8">
 <p>(Optional) Set to a boolean value of true to force all queries that go to the database to always refresh the cache</p>
 </td>
 <td align="left" headers="r7c1-t8 r1c3-t8">
 <p><code>false</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r8c1-t8" headers="r1c1-t8">
 <p><code>refreshOnlyIfNewer</code></p>
 </td>
 <td align="left" headers="r8c1-t8 r1c2-t8">
 <p>(Optional) Set to a boolean value of <code>true</code> to force all queries that go to the database to refresh the cache only if the data received from the database by a query is newer than the data in the cache (as determined by the optimistic locking field)</p>
 <p><strong>Note:</strong></p>
 <ul>
 <li>
 <p>This option only applies if one of the other refreshing options, such as <code>alwaysRefresh</code>, is already enabled.</p>
 </li>
 <li>
 <p>A version field is necessary to apply this feature.</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r8c1-t8 r1c3-t8">
 <p><code>false</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r9c1-t8" headers="r1c1-t8">
 <p><code>disableHits</code></p>
 </td>
 <td align="left" headers="r9c1-t8 r1c2-t8">
 <p>(Optional) Set to a boolean value of true to force all queries to bypass the cache for hits, but still resolve against the cache for identity. This forces all queries to hit the database.</p>
 </td>
 <td align="left" headers="r9c1-t8 r1c3-t8">
 <p><code>false</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r10c1-t8" headers="r1c1-t8">
 <p><code>coordinationType</code></p>
 </td>
 <td align="left" headers="r10c1-t8 r1c2-t8">
 <p>(Optional) Set this attribute to the cache coordination mode (<code>org.eclipse.persistence.annotations.CacheCoordinationType</code> enumerated type).</p>
 <ul>
 <li>
 <p><code>SEND_OBJECT_CHANGES</code> &#8211; Sends a list of changed objects, including data about the changes. This data is merged into the receiving cache.</p>
 </li>
 <li>
 <p>I<code>NVALIDATE_CHANGED_OBJECTS</code> &#8211; Sends a list of the identities of the objects that have changed. The receiving cache invalidates the objects (rather than changing any of the data).</p>
 </li>
 <li>
 <p><code>SEND_NEW_OBJECTS_WITH_CHANGES</code> &#8211; Same as <code>SEND_OBJECT_CHANGES</code> excepts it also includes any newly-created objects from the transaction</p>
 </li>
 <li>
 <p><code>NONE</code> &#8211; Does not cache coordination</p>
 </li>
 </ul>
 <p>You must also configure cache coordination in your persistence unit properties. See <a href="persistenceproperties_ref.htm#CACDCCEG2">"Caching"</a>.</p>
 </td>
 <td align="left" headers="r10c1-t8 r1c3-t8">
 <p><code>SEND_OBJECT_CHANGES</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r11c1-t8" headers="r1c1-t8">
 <p><code>databaseChangeNotificationType</code></p>
 </td>
 <td align="left" headers="r11c1-t8 r1c2-t8">
 <p>(Optional) The database change notification mode:</p>
 <ul>
 <li>
 <p>Invalidate &#8211; Invalidates the EclipseLink cache when a database change event is received for an object.</p>
 </li>
 <li>
 <p>None &#8211; No database change events will be processed. The database event listener must also be configured for the persistence unit/session.</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r11c1-t8 r1c3-t8">
 <p><code>INVALIDATE</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref31" name="sthref31"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Use the <code>@Cache</code> annotation instead of the JPA <code>@Cachable</code> annotation to provide additional caching configuration.</p>
 <p>You can define the <code>@Cache</code> annotation on the following:</p>
 <ul>
 <li>
 <p><code>@Entity</code></p>
 </li>
 <li>
 <p><code>@MappedSuperclass</code></p>
 </li>
 <li>
 <p>the root of the inheritance hierarchy (if applicable)</p>
 </li>
 </ul>
 <p>If you define the <code>@Cache</code> annotation on an inheritance subclass, the annotation will be ignored. If you define the <code>@Cache</code> annotation on <code>@Embeddable</code> EclipseLink will throw an exception.</p>
 <a id="TLJPA336" name="TLJPA336"></a>
 <p><b><font face="arial, helvetica, sans-serif" color="#330099">Caching in EclipseLink</font></b></p>
 <p>The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and primary key values. EclipseLink uses the cache to do the following:</p>
 <ul>
 <li>
 <p>Improve performance by holding recently read or written objects and accessing them in-memory to minimize database access.</p>
 </li>
 <li>
 <p>Manage locking and isolation level.</p>
 </li>
 <li>
 <p>Manage object identity.</p>
 </li>
 </ul>
 <p>For more information about the EclipseLink cache and its default behavior, see:</p>
 <ul>
 <li>
 <p>Caching examples:</p>
 <p><code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/Caching">http://wiki.eclipse.org/EclipseLink/Examples/JPA/Caching</a></code></p>
 </li>
 </ul>
 <p>EclipseLink defines the following entity caching annotations:</p>
 <ul>
 <li>
 <p><code>@Cache</code></p>
 </li>
 <li>
 <p><code><a href="#BGBGACHC">@TimeOfDay</a></code></p>
 </li>
 <li>
 <p><code><a href="#BABICJEJ">@ExistenceChecking</a></code></p>
 </li>
 </ul>
 <p>EclipseLink also provides a number of persistence unit properties that you can specify to configure the cache. These properties may compliment or provide an alternative to the usage of annotations.</p>
 <p>For more information, see <a href="persistenceproperties_ref.htm#CACDCCEG2">"Caching"</a>.</p>
 <a id="sthref32" name="sthref32"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDEEGCI">Example 2-10</a> illustrates an <code>@Cache</code> annotation.</p>
 <div class="example"><a id="CHDEEGCI" name="CHDEEGCI"></a><a id="TLJPA337" name="TLJPA337"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-10 Using @Cache Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 ...
 @Entity
 @Cache(
   type=CacheType.SOFT, // Cache everything until the JVM decides memory is low.
   size=64000  // Use 64,000 as the initial cache size.
   expiry=36000000,  // 10 minutes
   coordinationType=CacheCoordinationType.INVALIDATE_CHANGED_OBJECTS  // if cache coordination is used, only send invalidation messages.
 )
 public class Employee {
   ...
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CDEJDBFJ">Example 2-11</a> shows how to use this annotation in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="CDEJDBFJ" name="CDEJDBFJ"></a><a id="TLJPA338" name="TLJPA338"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-11 Using &lt;cache&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity-mappings
   xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/orm"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.eclipse.org/eclipselink/xsds/persistence/orm
   http://www.eclipse.org/eclipselink/xsds/eclipselink_orm_2_4.xsd"
   version="2.4"&gt;
     &lt;entity name="Employee" class="org.acme.Employee" access="FIELD"&gt;
       &lt;cache type="SOFT" size="64000" expiry="36000000" coordination-type="INVALIDATE_CHANGED_OBJECTS"/&gt;
     &lt;/entity&gt;
 &lt;/entity-mappings&gt;
 </pre></div>
 <!-- class="example" -->
 <p>You can also specify caching properties at the persistence unit level (in the <code>persistence.xml</code> file) as shown here:</p>
 <div class="example"><a id="CACHFEFD" name="CACHFEFD"></a><a id="TLJPA339" name="TLJPA339"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-12 Specifying Caching in persistence.xml</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;persistence xmlns="http://java.sun.com/xml/ns/persistence"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://java.sun.com/xml/ns/persistence persistence_2_0.xsd"
   version="2.0"&gt;
     &lt;persistence-unit name="acme" transaction-type="RESOURCE_LOCAL"&gt;
       &lt;provider&gt;org.eclipse.persistence.jpa.PersistenceProvider&lt;/provider&gt;
         &lt;exclude-unlisted-classes&gt;false&lt;/exclude-unlisted-classes&gt;
         &lt;properties&gt;
           &lt;property name="eclipselink.cache.shared.default" value="false"/&gt;
           &lt;property name="eclipselink.cache.shared.Employee" value="true"/&gt;
           &lt;property name="eclipselink.cache.type.Employee" value="SOFT"/&gt;
           &lt;property name="eclipselink.cache.size.Employee" value="64000"/&gt;
         &lt;/properties&gt;
     &lt;/persistence-unit&gt;
 &lt;/persistence&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref33" name="sthref33"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BABICJEJ">"@ExistenceChecking"</a></p>
 </li>
 <li>
 <p><a href="#BGBGACHC">"@TimeOfDay"</a></p>
 </li>
 <li>
 <p><a href="#BABJGDGB">"@CacheInterceptor"</a></p>
 </li>
 <li>
 <p>"Understanding Caching" in the <em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p>"Object Caching" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 <li>
 <p>EclipseLink Caching examples: <code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/Caching">http://wiki.eclipse.org/EclipseLink/Examples/JPA/Caching</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CEGFEJCH" name="CEGFEJCH"></a><a id="TLJPA340" name="TLJPA340"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@CacheIndex</font></h2>
 <p>Use <code>@CacheIndex</code> to define a cached index. Cache indexes are used only when caching is enabled.</p>
 <a id="sthref34" name="sthref34"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABFJHIC">Table 2-5</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA341" name="TLJPA341"></a><a id="sthref35" name="sthref35"></a><a id="BABFJHIC" name="BABFJHIC"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-5 @CacheIndex Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@CacheIndex Annotation Elements" summary="This table describes the attributes for the @CacheIndex annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="21%" />
 <col width="*" />
 <col width="20%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t9"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t9"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t9"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t9" headers="r1c1-t9">
 <p><code>columnNames</code></p>
 </td>
 <td align="left" headers="r2c1-t9 r1c2-t9">
 <p>(Optional) The set of columns on which to define the index. Not required when annotated on a field/method.</p>
 </td>
 <td align="left" headers="r2c1-t9 r1c3-t9"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t9" headers="r1c1-t9">
 <p><code>updateable</code></p>
 </td>
 <td align="left" headers="r3c1-t9 r1c2-t9">
 <p>(Optional) Specify if the indexed field is updateable.</p>
 <p>If <code>true</code>, the object will be re-indexed on each update or refresh.</p>
 </td>
 <td align="left" headers="r3c1-t9 r1c3-t9">
 <p>true</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref36" name="sthref36"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>A cache index allows <code>singleResult</code> queries to obtain a cache hit when querying on the indexed fields. A <code>resultList</code> query cannot obtain cache hits, as it is unknown if all of the objects are in memory, (unless the cache usage query hint is used).</p>
 <p>The index should be unique. If it is not, the first indexed object will be returned.</p>
 <p>You can use <code>@CacheIndex</code> on an Entity class or on an attribute. The column is defaulted when defined on a attribute.</p>
 <a id="sthref37" name="sthref37"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABEECHH">Example 2-13</a> shows an example of using the <code>@CacheIndex</code> annotation.</p>
 <div class="example"><a id="BABEECHH" name="BABEECHH"></a><a id="TLJPA342" name="TLJPA342"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-13 Using @CacheIndex Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 <strong>@CacheIndex(columnNames={"F_NAME", "L_NAME"}, updateable=true)</strong>
 public class Employee {
   @Id
   private long id;
   @CacheIndex
   private String ssn;
   @Column(name="F_NAME")
   private String firstName;
   @Column(name="L_NAME")
   private String lastName;
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BABIHBCC">Example 2-14</a> shows an example of using the <code>&lt;cache-index&gt;</code> XML element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="BABIHBCC" name="BABIHBCC"></a><a id="TLJPA343" name="TLJPA343"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-14 Using &lt;cache-index&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;?xml version="1.0"?&gt;
 &lt;entity-mappings
   xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/orm"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.eclipse.org/eclipselink/xsds/persistence/orm http://www.eclipse.org/eclipselink/xsds/eclipselink_orm_2_4.xsd"
   version="2.4"&gt;
     &lt;entity name="Employee" class="org.acme.Employee" access="FIELD"&gt;
         <strong>&lt;cache-index updateable="true"&gt;</strong>
             &lt;column-name&gt;F_NAME&lt;/column-name&gt;
             &lt;column-name&gt;L_NAME&lt;/column-name&gt;
         <strong>&lt;/cache-index&gt;</strong>
         &lt;attributes&gt;
             &lt;id name="id"/&gt;
             &lt;basic name="ssn"&gt;
                 &lt;cache-index/&gt;
             &lt;/basic&gt;
             &lt;basic name="firstName"&gt;
                 &lt;column name="F_NAME"/&gt;
             &lt;/basic&gt;
             &lt;basic name="lastName"&gt;
                 &lt;column name="L_NAME"/&gt;
             &lt;/basic&gt;
         &lt;/attributes&gt;
     &lt;/entity&gt;
 &lt;/entity-mappings&gt;
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BABBIAGH">Example 2-15</a> shows an example query using a cache index.</p>
 <div class="example"><a id="BABBIAGH" name="BABBIAGH"></a><a id="TLJPA344" name="TLJPA344"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-15 Caching an Index Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 Query query = em.createQuery("Select e from Employee e where e.firstName = :firstName and e.lastName = :lastName");
 query.setParameter("firstName", "Bob");
 query.setParameter("lastName", "Smith");
 Employee employee = (Employee)query.getSingleResult();
 </pre></div>
 <!-- class="example" -->
 <a id="sthref38" name="sthref38"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CHDBBIHE">"@Cache"</a></p>
 </li>
 <li>
 <p>"About Cache Indexes" in <em>Understanding EclipseLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABIJDDB" name="BABIJDDB"></a><a id="TLJPA345" name="TLJPA345"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@CacheIndexes</font></h2>
 <p>Use <code>@CacheIndexes</code> to define a set of <code>@CacheIndex</code> on an entity.</p>
 <a id="sthref39" name="sthref39"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CIHJDAHF">Table 2-6</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA346" name="TLJPA346"></a><a id="sthref40" name="sthref40"></a><a id="CIHJDAHF" name="CIHJDAHF"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-6 @CacheIndexes Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@CacheIndexes Annotation Elements" summary="This table describes attributes for the @CacheIndexes annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="31%" />
 <col width="*" />
 <col width="28%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t10"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t10"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t10"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t10" headers="r1c1-t10">
 <p><code>CacheIndex[]</code></p>
 </td>
 <td align="left" headers="r2c1-t10 r1c2-t10">
 <p>An array of cache indexes</p>
 </td>
 <td align="left" headers="r2c1-t10 r1c3-t10"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref41" name="sthref41"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CEGFEJCH">"@CacheIndex"</a> for examples of using the <code>@CacheIndexes</code> annotation.</p>
 <a id="sthref42" name="sthref42"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CEGFEJCH">"@CacheIndex"</a></p>
 </li>
 <li>
 <p>"About Cache Indexes" in <em>Understanding EclipseLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABJGDGB" name="BABJGDGB"></a><a id="TLJPA347" name="TLJPA347"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@CacheInterceptor</font></h2>
 <p>Use <code>@CacheInterceptor</code> on an entity to intercept all EclipseLink cache access to the entity instead of responding to cache operations through an event.</p>
 <a id="sthref43" name="sthref43"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BGBBHFBF">Table 2-7</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA348" name="TLJPA348"></a><a id="sthref44" name="sthref44"></a><a id="BGBBHFBF" name="BGBBHFBF"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-7 @CacheInterceptor Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@CacheInterceptor Annotation Elements" summary="This table describes the attributes for the @CacheInterceptor annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="24%" />
 <col width="*" />
 <col width="29%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t11"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t11"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t11"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t11" headers="r1c1-t11">
 <p>value</p>
 </td>
 <td align="left" headers="r2c1-t11 r1c2-t11">
 <p>The class to be used to intercept EclipseLink's cache access</p>
 </td>
 <td align="left" headers="r2c1-t11 r1c3-t11"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref45" name="sthref45"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Once set, the specified class will receive all caching calls. Existing EclipseLink cache settings will continue to be used, any calls allowed to continue to the EclipseLink cache will execute against the configured cache.</p>
 <p>When using with an entity in inheritance, you should define the <code>@CacheInterceptor</code> on the <em>root</em> of the inheritance hierarchy.</p>
 <a id="sthref46" name="sthref46"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BGBGHHFI">Example 2-16</a> shows how to integrate an external cache with EclipseLink.</p>
 <div class="example"><a id="BGBGHHFI" name="BGBGHHFI"></a><a id="TLJPA349" name="TLJPA349"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-16 Using @CacheInterceptor Annotation</font></em></strong></p>
 <p>In this example, the <code>Employee</code> class intercepts all EclipseLink calls to the internal EclipseLink cache and redirects them to the Oracle Coherence Grid cache (<code>CoherenceInterceptor</code>).</p>
 <pre xml:space="preserve" class="oac_no_warn">
 import oracle.eclipselink.coherence.integrated.cache.CoherenceInterceptor;
 import org.eclipse.persistence.annotations.Customizer;

 @Entity
 <strong>@CacheInterceptor</strong>(value = CoherenceInterceptor.class)
 public class Employee {
 ...
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BGBEBHDH">Example 2-17</a> shows an example of using the <code>&lt;cache-interceptor&gt;</code> XML element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="BGBEBHDH" name="BGBEBHDH"></a><a id="TLJPA350" name="TLJPA350"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-17 Using &lt;cache-interceptor&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity class="Employee"&gt;
     <strong>&lt;cache-interceptor class="CoherenceInterceptor"/&gt;</strong>
 ...
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref47" name="sthref47"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p><em>Oracle Coherence Integration Guide for EclipseLink with Coherence Grid</em></p>
 </li>
 <li>
 <p><a href="#CHDBBIHE">"@Cache"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CIABIIEB" name="CIABIIEB"></a><a id="TLJPA351" name="TLJPA351"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@CascadeOnDelete</font></h2>
 <p>Use the <code>@CascadeOnDelete</code> annotation to specify that a delete operation performed on a database object is cascaded on secondary or related tables.</p>
 <p><code>ON DELETE CASCADE</code> is a database foreign key constraint option that automatically removes the dependent rows.</p>
 <a id="sthref48" name="sthref48"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p>There are no elements for this annotation.</p>
 <a id="sthref49" name="sthref49"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You can place <code>@CascadeOnDelete</code> on any relationship in which the target is defined as foreign key to the source Entity.</p>
 <p>Add the annotation on the source relationship: <code>@OneToOne</code>, <code>@OneToMany</code>, <code>@ManyToMany</code>, and <code>@ElementCollection</code> You can also add <code>@CascadeOnDelete</code> to an Entity with a <code>@SecondaryTable</code> or <code>JOINED</code> inheritance. <a href="#CHDECJGE">Table 2-8</a> describes the affect of placing <code>@CascadeOnDelete</code> on these different elements</p>
 <div class="tblhruleformal"><a id="TLJPA353" name="TLJPA353"></a><a id="sthref50" name="sthref50"></a><a id="CHDECJGE" name="CHDECJGE"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-8 Using @Cascade on Different Elements</font></em></strong></p>
 <table class="HRuleFormal" title="Using @Cascade on Different Elements" summary="This table describes using @Cascade on different elements. It gives the element and the effect of @CascadeonDelete." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="31%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t12"><font face="Arial, Helvetica, sans-serif"><strong>Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t12"><font face="Arial, Helvetica, sans-serif"><strong>Effect of @CascadeOnDelete</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t12" headers="r1c1-t12">
 <p>Entity</p>
 </td>
 <td align="left" headers="r2c1-t12 r1c2-t12">
 <p>Defines that secondary or joined inheritance tables should cascade the delete on the database</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t12" headers="r1c1-t12">
 <p>OneToOne mapping</p>
 </td>
 <td align="left" headers="r3c1-t12 r1c2-t12">
 <p>The deletion of the related object is cascaded on the database.</p>
 <p>This is only allowed for mappedBy/target-foreign key OneToOne mappings (because of constraint direction).</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t12" headers="r1c1-t12">
 <p>OneToMany mapping</p>
 </td>
 <td align="left" headers="r4c1-t12 r1c2-t12">
 <p>For a OneToMany using a <code>mappedBy</code> or <code>JoinColumn</code>, the deletion of the related objects is cascaded on the database.</p>
 <p>For a OneToMany 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>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t12" headers="r1c1-t12">
 <p>ManyToMany mapping</p>
 </td>
 <td align="left" headers="r5c1-t12 r1c2-t12">
 <p>The deletion of the join table is cascaded on the database (target objects cannot be cascaded even if private because of constraint direction).</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t12" headers="r1c1-t12">
 <p>ElementCollection mapping</p>
 </td>
 <td align="left" headers="r6c1-t12 r1c2-t12">
 <p>The deletion of the collection table is cascaded on the database.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformal" -->
 <p><code>@CascadeOnDelete</code> has the following behavior:</p>
 <ul>
 <li>
 <p>DDL generation: If DDL generation is used, the generated constraint will include the cascade deletion option.</p>
 </li>
 <li>
 <p>Entity: Remove will not execute SQL for deletion from secondary or joined inheritance tables (as constraint will handle deletion).</p>
 </li>
 <li>
 <p>OneToOne: If the mapping uses cascading or orphanRemoval, SQL will not be executed to delete target object.</p>
 </li>
 <li>
 <p>OneToMany: If the mapping uses cascading or orphanRemoval, SQL will not be executed to delete target objects.</p>
 </li>
 <li>
 <p>ManyToMany: SQL will not be executed to delete from the join table.</p>
 </li>
 <li>
 <p>ElementCollection: SQL will not be executed to delete from the collection table.</p>
 </li>
 <li>
 <p>Cache: Cascaded objects will still be removed from the cache and persistence context.</p>
 </li>
 <li>
 <p>Version locking: Version will not be verified on deletion of cascaded object.</p>
 </li>
 <li>
 <p>Events: Deletion events may not be executed on the cascaded objects if the objects are not loaded.</p>
 </li>
 <li>
 <p>Cascading: The remove operation should still be configured to cascade in the mapping if using CascadeOnDelete.</p>
 </li>
 </ul>
 <a id="sthref51" name="sthref51"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDHCIGF">Example 2-18</a> shows the cascading deletion of the Employee secondary table and all of its owned relationships.</p>
 <div class="example"><a id="CHDHCIGF" name="CHDHCIGF"></a><a id="TLJPA354" name="TLJPA354"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-18 Using @CascadeOnDelete Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @SecondaryTable(name="EMP_SALARY")
 <strong>@CascadeOnDelete</strong>
 public class Employee{
     @Id
     private long id;
     private String firstName;
     private String lastName;
     @Column(table="EMP_SALARY")
     private String salary;
     @OneToOne(mappedBy="owner", orphanRemoval=true, cascade={CascadeType.ALL})
     @CascadeOnDelete
     private Address address;
     @OneToMany(mappedBy="owner", orphanRemoval=true, cascade={CascadeType.ALL})
     @CascadeOnDelete
     private List&lt;Phone&gt; phones;
     @ManyToMany
     @JoinTable(name="EMP_PROJ")
     @CascadeOnDelete
     private List&lt;Project&gt; projects;
     ...
 }

 </pre></div>
 <!-- class="example" -->
 <p>In the <code>eclipselink-orm.xml</code> descriptor file, specify cascade on delete as shown in <a href="#CHDJIBAJ">Example 2-19</a></p>
 <div class="example"><a id="CHDJIBAJ" name="CHDJIBAJ"></a><a id="TLJPA355" name="TLJPA355"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-19 Using &lt;cascade-on-delete&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 ...
 <strong>&lt;cascade-on-delete&gt;true&lt;/cascade-on-delete&gt;</strong>
 ...
 </pre></div>
 <!-- class="example" -->
 <a id="sthref52" name="sthref52"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>EclipseLink example: <code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/DeleteCascade">http://wiki.eclipse.org/EclipseLink/Examples/JPA/DeleteCascade</a></code></p>
 </li>
 <li>
 <p>"@CascadeOnDelete"<code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Schema_Generation/CascadeOnDelete">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Schema_Generation/CascadeOnDelete</a></code></p>
 </li>
 <li>
 <p>"Enhancing Performance" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CEGCCCCJ" name="CEGCCCCJ"></a><a id="TLJPA356" name="TLJPA356"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@ChangeTracking</font></h2>
 <p>Use <code>@ChangeTracking</code> to specify the <code>org.eclipse.persistence.descriptors.changetracking.ObjectChangePolicy</code>. This policy computes change sets for the EclipseLink commit process and optimizes the transaction by including objects in the change set calculation that have at least one changed attribute.</p>
 <a id="sthref53" name="sthref53"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BCGCIDCD">Table 2-9</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA357" name="TLJPA357"></a><a id="sthref54" name="sthref54"></a><a id="BCGCIDCD" name="BCGCIDCD"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-9 @ChangeTracking Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@ChangeTracking Annotation Elements" summary="This table describes the attributes for the @ChangeTracking annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="14%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t13"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t13"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t13"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t13" headers="r1c1-t13">
 <p><code>ChangeTrackingType</code></p>
 </td>
 <td align="left" headers="r2c1-t13 r1c2-t13">
 <p>(Optional) The change tracking policy to use:</p>
 <ul>
 <li>
 <p><code>ATTRIBUTE</code> &#8211; The object's <code>set</code> method is weaved to raise change events to collect changes as they are made.</p>
 <p>Requires usage of weaving, and LAZY collection relationships, or eager weaving.</p>
 </li>
 <li>
 <p><code>OBJECT</code> &#8211; The object's set method is weaved to mark the object as <em>dirty</em>. Any dirty objects are compared against a copy of their original state for changes on commit or flush operations.</p>
 <p>Requires usage of weaving, and LAZY collection relationships, or eager weaving.</p>
 </li>
 <li>
 <p><code>DEFERRED</code> &#8211; All managed objects are compared against a copy of their original state for changes on commit or flush.</p>
 <p>Does not require weaving.</p>
 </li>
 <li>
 <p><code>AUTO</code> &#8211; Does not set any change tracking policy; change tracking will be determined at runtime.</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r2c1-t13 r1c3-t13">
 <p><code>AUTO</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref55" name="sthref55"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Use this annotation to configure an alternative change policy, if the automatic policy is having issues with your application. Using <code>@ChangeTracking</code> may improve commit performance for objects with few attributes or objects with many changed attributes.</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>When using change tracking with <code>ATTRIBUTE</code> or <code>OBJECT</code>, if you modify an object's field through reflection, EclipseLink <em>will not</em> detect the change. However, if you use <code>DEFERRED</code>, EclipseLink <em>will</em> detect the change.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref56" name="sthref56"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BCGCHJHG">Example 2-20</a> shows how to use <code>@ChangeTracking</code> to set the unit of work's change policy.</p>
 <div class="example"><a id="BCGCHJHG" name="BCGCHJHG"></a><a id="TLJPA358" name="TLJPA358"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-20 Using @ChangeTracking Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>@ChangeTracking(DEFERRED)</strong>
 @Entity
 public class Employee {
     ...
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BCGHFGBB">Example 2-21</a> shows how to use the <code>&lt;change-tracking&gt;</code> element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="BCGHFGBB" name="BCGHFGBB"></a><a id="TLJPA359" name="TLJPA359"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-21 Using &lt;change-tracking&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity class="Employee"
     <strong>&lt;change-tracking type="DEFERRED"/&gt;</strong>
 ...
 &lt;/entity&gt;

 </pre></div>
 <!-- class="example" -->
 <p><a href="#BCGICDII">Example 2-22</a> shows how to configure change tracking in the persistence unit <code>persistence.xml</code> file or by importing a <code>property</code> map.</p>
 <div class="example"><a id="BCGICDII" name="BCGICDII"></a><a id="TLJPA360" name="TLJPA360"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-22 Specifying Change Tracking in persistence.xml</font></em></strong></p>
 <p>Using <code>persistence.xml</code> file:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;property name="<strong>eclipselink.weaving.changetracking</strong>" value="false"/&gt;

 </pre>
 <p>Using <code>property</code> map:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.PersistenceUnitProperties;
 propertiesMap.put(PersistenceUnitProperties.<strong>WEAVING_CHANGE_TRACKING</strong>, "false");

 </pre></div>
 <!-- class="example" -->
 <a id="sthref57" name="sthref57"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="persistenceproperties_ref.htm#weaving">"weaving"</a></p>
 </li>
 <li>
 <p>"Enhancing Performance" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BGBHAADB" name="BGBHAADB"></a><a id="TLJPA361" name="TLJPA361"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@ClassExtractor</font></h2>
 <p>Use <code>@ClassExtractor</code> to define a custom class indicator in place of providing a discriminator column.</p>
 <a id="sthref58" name="sthref58"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABGCAFI">Table 2-10</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA362" name="TLJPA362"></a><a id="sthref59" name="sthref59"></a><a id="BABGCAFI" name="BABGCAFI"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-10 @ClassExtractor Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@ClassExtractor Annotation Elements" summary="This table describes the attributes of the @ClassExtractor annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="21%" />
 <col width="*" />
 <col width="25%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t15"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t15"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t15"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t15" headers="r1c1-t15">
 <p><code>java.lang.Class</code></p>
 </td>
 <td align="left" headers="r2c1-t15 r1c2-t15">
 <p>(Required) The name of the class extractor to apply to the entity's descriptor</p>
 </td>
 <td align="left" headers="r2c1-t15 r1c3-t15"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref60" name="sthref60"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>If you are mapping to an existing database, and the tables do not have a discriminator column you can still define inheritance using the <code>@ClassExtractor</code> annotation or <code>&lt;class-extractor&gt;</code> element. The class extractor takes a class that implements the <code>ClassExtractor</code> interface. An instance of this class is used to determine the class type to use for a database row. The class extractor must define a <code>extractClassFromRow</code> method that takes the database <code>Record</code> and <code>Session</code>.</p>
 <p>If a class extractor is used with <code>SINGLE_TABLE</code> inheritance, the rows of the class type must be able to be filtered in queries. This can be accomplished by setting an <code>onlyInstancesExpression</code> or <code>withAllSubclassesExpression</code> for branch classes. These can be set to <code>Expression</code> objects using a <code>DescriptorCustomizer</code>.</p>
 <a id="sthref61" name="sthref61"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BGBEDADF">Example 2-23</a> shows an example of using <code>ClassExtractor</code> to define inheritance.</p>
 <div class="example"><a id="BGBEDADF" name="BGBEDADF"></a><a id="TLJPA363" name="TLJPA363"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-23 Using @ClassExtractor Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Table(name="MILES_ACCOUNT")
 @Inheritance(strategy=InheritanceType.SINGLE_TABLE)
 <strong>@ClassExtractor(AirMilesClassExtractor.class)</strong>
 @Customizer(AirMilesCustomizer.class)
 public class AirMilesAccount implements Serializable {
     @Id
     private Long id;
     @Basic
     private String totalMiles;
     @Basic
     private String milesBalance;
     ...
 }

 @Entity
 @Customizer(PreferredCustomizer.class)
 public class PreferredAccount extends AirMilesAccount {
     ...
 }

 public class AirMilesClassExtractor implements ClassExtractor {
     public void extractClassFromRow(Record row, Session session) {
         if (row.get("TOTALMILES").lessThan(100000)) {
             return AirMilesAccount.class;
         } else {
             return PreferredAccount.class;
         }
     }
 }

 public class AirMilesCustomizer implements DescriptorCustomizer {
     public void customize(ClassDescriptor descriptor) {
         ExpressionBuilder account = new ExpressionBuilder();
         Expression expression = account.getField("TOTALMILES").lessThan(100000);
         descriptor.getInheritancePolicy().setOnlyInstancesExpression(expression);
     }
 }

 public class PreferredCustomizer implements DescriptorCustomizer {
     public void customize(ClassDescriptor descriptor) {
         ExpressionBuilder account = new ExpressionBuilder();
         Expression expression = account.getField("TOTALMILES").greaterThanEqual(100000);
         descriptor.getInheritancePolicy().setOnlyInstancesExpression(expression);
     }
 }

 </pre></div>
 <!-- class="example" -->
 <p><a href="#BABDIJEG">Example 2-24</a> shows how to use the <code>&lt;class-extractor&gt;</code> element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="BABDIJEG" name="BABDIJEG"></a><a id="TLJPA364" name="TLJPA364"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-24 Using &lt;class-extractor&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity class="AirMilesAccount"&gt;
     &lt;table name="MILES_ACCOUNT"/&gt;
     &lt;inheritance strategy="SINGLE_TABLE"/&gt;
     &lt;<strong>class-extractor</strong> class="AirMilesClassExtractor"/&gt;
 ...
 &lt;/entity&gt;

 &lt;entity class="PreferredAccount"&gt;
     &lt;customizer class="PreferredCustomizer"/&gt;
 ...
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref62" name="sthref62"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Entities" in <em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p><a href="#CHDCCDGC">"@Customizer"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CDDJGFHA" name="CDDJGFHA"></a><a id="TLJPA365" name="TLJPA365"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@CloneCopyPolicy</font></h2>
 <p>Use <code>@CloneCopyPolicy</code> to specify an <code>org.eclipse.persistence.descriptors.copying.CloneCopyPolicy</code> on an Entity.</p>
 <a id="sthref63" name="sthref63"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABFHGIH">Table 2-11</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA366" name="TLJPA366"></a><a id="sthref64" name="sthref64"></a><a id="BABFHGIH" name="BABFHGIH"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-11 @CloneCopyPolicy Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@CloneCopyPolicy Annotation Elements" summary="This table describes the attributes for the @CloneCopyPolicy annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="20%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t16"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t16"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t16"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t16" headers="r1c1-t16">
 <p><code>method</code></p>
 </td>
 <td align="left" headers="r2c1-t16 r1c2-t16">
 <p>(Optional) The method that will be used to create a clone for comparison with EclispeLink's <code>DeferredChangeDetectionPolicy</code></p>
 </td>
 <td align="left" headers="r2c1-t16 r1c3-t16"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t16" headers="r1c1-t16">
 <p><code>workingCopyMethod</code></p>
 </td>
 <td align="left" headers="r3c1-t16 r1c2-t16">
 <p>(Optional) The <code>workingCopyoMethod</code> that will be used to create a clone that will be used when registering an object in an EclipseLink <code>UnitOfWork</code></p>
 </td>
 <td align="left" headers="r3c1-t16 r1c3-t16"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <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>You must specify either a <code>method</code> or <code>workingCopyMenthod</code>.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref65" name="sthref65"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>The clone <code>method</code> should perform a shallow clone of the object. This can be used to clone non-persistent fields from a instance in the shared cache.</p>
 <p>You can specify <code>@CloneCopyPolicy</code> on an Entity, MappedSuperclass, or Embeddable class.</p>
 <a id="sthref66" name="sthref66"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABEIGHC">Example 2-25</a> and <a href="#BABJAHCB">Example 2-26</a> show several examples of the <code>@CloneCopyPolicy</code> annotation and <code>&lt;clone-copy-policy&gt;</code> XML element, respectively.</p>
 <div class="example"><a id="BABEIGHC" name="BABEIGHC"></a><a id="TLJPA367" name="TLJPA367"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-25 Using @CloneCopyPolicy Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @CloneCopyPolicy(method="myClone")
 </pre>
 <pre xml:space="preserve" class="oac_no_warn">
 @CloneCopyPolicy(method="myClone", workingCopyMethod="myWorkingCopyClone")
 </pre>
 <pre xml:space="preserve" class="oac_no_warn">
 @CloneCopyPolicy(workingCopyMethod="myWorkingCopyClone")
 </pre></div>
 <!-- class="example" -->
 <div class="example"><a id="BABJAHCB" name="BABJAHCB"></a><a id="TLJPA368" name="TLJPA368"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-26 Using &lt;clone-copy-policy&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;clone-copy-policy type="copy" method="myClone" workingCopyMethod="myWorkingCopyClone"/&gt;
 </pre>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;clone-copy-policy type="copy" workingCopyMethod="myWorkingCopyClone"/&gt;
 </pre>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;clone-copy-policy type="copy" method="myClone"/&gt;

 </pre></div>
 <!-- class="example" -->
 <a id="sthref67" name="sthref67"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p><a href="#BGBDGCDJ">"@CopyPolicy"</a></p>
 </li>
 <li>
 <p><a href="#CHDCJEIG">"@InstantiationCopyPolicy"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BGBHHCJH" name="BGBHHCJH"></a><a id="TLJPA369" name="TLJPA369"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@CompositeMember</font></h2>
 <p>Use <code>@CompositeMember</code> to indicate that a class belongs to a composite persistence unit.</p>
 <p>It should be used if target type is a primitive type and <code>@CollectionTable</code> designates the table that belongs to composite member persistence unit other than the source composite member persistence unit. This allows the source and target to be mapped to different databases.</p>
 <a id="sthref68" name="sthref68"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABBCHAA">Table 2-12</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA370" name="TLJPA370"></a><a id="sthref69" name="sthref69"></a><a id="BABBCHAA" name="BABBCHAA"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-12 @CompositeMember Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@CompositeMember Annotation Elements" summary="This table describes the attributes for the @CompositeMember annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="20%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t18"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t18"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t18"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t18" headers="r1c1-t18">
 <p><code>value</code></p>
 </td>
 <td align="left" headers="r2c1-t18 r1c2-t18">
 <p>The name of a target composite member persistence unit to which element table belongs (if differs from source composite member persistence unit</p>
 </td>
 <td align="left" headers="r2c1-t18 r1c3-t18"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref70" name="sthref70"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>The <code>@CompositeMember</code> annotation is ignored unless it is in a composite member persistence unit. It may be used in conjunction with <code>@ElementCollection</code> and <code>@CollectionTable</code> annotations.</p>
 <a id="sthref71" name="sthref71"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>You can configure the <code>CompositeMember</code> using annotations or the <code>eclipselink-orm.xml</code> file, as shown in these examples.</p>
 <div class="example"><a id="TLJPA371" name="TLJPA371"></a><a id="sthref72" name="sthref72"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-27 Using @CompositeMember Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @ElementCollection()
 @CollectionTable(name = "MBR1_RESPONS", joinColumns=@JoinColumn(name="EMP_ID"))
 <strong>@CompositeMember("branch-database")</strong>
 @Column(name = "DESCRIPTION")
 public Collection&lt;String&gt; getResponsibilities() {
     return responsibilities;
 }
 </pre></div>
 <!-- class="example" -->
 <div class="example"><a id="TLJPA372" name="TLJPA372"></a><a id="sthref73" name="sthref73"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-28 Using &lt;composite-member&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;element-collection name="responsibilities" <strong>composite-member="branch-database"</strong>&gt;
   &lt;column name="DESCRIPTION"/&gt;
   &lt;collection-table name="XML_MBR3_RESPONS"&gt;
     &lt;join-column name="EMP_ID"/&gt;
   &lt;/collection-table&gt;
 &lt;/element-collection&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref74" name="sthref74"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Using Multiple Databases with a Composite Persistence Unit" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 <li>
 <p><a href="persistenceproperties_ref.htm#BIICFIDB">"composite-unit"</a></p>
 </li>
 <li>
 <p><a href="persistenceproperties_ref.htm#CHDHCIDH">"composite-unit.member"</a></p>
 </li>
 <li>
 <p>"Composite Persistence Units" <code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Composite_Persistence_Units">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Composite_Persistence_Units</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CBBJAJCH" name="CBBJAJCH"></a><a id="TLJPA373" name="TLJPA373"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@ConversionValue</font></h2>
 <p>Use <code>@ConversionValue</code> to specify the database and object values for an <code>ObjectTypeConverter</code>.</p>
 <a id="sthref75" name="sthref75"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABBEGIB">Table 2-13</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA374" name="TLJPA374"></a><a id="sthref76" name="sthref76"></a><a id="BABBEGIB" name="BABBEGIB"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-13 @ConversionValue Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@ConversionValue Annotation Elements" summary="This table describes the attributes for the @ConversionValue annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="20%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t19"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t19"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t19"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t19" headers="r1c1-t19">
 <p><code>dataValue</code></p>
 </td>
 <td align="left" headers="r2c1-t19 r1c2-t19">
 <p>(Required) The database value</p>
 </td>
 <td align="left" headers="r2c1-t19 r1c3-t19"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t19" headers="r1c1-t19">
 <p><code>objectValue</code></p>
 </td>
 <td align="left" headers="r3c1-t19 r1c2-t19">
 <p>(Required) The object value</p>
 </td>
 <td align="left" headers="r3c1-t19 r1c3-t19"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref77" name="sthref77"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>The JPA specification allows you to map an <code>Enum</code> to database columns using the <code>@Enumerated</code> annotation, when the database value is either the name of the <code>Enum</code> or its ordinal value. With EclipseLink, you can also map an <code>Enum</code> to a coded value, using a converter.</p>
 <a id="sthref78" name="sthref78"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>In <a href="#BABFEJHJ">Example 2-29</a>, the <code>enum</code> <code>Gender(MALE, FEMALE)</code> is mapped to a single character in the database where M=MALE and F=FEMALE.</p>
 <div class="example"><a id="BABFEJHJ" name="BABFEJHJ"></a><a id="TLJPA375" name="TLJPA375"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-29 Using @ConversionValue Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @ObjectTypeConverter(name = "gender", objectType = Gender.class, dataType = String.class, conversionValues = {
   <strong>@ConversionValue(objectValue = "Male", dataValue = "M")</strong>,
   <strong>@ConversionValue(objectValue = "Female", dataValue = "F")</strong> })

 ...

 @Basic
 @Convert("gender")
 private Gender gender = Gender.Male;

 </pre></div>
 <!-- class="example" -->
 <p><a href="#BABIHAFA">Example 2-30</a> illustrates the same function using XML.</p>
 <div class="example"><a id="BABIHAFA" name="BABIHAFA"></a><a id="TLJPA376" name="TLJPA376"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-30 Using &lt;conversion-value&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;object-type-converter name="gender" object-type="model.Gender   "data-type="java.lang.String"&gt;
   <strong>&lt;conversion-value object-value="Male" data-value="M" /&gt;</strong>
   <strong>&lt;conversion-value object-value="Female" data-value="F" /&gt;</strong>
 &lt;/object-type-converter&gt;

 ...

 &lt;basic name="gender"&gt;
   &lt;column name="GENDER" /&gt;
   &lt;convert&gt;gender&lt;/convert&gt;
 &lt;/basic&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref79" name="sthref79"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BGBBDGAI">"@ObjectTypeConverter"</a></p>
 </li>
 <li>
 <p><em>Understanding EclipseLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BEHGJHCD" name="BEHGJHCD"></a><a id="TLJPA377" name="TLJPA377"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Convert</font></h2>
 <p>Use <code>@Convert</code> to specify that a named converter should be used with the corresponding mapped attribute.</p>
 <a id="sthref80" name="sthref80"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BEHICGDB">Table 2-14</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA378" name="TLJPA378"></a><a id="sthref81" name="sthref81"></a><a id="BEHICGDB" name="BEHICGDB"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-14 @Convert Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Convert Annotation Elements" summary="This table describes the elements for the @Convert annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="18%" />
 <col width="*" />
 <col width="20%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t20"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t20"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t20"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t20" headers="r1c1-t20">
 <p><code>value</code></p>
 </td>
 <td align="left" headers="r2c1-t20 r1c2-t20">
 <p>(Optional) The <code>String</code> name for your converter</p>
 </td>
 <td align="left" headers="r2c1-t20 r1c3-t20">
 <p><code>none</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref82" name="sthref82"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>The <code>@Convert</code> has the following reserved names:</p>
 <ul>
 <li>
 <p><strong>serialized</strong> &#8211; Places the <code>org.eclipse.persistence.mappings.converters.SerializedObjectConverter</code> on the associated mapping.</p>
 </li>
 <li>
 <p><strong>class-instance</strong> &#8211; Uses an <code>ClassInstanceConverter</code> on the associated mapping. When using a <code>ClassInstanceConverter</code>, the database representation is a <code>String</code> representing the Class name and the object-model representation is an instance of that class built with a no-args constructor</p>
 </li>
 <li>
 <p><strong>none</strong> &#8211; Does not place a converter on the associated mapping.</p>
 </li>
 </ul>
 <a id="sthref83" name="sthref83"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BEHFAGHF">Example 2-31</a> shows how to use the <code>@Convert</code> annotation to define the <code>gender</code> field.</p>
 <div class="example"><a id="BEHFAGHF" name="BEHFAGHF"></a><a id="TLJPA379" name="TLJPA379"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-31 Using the <code>@Convert</code> Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
  @Table(name="EMPLOYEE")
  @Converter(
      name="genderConverter",
          converterClass=org.myorg.converters.GenderConverter.class
  )
  public class Employee implements Serializable{
      ...
      @Basic
      <strong>@Convert("genderConverter")</strong>
      public String getGender() {
          return gender;
      }
      ...
  }
 </pre></div>
 <!-- class="example" -->
 <a id="sthref84" name="sthref84"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CHDEHJEB">"@Converter"</a></p>
 </li>
 <li>
 <p><a href="#BGBBDGAI">"@ObjectTypeConverter"</a></p>
 </li>
 <li>
 <p><a href="#CHDHCCJF">"@TypeConverter"</a></p>
 </li>
 <li>
 <p><em>Understanding EclipseLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDEHJEB" name="CHDEHJEB"></a><a id="TLJPA380" name="TLJPA380"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Converter</font></h2>
 <p>Use the <code>@Converter</code> annotation to specify a custom converter for modification of the data value(s) during the reading and writing of a mapped attribute.</p>
 <a id="sthref85" name="sthref85"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BGBJIHHG">Table 2-15</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA381" name="TLJPA381"></a><a id="sthref86" name="sthref86"></a><a id="BGBJIHHG" name="BGBJIHHG"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-15 @Converter Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Converter Annotation Elements" summary="This table describes the elements for the @Converter annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="20%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t21"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t21"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t21"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t21" headers="r1c1-t21">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t21 r1c2-t21">
 <p>The <code>String</code> name for your converter, must be unique across the persistence unit</p>
 </td>
 <td align="left" headers="r2c1-t21 r1c3-t21">
 <p>none</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t21" headers="r1c1-t21">
 <p><code>converterClass</code></p>
 </td>
 <td align="left" headers="r3c1-t21 r1c2-t21">
 <p>The class of your converter. This class must implement the <code>org.eclipse.persistence.mappings.converters.Converter</code> interface.</p>
 </td>
 <td align="left" headers="r3c1-t21 r1c3-t21">
 <p>none</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref87" name="sthref87"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Use <code>@Converter</code> to define a named converter that can be used with mappings. A converter can be defined on an entity class, method, or field. Specify a converter with the <a href="#BEHGJHCD">@Convert</a> annotation on a Basic or ElementCollection mapping.</p>
 <a id="TLJPA382" name="TLJPA382"></a>
 <p><b><font face="arial, helvetica, sans-serif" color="#330099">Using non-JPA Converter Annotations</font></b></p>
 <p>EclipseLink provides a set of non-JPA converter annotations (in addition to the JPA default type mappings):</p>
 <ul>
 <li>
 <p>@Converter</p>
 </li>
 <li>
 <p><a href="#CHDHCCJF">@TypeConverter</a></p>
 </li>
 <li>
 <p><a href="#BGBBDGAI">@ObjectTypeConverter</a></p>
 </li>
 <li>
 <p><a href="#BGBJEBBB">@StructConverter</a></p>
 </li>
 <li>
 <p><a href="#BEHGJHCD">@Convert</a></p>
 </li>
 </ul>
 <p>The persistence provider searches the converter annotations in the following order:</p>
 <ol>
 <li>
 <p><code>@Convert</code></p>
 </li>
 <li>
 <p><code>@Enumerated</code></p>
 </li>
 <li>
 <p><code>@Lob</code></p>
 </li>
 <li>
 <p><code>@Temporal</code></p>
 </li>
 <li>
 <p>Serialized (automatic)</p>
 </li>
 </ol>
 <p>Specify the converters on the following classes:</p>
 <ul>
 <li>
 <p><code>@Entity</code></p>
 </li>
 <li>
 <p><code>@MappedSuperclass</code></p>
 </li>
 <li>
 <p><code>@Embeddable</code></p>
 </li>
 </ul>
 <p>Use the converters with the following mappings:</p>
 <ul>
 <li>
 <p><code>@Basic</code></p>
 </li>
 <li>
 <p><code>@Id</code></p>
 </li>
 <li>
 <p><code>@Version</code></p>
 </li>
 <li>
 <p><code>@ElementCollection</code></p>
 </li>
 </ul>
 <p>An exception is thrown if a converter is specified with any other type of mapping annotation.</p>
 <a id="sthref88" name="sthref88"