documentation/2.7/jpa/extensions/annotations_ref.htm - gerrit/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"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDFGEFJ">Example 2-32</a> shows how to use the <code>@Converter</code> annotation to specify a converter class for the <code>gender</code> field.</p>
 <div class="example"><a id="CHDFGEFJ" name="CHDFGEFJ"></a><a id="TLJPA383" name="TLJPA383"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-32 Using the @Converter Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
  public class Employee implements Serializable{
     ...
      @Basic
     <strong> @Converter</strong> (
          name="genderConverter",
          converterClass=org.myorg.converters.GenderConverter.class
      )
      @Convert("genderConverter")
      public String getGender() {
          return gender;
      }
      ...
  }

 </pre></div>
 <!-- class="example" -->
 <p><a href="#BGBBDAAJ">Example 2-33</a> shows how to use the <code>&lt;converter&gt;</code> element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="BGBBDAAJ" name="BGBBDAAJ"></a><a id="TLJPA384" name="TLJPA384"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-33 Using &lt;converter&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity class="Employee"&gt;
 ...
     &lt;attributes&gt;
     ...
       &lt;basic name="gender"&gt;
         &lt;convert&gt;genderConverter&lt;/convert&gt;
         &lt;<strong>converter</strong> name="genderConverter" class="org.myorg.converters.GenderConverter"/&gt;
       &lt;/basic&gt;
     ...
     &lt;/attributes&gt;
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref89" name="sthref89"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CIHEBAFB">"@Converters"</a></p>
 </li>
 <li>
 <p><a href="#BEHGJHCD">"@Convert"</a></p>
 </li>
 <li>
 <p><a href="#BEHBBCDB">"@MapKeyConvert"</a></p>
 </li>
 <li>
 <p><em>Understanding EclipseLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CIHEBAFB" name="CIHEBAFB"></a><a id="TLJPA385" name="TLJPA385"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Converters</font></h2>
 <p>Use <code>@Converters</code> annotation to define multiple <code>@Converter</code> elements.</p>
 <a id="sthref90" name="sthref90"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BCFIJFIB">Table 2-16</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA386" name="TLJPA386"></a><a id="sthref91" name="sthref91"></a><a id="BCFIJFIB" name="BCFIJFIB"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-16 @Converters Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Converters Annotation Elements" summary="This table describes the elements for the @Converters annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="17%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t22"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t22"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t22"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t22" headers="r1c1-t22">
 <p><code>Converter[]</code></p>
 </td>
 <td align="left" headers="r2c1-t22 r1c2-t22">
 <p>(Required) An array of converters</p>
 </td>
 <td align="left" headers="r2c1-t22 r1c3-t22"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref92" name="sthref92"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CHDEHJEB">"@Converter"</a> for an example of this annotation.</p>
 <a id="sthref93" name="sthref93"></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><em>Understanding EclipseLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BGBDGCDJ" name="BGBDGCDJ"></a><a id="TLJPA387" name="TLJPA387"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@CopyPolicy</font></h2>
 <p>Use <code>@CopyPolicy</code> to set an <code>org.eclipse.persistence.descriptors.copying.CopyPolicy</code> on an entity to produce a copy of the persistent element.</p>
 <a id="sthref94" name="sthref94"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABFHFGC">Table 2-17</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA388" name="TLJPA388"></a><a id="sthref95" name="sthref95"></a><a id="BABFHFGC" name="BABFHFGC"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-17 @CopyPolicy Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@CopyPolicy Annotation Elements" summary="This table describes the elements for the @CopyPolicy 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-t23"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t23"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t23"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t23" headers="r1c1-t23">
 <p><code>java.lang.Class</code></p>
 </td>
 <td align="left" headers="r2c1-t23 r1c2-t23">
 <p>(Required) The class of the copy policy. The class must implement <code>org.eclipse.persistence.descriptors.copying.CopyPolicy</code>.</p>
 </td>
 <td align="left" headers="r2c1-t23 r1c3-t23"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref96" name="sthref96"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You can specify <code>@CopyPolicy</code> on an Entity, MappedSuperclass, or Embeddable class.</p>
 <a id="sthref97" name="sthref97"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABCIIIJ">Example 2-34</a> shows how to use this annotation.</p>
 <div class="example"><a id="BABCIIIJ" name="BABCIIIJ"></a><a id="TLJPA389" name="TLJPA389"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-34 Using @CopyPolicy Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
   @Table(name="EMPLOYEE")
   <strong>@CopyPolicy(mypackage.MyCopyPolicy.class)</strong>
   public class Employee implements Serializable {
     ...
   }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BABECEEG">Example 2-35</a> shows how to use the <code>&lt;copy-policy&gt;</code> element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="BABECEEG" name="BABECEEG"></a><a id="TLJPA390" name="TLJPA390"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-35 Using &lt;copy-policy&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity class="Employee"&gt;
   &lt;table name="EMPLOYEE"/&gt;
   <strong>&lt;copy-policy class="mypackage.MyCopyPolicy"/&gt;</strong>
 ...
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref98" name="sthref98"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CDDJGFHA">"@CloneCopyPolicy"</a></p>
 </li>
 <li>
 <p><a href="#CHDCJEIG">"@InstantiationCopyPolicy"</a></p>
 </li>
 <li>
 <p><em>Understanding EclipseLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDCCDGC" name="CHDCCDGC"></a><a id="TLJPA391" name="TLJPA391"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Customizer</font></h2>
 <p>Use <code>@Customizer</code> to specify a class that implements <code>org.eclipse.persistence.config.DescriptorCustomizer</code> and is to run against an entity's class descriptor after all metadata processing has been completed.</p>
 <a id="sthref99" name="sthref99"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABCJCHB">Table 2-18</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA392" name="TLJPA392"></a><a id="sthref100" name="sthref100"></a><a id="BABCJCHB" name="BABCJCHB"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-18 @Customizer Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Customizer Annotation Elements" summary="This table describes the elements for the @Customizer 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-t24"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t24"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t24"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t24" headers="r1c1-t24">
 <p><code>java.lang.Class</code></p>
 </td>
 <td align="left" headers="r2c1-t24 r1c2-t24">
 <p>(Required) The name of the descriptor customizer to apply to the entity's descriptor</p>
 </td>
 <td align="left" headers="r2c1-t24 r1c3-t24"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref101" name="sthref101"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Use this annotation to customize or extend the mapping metadata through the EclipseLink native API. With <code>@Customizer</code>, you can access additional EclipseLink functionality and configurations.</p>
 <p>You can specify <code>@Customizer</code> on an Entity, MappedSuperclass, or Embeddable class.</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>A <code>@Customizer</code> is not inherited from its parent classes.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref102" name="sthref102"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABBFAGB">Example 2-36</a> show how to use the <code>@Customizer</code> annotation with the following <code>DescriptorCustomer</code>:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 public class <strong>MyCustomizer</strong> implements DescriptorCustomizer {
   public void customize(ClassDescriptor descriptor) {
     DirectToFieldMapping genderMapping = (DirectToFieldMapping)descriptor.getMappingForAttributeName("gender");
     ObjectTypeConverter converter = new ObjectTypeConverter();
     convert.addConversionValue("M", Gender.MALE);
     convert.addConversionValue("F", Gender.FEMALE);
     genderMapping.setConverter(converter);
   }
 }
 </pre>
 <div class="example"><a id="BABBFAGB" name="BABBFAGB"></a><a id="TLJPA393" name="TLJPA393"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-36 Using @Customizer Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
  @Table(name="EMPLOYEE")
  <strong>@Customizer(mypackage.MyCustomizer.class)</strong>
  public class Employee implements Serializable {
      ...
  }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BABDJIFC">Example 2-37</a> show how to use the <code>&lt;customizer&gt;</code> element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="BABDJIFC" name="BABDJIFC"></a><a id="TLJPA394" name="TLJPA394"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-37 Using &lt;customizer&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity class="Employee"&gt;
   &lt;table name="EMPLOYEE"/&gt;
   <strong>&lt;customizer class="mypackage.MyCustomizer"/&gt;</strong>
 ...
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref103" name="sthref103"></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#CCHIEAIA">"descriptor.customizer"</a></p>
 </li>
 <li>
 <p>"Binding JPA Entities to XML" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 <li>
 <p>EclipseLink Examples <code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/MappingSelectionCriteria">http://wiki.eclipse.org/EclipseLink/Examples/JPA/MappingSelectionCriteria</a></code></p>
 </li>
 <li>
 <p>"Customizers" <code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Customizers">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Customizers</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABDDGFG" name="BABDDGFG"></a><a id="TLJPA395" name="TLJPA395"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@DeleteAll</font></h2>
 <p>Use <code>@DeleteAll</code> to indicate that when an relationship is deleted, EclipseLink should use a delete all query. This typically happens if the relationship is <code>PrivateOwned</code> and its owner is deleted. In that case, the members of the relationship will be deleted without reading them in.</p>
 <a id="sthref104" name="sthref104"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p>There are no elements for this annotation.</p>
 <a id="sthref105" name="sthref105"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <div align="center">
 <div class="inftblnotewarn"><br />
 <table class="NoteWarn oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
 <tbody>
 <tr>
 <td align="left">
 <p><font face="arial, helvetica, sans-serif"><strong>WARNING:</strong></font></p>
 <p><strong>Use this annotation with caution. EclipseLink will not validate whether the target entity is mapped in such a way as to allow the delete all to work.</strong></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnotewarn" --></div>
 <a id="sthref106" name="sthref106"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CBHBIFII">Example 2-38</a> shows how to use <code>@DeleteAll</code> on a relationship mapping.</p>
 <div class="example"><a id="CBHBIFII" name="CBHBIFII"></a><a id="TLJPA396" name="TLJPA396"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-38 Using @DeleteAll Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 public class Department {
   ...
   @OneToMany(mappedBy = "department")
   @PrivateOwned
   <strong>@DeleteAll</strong>
   public List&lt;Equipment&gt; getEquipment() {
     return equipment;
     }
   ...
   }

 </pre></div>
 <!-- class="example" -->
 <p><a href="#CBHBIFII">Example 2-38</a> shows how to use the <code>&lt;delete-all&gt;</code> element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="TLJPA397" name="TLJPA397"></a><a id="sthref107" name="sthref107"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-39 Using &lt;delete-all&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity class="Department"&gt;
   ...
   &lt;attributes&gt;
     &lt;one-to-many name="equipment" target-entity="Equipment" mapped-by="department"&gt;
       &lt;private-owned/&gt;
       <strong>&lt;delete-all/&gt;</strong>
     &lt;/one-to-many&gt;
 ...
 &lt;/attributes&gt;
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref108" name="sthref108"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CHDDDDAI">"@PrivateOwned"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CIHGDDED" name="CIHGDDED"></a><a id="TLJPA398" name="TLJPA398"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@DiscriminatorClass</font></h2>
 <p>Use <code>@DiscriminatorClass</code> with a <code>@VariableOneToOne</code> annotation to determine which entities will be added to the list of types for the mapping.</p>
 <a id="sthref109" name="sthref109"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABGACBF">Table 2-19</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA399" name="TLJPA399"></a><a id="sthref110" name="sthref110"></a><a id="BABGACBF" name="BABGACBF"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-19 @DiscriminatorClass Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@DiscriminatorClass Annotation Elements" summary="This table describes the elements for the @DiscriminatorClass annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="19%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t27"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t27"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t27"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t27" headers="r1c1-t27">
 <p><code>discriminator</code></p>
 </td>
 <td align="left" headers="r2c1-t27 r1c2-t27">
 <p>(Required) The discriminator to be stored in the database</p>
 </td>
 <td align="left" headers="r2c1-t27 r1c3-t27"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t27" headers="r1c1-t27">
 <p>value</p>
 </td>
 <td align="left" headers="r3c1-t27 r1c2-t27">
 <p>(Required) The class to be instantiated with the <code>discriminator</code></p>
 </td>
 <td align="left" headers="r3c1-t27 r1c3-t27"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref111" name="sthref111"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>The <code>@DiscriminatorClass</code> annotation can be specified only within a <code><a href="#CHDDFDGF">@VariableOneToOne</a></code> mapping.</p>
 <a id="sthref112" name="sthref112"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CHDDFDGF">"@VariableOneToOne"</a> for an example of a variable one-to-one mapping with <code>@DiscriminatorClass</code>.</p>
 <a id="sthref113" name="sthref113"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CHDDFDGF">"@VariableOneToOne"</a></p>
 </li>
 <li>
 <p><em>Understanding EclipseLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BEICFBDD" name="BEICFBDD"></a><a id="TLJPA400" name="TLJPA400"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@ExcludeDefaultMappings</font></h2>
 <p>Use <code>@ExcludeDefaultMappings</code> to specify that no default mapping should be added to a specific class. Instead, EclipseLink will use only mappings that are explicitly defined by annotations or the XML mapping file.</p>
 <a id="sthref114" name="sthref114"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p>There are no elements for this annotation.</p>
 <a id="sthref115" name="sthref115"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You can specify <code>@ExcludeDefaultMappings</code> on an Entity, MappedSuperclass, or Embeddable class.</p>
 <a id="sthref116" name="sthref116"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BACGGFEH">Example 2-40</a> shows how to use the <code>@ExcludeDefaultMapping</code> annotation.</p>
 <div class="example"><a id="BACGGFEH" name="BACGGFEH"></a><a id="TLJPA54002" name="TLJPA54002"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-40 Using the @ExcludeDefaultMappings Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @ExcludeDefaultMappings
 @Entity
 public class Dealer {
     @Id
     private long id;
     @Basic
     private String name;
     // These would be ignored
     private List&lt;Card&gt; deck;
     private List&lt;Card&gt; hand;
     ...
 }
 </pre></div>
 <!-- class="example" -->
 <a id="sthref117" name="sthref117"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Building Blocks for a EclipseLink Project" in <em>Understanding EclipseLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABICJEJ" name="BABICJEJ"></a><a id="TLJPA401" name="TLJPA401"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@ExistenceChecking</font></h2>
 <p>Use <code>@ExistenceChecking</code> to specify how EclipseLink should check to determine if an entity is new or exists.</p>
 <p>On <code>merge()</code> operations, use <code>@ExistenceChecking</code> to specify if EclipseLink uses only the cache to determine if an object exists, or if the object should be read (from the database or cache). By default the object will be read from the database.</p>
 <a id="sthref118" name="sthref118"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CEGHFAIB">Table 2-20</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA402" name="TLJPA402"></a><a id="sthref119" name="sthref119"></a><a id="CEGHFAIB" name="CEGHFAIB"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-20 @ExistenceChecking Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@ExistenceChecking Annotation Elements" summary="This table describes the elements for the @ExistenceChecking 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-t28"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t28"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t28"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t28" headers="r1c1-t28">
 <p><code>ExistenceType</code></p>
 </td>
 <td align="left" headers="r2c1-t28 r1c2-t28">
 <p>(Optional) Set the existence checking type:</p>
 <ul>
 <li>
 <p><code>ASSUME_EXISTENCE</code></p>
 </li>
 <li>
 <p><code>ASSUME_NON_EXISTENCE</code></p>
 </li>
 <li>
 <p><code>CHECK_CHACHE</code></p>
 </li>
 <li>
 <p><code>CHECK_DATABASE</code></p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r2c1-t28 r1c3-t28">
 <p><code>CHECK_CACHE</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref120" name="sthref120"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You can specify <code>@ExistenceChecking</code> on an Entity or MappedSuperclass.</p>
 <p>EclipseLink supports the following existence checking types:</p>
 <ul>
 <li>
 <p><code>ASSUME_EXISTENCE</code> &#8211; If the object's primary key does not include <code>null</code> then it must exist. You may use this option if the application guarantees or does not care about the existence check.</p>
 </li>
 <li>
 <p><code>ASSUME_NON_EXISTENCE</code> &#8211; Assume that the object does not exist. You may use this option if the application guarantees or does not care about the existence check. This will always force an <code>INSERT</code> operation.</p>
 </li>
 <li>
 <p><code>CHECK_CHACHE</code> &#8211; If the object's primary key does not include <code>null</code> and it is in the cache, then it must exist.</p>
 </li>
 <li>
 <p><code>CHECK_DATABASE</code> &#8211; Perform a <code>SELECT</code> on the database.</p>
 </li>
 </ul>
 <a id="sthref121" name="sthref121"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CEGDGCHF">Example 2-41</a> shows how to use this annotation.</p>
 <div class="example"><a id="CEGDGCHF" name="CEGDGCHF"></a><a id="TLJPA54003" name="TLJPA54003"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-41 Using @ExistenceChecking Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Cache(type=CacheType.HARD_WEAK,  expiryTimeOfDay=@TimeOfDay(hour=1))
 <strong>@ExistenceChecking(ExistenceType.CHECK_DATABASE)</strong>
 public  class  Employee  implements  Serializable  {
 ...
 }

 </pre></div>
 <!-- class="example" -->
 <a id="sthref122" name="sthref122"></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>"Enhancing Performance" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABCHIGE" name="BABCHIGE"></a><a id="TLJPA403" name="TLJPA403"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@FetchAttribute</font></h2>
 <p>Use <code>@FetchAttribute</code> to improve performance within a fetch group; it allows on-demand loading of a group of an object's attributes. As a result, the data for an attribute might not be loaded from the datasource until an explicit access call occurs.</p>
 <p>This avoids loading all the data of an object's attributes if the user requires only some of the attributes.</p>
 <a id="sthref123" name="sthref123"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABDFABA">Table 2-21</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA404" name="TLJPA404"></a><a id="sthref124" name="sthref124"></a><a id="BABDFABA" name="BABDFABA"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-21 @FetchAttribute Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@FetchAttribute Annotation Elements" summary="This table describes the elements for the @FetchAttribute 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-t29"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t29"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t29"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t29" headers="r1c1-t29">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t29 r1c2-t29">
 <p>(Required) Name of the fetch attribute</p>
 </td>
 <td align="left" headers="r2c1-t29 r1c3-t29"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref125" name="sthref125"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>EclipseLink provides two types of fetch groups:</p>
 <ul>
 <li>
 <p>Pre-defined fetch groups at the Entity or MappedSuperclass level</p>
 </li>
 <li>
 <p>Dynamic (use case) fetch groups at the query level</p>
 </li>
 </ul>
 <p>You should extensively review your use cases when using fetch groups. In many cases, additional round-trips will offset any gains from deferred loading.</p>
 <a id="sthref126" name="sthref126"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABFDFHD">Example 2-42</a> shows how to use <code>@FetchAttribute</code> within a <code>@FetchGroup</code> annotation.</p>
 <div class="example"><a id="BABFDFHD" name="BABFDFHD"></a><a id="TLJPA405" name="TLJPA405"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-42 Using @FetchAttribute Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @FetchGroup(name="basic-fetch-group", attributes={
         <strong>@FetchAttribute(name="id")</strong>,
         <strong>@FetchAttribute(name="name")</strong>,
         <strong>@FetchAttribute(name="address")</strong>})
 public class Person {

    @Id
    private int id;

    private String name;

    @OneToOne(fetch=LAZY)
    private Address address;

    @ManyToOne(fetch=EAGER)
    private ContactInfo contactInfo;
 </pre></div>
 <!-- class="example" -->
 <div class="example"><a id="TLJPA54004" name="TLJPA54004"></a><a id="sthref127" name="sthref127"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-43 Using &lt;fetch-group&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>&lt;fetch-group name="basic-fetch-group"&gt;</strong>
     &lt;attribute name="id"/&gt;
     &lt;attribute name="name"/&gt;
     &lt;attribute name="address"/&gt;
 &lt;/fetch-group&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref128" name="sthref128"></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="#BABJBDEG">"@FetchGroup"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABJBDEG" name="BABJBDEG"></a><a id="TLJPA406" name="TLJPA406"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@FetchGroup</font></h2>
 <p>Use <code>@FetchGroup</code> to load a group of attributes on demand, as needed.</p>
 <p>This avoids wasteful practice of loading all data of the object's attributes, if the user is interested in only partial of them. However, it also means that the data for an attribute might not be loaded from the underlying data source until an explicit access call for the attribute first occurs.</p>
 <a id="sthref129" name="sthref129"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABFGBBD">Table 2-22</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA407" name="TLJPA407"></a><a id="sthref130" name="sthref130"></a><a id="BABFGBBD" name="BABFGBBD"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-22 @FetchGroup Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@FetchGroup Annotation Elements" summary="This table describes the elements for the @FetchGroup annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="31%" />
 <col width="*" />
 <col width="19%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t30"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t30"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t30"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t30" headers="r1c1-t30">
 <p><code>FetchAttribute[] attributes</code></p>
 </td>
 <td align="left" headers="r2c1-t30 r1c2-t30">
 <p>(Required) The list of attributes to fetch</p>
 </td>
 <td align="left" headers="r2c1-t30 r1c3-t30">
 <p>none</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t30" headers="r1c1-t30">
 <p><code>java.lang.String name</code></p>
 </td>
 <td align="left" headers="r3c1-t30 r1c2-t30">
 <p>(Required) The fetch group name</p>
 </td>
 <td align="left" headers="r3c1-t30 r1c3-t30">
 <p>none</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t30" headers="r1c1-t30">
 <p><code>boolean load</code></p>
 </td>
 <td align="left" headers="r4c1-t30 r1c2-t30">
 <p>(Optional) Indicates whether all relationship attributes specified in the fetch group should be loaded.</p>
 </td>
 <td align="left" headers="r4c1-t30 r1c3-t30">
 <p><code>false</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref131" name="sthref131"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You should perform a careful use case analysis when using <code>@FetchGroup</code>; any gains realized from the deferred loading could be offset by the extra round-trip.</p>
 <p>EclipseLink supports fetch groups at two levels:</p>
 <ul>
 <li>
 <p>Pre-defined fetch groups at the Entity or MappedSuperclass level</p>
 </li>
 <li>
 <p>Dynamic (use case) fetch groups at the query level</p>
 </li>
 </ul>
 <p>You can use fetch groups only when using weaving or when individual classes that define them explicitly implement the <code>org.eclipse.persistence.queries.FetchGroupTracker</code> interface.</p>
 <p>When using a fetch group, you can define a subset of an object's attributes and associate the fetch group with a query. When you execute the query, EclipseLink retrieves only the attributes in the fetch group. EclipseLink automatically executes a query to fetch all the attributes excluded from this subset when and if you call a get method on any one of the excluded attributes.</p>
 <p>You can define more than one fetch group for a class. You can optionally designate at most one such fetch group as the default fetch group. If you execute a query without specifying a fetch group, EclipseLink will use the default fetch group, unless you configure the query otherwise.</p>
 <p>Before using fetch groups, it is recommended that you perform a careful analysis of system use. In many cases, the extra queries required to load attributes not in the fetch group could well offset the gain from the partial attribute loading.</p>
 <a id="sthref132" name="sthref132"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABGHDJB">Example 2-44</a> shows how to use this annotation.</p>
 <div class="example"><a id="BABGHDJB" name="BABGHDJB"></a><a id="TLJPA408" name="TLJPA408"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-44 Using @FetchGroup Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>@FetchGroup</strong>(name="names", attributes={
     @FetchAttribute(name="firstName"),
     @FetchAttribute(name="lastName")})
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CACEFCDH">Example 2-45</a> shows how to use this feature in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="CACEFCDH" name="CACEFCDH"></a><a id="TLJPA409" name="TLJPA409"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-45 Using &lt;fetch-group&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity class="model.Employee"&gt;
     &lt;secondary-table name="SALARY" /&gt;
     <strong>&lt;fetch-group name="names"&gt;</strong>
         &lt;attribute name="firstName" /&gt;
         &lt;attribute name="lastName" /&gt;
     <strong>&lt;/fetch-group&gt;</strong>
 ...
 </pre></div>
 <!-- class="example" -->
 <p>You can also use a named fetch group with a query, as shown in <a href="#BABGFDJA">Example 2-46</a>.</p>
 <div class="example"><a id="BABGFDJA" name="BABGFDJA"></a><a id="TLJPA410" name="TLJPA410"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-46 Using a Named Fetch Group on a Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 TypedQuery query = em.createQuery("SELECT e FROM Employee e", Employee.class);

 query.setHint(QueryHints.FETCH_GROUP_NAME, "names");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref133" name="sthref133"></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="#BABCHIGE">"@FetchAttribute"</a></p>
 </li>
 <li>
 <p><a href="#CHDIEBGG">"@FetchGroups"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDIEBGG" name="CHDIEBGG"></a><a id="TLJPA411" name="TLJPA411"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@FetchGroups</font></h2>
 <p>Use <code>@FetchGroups</code> to define a group of <code>@FetchGroup</code>.</p>
 <a id="sthref134" name="sthref134"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BACDEJEJ">Table 2-23</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA412" name="TLJPA412"></a><a id="sthref135" name="sthref135"></a><a id="BACDEJEJ" name="BACDEJEJ"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-23 @FetchGroups Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@FetchGroups Annotation Elements" summary="This table describes the elements for the @FetchGroups 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-t31"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t31"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t31"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t31" headers="r1c1-t31">
 <p><code>FetchGroup</code></p>
 </td>
 <td align="left" headers="r2c1-t31 r1c2-t31">
 <p>(Required) An array of fetch groups (<code>@FetchGroup</code>)</p>
 </td>
 <td align="left" headers="r2c1-t31 r1c3-t31"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref136" name="sthref136"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You can specify <code>@FetchGroups</code> on an Entity or MappedSuperclass.</p>
 <p>You can also enable or disable fetch groups through weaving for the persistence unit.</p>
 <a id="sthref137" name="sthref137"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#BABJBDEG">"@FetchGroup"</a> for an example of using fetch groups.</p>
 <p><a href="#CHDJCEHI">Example 2-47</a> shows how to configure fetch groups in the persistence unit <code>persistence.xml</code> file or by importing a <code>property</code> map.</p>
 <div class="example"><a id="CHDJCEHI" name="CHDJCEHI"></a><a id="TLJPA413" name="TLJPA413"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-47 Specifying Fetch Groups 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="eclipselink.weaving.fetchgroups" 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.WEAVING_FETCHGROUPS, "false");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref138" name="sthref138"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BABJBDEG">"@FetchGroup"</a></p>
 </li>
 <li>
 <p><a href="#BABCHIGE">"@FetchAttribute"</a></p>
 </li>
 <li>
 <p><a href="persistenceproperties_ref.htm#weaving">"weaving"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CBHHCHAC" name="CBHHCHAC"></a><a id="TLJPA414" name="TLJPA414"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Field</font></h2>
 <p>Use <code>@Field</code> to define a structured data type's field name for an object mapped to NoSql data.</p>
 <a id="sthref139" name="sthref139"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CBHEEEGE">Table 2-24</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA415" name="TLJPA415"></a><a id="sthref140" name="sthref140"></a><a id="CBHEEEGE" name="CBHEEEGE"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-24 @Field Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Field Annotation Elements" summary="This table describes the elements for the @Field 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-t32"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t32"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t32"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t32" headers="r1c1-t32">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t32 r1c2-t32">
 <p>(Optional) The data type's name of the field</p>
 </td>
 <td align="left" headers="r2c1-t32 r1c3-t32"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref141" name="sthref141"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>The <code>@Field</code> annotation is a generic form of the <code>@Column</code> annotation, which is not specific to relational databases. You can use <code>@Field</code> to map EIS and NoSQL data.</p>
 <a id="sthref142" name="sthref142"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#BJEIEBHC">"@NoSql"</a> for an example of the <code>@Field</code> annotation.</p>
 <a id="sthref143" name="sthref143"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BJEIEBHC">"@NoSql"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CEGBDBEG" name="CEGBDBEG"></a><a id="TLJPA416" name="TLJPA416"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@HashPartitioning</font></h2>
 <p>Use <code>@HashPartitioning</code> to partition access to a database cluster by the hash of a field value from the object (such as the object's location or tenant). The hash indexes into the list of connection pools.</p>
 <a id="sthref144" name="sthref144"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CEGCAGJF">Table 2-25</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA417" name="TLJPA417"></a><a id="sthref145" name="sthref145"></a><a id="CEGCAGJF" name="CEGCAGJF"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-25 @HashPartitioning Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@HashPartitioning Annotation Elements" summary="This table describes the elements for the @HashPartitioning 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-t33"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t33"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t33"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t33" headers="r1c1-t33">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t33 r1c2-t33">
 <p>(Required) The name of the partition policy. The name must be unique within the persistence unit.</p>
 </td>
 <td align="left" headers="r2c1-t33 r1c3-t33"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t33" headers="r1c1-t33">
 <p><code>partitionColumn</code></p>
 </td>
 <td align="left" headers="r3c1-t33 r1c2-t33">
 <p>(Required) The database column or query parameter by which to partition queries</p>
 </td>
 <td align="left" headers="r3c1-t33 r1c3-t33"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t33" headers="r1c1-t33">
 <p><code>connectionPools</code></p>
 </td>
 <td align="left" headers="r4c1-t33 r1c2-t33">
 <p>(Optional) List of connection pool names across which to partition</p>
 </td>
 <td align="left" headers="r4c1-t33 r1c3-t33">
 <p>All defined pools in the ServerSession</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t33" headers="r1c1-t33">
 <p><code>unionUnpartitionableQueries</code></p>
 </td>
 <td align="left" headers="r5c1-t33 r1c2-t33">
 <p>(Optional) Specify if queries that <em>do not</em> contain the partition hash should be sent to every database and union the result.</p>
 </td>
 <td align="left" headers="r5c1-t33 r1c3-t33">
 <p>False</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref146" name="sthref146"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>All write or read requests for objects with the hash value are sent to the server. Queries that do not include the field as a parameter will be:</p>
 <ul>
 <li>
 <p>Sent to all servers and unioned</p>
 <p>or</p>
 </li>
 <li>
 <p>Handled based on the session's default behavior.</p>
 </li>
 </ul>
 <p>You can enable partitioning on an Entity, relationship, query, or session/persistence unit. Partition policies are globally named (to allow reuse) and must set using the <code>@Partitioned</code> annotation.</p>
 <p>The persistence unit properties support adding named connection pools in addition to the existing configuration for read/write/sequence. A named connection pool must be defined for each node in the database cluster.</p>
 <p>If a transaction modifies data from multiple partitions, you should use JTA to ensure proper two-phase commit of the data. You can also configure an exclusive connection in the EntityManager to ensure that only a single node is used for a single transaction.</p>
 <a id="sthref147" name="sthref147"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CHDDAHEB">"@Partitioned"</a> for an example of partitioning with EclipseLink.</p>
 <a id="sthref148" name="sthref148"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Data Partitioning"<code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning</a></code></p>
 </li>
 <li>
 <p><a href="#CHDDAHEB">"@Partitioned"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABGIFEC" name="BABGIFEC"></a><a id="TLJPA418" name="TLJPA418"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Index</font></h2>
 <p>An index is a database structure defined for a table, to improve query and look-up performance for a set of columns. Use the <code>@Index</code> annotation in code or the <code>&lt;index&gt;</code> element in the <code>eclipselink-orm.xml</code> descriptor to create an index on a table.</p>
 <p>An index can be defined on an entity or on an attribute. For the entity it must define a set of columns to index.</p>
 <p>Index creation is database specific. Some databases may not support indexes. Most databases auto-index primary key and foreign key columns. Some databases support advanced index DDL options. To create more advanced index DDL, a DDL script or native query can be used.</p>
 <a id="sthref149" name="sthref149"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABCGCDG">Table 2-26</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA419" name="TLJPA419"></a><a id="sthref150" name="sthref150"></a><a id="BABCGCDG" name="BABCGCDG"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-26 @Index Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Index Annotation Elements" summary="This table describes the elements of the @Index 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-t34"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t34"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t34"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t34" headers="r1c1-t34">
 <p><code>java.lang.String catalog</code></p>
 </td>
 <td align="left" headers="r2c1-t34 r1c2-t34">
 <p>(Optional) The catalog of the <code>INDEX</code></p>
 </td>
 <td align="left" headers="r2c1-t34 r1c3-t34">
 <p>Default catalog</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t34" headers="r1c1-t34">
 <p><code>java.lang.String[] columnNames</code></p>
 </td>
 <td align="left" headers="r3c1-t34 r1c2-t34">
 <p>(Not required when annotated on a field or method) Specify the set of columns to define the index on.</p>
 </td>
 <td align="left" headers="r3c1-t34 r1c3-t34">
 <p>For an Entity, none.</p>
 <p>For an attribute, the attribute's column.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t34" headers="r1c1-t34">
 <p>j<code>ava.lang.String name</code></p>
 </td>
 <td align="left" headers="r4c1-t34 r1c2-t34">
 <p>(Optional) The name of the <code>INDEX</code></p>
 </td>
 <td align="left" headers="r4c1-t34 r1c3-t34">
 <p><code>&lt;table&gt;_&lt;column&gt;_INDEX</code> (but a name should be provided)</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t34" headers="r1c1-t34">
 <p><code>java.lang.String schema</code></p>
 </td>
 <td align="left" headers="r5c1-t34 r1c2-t34">
 <p>(Optional) The schema of the <code>INDEX</code></p>
 </td>
 <td align="left" headers="r5c1-t34 r1c3-t34">
 <p>Default schema</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t34" headers="r1c1-t34">
 <p><code>java.lang.String table</code></p>
 </td>
 <td align="left" headers="r6c1-t34 r1c2-t34">
 <p>(Optional) The table to define the index on; defaults to entities primary table.</p>
 </td>
 <td align="left" headers="r6c1-t34 r1c3-t34">
 <p>The entity's primary table.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r7c1-t34" headers="r1c1-t34">
 <p><code>boolean unique</code></p>
 </td>
 <td align="left" headers="r7c1-t34 r1c2-t34">
 <p>(Optional) Specify whether the index is unique or non-unique.</p>
 </td>
 <td align="left" headers="r7c1-t34 r1c3-t34">
 <p><code>false</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref151" name="sthref151"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Use <code>@Index</code> annotation to index any attributes or columns that will commonly be used in queries.</p>
 <a id="sthref152" name="sthref152"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>This example defines three indexes, one on <strong>first name</strong>, one on <strong>last name</strong>, and a multiple column index on <strong>first name</strong> <em>and</em> <strong>last name</strong>.</p>
 <div class="example"><a id="TLJPA420" name="TLJPA420"></a><a id="sthref153" name="sthref153"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-48 Using @Index Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 <strong>@Index(name="EMP_NAME_INDEX", columns={"F_NAME","L_NAME"})</strong>
 public class Employee{
     @Id
     private long id;
     <strong>@Index</strong>
     @Column(name="F_NAME")
     private String firstName;
     <strong>@Index</strong>
     @Column(name="L_NAME")
     private String lastName;
     ...
 }
 </pre></div>
 <!-- class="example" -->
 <p>You can also create an index in the <code>eclipselink-orm.xml</code> descriptor using <code>&lt;index&gt;</code>, as shown in the following example. Define columns using the <code>&lt;column&gt;</code> subelement. All the attributes supported in the <code>@Index</code> annotation are also supported in the <code>&lt;index&gt;</code> element.</p>
 <div class="example"><a id="TLJPA421" name="TLJPA421"></a><a id="sthref154" name="sthref154"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-49 Using &lt;index&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>&lt;index name="EMP_NAME_INDEX" table="EMPLOYEE" unique="true"&gt;</strong>
     &lt;column&gt;F_NAME&lt;/column&gt;
     &lt;column&gt;L_NAME&lt;/column&gt;
 <strong>&lt;/index&gt;</strong>
 </pre></div>
 <!-- class="example" -->
 <a id="sthref155" name="sthref155"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information see:</p>
 <ul>
 <li>
 <p><a href="#CHDHGAIE">"@Indexes"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDHGAIE" name="CHDHGAIE"></a><a id="TLJPA422" name="TLJPA422"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Indexes</font></h2>
 <p>Use <code>@Indexes</code> to define a set of database indexes for an Entity.</p>
 <a id="sthref156" name="sthref156"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDHCABJ">Table 2-27</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA423" name="TLJPA423"></a><a id="sthref157" name="sthref157"></a><a id="CHDHCABJ" name="CHDHCABJ"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-27 @Indexes Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Indexes Annotation Elements" summary="This table describes the elements for the @Indexes 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-t35"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t35"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t35"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t35" headers="r1c1-t35">
 <p><code>Index[]</code></p>
 </td>
 <td align="left" headers="r2c1-t35 r1c2-t35">
 <p>An array of database indexes</p>
 </td>
 <td align="left" headers="r2c1-t35 r1c3-t35"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref158" name="sthref158"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#BABGIFEC">"@Index"</a> for an example of using the <code>@Index</code> annotation.</p>
 <a id="sthref159" name="sthref159"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information see:</p>
 <ul>
 <li>
 <p><a href="#BGBDGCDJ">"@CopyPolicy"</a></p>
 </li>
 <li>
 <p><a href="#CDDJGFHA">"@CloneCopyPolicy"</a></p>
 </li>
 <li>
 <p><a href="#BABGIFEC">"@Index"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDCJEIG" name="CHDCJEIG"></a><a id="TLJPA424" name="TLJPA424"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@InstantiationCopyPolicy</font></h2>
 <p>Use <code>@InstantiationCopyPolicy</code> to set an <code>org.eclipse.persistence.descriptors.copying.InstantiationCopyPolicy</code> on an Entity.</p>
 <a id="sthref160" name="sthref160"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p>There are no elements for this annotation.</p>
 <a id="sthref161" name="sthref161"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>The copy policy specifies how EclipseLink clones objects to and from the shared cache. With <code>@InstantiationCopyPolicy</code>, in order to clone an object EclipseLink will create a new instance of the object and copy each persistent attribute. Alternative methods include <code><a href="#CDDJGFHA">@CloneCopyPolicy</a></code>, which clones the object.</p>
 <p>Cloning is more efficient than creating a new instance and maintains transient or non-persistent attribute values. If you do not need transient or non-persistent attribute values in the shared cache, then use <code>@InstantiationCopyPolicy</code>.</p>
 <p>The default EclipseLink copy policy depends on your configuration:</p>
 <ul>
 <li>
 <p>When using <a href="persistenceproperties_ref.htm#BABJICDJ">weaving.internal</a> (and field access), EclipseLink generates a specialized clone method to copy objects.</p>
 </li>
 <li>
 <p>Without weaving, EclipseLink uses instantiation to copy objects.</p>
 </li>
 </ul>
 <p>You can specify <code>@InstantiationCopyPolicy</code> on an Entity, MappedSuperclass, or Embeddable entity.</p>
 <a id="sthref162" name="sthref162"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDDBCHI">Example 2-50</a> shows how to use this annotation.</p>
 <div class="example"><a id="CHDDBCHI" name="CHDDBCHI"></a><a id="TLJPA426" name="TLJPA426"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-50 Using @InstantiationCopyPolicy Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 <strong>@InstantiationCopyPolicy</strong>
 public class Employee {
     ...
     transient List events = new ArrayList();
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDGCDAI">Example 2-51</a> shows how to use this extension in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="CHDGCDAI" name="CHDGCDAI"></a><a id="TLJPA427" name="TLJPA427"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-51 Using &lt;instantiation-copy-policy&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity name="Employee" class="org.acme.Employee" access="FIELD"&gt;
     <strong>&lt;instantiation-copy-policy/&gt;</strong>
     ...
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref163" name="sthref163"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BGBDGCDJ">"@CopyPolicy"</a></p>
 </li>
 <li>
 <p><a href="#CDDJGFHA">"@CloneCopyPolicy"</a></p>
 </li>
 <li>
 <p><a href="persistenceproperties_ref.htm#BABJICDJ">"weaving.internal"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CEGFFHHA" name="CEGFFHHA"></a><a id="TLJPA428" name="TLJPA428"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@JoinFetch</font></h2>
 <p>Use the <code>@JoinFetch</code> annotation to enable the joining and reading of the related objects in the same query as the source object.</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>You should set join fetching at the query level, as not all queries require joining.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref164" name="sthref164"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CEGFCHJB">Table 2-28</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA429" name="TLJPA429"></a><a id="sthref165" name="sthref165"></a><a id="CEGFCHJB" name="CEGFCHJB"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-28 @JoinFetch Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@JoinFetch Annotation Elements" summary="This table describes the elements for the @JoinFetch 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-t37"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t37"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t37"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t37" headers="r1c1-t37">
 <p><code>value</code></p>
 </td>
 <td align="left" headers="r2c1-t37 r1c2-t37">
 <p>(Optional) Set this attribute to the <code>org.eclipse.persistence.annotations.</code><code>JoinFetchType</code> enumerated type of the fetch that you will be using.</p>
 <p>The following are the valid values for the <code>JoinFetchType</code>:</p>
 <ul>
 <li>
 <p><code>INNER</code>&#8212;This option provides the inner join fetching of the related object.</p>
 <p><strong>Note</strong>: Inner joining does not allow for null or empty values.</p>
 </li>
 <li>
 <p><code>OUTER</code>&#8212;This option provides the outer join fetching of the related object.</p>
 <p><strong>Note</strong>: Outer joining allows for null or empty values.</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r2c1-t37 r1c3-t37">
 <p><code>JoinFetchType.INNER</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref166" name="sthref166"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You can specify the <code>@JoinFetch</code> annotation for the following mappings:</p>
 <ul>
 <li>
 <p><code>@OneToOne</code></p>
 </li>
 <li>
 <p><code>@OneToMany</code></p>
 </li>
 <li>
 <p><code>@ManyToOne</code></p>
 </li>
 <li>
 <p><code>@ManyToMany</code></p>
 </li>
 <li>
 <p><code>@ElementCollection</code></p>
 </li>
 </ul>
 <p>Alternatively, you can use batch fetching which is more efficient, especially for collection relationships.</p>
 <a id="sthref167" name="sthref167"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>The following example shows how to use the <code>@JoinFetch</code> annotation to specify Employee field <code>managedEmployees</code>.</p>
 <div class="example"><a id="TLJPA430" name="TLJPA430"></a><a id="sthref168" name="sthref168"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-52 Using @JoinFetch Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
  public class Employee implements Serializable {
     ...
     @OneToMany(cascade=ALL, mappedBy="owner")
     <strong>@JoinFetch(value=OUTER)</strong>
     public Collection&lt;Employee&gt; getManagedEmployees() {
         return managedEmployees;
     }
     ...
  }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CEGJIBCF">Example 2-53</a> shows how to use this extension in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="CEGJIBCF" name="CEGJIBCF"></a><a id="TLJPA54005" name="TLJPA54005"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-53 Using &lt;join-fetch&gt; in XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;one-to-many name="managedEmployees"&gt;
     &lt;join-fetch&gt;OUTER&lt;/join-fetch&gt;
 &lt;/one-to-many&gt;

 </pre></div>
 <!-- class="example" -->
 <a id="sthref169" name="sthref169"></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>"Enhancing Performance" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 <li>
 <p><a href="#CHDCCIDA">"@BatchFetch"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CIHCAFEI" name="CIHCAFEI"></a><a id="TLJPA431" name="TLJPA431"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@JoinField</font></h2>
 <p>Use <code>@JoinField</code> to define a structured data type's foreign key field for an object mapped to NoSql data.</p>
 <a id="sthref170" name="sthref170"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CIHEHJJH">Table 2-29</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA432" name="TLJPA432"></a><a id="sthref171" name="sthref171"></a><a id="CIHEHJJH" name="CIHEHJJH"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-29 @JoinField Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@JoinField Annotation Elements" summary="This table describes the elements for the @JoinField 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-t38"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t38"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t38"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t38" headers="r1c1-t38">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t38 r1c2-t38">
 <p>(Optional) The name of the foreign key/ID reference field in the source record</p>
 </td>
 <td align="left" headers="r2c1-t38 r1c3-t38"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t38" headers="r1c1-t38">
 <p><code>referencedFieldName</code></p>
 </td>
 <td align="left" headers="r3c1-t38 r1c2-t38">
 <p>(Optional) The name of the ID field in the target record</p>
 </td>
 <td align="left" headers="r3c1-t38 r1c3-t38"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref172" name="sthref172"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>The <code>@JoinField</code> annotation is a generic form of the <code>@JoinColumn</code> annotation, which is not specific to relational databases. You can use <code>@JoinField</code> to map EIS and NoSQL data.</p>
 <a id="sthref173" name="sthref173"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>These examples show how to use this extension as an annotation and in XML.</p>
 <div class="example"><a id="CIHCFEJH" name="CIHCFEJH"></a><a id="TLJPA54006" name="TLJPA54006"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-54 Using @JoinField Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @NoSql
 public class Order {
     ...
     @ManyToOne
     @JoinField(name="customerId")
     private Customer customer;
 }
 </pre></div>
 <!-- class="example" -->
 <div class="example"><a id="TLJPA54007" name="TLJPA54007"></a><a id="sthref174" name="sthref174"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-55 Using &lt;join-field&gt; in XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity name="Order" class="org.acme.Order"&gt;
     &lt;no-sql/&gt;
     ...
     &lt;many-to-one name="customer"&gt;
         &lt;join-field name="customerId"/&gt;
     &lt;/many-to-one&gt;
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref175" name="sthref175"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Mappings"<code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/NoSQL/Mappings">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/NoSQL/Mappings</a></code></p>
 </li>
 <li>
 <p><a href="#BEIFHJJE">"@JoinFields"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BEIFHJJE" name="BEIFHJJE"></a><a id="TLJPA433" name="TLJPA433"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@JoinFields</font></h2>
 <p>Use <code>@JoinFields</code> to define a set of <code>@JoinField</code> annotations on a relationship.</p>
 <a id="sthref176" name="sthref176"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BEIBIGIJ">Table 2-30</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA434" name="TLJPA434"></a><a id="sthref177" name="sthref177"></a><a id="BEIBIGIJ" name="BEIBIGIJ"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-30 @JoinFields Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@JoinFields Annotation Elements" summary="This table describes the elements for the @JoinFields 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-t39"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t39"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t39"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t39" headers="r1c1-t39">
 <p><code>JoinField[]</code>J</p>
 </td>
 <td align="left" headers="r2c1-t39 r1c2-t39">
 <p>An array of join fields</p>
 </td>
 <td align="left" headers="r2c1-t39 r1c3-t39"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref178" name="sthref178"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CIHCAFEI">"@JoinField"</a> for an example of using the <code>@Index</code> annotation.</p>
 <a id="sthref179" name="sthref179"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CIHCAFEI">"@JoinField"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BEHBBCDB" name="BEHBBCDB"></a><a id="TLJPA435" name="TLJPA435"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@MapKeyConvert</font></h2>
 <p>Use <code>@MapKeyConvert</code> to specify a named converter to be used with the corresponding mapped attribute key column.</p>
 <a id="sthref180" name="sthref180"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BEHBBBEH">Table 2-31</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA436" name="TLJPA436"></a><a id="sthref181" name="sthref181"></a><a id="BEHBBBEH" name="BEHBBBEH"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-31 @MapKeyConvert Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@MapKeyConvert Annotation Elements" summary="This table describes the elements for the @MapKeyConvert 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-t40"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t40"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t40"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t40" headers="r1c1-t40">
 <p><code>value</code></p>
 </td>
 <td align="left" headers="r2c1-t40 r1c2-t40">
 <p>(Optional) Name of the converter to use:</p>
 <ul>
 <li>
 <p><code>serialized</code></p>
 </li>
 <li>
 <p><code>class-instance</code></p>
 </li>
 <li>
 <p><code>none</code></p>
 </li>
 <li>
 <p>custom converter</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r2c1-t40 r1c3-t40">
 <p>none</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref182" name="sthref182"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Use <code>@MapKeyConvert</code> to convert the key value used in a <code>@MapKeyColumn</code> to have a different type or value than the database column.</p>
 <p>The <code>@MapKeyConvert</code> annotation has the following reserved names:</p>
 <ul>
 <li>
 <p><code>serialized</code>: Will use a <code>SerializedObjectConverter</code> on the associated mapping. When using a <code>SerializedObjectConverter</code> the database representation is a binary field holding a serialized version of the object and the object-model representation is a the actual object</p>
 </li>
 <li>
 <p><code>class-instance</code>: Will use an ClassInstanceConverter on the associated mapping. When using a ClassInstanceConverter the database representation is a String 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><code>none</code> - Will place no converter on the associated mapping. This can be used to override a situation where either another converter is defaulted or another converter is set.</p>
 </li>
 </ul>
 <p>If you do not use one of these reserved names, you must define a custom converter, using the <code>@Converter</code> annotation.</p>
 <a id="sthref183" name="sthref183"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BEHEHJJC">Example 2-56</a> shows using a <code>@MapKeyConvert</code> annotation to apply a converter to a map's key.</p>
 <div class="example"><a id="BEHEHJJC" name="BEHEHJJC"></a><a id="TLJPA437" name="TLJPA437"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-56 Using @MapKeyConvert Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 public class Entity
  &#8230;
     @ElementCollection
     @MapKeyColumn(name=&#8221;BANK&#8221;)
     @Column(name=&#8221;ACCOUNT&#8221;)
     @Convert(&#8221;Long2String&#8221;)
     <strong>@MapKeyConvert</strong>(&#8221;CreditLine&#8221;)
     public Map&lt;String,Long&gt; getCreditLines() {
         return creditLines;
     }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BEHCFGDH">Example 2-57</a> shows how to use the <code>&lt;map-key-convert&gt;</code> element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="BEHCFGDH" name="BEHCFGDH"></a><a id="TLJPA438" name="TLJPA438"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-57 Using &lt;map-key-convert&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;element-collection name="creditLines"&gt;
   <strong>&lt;map-key-convert&gt;</strong>CreditLine&lt;/map-key-convert&gt;
   &lt;map-key-column name="BANK"/&gt;
   &lt;column name="ACCOUNT"/&gt;
   &lt;convert&gt;Long2String&lt;/convert&gt;
   &lt;object-type-converter name="CreditLine"&gt;
     &lt;conversion-value data-value="RBC" object-value="RoyalBank"/&gt;
     &lt;conversion-value data-value="CIBC" object-value="CanadianImperial"/&gt;
     &lt;conversion-value data-value="SB" object-value="Scotiabank"/&gt;
     &lt;conversion-value data-value="TD" object-value="TorontoDominion"/&gt;
   &lt;/object-type-converter&gt;
   &lt;type-converter name="Long2String" data-type="String" object-type="Long"/&gt;
   &lt;collection-table name="EMP_CREDITLINES"&gt;
     &lt;join-column name="EMP_ID"/&gt;
   &lt;/collection-table&gt;
 &lt;/element-collection&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref184" name="sthref184"></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="#BEHGJHCD">"@Convert"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABIEJGD" name="BABIEJGD"></a><a id="TLJPA707" name="TLJPA707"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Multitenant</font></h2>
 <p>The <code>@Multitenant</code> annotation specifies that a given entity is shared among multiple tenants of an application. The multitenant type specifies how the data for these entities are to be stored on the database for each tenant. Multitenancy can be specified at the entity or mapped superclass level.</p>
 <a id="sthref185" name="sthref185"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDGJGDC">Table 2-32</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA708" name="TLJPA708"></a><a id="sthref186" name="sthref186"></a><a id="CHDGJGDC" name="CHDGJGDC"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-32 @Multitenant Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Multitenant Annotation Elements" summary="This table describes the attributes for the @Multitenant 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-t41"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t41"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t41"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t41" headers="r1c1-t41">
 <p><code>boolean includeCriteria</code></p>
 </td>
 <td align="left" headers="r2c1-t41 r1c2-t41">
 <p>Indicates if the database requires the tenant criteria to be added to the <code>SELECT</code>, <code>UPDATE</code>, and <code>DELETE</code> queries.</p>
 </td>
 <td align="left" headers="r2c1-t41 r1c3-t41">
 <p><code>true</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t41" headers="r1c1-t41">
 <p><code>MultitenantType value</code></p>
 </td>
 <td align="left" headers="r3c1-t41 r1c2-t41">
 <p>Specifies the multitenant strategy to use: <code>SINGLE_TABLE</code>, <code>TABLE_PER_TENANT</code>, or <code>VPD</code>.</p>
 </td>
 <td align="left" headers="r3c1-t41 r1c3-t41">
 <p><code>SINGLE_TABLE</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref187" name="sthref187"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>To use the <code>@Multitenant</code> annotation, include the annotation with an <code>@Entity</code> or <code>@MappedSuperclass</code> annotation. For example:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Multitenant
 ...
 public class Employee() {
   ...
 }

 </pre>
 <p>Three types of multitenancy are available:</p>
 <ul>
 <li>
 <p><a href="#BABICDGI">Single-Table Multitenancy</a></p>
 </li>
 <li>
 <p><a href="#BABEGBIJ">Table-Per-Tenanat Multitenancy</a></p>
 </li>
 <li>
 <p><a href="#CHDBFBGI">VPD Multitenancy</a></p>
 </li>
 </ul>
 <a id="sthref188" name="sthref188"></a>
 <p><strong><font face="arial, helvetica, sans-serif" color="#330099">Example</font></strong></p>
 <p><a href="#BABEHCGI">Example 2-58</a> shows a simple example of a <code>@Multitenant</code> annotation. In this example, the <strong>Player</strong> entity has rows for multiple tenants stored in its default <code>PLAYER</code> table and that the default <code>TENANT_ID</code> column is used as a discriminator along with the default context property <code>eclipselink.tenant-id</code>.</p>
 <div class="example"><a id="BABEHCGI" name="BABEHCGI"></a><a id="TLJPA54008" name="TLJPA54008"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-58 Minimal @Multitenant Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Multitenant
 public class Player  {
 }
 </pre>
 <p>To have your application use a shared <code>EntityManagerFactory</code> and have the <code>EntityManager</code> be tenant specific, your runtime code might be:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 Map&lt;String, Object&gt; emProperties = new HashMap&lt;String, Object&gt;();

 emProperties.set("eclipselink.tenant-id", "HTHL");

 EntityManager em = emf.createEntityManager(emProperties);
 </pre></div>
 <!-- class="example" -->
 <p>Review <a href="#BABICDGI">"Single-Table Multitenancy"</a>, <a href="#BABEGBIJ">"Table-Per-Tenanat Multitenancy"</a>, and <a href="#CHDBFBGI">"VPD Multitenancy"</a> for more detailed examples.</p>
 <a id="BABICDGI" name="BABICDGI"></a><a id="TLJPA709" name="TLJPA709"></a>
 <hr />
 <h3 class="refsect2"><font face="arial, helvetica, sans-serif" color="#330099">Single-Table Multitenancy</font></h3>
 <p>The <code>SINGLE_TABLE</code> multitenant type specifies that any table to which an entity or mapped superclass maps can include rows for multiple tenants. Access to tenant-specific rows is restricted to the tenant.</p>
 <p>Tenant-specific rows are associated with the tenant by using tenant discriminator columns. The discriminator columns are used with application context values to limit what a persistence context can access.</p>
 <p>The results of queries on the mapped tables are limited to the tenant discriminator value(s) provided as property values. This applies to all insert, update, and delete operations on the table. When multitenant metadata is applied at the mapped superclass level, it is applied to all subentities unless they specify their own multitenant metadata.</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 the context of single-table multitenancy, &#8221;single-table&#8221; means multiple tenants can share a single table, and each tenant's data is distinguished from other tenants' data via the discriminator column(s). It is possible to use multiple tables with single-table multitenancy; but in that case, an entity's persisted data is stored in multiple tables (<code>Table</code> and <code>SecondaryTable</code>), and multiple tenants can share all the tables.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <p>For more information how to use tenant discriminator columns to configure single-table multitenancy, see <a href="#CHECIDGH">"@TenantDiscriminatorColumn"</a>.</p>
 <a id="TLJPA710" name="TLJPA710"></a><a id="sthref189" name="sthref189"></a>
 <h4 class="refsect3"><br /><span class="refsubsect">Examples</span></h4>
 <p>The following example uses <code>@Multitenant</code>, <code>@TenantDiscriminatorColumn</code>, and a context property to define single-table multitenancy on an entity:</p>
 <div class="example"><a id="TLJPA711" name="TLJPA711"></a><a id="sthref190" name="sthref190"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-59 Example Using @Multitenant</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Table(name=&#8221;EMP&#8221;)
 @Multitenant(SINGLE_TABLE)
 @TenantDiscriminatorColumn(name = &#8221;TENANT_ID&#8221;,
    contextProperty = "employee-tenant.id")
 </pre></div>
 <!-- class="example" -->
 <p>The following example uses the <code>&lt;multitenant&gt;</code> element to specify a minimal single-table multitenancy. <code>SINGLE_TABLE</code> is the default value and therefore does not have to be specified.</p>
 <div class="example"><a id="TLJPA712" name="TLJPA712"></a><a id="sthref191" name="sthref191"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-60 Example Using &lt;multitenant&gt;</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity class="model.Employee"&gt;
   &lt;multitenant/&gt;
   &lt;table name="EMP"/&gt;
   ...
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="BABEGBIJ" name="BABEGBIJ"></a><a id="TLJPA713" name="TLJPA713"></a>
 <hr />
 <h3 class="refsect2"><font face="arial, helvetica, sans-serif" color="#330099">Table-Per-Tenanat Multitenancy</font></h3>
 <p>The <code>TABLE_PER_TENANT</code> multitenant type specifies that the table(s) (<code>Table</code> and <code>SecondaryTable</code>) for an entity are tenant-specific tables based on the tenant context.. Access to these tables is restricted to the specified tenant. Relationships within an entity that use a join or collection table are also assumed to exist within that context.</p>
 <p>As with other multitenant types, table-per-tenant multitenancy can be specified at the entity or mapped superclass level. At the entity level, a tenant context property must be provided on each entity manager after a transaction has started.</p>
 <p>Table-per-tenant entities can be mixed with other multitenant-type entities within the same persistence unit.</p>
 <p>All read, insert, update, and delete operations for the tenant apply only to the tenant's table(s).</p>
 <p>Tenants share the same server session by default. The table-per-tenant identifier must be set or updated for each entity manager. ID generation is assumed to be unique across all the tenants in a table-per-tenant strategy.</p>
 <p>To configure table-per-tenant multitenancy, you must specify:</p>
 <ul>
 <li>
 <p>A table-per-tenant property to identify the user. This can be set per entity manager, or it can be set at the entity manager factory to isolate table-per-tenant per persistence unit.)</p>
 </li>
 <li>
 <p>A tenant table discriminator to identify and isolate the tenant's tables from other tenants' tables. The discriminator types are <code>SCHEMA</code>, <code>SUFFIX</code>, and <code>PREFIX</code>. For more information about tenant discriminator types, see <a href="#CHDFJJEC">"@TenantTableDiscriminator"</a>.</p>
 </li>
 </ul>
 <a id="TLJPA714" name="TLJPA714"></a><a id="sthref192" name="sthref192"></a>
 <h4 class="refsect3"><br /><span class="refsubsect">Examples</span></h4>
 <p>The following example shows the <code>@Multitenant</code> annotation used to define table-per-tenant multitenancy on an entity. <code>@TenantTableDiscriminator(SCHEMA)</code> specifies that the discriminator table is identified by schema.</p>
 <div class="example"><a id="TLJPA715" name="TLJPA715"></a><a id="sthref193" name="sthref193"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-61 Example Using @Multitenant with @TenantTableDiscriminator</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Table(name=&#8221;EMP&#8221;)
 @Multitenant(TABLE_PER_TENANT)
 @TenantTableDiscriminator(SCHEMA)
 public class Employee {
     ...
 }
 </pre></div>
 <!-- class="example" -->
 <p>The following example shows the <code>&lt;multitenant&gt;</code> element and the <code>&lt;tenant-table-discriminator&gt;</code> elements used to define a minimal table-per-tenant multitenancy.</p>
 <div class="example"><a id="TLJPA716" name="TLJPA716"></a><a id="sthref194" name="sthref194"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-62 Example Using &lt;multitenant&gt; with &lt;tenant-table-discriminator&gt;</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity class="Employee"&gt;
   &lt;multitenant type="TABLE_PER_TENANT"&gt;
     &lt;tenant-table-discriminator type="SCHEMA"/&gt;
   &lt;/multitenant&gt;
   &lt;table name="EMP"&gt;
   ...
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="CHDBFBGI" name="CHDBFBGI"></a><a id="TLJPA717" name="TLJPA717"></a>
 <hr />
 <h3 class="refsect2"><font face="arial, helvetica, sans-serif" color="#330099">VPD Multitenancy</font></h3>
 <p>The <code>VPD</code> (Virtual Private Database) multitanancy type specifies that the database handles the tenant filtering on all SELECT, UPDATE and DELETE queries. To use this type, the platform used with the persistence unit must support VPD.</p>
 <p>To use EclipseLink VPD multitenancy, you must first configure VPD in the database and then specify multitenancy on the entity or mapped superclass, using <code>@Multitenant</code> and <code>@TenantDiscriminatorColumn</code>:</p>
 <a id="TLJPA718" name="TLJPA718"></a><a id="sthref195" name="sthref195"></a>
 <h4 class="refsect3"><br /><span class="refsubsect">Examples</span></h4>
 <p><a href="#CHDIEFCF">Example 2-63</a> shows VPD multitenancy defined on an entity. As noted above, VPD in the database must also be configured to enable VPD multitenancy. In this case, the VPD database was configured to use the USER_ID column to restrict access to specified rows by specified clients. Therefore, <code>USER_ID</code> is also specified as the tenant discriminator column for the EclipseLink multitenant operations.</p>
 <div class="example"><a id="CHDIEFCF" name="CHDIEFCF"></a><a id="TLJPA719" name="TLJPA719"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-63 Example Using @Multitenant(VPD)</font></em></strong></p>
 <p>The following example shows</p>
 <pre xml:space="preserve" class="oac_no_warn">
 </pre></div>
 <!-- class="example" -->
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Multitenant(VPD)
 @TenantDiscriminatorColumn(name = "USER_ID", contextProperty = "tenant.id")
 @Cacheable(false)

 public class Task implements Serializable {
 ...
 ...
 </pre>
 <p>The following example shows...</p>
 <div class="example"><a id="TLJPA720" name="TLJPA720"></a><a id="sthref196" name="sthref196"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-64 Example Using &lt;multitenant&gt;</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity class="model.Employee"&gt;
   &lt;multitenant type="VPD"&gt;
     &lt;tenant-discriminator-column name="USER_ID" context-property="tenant.id"/&gt;
   &lt;/multitenant&gt;
   &lt;table name="EMPLOYEE"/&gt;
   ...
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref197" name="sthref197"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <ul>
 <li>
 <p><a href="#CHECIDGH">"@TenantDiscriminatorColumn"</a></p>
 </li>
 <li>
 <p><a href="#CECBEBEA">"@TenantDiscriminatorColumns"</a></p>
 </li>
 <li>
 <p>"Using Multitenancy" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 <li>
 <p>Multitenant Examples at <code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/Multitenant">http://wiki.eclipse.org/EclipseLink/Examples/JPA/Multitenant</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDIFIJF" name="CHDIFIJF"></a><a id="TLJPA454" name="TLJPA454"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Mutable</font></h2>
 <p>Use <code>@Mutable</code> on a <code>@Basic</code> mapping to specify if the value of a complex field type can be <em>changed</em> (or not changed) instead of being <em>replaced</em>. Mutable mappings may affect the performance of change tracking; attribute change tracking can only be weaved with non-mutable mappings.</p>
 <a id="sthref198" name="sthref198"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDDHGFD">Table 2-33</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA455" name="TLJPA455"></a><a id="sthref199" name="sthref199"></a><a id="CHDDHGFD" name="CHDDHGFD"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-33 @Mutable Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Mutable Annotation Elements" summary="This table describes the elements for the @Mutable 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-t43"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t43"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t43"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t43" headers="r1c1-t43">
 <p><code>boolean value</code></p>
 </td>
 <td align="left" headers="r2c1-t43 r1c2-t43">
 <p>(Optional) Specifies if the mapping is mutable.</p>
 </td>
 <td align="left" headers="r2c1-t43 r1c3-t43">
 <p>true</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref200" name="sthref200"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Most basic types (such as <code>int</code>, <code>long</code>, <code>float</code>, <code>double</code>, <code>String</code>, and <code>BigDecimal</code>) are not mutable.</p>
 <p>By default, <code>Date</code> and <code>Calendar</code> types are assumed to be not mutable. To make these types mutable, use the <code>@Mutable</code> annotation. You can also use the global persistence property <code>eclipselink.temporal.mutable</code> to set the mappings as mutable.</p>
 <p>By default, serialized types are assumed to be mutable. You can set the <code>@Mutable</code> annotation to <code>false</code> to make these types not mutable.</p>
 <p>You can also configure mutable mappings for <code>Date</code> and <code>Calendar</code> fields in the persistence unit in the <code>persistence.xml</code> file.</p>
 <a id="sthref201" name="sthref201"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDDJJEE">Example 2-65</a> shows how to use the <code>@Mutable</code> annotation to specify <code>Employee</code> field <code>hireDate</code>.</p>
 <div class="example"><a id="CHDDJJEE" name="CHDDJJEE"></a><a id="TLJPA456" name="TLJPA456"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-65 Using @Mutable Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 public class Employee implements Serializable {

     ...

     @Temporal(DATE)
     <strong>@Mutable</strong>
     public Calendar getHireDate() {
         return hireDate;
     }

 ..
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDCDIBH">Example 2-66</a> shows how to configure mutable mappings in the persistence unit <code>persistence.xml</code> file or by importing a <code>property</code> map.</p>
 <div class="example"><a id="CHDCDIBH" name="CHDCDIBH"></a><a id="TLJPA457" name="TLJPA457"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-66 Specifying Mutable Mappings in persistence.xml</font></em></strong></p>
 <p>Using <code>persistence.xml</code> file:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>&lt;property name="eclipselink.temporal.mutable" value="true"/&gt;</strong>

 </pre>
 <p>Using <code>property</code> map:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.PersistenceUnitProperties;
 propertiesMap.put(<strong>PersistenceUnitProperties.TEMPORAL_MUTABLE, "false"</strong>);
 </pre></div>
 <!-- class="example" -->
 <a id="sthref202" name="sthref202"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CACFGAIC">"Mapping Annotations"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BGBDHGJE" name="BGBDHGJE"></a><a id="TLJPA458" name="TLJPA458"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@NamedPLSQLStoredFunctionQueries</font></h2>
 <p>Use the <code>@NamedPLSQLStoredFunctionQueries</code> annotation to define multiple <code>NamedPLSQLStoredFunctionQuery</code> items.</p>
 <a id="sthref203" name="sthref203"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CIHJIIDJ2">Table 2-34</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA459" name="TLJPA459"></a><a id="sthref204" name="sthref204"></a><a id="CIHJIIDJ2" name="CIHJIIDJ2"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-34 @NamedPLSQLStoredFunctionQueries Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@NamedPLSQLStoredFunctionQueries Annotation Elements" summary="This table describes the elements for the @NamedPLSQLStoredFunctionQueries annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="31%" />
 <col width="*" />
 <col width="17%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t44"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t44"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t44"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t44" headers="r1c1-t44">
 <p><code>NamedStoredFunctionQuery[]</code></p>
 </td>
 <td align="left" headers="r2c1-t44 r1c2-t44">
 <p>(Required) An array of named stored procedure query</p>
 </td>
 <td align="left" headers="r2c1-t44 r1c3-t44"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref205" name="sthref205"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BGBDHGJE">"@NamedPLSQLStoredFunctionQueries"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDIAEFF" name="CHDIAEFF"></a><a id="TLJPA54056" name="TLJPA54056"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@NamedPLSQLStoredFunctionQuery</font></h2>
 <p>Use the <code>@NamedPLSQLStoredFunctionQuery</code> annotation to define queries that call Oracle PLSQL stored functions as named queries</p>
 <a id="sthref206" name="sthref206"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABCHEIG3">Table 2-36</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA54057" name="TLJPA54057"></a><a id="sthref207" name="sthref207"></a><a id="sthref208" name="sthref208"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-35 @NamedPLSQLStoredFunctionQuery Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@NamedPLSQLStoredFunctionQuery Annotation Elements" summary="This table describes the elements for the @NamedPLSQLStoredFunctionQuery annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="21%" />
 <col width="*" />
 <col width="13%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t45"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t45"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t45"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t45" headers="r1c1-t45">
 <p><code>functionName</code></p>
 </td>
 <td align="left" headers="r2c1-t45 r1c2-t45">
 <p>(Required) The name of the stored function</p>
 </td>
 <td align="left" headers="r2c1-t45 r1c3-t45"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t45" headers="r1c1-t45">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r3c1-t45 r1c2-t45">
 <p>(Required) The unique name that references this stored function query</p>
 </td>
 <td align="left" headers="r3c1-t45 r1c3-t45"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t45" headers="r1c1-t45">
 <p><code>returnParamter</code></p>
 </td>
 <td align="left" headers="r4c1-t45 r1c2-t45">
 <p>(Required) The return value of the stored function</p>
 </td>
 <td align="left" headers="r4c1-t45 r1c3-t45"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t45" headers="r1c1-t45">
 <p><code>hints</code></p>
 </td>
 <td align="left" headers="r5c1-t45 r1c2-t45">
 <p>(Optional) Query hints</p>
 </td>
 <td align="left" headers="r5c1-t45 r1c3-t45"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t45" headers="r1c1-t45">
 <p><code>parameters</code></p>
 </td>
 <td align="left" headers="r6c1-t45 r1c2-t45">
 <p>(Optional) The parameters for the stored function</p>
 </td>
 <td align="left" headers="r6c1-t45 r1c3-t45"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r7c1-t45" headers="r1c1-t45">
 <p><code>resultSetMapping</code></p>
 </td>
 <td align="left" headers="r7c1-t45 r1c2-t45">
 <p>(Optional) The name of the <code>SQLResultMapping</code></p>
 </td>
 <td align="left" headers="r7c1-t45 r1c3-t45"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref209" name="sthref209"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>This annotation adds support for complex PLSQL types such as <code>RECORD</code> and <code>TABLE</code>, that are not accessible from JDBC.</p>
 <p>You can specify <code>@NamedPLSQLStoredFunctionQuery</code> on an Entity or MappedSuperclass.</p>
 <a id="sthref210" name="sthref210"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDICCEF">Example 2-67</a> shows how to use this annotation.</p>
 <div class="example"><a id="CHDICCEF" name="CHDICCEF"></a><a id="TLJPA54058" name="TLJPA54058"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-67 Using @NamedPLSQLStoredFunctionQuery Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>@NamedPLSQLStoredFunctionQuery</strong>(
     name="getEmployee",
     functionName="EMP_PKG.GET_EMP",
     returnParameter=@PLSQLParameter(
         name="RESULT",
         databaseType="EMP_PKG.EMP_TABLE"
     )
 )
 @Embeddable
 @Struct(name="EMP_TYPE", fields={"F_NAME", "L_NAME", "SALARY"})
 @PLSQLRecord(
     name="EMP_PKG.EMP_REC",
     compatibleType="EMP_TYPE",
     javaType=Employee.class,
     fields={
         @PLSQLParameter(name="F_NAME"),
         @PLSQLParameter(name="L_NAME"),
         @PLSQLParameter(
             name="SALARY",
             databaseType="NUMERIC_TYPE"
         )
     }
 )

 public class Employee { ...}
 </pre></div>
 <!-- class="example" -->
 <a id="sthref211" name="sthref211"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>Oracle PL/SQL<br />
 <code><a href="http://www.oracle.com/technetwork/database/features/plsql/index.html">http://www.oracle.com/technetwork/database/features/plsql/index.html</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABJCEJH3" name="BABJCEJH3"></a><a id="TLJPA465" name="TLJPA465"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@NamedPLSQLStoredProcedureQueries</font></h2>
 <p>Use the <code>@NamedPLSQLStoredProcedureQueries</code> annotation to define multiple <code>NamedPLSQLStoredProcedureQuery</code> items.</p>
 <a id="sthref212" name="sthref212"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABCHEIG3">Table 2-36</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA466" name="TLJPA466"></a><a id="sthref213" name="sthref213"></a><a id="BABCHEIG3" name="BABCHEIG3"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-36 @NamedPLSQLStoredProcedureQueries Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@NamedPLSQLStoredProcedureQueries Annotation Elements" summary="This table describes the elements for the @NamedPLSQLStoredProcedureQueries annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="17%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t46"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t46"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t46"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t46" headers="r1c1-t46">
 <p><code>value</code></p>
 </td>
 <td align="left" headers="r2c1-t46 r1c2-t46">
 <p>(Required) An array of named stored procedure query</p>
 </td>
 <td align="left" headers="r2c1-t46 r1c3-t46"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref214" name="sthref214"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABFCGCE">Example 2-68</a> shows how to use this annotation.</p>
 <div class="example"><a id="BABFCGCE" name="BABFCGCE"></a><a id="TLJPA467" name="TLJPA467"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-68 Using @NamedPLSQLStoredProcedureQueries Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @NamedPLSQLStoredProcedureQueries({
     @NamedPLSQLStoredProcedureQuery(name="getEmployee",
     functionName="EMP_PKG.GET_EMP",
     parameters={ @PLSQLParameter( name="EMP_OUT", direction=:Direction.OUT, databaseType="EMP_PKG.EMP_REC") } )
     })
 </pre></div>
 <!-- class="example" -->
 <a id="sthref215" name="sthref215"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BGBDHGJE2">"@NamedPLSQLStoredProcedureQuery"</a></p>
 </li>
 <li>
 <p>"Stored Procedures" in <em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p>Oracle PL/SQL <code><a href="http://www.oracle.com/technetwork/database/features/plsql/index.html">http://www.oracle.com/technetwork/database/features/plsql/index.html</a></code></p>
 </li>
 <li>
 <p>PLSQL Stored Procedure Examples<code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/PLSQLStoredFunction">http://wiki.eclipse.org/EclipseLink/Examples/JPA/PLSQLStoredFunction</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BGBDHGJE2" name="BGBDHGJE2"></a><a id="TLJPA54012" name="TLJPA54012"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@NamedPLSQLStoredProcedureQuery</font></h2>
 <p>Use the <code>@NamedPLSQLStoredProcedureQuery</code> annotation to define queries that call Oracle PLSQL stored procedures as named queries.</p>
 <a id="sthref216" name="sthref216"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BGBEAJEH2">Table 2-37</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA54013" name="TLJPA54013"></a><a id="sthref217" name="sthref217"></a><a id="BGBEAJEH2" name="BGBEAJEH2"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-37 @NamedPLSQLStoredProcedureQuery Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@NamedPLSQLStoredProcedureQuery Annotation Elements" summary="This table describes the elements for the @NamedPLSQLStoredProcedureQuery annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="21%" />
 <col width="*" />
 <col width="13%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t47"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t47"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t47"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t47" headers="r1c1-t47">
 <p><code>procedureName</code></p>
 </td>
 <td align="left" headers="r2c1-t47 r1c2-t47">
 <p>(Required) The name of the stored procedure</p>
 </td>
 <td align="left" headers="r2c1-t47 r1c3-t47"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t47" headers="r1c1-t47">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r3c1-t47 r1c2-t47">
 <p>(Required) The unique name that references this stored procedure query</p>
 </td>
 <td align="left" headers="r3c1-t47 r1c3-t47"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t47" headers="r1c1-t47">
 <p><code>resultClass</code></p>
 </td>
 <td align="left" headers="r4c1-t47 r1c2-t47">
 <p>(Optional) The class of the result</p>
 </td>
 <td align="left" headers="r4c1-t47 r1c3-t47"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t47" headers="r1c1-t47">
 <p><code>hints</code></p>
 </td>
 <td align="left" headers="r5c1-t47 r1c2-t47">
 <p>(Optional) Query hints</p>
 </td>
 <td align="left" headers="r5c1-t47 r1c3-t47"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t47" headers="r1c1-t47">
 <p><code>parameters</code></p>
 </td>
 <td align="left" headers="r6c1-t47 r1c2-t47">
 <p>(Optional) The parameters for the stored procedure</p>
 </td>
 <td align="left" headers="r6c1-t47 r1c3-t47"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r7c1-t47" headers="r1c1-t47">
 <p><code>resultSetMapping</code></p>
 </td>
 <td align="left" headers="r7c1-t47 r1c2-t47">
 <p>(Optional) The name of the <code>SQLResultMapping</code></p>
 </td>
 <td align="left" headers="r7c1-t47 r1c3-t47"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref218" name="sthref218"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>This annotation adds support for complex PLSQL types such as <code>RECORD</code> and <code>TABLE</code>, that are not accessible from JDBC.</p>
 <p>You can specify <code>@NamedPLSQLStoredProcedureQuery</code> on an Entity, Embeddable, or MappedSuperclass.</p>
 <a id="sthref219" name="sthref219"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BGBICFEB2">Example 2-69</a> shows how to use this annotation.</p>
 <div class="example"><a id="BGBICFEB2" name="BGBICFEB2"></a><a id="TLJPA54014" name="TLJPA54014"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-69 Using @NamedPLSQLStoredProcedureQuery Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @NamedPLSQLStoredProcedureQuery(
     name="getEmployee",
     procedureName="MyStoredProcedure",
     functionName="EMP_PKG.GET_EMP",
     parameters={
         @PLSQLParameter(
             name="EMP_OUT",
             direction=Direction.OUT,
             databaseType="EMP_PKG.EMP_REC"
         )
     }
 )
 @Embeddable
 @Struct(name="EMP_TYPE", fields={"F_NAME", "L_NAME", "SALARY"})
 @OracleObject(
     name="EMP_PKG.EMP_REC",
     compatibleType="EMP_TYPE",
     javaType=Employee.class,
     fields={
         @PLSQLParameter(name="F_NAME"),
         @PLSQLParameter(name="L_NAME"),
         @PLSQLParameter(
             name="SALARY",
             databaseType="NUMERIC_TYPE"
         )
     }
 )

 public class Employee { ...}
 </pre></div>
 <!-- class="example" -->
 <a id="sthref220" name="sthref220"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Stored Procedures" in <em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p>Oracle PL/SQL <code><a href="http://www.oracle.com/technetwork/database/features/plsql/index.html">http://www.oracle.com/technetwork/database/features/plsql/index.html</a></code></p>
 </li>
 <li>
 <p>PLSQL Stored Procedure Examples<code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/PLSQLStoredFunction">http://wiki.eclipse.org/EclipseLink/Examples/JPA/PLSQLStoredFunction</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CIHJFFDI" name="CIHJFFDI"></a><a id="TLJPA54015" name="TLJPA54015"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@NamedStoredFunctionQueries</font></h2>
 <p>Use the <code>@NamedStoredFunctionQueries</code> annotation to define multiple <code>NamedStoredFunctionQuery</code> items.</p>
 <a id="sthref221" name="sthref221"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CIHJIIDJ">Table 2-38</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA54016" name="TLJPA54016"></a><a id="sthref222" name="sthref222"></a><a id="CIHJIIDJ" name="CIHJIIDJ"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-38 @NamedStoredFunctionQueries Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@NamedStoredFunctionQueries Annotation Elements" summary="This table describes the annotations for the @NamedStoredFunctionQueries annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="31%" />
 <col width="*" />
 <col width="17%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t48"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t48"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t48"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t48" headers="r1c1-t48">
 <p><code>NamedStoredFunctionQuery[]</code></p>
 </td>
 <td align="left" headers="r2c1-t48 r1c2-t48">
 <p>(Required) An array of named stored procedure query</p>
 </td>
 <td align="left" headers="r2c1-t48 r1c3-t48"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref223" name="sthref223"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CIHBJIHJ">Example 2-70</a> shows how to use this annotation.</p>
 <div class="example"><a id="CIHBJIHJ" name="CIHBJIHJ"></a><a id="TLJPA54017" name="TLJPA54017"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-70 Using @NamedStoredFunctionQueries Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>@NamedStoredFunctionQueries</strong>{(
     @NamedStoredFunctionQuery(
         name="StoredFunction_In",
         functionName="StoredFunction_In",
         parameters={
             @StoredProcedureParameter(direction=IN, name="P_IN", queryParameter="P_IN", type=Long.class)
         },
         returnParameter=@StoredProcedureParameter(queryParameter="RETURN", type=Long.class)
     )
 )}
 </pre></div>
 <!-- class="example" -->
 <p>To define multiple named stored procedures in the <code>eclipselink-orm.xml</code> file, create a list of multiple <code>&lt;named-stored-function_query&gt;</code> elements.</p>
 <a id="sthref224" name="sthref224"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BABFBIFE">"@NamedStoredFunctionQuery"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABFBIFE" name="BABFBIFE"></a><a id="TLJPA461" name="TLJPA461"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@NamedStoredFunctionQuery</font></h2>
 <p>Use <code>@NamedStoredFunctionQuery</code> to define queries that call stored functions as named queries.</p>
 <a id="sthref225" name="sthref225"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABFFDDG">Table 2-39</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA462" name="TLJPA462"></a><a id="sthref226" name="sthref226"></a><a id="BABFFDDG" name="BABFFDDG"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-39 @NamedStoredFunctionQuery Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@NamedStoredFunctionQuery Annotation Elements" summary="This table describes the elements for the @NamedStoredFunctionQuery annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="21%" />
 <col width="*" />
 <col width="13%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t49"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t49"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t49"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t49" headers="r1c1-t49">
 <p><code>functionName</code></p>
 </td>
 <td align="left" headers="r2c1-t49 r1c2-t49">
 <p>(Required) The name of the stored function</p>
 </td>
 <td align="left" headers="r2c1-t49 r1c3-t49"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t49" headers="r1c1-t49">
 <p>name</p>
 </td>
 <td align="left" headers="r3c1-t49 r1c2-t49">
 <p>(Required) The unique name that references this stored function query</p>
 </td>
 <td align="left" headers="r3c1-t49 r1c3-t49"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t49" headers="r1c1-t49">
 <p><code>returnParamter</code></p>
 </td>
 <td align="left" headers="r4c1-t49 r1c2-t49">
 <p>(Required) The return value of the stored function</p>
 </td>
 <td align="left" headers="r4c1-t49 r1c3-t49"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t49" headers="r1c1-t49">
 <p><code>callByIndex</code></p>
 </td>
 <td align="left" headers="r5c1-t49 r1c2-t49">
 <p>(Optional) Specifies if the stored function should be called by <strong>index</strong> or by <strong>name</strong>.</p>
 <ul>
 <li>
 <p>If by index, the parameters must be defined in the same order as the procedure on the database.</p>
 </li>
 <li>
 <p>If by name, you must use the database platform support naming procedure parameters.</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r5c1-t49 r1c3-t49">
 <p>false</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t49" headers="r1c1-t49">
 <p><code>hints</code></p>
 </td>
 <td align="left" headers="r6c1-t49 r1c2-t49">
 <p>(Optional) Query hints</p>
 </td>
 <td align="left" headers="r6c1-t49 r1c3-t49"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r7c1-t49" headers="r1c1-t49">
 <p><code>parameters</code></p>
 </td>
 <td align="left" headers="r7c1-t49 r1c2-t49">
 <p>(Optional) The parameters for the stored function</p>
 </td>
 <td align="left" headers="r7c1-t49 r1c3-t49"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r8c1-t49" headers="r1c1-t49">
 <p><code>resultSetMapping</code></p>
 </td>
 <td align="left" headers="r8c1-t49 r1c2-t49">
 <p>(Optional) The name of the SQLResultMapping</p>
 </td>
 <td align="left" headers="r8c1-t49 r1c3-t49"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref227" name="sthref227"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You can specify <code>@NamedStoredFunctionQuery</code> on an Entity or MappedSuperclass.</p>
 <a id="sthref228" name="sthref228"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABHABEG">Example 2-71</a> shows how to use this annotation.</p>
 <div class="example"><a id="BABHABEG" name="BABHABEG"></a><a id="TLJPA463" name="TLJPA463"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-71 Using @NamedStoredFunctionQuery Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Table(name="CMP3_ADDRESS")

 <strong>@NamedStoredFunctionQuery</strong>(
   name="StoredFunction_In",
   functionName="StoredFunction_In",
   parameters={
     @StoredProcedureParameter(direction=IN, name="P_IN", queryParameter="P_IN", type=Long.class)
     },
   returnParameter=@StoredProcedureParameter(queryParameter="RETURN", type=Long.class)
   )
 public class Address implements Serializable {
 ...
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BABGJGJJ">Example 2-72</a> shows how to use the <code>&lt;named-stored-function-query&gt;</code> element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="BABGJGJJ" name="BABGJGJJ"></a><a id="TLJPA464" name="TLJPA464"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-72 Using &lt;named-stored-function-query&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;<strong>named-stored-function-query</strong> name="StoredFunction_In" procedure-name="StoredFunction_In"&gt;
     &lt;parameter direction="IN" name="P_IN" query-parameter="P_IN" type="Long"/&gt;
 &lt;/named-stored-function-query&gt;

 </pre></div>
 <!-- class="example" -->
 <a id="sthref229" name="sthref229"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CIHJFFDI">"@NamedStoredFunctionQueries"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABJCEJH" name="BABJCEJH"></a><a id="TLJPA54018" name="TLJPA54018"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@NamedStoredProcedureQueries</font></h2>
 <p>Use the <code>@NamedStoredProcedureQueries</code> annotation to define multiple <code>NamedStoredProcedureQuery</code> items.</p>
 <a id="sthref230" name="sthref230"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABCHEIG">Table 2-40</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA54019" name="TLJPA54019"></a><a id="sthref231" name="sthref231"></a><a id="BABCHEIG" name="BABCHEIG"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-40 @NamedStoredProcedureQueries Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@NamedStoredProcedureQueries Annotation Elements" summary="This table describes the elements for the @NamedStoredProcedureQueries annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="17%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t50"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t50"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t50"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t50" headers="r1c1-t50">
 <p><code>value</code></p>
 </td>
 <td align="left" headers="r2c1-t50 r1c2-t50">
 <p>(Required) An array of named stored procedure query</p>
 </td>
 <td align="left" headers="r2c1-t50 r1c3-t50"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref232" name="sthref232"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABIFCAJ">Example 2-73</a> shows how to use this annotation.</p>
 <div class="example"><a id="BABIFCAJ" name="BABIFCAJ"></a><a id="TLJPA54020" name="TLJPA54020"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-73 Using @NamedStoredProcedureQueries Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Table(name="EMPLOYEE")
 <strong>@NamedStoredProcedureQueries</strong>({
   @NamedStoredProcedureQuery(
     name="ReadEmployeeInOut",
      resultClass=org.eclipse.persistence.testing.models.jpa.customfeatures.Employee.class,
     procedureName="Read_Employee_InOut",
     parameters={
       @StoredProcedureParameter(direction=IN_OUT, name="employee_id_v", queryParameter="ID", type=Integer.class),
       @StoredProcedureParameter(direction=OUT, name="nchar_v", queryParameter="NCHARTYPE", type=Character.class)}
     ),
     @NamedStoredProcedureQuery(
       name="ReadEmployeeCursor",
       resultClass=org.eclipse.persistence.testing.models.jpa.customfeatures.Employee.class,
       procedureName="Read_Employee_Cursor",
       parameters={
         @StoredProcedureParameter(direction=IN, name="employee_id_v", queryParameter="ID", type=Integer.class),
         @StoredProcedureParameter(direction=OUT_CURSOR, queryParameter="RESULT_CURSOR")})
 })
 public class Employee implements Serializable {
 </pre></div>
 <!-- class="example" -->
 <p>To define multiple named stored procedure queries in the <code>eclipselink-orm.xml</code> file, simply create a list of multiple <code>&lt;named-stored-procedure_query&gt;</code> elements.</p>
 <a id="sthref233" name="sthref233"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BGBGAEFF">"@NamedStoredProcedureQuery"</a></p>
 </li>
 <li>
 <p>"Stored Procedures" in <em>Understanding EclipseLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BGBGAEFF" name="BGBGAEFF"></a><a id="TLJPA468" name="TLJPA468"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@NamedStoredProcedureQuery</font></h2>
 <p>Use the <code>@NamedStoredProcedureQuery</code> annotation to define queries that call stored procedures as named queries.</p>
 <a id="sthref234" name="sthref234"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BGBHHIAB">Table 2-41</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA469" name="TLJPA469"></a><a id="sthref235" name="sthref235"></a><a id="BGBHHIAB" name="BGBHHIAB"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-41 @NamedStoredProcedureQuery Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@NamedStoredProcedureQuery Annotation Elements" summary="This table describes the elements for the @NamedStoredProcedureQuery annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="24%" />
 <col width="*" />
 <col width="16%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t51"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t51"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t51"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t51" headers="r1c1-t51">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t51 r1c2-t51">
 <p>(Required) Unique name that references this stored procedure query</p>
 </td>
 <td align="left" headers="r2c1-t51 r1c3-t51"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t51" headers="r1c1-t51">
 <p><code>procedureName</code></p>
 </td>
 <td align="left" headers="r3c1-t51 r1c2-t51">
 <p>(Required) Name of the stored procedure</p>
 </td>
 <td align="left" headers="r3c1-t51 r1c3-t51"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t51" headers="r1c1-t51">
 <p><code>callByIndex</code></p>
 </td>
 <td align="left" headers="r4c1-t51 r1c2-t51">
 <p>(Optional) Specifies if the stored procedure should be called by name.</p>
 <ul>
 <li>
 <p>If <strong>true</strong>, the StoredProcedureParameters must be defined in the same order as the procedure on the database.</p>
 </li>
 <li>
 <p>If <strong>false</strong>, the database platform must support naming procedure parameters.</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r4c1-t51 r1c3-t51">
 <p><code>false</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t51" headers="r1c1-t51">
 <p><code>hints</code></p>
 </td>
 <td align="left" headers="r5c1-t51 r1c2-t51">
 <p>(Optional) An array of query hints</p>
 </td>
 <td align="left" headers="r5c1-t51 r1c3-t51"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t51" headers="r1c1-t51">
 <p><code>multipleResultSets</code></p>
 </td>
 <td align="left" headers="r6c1-t51 r1c2-t51">
 <p>(Optional) Specifies if the stored procedure returns multiple result sets.</p>
 <p>This applies only for databases that support multiple result sets from stored procedures.</p>
 </td>
 <td align="left" headers="r6c1-t51 r1c3-t51">
 <p><code>false</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r7c1-t51" headers="r1c1-t51">
 <p><code>parameters</code></p>
 </td>
 <td align="left" headers="r7c1-t51 r1c2-t51">
 <p>(Optional) An array of parameters for the stored procedure</p>
 </td>
 <td align="left" headers="r7c1-t51 r1c3-t51"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r8c1-t51" headers="r1c1-t51">
 <p><code>resultClass</code></p>
 </td>
 <td align="left" headers="r8c1-t51 r1c2-t51">
 <p>(Optional) The class of the result</p>
 </td>
 <td align="left" headers="r8c1-t51 r1c3-t51">
 <p><code>void.class</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r9c1-t51" headers="r1c1-t51">
 <p><code>resultSetMapping</code></p>
 </td>
 <td align="left" headers="r9c1-t51 r1c2-t51">
 <p>(Optional) Name of the <code>SQLResultMapping</code></p>
 </td>
 <td align="left" headers="r9c1-t51 r1c3-t51"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r10c1-t51" headers="r1c1-t51">
 <p><code>returnsResultSet</code></p>
 </td>
 <td align="left" headers="r10c1-t51 r1c2-t51">
 <p>(Optional) Specifies if the stored procedure retainers a result set.</p>
 <p>This applies only for databases that support result sets from stored procedures.</p>
 </td>
 <td align="left" headers="r10c1-t51 r1c3-t51">
 <p><code>false</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref236" name="sthref236"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You can specify <code>@NamedStoredProcedureQuery</code> on an Entity or MappedSuper class.</p>
 <a id="sthref237" name="sthref237"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BGBJBAFD">Example 2-74</a> shows how to use <code>@NamedStoredProcedureQuery</code> to define a stored procedure.</p>
 <div class="example"><a id="BGBJBAFD" name="BGBJBAFD"></a><a id="TLJPA470" name="TLJPA470"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-74 Using @NamedStoredProcedureQuery Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @<strong>NamedStoredProcedureQuery</strong>(name="findAllEmployees", procedureName="EMP_READ_ALL", resultClass=Employee.class, parameters={
     @StoredProcedureParameter(queryParameter="result", name="RESULT_CURSOR", direction=Direction.OUT_CURSOR})
 @Entity
 public class Employee {
  ...
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BGBIHIHB">Example 2-75</a> shows how to use the <code>&lt;named-stored-procedure-query&gt;</code> element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="BGBIHIHB" name="BGBIHIHB"></a><a id="TLJPA471" name="TLJPA471"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-75 Using &lt;named-stored-procedure-query&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;<strong>named-stored-procedure-query</strong> name="SProcXMLInOut" result-class="Address" procedure-name="SProc_Read_XMLInOut"&gt;
     &lt;parameter direction="IN_OUT" name="address_id_v" query-parameter="ADDRESS_ID" type="Long"/&gt;
     &lt;parameter direction="OUT" name="street_v" query-parameter="STREET" type="String"/&gt;
 &lt;/named-stored-procedure-query&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref238" name="sthref238"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BABJCEJH">"@NamedStoredProcedureQueries"</a></p>
 </li>
 <li>
 <p>"Stored Procedures" in <em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p>"Stored Procedures Examples" <code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/StoredProcedures">http://wiki.eclipse.org/EclipseLink/Examples/JPA/StoredProcedures</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDGEFGD" name="CHDGEFGD"></a><a id="TLJPA472" name="TLJPA472"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Noncacheable</font></h2>
 <p>Use <code>@Noncacheable</code> to configure caching behavior for relationships. If used on a relationship, that relationship <em>will not</em> be cached, even though the parent Entity may be cached.</p>
 <a id="sthref239" name="sthref239"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p>There are no elements for this annotation.</p>
 <a id="sthref240" name="sthref240"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Each time EclipseLink retrieves the Entity, the relationship will be reloaded from the datasource. This may be useful for situations where caching of relationships is not desired or when using different EclipseLink cache types and having cached references extends the cache lifetime of related Entities using a different caching scheme. For instance Entity A references Entity B, Entity A is Full and Entity B is Weak. Without removing the caching of the relationsip the Entity B's cache effectively become Full.</p>
 <a id="sthref241" name="sthref241"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDDEGCI">Example 2-76</a> shows how to use <code>@Noncacheable</code> to create a protected cache.</p>
 <div class="example"><a id="CHDDEGCI" name="CHDDEGCI"></a><a id="TLJPA473" name="TLJPA473"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-76 Using @Noncacheable Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Cache(
   isolation=CacheIsolationType.PROTECTED
 )
 public class Employee {
   @Id
   private long id;
   ...
   @OneToMany(mappedBy="manager")
   <strong>@Noncacheable</strong>
   private List&lt;Employee&gt; managedEmployees;
   ...
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDDFJCH">Example 2-77</a> shows using the <code>&lt;noncacheable&gt;</code> XML element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="CHDDFJCH" name="CHDDFJCH"></a><a id="TLJPA474" name="TLJPA474"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-77 Using &lt;noncacheable&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;
         &lt;cache isolation="PROTECTED"/&gt;
         &lt;attributes&gt;
             &lt;id name= "id"/&gt;
             &lt;one-to-many name="managedEmployees" mapped-by="manager"&gt;
                 <strong>&lt;noncacheable/&gt;</strong>
             &lt;/one-to-many&gt;
         &lt;/attributes&gt;
     &lt;/entity&gt;
 &lt;/entity-mappings
 </pre></div>
 <!-- class="example" -->
 <a id="sthref242" name="sthref242"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Caching"<code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching</a></code></p>
 </li>
 <li>
 <p>"EclipseLink Caches" in <em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p>"Scaling EclipseLink Applications in Clusters" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BJEIEBHC" name="BJEIEBHC"></a><a id="TLJPA475" name="TLJPA475"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@NoSql</font></h2>
 <p>Use <code>@NoSql</code> to specify a non-relational (that is, no SQL) data source. EclipseLink can map non-relational data to objects and access that data through JPA.</p>
 <a id="sthref243" name="sthref243"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BJEBBCFE">Table 2-42</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA476" name="TLJPA476"></a><a id="sthref244" name="sthref244"></a><a id="BJEBBCFE" name="BJEBBCFE"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-42 @NoSql Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@NoSql Annotation Elements" summary="This table describes the elements for the @NoSQL 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-t52"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t52"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t52"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t52" headers="r1c1-t52">
 <p><code>dataType</code></p>
 </td>
 <td align="left" headers="r2c1-t52 r1c2-t52">
 <p>The name of the entities structure. The purpose of the <code>dataType</code> depends on the NoSQL platform used:</p>
 <ul>
 <li>
 <p>For MongoDB, it is the collection name that the JSON documents are stored to.</p>
 </li>
 <li>
 <p>For Oracle NoSQL, it is the first part of the major key value.</p>
 </li>
 <li>
 <p>For XML files, it is the file name. and XML messaging, use <code>XML</code>.</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r2c1-t52 r1c3-t52"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t52" headers="r1c1-t52">
 <p><code>dataFormat</code></p>
 </td>
 <td align="left" headers="r3c1-t52 r1c2-t52">
 <p>(Optional) The type structure (data format) in which the data is stored within the database:</p>
 <ul>
 <li>
 <p><code>INDEXED</code> &#8211; Maps a class to an array of values.</p>
 </li>
 <li>
 <p><code>MAPPED</code> &#8211; Maps a class to a set of nested key/value pairs, a value can be an embedded map or list.</p>
 <p>Use to map to key/value stores, JSON databases, and other structured data systems.</p>
 </li>
 <li>
 <p><code>XML</code> &#8211; Maps a class to an XML document.</p>
 <p>Use with XML data-stores, XML files, XML messaging systems, and other XML systems.</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r3c1-t52 r1c3-t52">
 <p>XML</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref245" name="sthref245"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>The <code>dataFormat</code> depends on the NoSQL platform used:</p>
 <ul>
 <li>
 <p>For MongoDB, use <code>MAPPED</code>.</p>
 </li>
 <li>
 <p>For Oracle NoSQL, use <code>MAPPED</code> (for key/value data) or <code>XML</code> (for a single XML document).</p>
 </li>
 <li>
 <p>For XML files and XML messaging, use <code>XML</code>.</p>
 </li>
 </ul>
 <a id="TLJPA721" name="TLJPA721"></a>
 <p><b><font face="arial, helvetica, sans-serif" color="#330099">Supported Datasources</font></b></p>
 <p>EclipseLink supports several NoSQL and EIS platforms, as well as generic NoSQL and EIS datasources through the JavaEE Connector Architecture CCI (Common Client Interface) API. You can also define your own <code>EISPlatform</code> subclass and JCA adapter</p>
 <p>EclipseLink supports the following datasources:</p>
 <ul>
 <li>
 <p>MongoDB</p>
 </li>
 <li>
 <p>Oracle NoSQL</p>
 </li>
 <li>
 <p>XML Files</p>
 </li>
 <li>
 <p>JMS</p>
 </li>
 <li>
 <p>Oracle AQ</p>
 </li>
 </ul>
 <a id="sthref246" name="sthref246"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BJECFBJG">Example 2-78</a> shows using <code>@NoSql</code> with an XML data source.</p>
 <div class="example"><a id="BJECFBJG" name="BJECFBJG"></a><a id="TLJPA477" name="TLJPA477"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-78 Using @NoSql Annotation with XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 <strong>@NoSql</strong><strong>(dataType="order")</strong>
 public class Order {
   @Id
   @GeneratedValue
   @Field(name="@id")
   private long id;
   @Basic
   @Field(name="@description")
   private String description;
   @Embedded
   @Field(name="delivery-address")
   private Address deliveryAddress
   @ElementCollection
   @Field(name="orderLines/order-line")
   private List&lt;OrderLine&gt; orderLines;
   @ManyToOne
   @JoinField(name="customer-id")
   private Customer customer;
 }

 @Embeddable
 <strong>@NoSql</strong>
 public class OrderLine {
     @Field(name="@line-number")
     private int lineNumber;
     @Field(name="@item-name")
     private String itemName;
     @Field(name="@quantity")
     private int quantity;
 }
 </pre>
 <p>This would produce the following XML data:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;order id="4F99702B271B1948027FAF06" description="widget order"&gt;
   &lt;deliveryAddress street="1712 Hasting Street" city="Ottawa" province="ON" postalCode="L5J1H5"/&gt;
   &lt;order-lines&gt;
       &lt;order-line lineNumber="1" itemName="widget A" quantity="5"/&gt;
       &lt;order-line lineNumber="2" itemName="widget B" quantity="1"/&gt;
       &lt;order-line lineNumber="3" itemName="widget C" quantity="2"/&gt;
   &lt;order-lines&gt;
   &lt;customer-id&gt;4F99702B271B1948027FAF08&lt;/customer-id&gt;
 &lt;order&gt;
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BJECHGJH">Example 2-79</a> shows using <code>@NoSql</code> with a JSON data source.</p>
 <div class="example"><a id="BJECHGJH" name="BJECHGJH"></a><a id="TLJPA722" name="TLJPA722"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-79 Using @NoSql Annotation with JSON</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 <strong>@NoSql(dataType="orders", dataFormat=DataFormatType.MAPPED)</strong>
 public class Order {
   @Id
   @GeneratedValue
   @Field(name="_id")
   private long id;
   @Basic
   @Field(name="description")
   private String description;
   @Embedded
   @Field(name="deliveryAddress")
   private Address deliveryAddress
   @ElementCollection
   @Field(name="orderLines")
   private List&lt;OrderLine&gt; orderLines;
   @ManyToOne
   @JoinField(name="customerId")
   private Customer customer;
 }

 @Embeddable
 <strong>@NoSql(dataFormat=DataFormatType.MAPPED)</strong>
 public class OrderLine {
     @Field(name="lineNumber")
     private int lineNumber;
     @Field(name="itemName")
     private String itemName;
     @Field(name="quantity")
     private int quantity;
 }
 </pre>
 <p>This would produce the following JSON document:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 {
   "_id": "4F99702B271B1948027FAF06",
   "description": "widget order",
   "deliveryAddress": {
       "street": "1712 Hasting Street",
       "city": "Ottawa",
       "province": "ON",
       "postalCode": "L5J1H5",
   },
   "orderLines": [
       {"lineNumber": "1", "itemName": "widget A", "quantity": "5"},
       {"lineNumber": "2", "itemName": "widget B", "quantity": "1"},
       {"lineNumber": "3", "itemName": "widget C", "quantity": "2"}
   ],
   "customerId": "4F99702B271B1948027FAF08",
 }
 </pre></div>
 <!-- class="example" -->
 <a id="sthref247" name="sthref247"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>@NoSQL <code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/NoSQL">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/NoSQL</a></code></p>
 </li>
 <li>
 <p>NoSQL Persistence Units <code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/NoSQL/Persistence_Units">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/NoSQL/Persistence_Units</a></code></p>
 </li>
 <li>
 <p>Examples <code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/NoSQL">http://wiki.eclipse.org/EclipseLink/Examples/JPA/NoSQL</a></code></p>
 </li>
 <li>
 <p><em>Oracle Coherence Integration Guide for EclipseLink with Coherence Grid</em></p>
 </li>
 <li>
 <p>"Using Non-SQL Databases" in <em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p>"Using NoSQL Databases" in <em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p>"Using EclipseLink with Nonrelational Databases" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 <li>
 <p><a href="persistenceproperties_ref.htm#BABJAJAI">"nosql.property"</a></p>
 </li>
 <li>
 <p>EclipseLink Platform Incubator <code><a href="http://wiki.eclipse.org/EclipseLink/Development/Incubator/Platform">http://wiki.eclipse.org/EclipseLink/Development/Incubator/Platform</a></code></p>
 </li>
 <li>
 <p>Supported NoSQL and EIS Datasources <code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/NoSQL/Supported_Data-sources">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/NoSQL/Supported_Data-sources</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BGBBDGAI" name="BGBBDGAI"></a><a id="TLJPA478" name="TLJPA478"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@ObjectTypeConverter</font></h2>
 <p>The <code>@ObjectTypeConverter</code> annotation specifies an <code>org.eclipse.persistence.mappings.converters.ObjectTypeConverter</code> that converts a fixed number of database data value(s) to Java object value(s) during the reading and writing of a mapped attribute.</p>
 <a id="sthref248" name="sthref248"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BGBDHDHC">Table 2-43</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA479" name="TLJPA479"></a><a id="sthref249" name="sthref249"></a><a id="BGBDHDHC" name="BGBDHDHC"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-43 @ObjectTypeConverter Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@ObjectTypeConverter Annotation Elements" summary="This table describes the elements for the @ObjectTypeConverter 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-t53"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t53"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t53"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t53" headers="r1c1-t53">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t53 r1c2-t53">
 <p>Set this attribute to the <code>String</code> name for your converter. Ensure that this name is unique across the persistence unit.</p>
 </td>
 <td align="left" headers="r2c1-t53 r1c3-t53">
 <p>none</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t53" headers="r1c1-t53">
 <p><code>dataType</code></p>
 </td>
 <td align="left" headers="r3c1-t53 r1c2-t53">
 <p>(Optional) Set this attribute to the type stored in the database.</p>
 </td>
 <td align="left" headers="r3c1-t53 r1c3-t53">
 <p><code>void.class</code><a id="CEGCJGHC" name="CEGCJGHC" href="#CEGCJGHC" onclick='footdisplay(1,"The default is inferred from the type of the persistence field or property.")'><sup><font size="-3">Foot&nbsp;</font>1&nbsp;</sup></a></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t53" headers="r1c1-t53">
 <p><code>objectType</code></p>
 </td>
 <td align="left" headers="r4c1-t53 r1c2-t53">
 <p>(Optional) Set the value of this attribute to the type stored on the entity.</p>
 </td>
 <td align="left" headers="r4c1-t53 r1c3-t53">
 <p><code>void.class</code><a id="sthref250" name="sthref250" href="#sthref250" onclick='footdisplay(1,"The default is inferred from the type of the persistence field or property.")'><sup><font size="-3">Footref&nbsp;</font>1</sup></a></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t53" headers="r1c1-t53">
 <p><code>conversionValues</code></p>
 </td>
 <td align="left" headers="r5c1-t53 r1c2-t53">
 <p>Set the value of this attribute to the array of conversion values (instances of <code>ConversionValue: String objectValue</code> and <code>String dataValue</code>).</p>
 </td>
 <td align="left" headers="r5c1-t53 r1c3-t53">
 <p>none</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t53" headers="r1c1-t53">
 <p><code>defaultObjectValue</code></p>
 </td>
 <td align="left" headers="r6c1-t53 r1c2-t53">
 <p>Set the value of this attribute to the default object value. Note that this argument is for dealing with legacy data if the data value is missing.</p>
 </td>
 <td align="left" headers="r6c1-t53 r1c3-t53">
 <p>Empty <code>String</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <font size="-1"><sup><font size="1">Footnote&nbsp;</font>1&nbsp;</sup>The default is inferred from the type of the persistence field or property.<br /></font><a id="sthref251" name="sthref251"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>EclipseLink also includes <code><a href="#CHDHCCJF">@TypeConverter</a></code> and <code><a href="#BGBJEBBB">@StructConverter</a></code> converters.</p>
 <a id="sthref252" name="sthref252"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BGBFDFEJ">Example 2-80</a> shows how to use the <code>@ObjectTypeConverter</code> annotation to specify object converters for the <code>gender</code> field.</p>
 <div class="example"><a id="BGBFDFEJ" name="BGBFDFEJ"></a><a id="TLJPA480" name="TLJPA480"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-80 Using the @ObjectTypeConverter Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 public class Employee implements Serializable{
      ...
      @ObjectTypeConverter (
          name="genderConverter",
          dataType=java.lang.String.class,
          objectType=java.lang.String.class,
          conversionValues={
              @ConversionValue(dataValue="F", objectValue="Female"),
              @ConversionValue(dataValue="M", objectValue="Male")}
      )
      @Convert("genderConverter")
      public String getGender() {
          return gender;
      }
      ...
  }
 </pre>
 <p>You can use the <code>&lt;object-type-converter&gt;</code> element in the deployment descriptor as an alternative to using the <code>@ObjectTypeConverter</code> annotation in the source code, as shown in <a href="#BGBCECGI">Example 2-81</a>.</p>
 </div>
 <!-- class="example" -->
 <div class="example"><a id="BGBCECGI" name="BGBCECGI"></a><a id="TLJPA481" name="TLJPA481"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-81 Using &lt;object-type-converter&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>&lt;object-type-converter name="gender-converter" object-type="model.Gender"     data-type="java.lang.String"&gt;</strong>
     &lt;conversion-value object-value="Male" data-value="M" /&gt;
     &lt;conversion-value object-value="Female" data-value="F" /&gt;
 <strong>&lt;/object-type-converter&gt;</strong>
 </pre></div>
 <!-- class="example" -->
 <a id="sthref253" name="sthref253"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><code><a href="#CHDHCCJF">"@TypeConverter"</a></code></p>
 </li>
 <li>
 <p><code><a href="#BGBJEBBB">"@StructConverter"</a></code></p>
 </li>
 <li>
 <p><a href="#CBBJAJCH">"@ConversionValue"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDCHJHF" name="CHDCHJHF"></a><a id="TLJPA482" name="TLJPA482"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@ObjectTypeConverters</font></h2>
 <p>Use <code>@ObjectTypeConverters</code> to define multiple <code>ObjectTypeConverter</code> items.</p>
 <a id="sthref254" name="sthref254"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDBIIEH">Table 2-44</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA483" name="TLJPA483"></a><a id="sthref255" name="sthref255"></a><a id="CHDBIIEH" name="CHDBIIEH"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-44 @ObjectTypeConverters Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@ObjectTypeConverters Annotation Elements" summary="This table describes the elements for the @ObjectTypeConverters annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="24%" />
 <col width="*" />
 <col width="19%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t54"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t54"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t54"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t54" headers="r1c1-t54">
 <p><code>ObjectTypeConverter</code></p>
 </td>
 <td align="left" headers="r2c1-t54 r1c2-t54">
 <p>(Required) An array of <code>@ObjectTypeConverter</code></p>
 </td>
 <td align="left" headers="r2c1-t54 r1c3-t54"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref256" name="sthref256"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDBGGJB">Example 2-82</a> shows how to use this annotation.</p>
 <div class="example"><a id="CHDBGGJB" name="CHDBGGJB"></a><a id="TLJPA484" name="TLJPA484"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-82 Using @ObjectTypeConverters Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity(name="Employee")
 @Table(name="CMP3_FA_EMPLOYEE")
 <strong>@ObjectTypeConverters</strong>({
   @ObjectTypeConverter(
     name="sex",
     dataType=String.class,
     objectType=org.eclipse.persistence.testing.models.jpa.fieldaccess.advanced.Employee.Gender.class,
     conversionValues={
       @ConversionValue(dataValue="F", objectValue="Female"),
       @ConversionValue(dataValue="M", objectValue="Male")
     }
   )
 })
 </pre></div>
 <!-- class="example" -->
 <p>To define multiple object type converts in the <code>eclipselink-orm.xml</code> file, simply create a list of multiple <code>&lt;object-type-converter&gt;</code> elements.</p>
 <a id="sthref257" name="sthref257"></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>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BCGIACHD" name="BCGIACHD"></a><a id="TLJPA485" name="TLJPA485"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@OptimisticLocking</font></h2>
 <p>Use <code>@OptimisticLocking</code> to specify the type of optimistic locking EclipseLink should use when updating or deleting entities.</p>
 <a id="sthref258" name="sthref258"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BCGEDBBI">Table 2-45</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA486" name="TLJPA486"></a><a id="sthref259" name="sthref259"></a><a id="BCGEDBBI" name="BCGEDBBI"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-45 @OptimisticLocking Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@OptimisticLocking Annotation Elements" summary="This table describes the elements for the @OptimisticLocking annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="24%" />
 <col width="*" />
 <col width="19%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t55"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t55"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t55"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t55" headers="r1c1-t55">
 <p><code>cascade</code></p>
 </td>
 <td align="left" headers="r2c1-t55 r1c2-t55">
 <p>(Optional) Specify where the optimistic locking policy should cascade lock. When changing <strong>private owned</strong> and <strong>delete orphan</strong> object, EclipseLink will update the version.</p>
 <p>This element is currently only supported with <code>VERSION_COLUMN</code> locking.</p>
 </td>
 <td align="left" headers="r2c1-t55 r1c3-t55">
 <p><code>false</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t55" headers="r1c1-t55">
 <p><code>selectedColumns</code></p>
 </td>
 <td align="left" headers="r3c1-t55 r1c2-t55">
 <p>(Optional) Specify a list of columns that will be optimistically locked.</p>
 <p>This element is required when <code>type=SELECTED_COLUMNS</code>.</p>
 </td>
 <td align="left" headers="r3c1-t55 r1c3-t55"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t55" headers="r1c1-t55">
 <p><code>type</code></p>
 </td>
 <td align="left" headers="r4c1-t55 r1c2-t55">
 <p>(Optional) The type of optimistic locking policy to use:</p>
 <ul>
 <li>
 <p><code>ALL_COLUMNS</code> &#8211; EclipseLink compares every field in the table with the <code>WHERE</code> clause, when performing and update or delete operation.</p>
 </li>
 <li>
 <p><code>CHANGED_COLUMNS</code> &#8211; EclipseLink compares only the changed fields in the <code>WHERE</code> clause when performing an update.</p>
 </li>
 <li>
 <p><code>SELECTED_COLUMNS</code> &#8211; EclipseLink compares the selected field in the <code>WHERE</code> clause when performing and update or delete operation on the <code>SelectedColumns</code>.</p>
 </li>
 <li>
 <p><code>VERSION_COLUMN</code> &#8211; EclipseLink compares a single version number in the <code>WHERE</code> clause when performing an update.</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r4c1-t55 r1c3-t55">
 <p><code>VERSION_COLUMN</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref260" name="sthref260"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You can specify <code>@OptimisticLocking</code> on an Entity or MappedSuperclass.</p>
 <a id="sthref261" name="sthref261"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BCGJBJFJ">Example 2-83</a> shows how to use the <code>@OptimisticLocking</code> annotation for all columns</p>
 <div class="example"><a id="BCGJBJFJ" name="BCGJBJFJ"></a><a id="TLJPA487" name="TLJPA487"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-83 Using @OptimisticLocking Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Table(name = "EMPLOYEES")
   @OptimisticLocking(type=OptimisticLockingType.ALL_COLUMNS)
   public class Employee implements Serializable {
       ...
   }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BCGJBJFJ">Example 2-83</a> shows how to use the <code>&lt;optimistic-locking&gt;</code> element in the <code>eclipselink-orm.xml</code> file for a single column.</p>
 <div class="example"><a id="TLJPA488" name="TLJPA488"></a><a id="sthref262" name="sthref262"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-84 Using &lt;optimistic-locking&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity name="Employee" class="my.Employee" access="PROPERTY" change-tracking="DEFERRED"&gt;
 ...
     &lt;optimistic-locking type="SELECTED_COLUMNS" cascade="false"&gt;
       &lt;selected-column name="id"/&gt;
       &lt;selected-column name="firstName"/&gt;
     &lt;/optimistic-locking&gt;
 ...
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref263" name="sthref263"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Scaling EclipseLink Applications in Clusters" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CACGHFJB" name="CACGHFJB"></a><a id="TLJPA54101" name="TLJPA54101"></a>
 <hr />
 <div class="refsect1"><!-- infolevel="all" infotype="General" -->
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@OracleArray</font></h2>
 <p>Use the <code>@OracleArray</code> annotation to define an Oracle database <code>VARRAY</code> type, which you can use within PLSQL procedure calls.</p>
 <a id="sthref264" name="sthref264"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CACCDHDF">Table 2-46</a> describes the annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA54102" name="TLJPA54102"></a><a id="sthref265" name="sthref265"></a><a id="CACCDHDF" name="CACCDHDF"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-46 @OracleArray Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@OracleArray Annotation Elements" summary="This table describes the elements for the @OracleArray annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="20%" />
 <col width="*" />
 <col width="20%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t56"><font face="Arial, Helvetica, sans-serif"><strong>Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t56"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t56"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t56" headers="r1c1-t56">
 <p>name</p>
 </td>
 <td align="left" headers="r2c1-t56 r1c2-t56">
 <p>(Required) The name of the <code>VARRAY</code> in the database</p>
 </td>
 <td align="left" headers="r2c1-t56 r1c3-t56"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t56" headers="r1c1-t56">
 <p>nestedType</p>
 </td>
 <td align="left" headers="r3c1-t56 r1c2-t56">
 <p>(Required) The name of the database type that the <code>VARRAY</code> holds</p>
 </td>
 <td align="left" headers="r3c1-t56 r1c3-t56">
 <p><code>VARCHAR_TYPE</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t56" headers="r1c1-t56">
 <p>javaType</p>
 </td>
 <td align="left" headers="r4c1-t56 r1c2-t56">
 <p>(Optional) The Java <code>Collection</code> class to which the <code>VARRAY</code> is mapped</p>
 </td>
 <td align="left" headers="r4c1-t56 r1c3-t56">
 <p><code>ArrayList</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref266" name="sthref266"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CACFFDHH">Example 2-85</a> shows how to use the <code>@OracleArray</code> annotation to define a <code>VARRAY</code> type.</p>
 <div class="example"><a id="CACFFDHH" name="CACFFDHH"></a><a id="TLJPA54109" name="TLJPA54109"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-85 Using the @OracleArray Annoation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @NamedPLSQLStoredFunctionQuery(
 name="getEmployee",
 functionName="EMP_PKG.GET_EMP",
 parameters={
    @PLSQLParameter(
      name="EMP_OUT",
      direction=Direction.OUT,
      databaseType="EMP_PKG.EMP_REC"
      )
    }
 )
 @Embeddable
 @Struct(name="EMP_TYPE", fields={"F_NAME",
 "L_NAME","SALARY"})
 @OracleArray(
    name="EMP_PKG.EMP_REC",
    nestedType=VARCHAR_TYPE
    javaType=Employee.class,
 )
 public class Employee{...}
 </pre></div>
 <!-- class="example" -->
 <a id="sthref267" name="sthref267"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BGBDHGJE2">"@NamedPLSQLStoredProcedureQuery"</a></p>
 </li>
 <li>
 <p><a href="#CACCIBAB">"@OracleArrays"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CACCIBAB" name="CACCIBAB"></a><a id="TLJPA54103" name="TLJPA54103"></a>
 <hr />
 <div class="refsect1"><!-- infolevel="all" infotype="General" -->
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@OracleArrays</font></h2>
 <p>Use the <code>@OracleArrays</code> annotation to define multiple <code>VARRAY</code> types.</p>
 <a id="sthref268" name="sthref268"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CACBFHJC">Table 2-47</a> describes the annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA54104" name="TLJPA54104"></a><a id="sthref269" name="sthref269"></a><a id="CACBFHJC" name="CACBFHJC"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-47 @OracleArrays Attribute Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@OracleArrays Attribute Elements" summary="This table describes the elements of the @OracleArrays attribute." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="26%" />
 <col width="*" />
 <col width="14%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t57"><font face="Arial, Helvetica, sans-serif"><strong>Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t57"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t57"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t57" headers="r1c1-t57">
 <p>value</p>
 </td>
 <td align="left" headers="r2c1-t57 r1c2-t57">
 <p>(Required) An array of Oracle <code>VARRAY</code> types</p>
 </td>
 <td align="left" headers="r2c1-t57 r1c3-t57"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref270" name="sthref270"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CACGHFJB">"@OracleArray"</a> for an example of how to use this annotation.</p>
 <a id="sthref271" name="sthref271"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CACGHFJB">"@OracleArray"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CACEBEGE" name="CACEBEGE"></a><a id="TLJPA54105" name="TLJPA54105"></a>
 <hr />
 <div class="refsect1"><!-- infolevel="all" infotype="General" -->
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@OracleObject</font></h2>
 <p>Use the <code>@OracleObject</code> annotation to define an Oracle database <code>OBJECT</code> type, which you can use within PLSQL procedure calls.</p>
 <a id="sthref272" name="sthref272"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CACGCCBA">Table 2-48</a> describes the annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA54106" name="TLJPA54106"></a><a id="sthref273" name="sthref273"></a><a id="CACGCCBA" name="CACGCCBA"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-48 @OracleObject Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@OracleObject Annotation Elements" summary="This table describes the elements of the @OracleObject annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="20%" />
 <col width="*" />
 <col width="20%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t58"><font face="Arial, Helvetica, sans-serif"><strong>Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t58"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t58"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t58" headers="r1c1-t58">
 <p>name</p>
 </td>
 <td align="left" headers="r2c1-t58 r1c2-t58">
 <p>(Required) The name of the <code>OBJECT</code> type in the database</p>
 </td>
 <td align="left" headers="r2c1-t58 r1c3-t58"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t58" headers="r1c1-t58">
 <p>javaType</p>
 </td>
 <td align="left" headers="r3c1-t58 r1c2-t58">
 <p>(Optional) The Java type to which you want to map the <code>OBJECT</code> type. This class must be mapped using an <code>@STRUCT</code> annotation</p>
 </td>
 <td align="left" headers="r3c1-t58 r1c3-t58">
 <p>void</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t58" headers="r1c1-t58">
 <p>fields</p>
 </td>
 <td align="left" headers="r4c1-t58 r1c2-t58">
 <p>(Required) Defines the parameter fields in the record type</p>
 </td>
 <td align="left" headers="r4c1-t58 r1c3-t58"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref274" name="sthref274"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CACBHHBD">Example 2-86</a> shows how to use the <code>@OracleObject</code> annotation to define an Oracle <code>OBJECT</code> type.</p>
 <div class="example"><a id="CACBHHBD" name="CACBHHBD"></a><a id="TLJPA54110" name="TLJPA54110"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-86 Using the @OracleObject Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @NamedPLSQLStoredFunctionQuery(
 name="getEmployee",
 functionName="EMP_PKG.GET_EMP",
 parameters={
    @PLSQLParameter(
      name="EMP_OUT",
      direction=Direction.OUT,
      databaseType="EMP_PKG.EMP_REC"
      )
    }
 )
 @Embeddable
 @Struct(name="EMP_TYPE", fields={"F_NAME",
 "L_NAME","SALARY"})
 @OracleObject(
    name="EMP_PKG.EMP_REC",
    javaType=Employee.class,
    fields={
      @PLSQLParameter(name="F_NAME"),
      @PLSQLParameter(name="L_NAME"),
      @PLSQLParameter(
       name="SALARY",
       databaseType="NUMERIC_TYPE"
      )
    }
 )
 public class Employee{...}
 </pre></div>
 <!-- class="example" -->
 <a id="sthref275" name="sthref275"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BGBDHGJE2">"@NamedPLSQLStoredProcedureQuery"</a></p>
 </li>
 <li>
 <p><a href="#CACFFCEE">"@OracleObjects"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CACFFCEE" name="CACFFCEE"></a><a id="TLJPA54107" name="TLJPA54107"></a>
 <hr />
 <div class="refsect1"><!-- infolevel="all" infotype="General" -->
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@OracleObjects</font></h2>
 <p>Use the <code>@OracleObjects</code> annotation to define multiple Oracle <code>OBJECT</code> types.</p>
 <a id="sthref276" name="sthref276"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CACDICGC">Table 2-49</a> describes the annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA54108" name="TLJPA54108"></a><a id="sthref277" name="sthref277"></a><a id="CACDICGC" name="CACDICGC"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-49 @OracleObjects Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@OracleObjects Annotation Elements" summary="This table describes the elements of the @OracleObjects annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="26%" />
 <col width="*" />
 <col width="14%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t59"><font face="Arial, Helvetica, sans-serif"><strong>Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t59"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t59"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t59" headers="r1c1-t59">
 <p>value</p>
 </td>
 <td align="left" headers="r2c1-t59 r1c2-t59">
 <p>(Required) An array of Oracle <code>OBJECT</code> types</p>
 </td>
 <td align="left" headers="r2c1-t59 r1c3-t59"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref278" name="sthref278"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CACEBEGE">"@OracleObject"</a> for an example of how to use this annotation.</p>
 <a id="sthref279" name="sthref279"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CACEBEGE">"@OracleObject"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDDIBJF" name="CHDDIBJF"></a><a id="TLJPA489" name="TLJPA489"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@OrderCorrection</font></h2>
 <p>Use <code>@OrderCorrection</code> to specify a strategy to use if the order list read from the database is invalid (for example, it has nulls, duplicates, negative values, or values greater than or equal to the list size).</p>
 <p>To be valid, an order list of <em>n</em> elements must be <code>{0, 1,..., n-1}</code></p>
 <a id="sthref280" name="sthref280"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDIFBBF">Table 2-50</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA490" name="TLJPA490"></a><a id="sthref281" name="sthref281"></a><a id="CHDIFBBF" name="CHDIFBBF"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-50 @OrderCorrection Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@OrderCorrection Annotation Elements" summary="This table describes the elements for the @OrderCorrection annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="26%" />
 <col width="*" />
 <col width="14%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t60"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t60"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t60"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t60" headers="r1c1-t60">
 <p>value</p>
 </td>
 <td align="left" headers="r2c1-t60 r1c2-t60">
 <p>(Optional) Specify a strategy to use if the order list read from the database is invalid:</p>
 <ul>
 <li>
 <p><code>EXCEPTION</code></p>
 </li>
 <li>
 <p><code>READ</code></p>
 </li>
 <li>
 <p><code>READ_WRITE</code></p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r2c1-t60 r1c3-t60">
 <p><code>READ_WRITE</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref282" name="sthref282"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>When using <code>@OrderCorrection</code>, you can specify how EclipseLink should handle invalid list orders:</p>
 <ul>
 <li>
 <p><code>EXCEPTION</code> &#8211; When <code>OrderCorrectionType=EXCEPTION</code>, EclipseLink will not correct the list. Instead, EclipseLink will throw a <code>QueryException</code> with error code <code>QueryException.LIST_ORDER_FIELD_WRONG_VALUE</code></p>
 <p>For example, given the following list of three objects in the database:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 {null, objectA}; {2, objectB}, {5, ObjectC};
 </pre>
 <p>When read into the application, EclipseLink will throw an exception.</p>
 </li>
 <li>
 <p><code>READ</code> &#8211; When <code>OrderCorrectionType=READ</code>, EclipseLink corrects the list read into application, but does not retain any information about the invalid list order that remains in the database. Although this is not an issue in read-only uses of the list, if the list is modified and then saved into the database, the order will most likely differ from the cache and be invalid.</p>
 <p>The <code>READ</code> mode is used as the default when the mapped attribute is not a <code>List</code>.</p>
 <p>For example, given the following list of three objects in the database:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 {null, objectA}; {2, objectB}, {5, ObjectC}
 </pre>
 <ul>
 <li>
 <p>When read as a list: <code>{objectA, objectB, objectC}</code></p>
 </li>
 <li>
 <p>When adding a new element to the list: <code>{objectA, objectB, objectC, objectD}</code></p>
 </li>
 <li>
 <p>When saving the updated list to the database: <code>{null, objectA}, {2, objectB}, {5, objectC}, {3, objectD}</code></p>
 </li>
 <li>
 <p>When reading the list again: <code>{objectA, objectB, objectD, objectC}</code></p>
 </li>
 </ul>
 </li>
 <li>
 <p><code>READ_WRITE</code> &#8211; When <code>OrderCorrectionType=READ_WRITE</code>, EclipseLink corrects the order of the list read into application <em>and</em> remembers the invalid list order left in the database. If the list is updated and saved to the database, the order indexes are saved ensuring that the list order in the data base will be exactly the same as in cache (and therefore valid).</p>
 <p>The <code>READ_WRITE</code> mode is used as the default when the mapped attribute is either a <code>List</code> or <code>Vector</code> (that is, it is assignable from the EclipseLink internal class <code>IndirectList</code>). In JPA, if the mode is not specified, <code>READ_WRITE</code> is used by default.</p>
 <p>For example, given the following list of three objects in the database:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 {null, objectA}; {2, objectB}, {5, ObjectC}
 </pre>
 <ul>
 <li>
 <p>When read as a list: <code>{objectA, objectB, objectC}</code></p>
 </li>
 <li>
 <p>When adding a new element to the list: <code>{objectA, objectB, objectC, objectD}</code></p>
 </li>
 <li>
 <p>When saving the updated list to the database: <code>{0, objectA}, {1, objectB}, {2, objectC}, {3, objectD}</code></p>
 </li>
 <li>
 <p>When reading the list again: <code>{objectA, objectB, objectC, objectD}</code></p>
 </li>
 </ul>
 </li>
 </ul>
 <a id="sthref283" name="sthref283"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDFIAIE">Example 2-87</a> shows how to use this annotation.</p>
 <div class="example"><a id="CHDFIAIE" name="CHDFIAIE"></a><a id="TLJPA491" name="TLJPA491"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-87 Using @OrderCorrection Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @OrderColumn(name="ORDER_COLUMN")
 <strong>@OrderCorrection(EXCEPTION)</strong>
 List&lt;String&gt; designations;
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDHIFFI">Example 2-88</a> shows how to use this extension in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="CHDHIFFI" name="CHDHIFFI"></a><a id="TLJPA54021" name="TLJPA54021"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-88 Using &lt;element-collection&gt; in XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;element-collection name="designations"&gt;
     &lt;order-column name="ORDER_COLUMN" correction-type="EXCEPTION"/&gt;
 &lt;/element-collection&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref284" name="sthref284"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information see:</p>
 <ul>
 <li>
 <p><a href="#CACGCEIJ">"Entity Annotations"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDDAHEB" name="CHDDAHEB"></a><a id="TLJPA492" name="TLJPA492"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Partitioned</font></h2>
 <p>Use <code>@Partitioned</code> to specify a partitioning policy to use for an Entity or relationship.</p>
 <a id="sthref285" name="sthref285"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDCJBCE">Table 2-51</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA493" name="TLJPA493"></a><a id="sthref286" name="sthref286"></a><a id="CHDCJBCE" name="CHDCJBCE"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-51 @Partitioned Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Partitioned Annotation Elements" summary="This table describes the elements for the @Partitioned 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-t61"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t61"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t61"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t61" headers="r1c1-t61">
 <p><code>value</code></p>
 </td>
 <td align="left" headers="r2c1-t61 r1c2-t61">
 <p>(Required) Name of the partitioning policy</p>
 </td>
 <td align="left" headers="r2c1-t61 r1c3-t61"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref287" name="sthref287"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Use partitioning to partition the data for a class across multiple databases or a database cluster (such as Oracle RAC). Partitioning can provide improved scalability by allowing multiple database machines to service requests.</p>
 <p>You can specify <code>@Partitioned</code> on an Entity, relationship, query, or session/persistence unit.</p>
 <a id="TLJPA497" name="TLJPA497"></a>
 <p><b><font face="arial, helvetica, sans-serif" color="#330099">Partitioning Policies</font></b></p>
 <p>To configure data partitioning, use the <code>@Partitioned</code> annotation and one or more partitioning policy annotations. The annotations for defining the different kinds of policies are:</p>
 <ul>
 <li>
 <p><code><a href="#CEGBDBEG">@HashPartitioning</a></code>: Partitions access to a database cluster by the hash of a field value from the object, such as the object's ID, location, or tenant. The hash indexes into the list of connection pools/nodes. All write or read request for objects with that hash value are sent to the same server. If a query does not include the hash field as a parameter, it can be sent to all servers and unioned, or it can be left to the session's default behavior.</p>
 </li>
 <li>
 <p><code><a href="#BCGIIAFB">@PinnedPartitioning</a></code>: Pins requests to a single connection pool/node. This allows for vertical partitioning.</p>
 </li>
 <li>
 <p><code><a href="#BCGCGEIH">@RangePartitioning</a></code>: Partitions access to a database cluster by a field value from the object, such as the object's ID, location, or tenant. Each server is assigned a range of values. All write or read requests for objects with that value are sent to the same server. If a query does not include the field as a parameter, then it can either be sent to all server's and unioned, or left to the session's default behavior.</p>
 </li>
 <li>
 <p><code><a href="#BABJEFJH">@ReplicationPartitioning</a></code>: Sends requests to a set of connection pools/nodes. This policy is for replicating data across a cluster of database machines. Only modification queries are replicated.</p>
 </li>
 <li>
 <p><code><a href="#BCGBJGFF">@RoundRobinPartitioning</a></code>: Sends requests in a round-robin fashion to the set of connection pools/nodes. It is for load balancing read queries across a cluster of database machines. It requires that the full database be replicated on each machine, so it does not support partitioning. The data should either be read-only, or writes should be replicated.</p>
 </li>
 <li>
 <p><code><a href="#BCGEJFAH">@UnionPartitioning</a></code>: Sends queries to all connection pools and unions the results. This is for queries or relationships that span partitions when partitioning is used, such as on a <code>ManyToMany</code> cross partition relationship.</p>
 </li>
 <li>
 <p><code><a href="#CEGHFJDJ">@ValuePartitioning</a></code>: Partitions access to a database cluster by a field value from the object, such as the object's location or tenant. Each value is assigned a specific server. All write or read requests for objects with that value are sent to the same server. If a query does not include the field as a parameter, then it can be sent to all servers and unioned, or it can be left to the session's default behavior.</p>
 </li>
 <li>
 <p><code>@Partitioning</code>: Partitions access to a database cluster by a custom partitioning policy. A PartitioningPolicy class must be provided and implemented.</p>
 </li>
 </ul>
 <p>Partitioning policies are globally-named objects in a persistence unit and are reusable across multiple descriptors or queries. This improves the usability of the configuration, specifically with JPA annotations and XML.</p>
 <p>The persistence unit properties support adding named connection pools in addition to the existing configuration for read/write/sequence. A named connection pool must be defined for each node in the database cluster.</p>
 <p>If a transaction modifies data from multiple partitions, JTA should be used to ensure 2-phase commit of the data. An exclusive connection can also be configured in the EntityManager to ensure only a single node is used for a single transaction.</p>
 <a id="TLJPA498" name="TLJPA498"></a>
 <p><b><font face="arial, helvetica, sans-serif" color="#330099">Clustered Databases and Oracle RAC</font></b></p>
 <p>Some databases support clustering the database across multiple machines. Oracle RAC allows for a single database to span multiple different server nodes. Oracle RAC also supports table and node partitioning of data. A database cluster allows for any of the data to be accessed from any node in the cluster. However, it is generally it is more efficient to partition the data access to specific nodes, to reduce cross node communication.</p>
 <p>EclipseLink partitioning can be used in conjunction with a clustered database to reduce cross node communication, and improve scalability.</p>
 <p>To use partitioning with a database cluster to following is required:</p>
 <ul>
 <li>
 <p>Partition policy should not enable replication, as database cluster makes data available to all nodes.</p>
 </li>
 <li>
 <p>Partition policy should not use unions, as database cluster returns the complete query result from any node.</p>
 </li>
 <li>
 <p>A data source and EclipseLink connection pool should be defined for each node in the cluster.</p>
 </li>
 <li>
 <p>The application's data access and data partitioning should be designed to have each transaction only require access to a single node.</p>
 </li>
 <li>
 <p>Usage of an exclusive connection for an EntityManager is recommended to avoid having multiple nodes in a single transaction and avoid 2-phase commit.</p>
 </li>
 </ul>
 <a id="sthref288" name="sthref288"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CEGHAIDJ">Example 2-89</a> shows how to partition Employee data by location. The two primary sites, <strong>Ottawa</strong> and <strong>Toronto</strong> are each stored on a separate database. All other locations are stored on the default database. Project is range partitioned by its ID, as shown in <a href="#CEGJCEIH">Example 2-90</a>. Each range of ID values are stored on a different database. The employee/project relationship is an example of a cross partition relationship. To allow the employees and projects to be stored on different databases a union policy is used and the join table is replicated to each database.</p>
 <div class="example"><a id="CEGHAIDJ" name="CEGHAIDJ"></a><a id="TLJPA499" name="TLJPA499"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-89 Using Partitioning</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @IdClass(EmployeePK.class)
 @UnionPartitioning(
         name="UnionPartitioningAllNodes",
         replicateWrites=true)
 @ValuePartitioning(
         name="ValuePartitioningByLOCATION",
         partitionColumn=@Column(name="LOCATION"),
         unionUnpartitionableQueries=true,
         defaultConnectionPool="default",
         partitions={
             @ValuePartition(connectionPool="node2", value="Ottawa"),
             @ValuePartition(connectionPool="node3", value="Toronto")
         })
 @Partitioned("ValuePartitioningByLOCATION")
 public class Employee {
     @Id
     @Column(name = "EMP_ID")
     private Integer id;

     @Id
     private String location;
     ...

     @ManyToMany(cascade = { PERSIST, MERGE })
     @Partitioned("UnionPartitioningAllNodes")
     private Collection&lt;Project&gt; projects;
     ...
 }
 </pre></div>
 <!-- class="example" -->
 <div class="example"><a id="CEGJCEIH" name="CEGJCEIH"></a><a id="TLJPA500" name="TLJPA500"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-90 Using @RangePartitioning</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @RangePartitioning(
         name="RangePartitioningByPROJ_ID",
         partitionColumn=@Column(name="PROJ_ID"),
         partitionValueType=Integer.class,
         unionUnpartitionableQueries=true,
         partitions={
             @RangePartition(connectionPool="default", startValue="0", endValue="1000"),
             @RangePartition(connectionPool="node2", startValue="1000", endValue="2000"),
             @RangePartition(connectionPool="node3", startValue="2000")
         })
 @Partitioned("RangePartitioningByPROJ_ID")
 public class Project {
     @Id
     @Column(name="PROJ_ID")
     private Integer id;
     ...
 }
 </pre></div>
 <!-- class="example" -->
 <a id="sthref289" name="sthref289"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CEGDCFDA">"@Partitioning"</a></p>
 </li>
 <li>
 <p><a href="#CEGBDBEG">"@HashPartitioning"</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="#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>
 <li>
 <p>"Data Partitioning"<code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning</a></code></p>
 </li>
 <li>
 <p>Partitioning Examples<code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/Partitioning">http://wiki.eclipse.org/EclipseLink/Examples/JPA/Partitioning</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CEGDCFDA" name="CEGDCFDA"></a><a id="TLJPA495" name="TLJPA495"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Partitioning</font></h2>
 <p>Use <code>@Partitioning</code> to configure a custom <code>PartitioningPolicy</code>.</p>
 <a id="sthref290" name="sthref290"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CEGGJJDE">Table 2-52</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA496" name="TLJPA496"></a><a id="sthref291" name="sthref291"></a><a id="CEGGJJDE" name="CEGGJJDE"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-52 @Partitioning Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Partitioning Annotation Elements" summary="This table describes the elements for the @Partitioning annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="19%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t62"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t62"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t62"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t62" headers="r1c1-t62">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t62 r1c2-t62">
 <p>Name of the partition policy. Names must be unique for the persistence unit.</p>
 </td>
 <td align="left" headers="r2c1-t62 r1c3-t62"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t62" headers="r1c1-t62">
 <p><code>partitioningClass</code></p>
 </td>
 <td align="left" headers="r3c1-t62 r1c2-t62">
 <p>(Required) Full <code>package.class</code> name of a subclass of <code>PartitioningPolicy</code></p>
 </td>
 <td align="left" headers="r3c1-t62 r1c3-t62"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref292" name="sthref292"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Data partitioning allows for an application to scale its data across more than a single database machine. EclipseLink supports data partitioning at the Entity level to allow a different set of entity instances for the same class to be stored in a different physical database or different node within a database cluster. Both regular databases and clustered databases are supported. Data can be partitioned both horizontally and vertically.</p>
 <p>Partitioning can be enabled on an entity, a relationship, a query, or a persistence unit.</p>
 <a id="sthref293" name="sthref293"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CEGCEIBF">Example 2-91</a> shows a custom partitioning policy.</p>
 <div class="example"><a id="CEGCEIBF" name="CEGCEIBF"></a><a id="TLJPA54022" name="TLJPA54022"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-91 Using @Partitioning Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 <strong>@Partitioning(name="order", partitioningClass=OrderPartitioningPolicy.class)</strong>
 @public class Order {
     ...
 }

 public class OrderPartitioningPolicy extends PartitioningPolicy {

     public List&lt;Accessor&gt; getConnectionsForQuery(AbstractSession session, DatabaseQuery query, AbstractRecord arguments) {

         List&lt;Accessor&gt; accessors = new ArrayList&lt;Accessor&gt;(1);
         accessors.add(getAccessor(ACMEPool.leastBusy(), session, query, false));
         return accessors;
     }
 }
 </pre></div>
 <!-- class="example" -->
 <a id="sthref294" name="sthref294"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CHDDAHEB">"@Partitioned"</a></p>
 </li>
 <li>
 <p><a href="#CEGBDBEG">"@HashPartitioning"</a></p>
 </li>
 <li>
 <p><a href="#BCGIIAFB">"@PinnedPartitioning"</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>
 <li>
 <p><a href="persistenceproperties_ref.htm#partitioning">"partitioning"</a></p>
 </li>
 <li>
 <p>"Data Partitioning" <code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning</a></code></p>
 </li>
 <li>
 <p>EclipseLink Examples <code>http://wiki.eclipse.org/EclipseLink/Examples/JPA/Partitioning</code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BCGIIAFB" name="BCGIIAFB"></a><a id="TLJPA501" name="TLJPA501"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@PinnedPartitioning</font></h2>
 <p>Use <code>@PinnedPartitionPolicy</code> to pin requests to a single connection pool, allowing for vertical partitioning (that is, having an entity, query, or session always access a single database).</p>
 <a id="sthref295" name="sthref295"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BCGFGBAF">Table 2-53</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA502" name="TLJPA502"></a><a id="sthref296" name="sthref296"></a><a id="BCGFGBAF" name="BCGFGBAF"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-53 @PinnedPartitioning Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@PinnedPartitioning Annotation Elements" summary="This table describes the elements for the @PinnedPartitioning annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="19%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t63"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t63"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t63"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t63" headers="r1c1-t63">
 <p><code>connectionPool</code></p>
 </td>
 <td align="left" headers="r2c1-t63 r1c2-t63">
 <p>Connection pool name to which to pin queries</p>
 </td>
 <td align="left" headers="r2c1-t63 r1c3-t63"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t63" headers="r1c1-t63">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r3c1-t63 r1c2-t63">
 <p>Name of the partition policy. Names must be unique for the persistence unit.</p>
 </td>
 <td align="left" headers="r3c1-t63 r1c3-t63"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref297" name="sthref297"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Partition policies are globally named, to allow reuse. You must also set the partitioning policy with the <code>@Partitioned</code> annotation.</p>
 <p>You can specify <code>@PinnedPartitioning</code> on an Entity, relationship, query, or session/persistence unit.</p>
 <p>The persistence unit properties support adding named connection pools in addition to the existing configuration for read/write/sequence. A named connection pool must be defined for each node in the database cluster.</p>
 <p>If a transaction modifies data from multiple partitions, you should use JTA ensure proper two-phase commit of the data. You can also configure an exclusive connection in the EntityManager to ensure that only a single node is used for a single transaction.</p>
 <a id="sthref298" name="sthref298"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CEGHAIDJ">"Using Partitioning"</a> for an example of partitioning with EclipseLink.</p>
 <a id="sthref299" name="sthref299"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Data Partitioning"<code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning</a></code></p>
 </li>
 <li>
 <p><a href="#CHDDAHEB">"@Partitioned"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDDEBEC" name="CHDDEBEC"></a><a id="TLJPA539" name="TLJPA539"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@PLSQLParameter</font></h2>
 <p>Use <code>@PLSQLParameter</code> within a <code>NamedPLSQLStoredProcedureQuery</code> or <code>PLSQLRecord</code> annotation.</p>
 <a id="sthref300" name="sthref300"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDDEJEC">Table 2-54</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA540" name="TLJPA540"></a><a id="sthref301" name="sthref301"></a><a id="CHDDEJEC" name="CHDDEJEC"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-54 @PLSQLParameter Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@PLSQLParameter Annotation Elements" summary="This table describes the elements for the @PLSQLParameter annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="21%" />
 <col width="*" />
 <col width="14%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t64"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t64"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t64"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t64" headers="r1c1-t64">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t64 r1c2-t64">
 <p>(Required) The query parameter name</p>
 </td>
 <td align="left" headers="r2c1-t64 r1c3-t64"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t64" headers="r1c1-t64">
 <p><code>direction</code></p>
 </td>
 <td align="left" headers="r3c1-t64 r1c2-t64">
 <p>(Optional) The direction of the stored procedure parameter:</p>
 <ul>
 <li>
 <p><code>IN</code> &#8211; Input parameter</p>
 </li>
 <li>
 <p><code>IN_OUT</code> &#8211; Input and output parameters</p>
 </li>
 <li>
 <p><code>OUT</code> &#8211; Output parameter</p>
 </li>
 <li>
 <p><code>OUT_CURSOR</code> &#8211; Output cursor</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r3c1-t64 r1c3-t64">
 <p><code>IN</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t64" headers="r1c1-t64">
 <p><code>databaseType</code></p>
 </td>
 <td align="left" headers="r4c1-t64 r1c2-t64">
 <p>(Optional) Database data type for the parameter. This either one of the type constants defined in <code>OraclePLSQLTypes</code>, or <code>JDBCTypes</code>, or a custom record or table type name.</p>
 </td>
 <td align="left" headers="r4c1-t64 r1c3-t64"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t64" headers="r1c1-t64">
 <p><code>length</code></p>
 </td>
 <td align="left" headers="r5c1-t64 r1c2-t64">
 <p>(Optional) Maximum length of the field value</p>
 </td>
 <td align="left" headers="r5c1-t64 r1c3-t64"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t64" headers="r1c1-t64">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r6c1-t64 r1c2-t64">
 <p>(Optional) Stored procedure parameter name</p>
 </td>
 <td align="left" headers="r6c1-t64 r1c3-t64"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r7c1-t64" headers="r1c1-t64">
 <p><code>optional</code></p>
 </td>
 <td align="left" headers="r7c1-t64 r1c2-t64">
 <p>(Optional) Specify if the parameter is required, or optional and defaulted by the procedure.</p>
 </td>
 <td align="left" headers="r7c1-t64 r1c3-t64">
 <p><code>false</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r8c1-t64" headers="r1c1-t64">
 <p><code>scale</code></p>
 </td>
 <td align="left" headers="r8c1-t64 r1c2-t64">
 <p>(Optional) Maximum precision value</p>
 </td>
 <td align="left" headers="r8c1-t64 r1c3-t64"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r9c1-t64" headers="r1c1-t64">
 <p><code>precision</code></p>
 </td>
 <td align="left" headers="r9c1-t64 r1c2-t64">
 <p>(Optional) Maximum precision value</p>
 </td>
 <td align="left" headers="r9c1-t64 r1c3-t64"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref302" name="sthref302"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Use the <code>@PLSQLParameter</code> annotation to configure the parameter and type for Oracle PLSQL stored procedures and record types that use extended PLSQL types instead of regular SQL types. They support <code>PLSQL RECORD</code>, <code>TABLE</code>, <code>BOOLEAN</code> and other extend PLSQL types.</p>
 <a id="sthref303" name="sthref303"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#BGBDHGJE2">"@NamedPLSQLStoredProcedureQuery"</a> for an example using the <code>@PLSQLParameter</code> annotation.</p>
 <a id="sthref304" name="sthref304"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information:</p>
 <ul>
 <li>
 <p><a href="#BGBDHGJE2">"@NamedPLSQLStoredProcedureQuery"</a></p>
 </li>
 <li>
 <p><a href="#CHDBGAED">"@PLSQLRecord"</a></p>
 </li>
 <li>
 <p>PLSQL Stored Procedure Examples<code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/PLSQLStoredFunction">http://wiki.eclipse.org/EclipseLink/Examples/JPA/PLSQLStoredFunction</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDBGAED" name="CHDBGAED"></a><a id="TLJPA54023" name="TLJPA54023"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@PLSQLRecord</font></h2>
 <p>Use <code>@PLSQLRecord</code> to define a database PLSQL <code>RECORD</code> type for use within PLSQL procedures.</p>
 <a id="sthref305" name="sthref305"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDDABDB">Table 2-55</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA54024" name="TLJPA54024"></a><a id="sthref306" name="sthref306"></a><a id="CHDDABDB" name="CHDDABDB"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-55 @PLSQLRecord Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@PLSQLRecord Annotation Elements" summary="This table describes the elements for the @PLSQLRecord annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="21%" />
 <col width="*" />
 <col width="13%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t65"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t65"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t65"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t65" headers="r1c1-t65">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t65 r1c2-t65">
 <p>(Required) The name of the table in the database</p>
 </td>
 <td align="left" headers="r2c1-t65 r1c3-t65"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t65" headers="r1c1-t65">
 <p><code>compatibileType</code></p>
 </td>
 <td align="left" headers="r3c1-t65 r1c2-t65">
 <p>(Required) Name of the database <code>OBJECTYPE</code> that mirror's the record's structure</p>
 </td>
 <td align="left" headers="r3c1-t65 r1c3-t65"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t65" headers="r1c1-t65">
 <p><code>fields</code></p>
 </td>
 <td align="left" headers="r4c1-t65 r1c2-t65">
 <p>(Required) The fields in the record type</p>
 </td>
 <td align="left" headers="r4c1-t65 r1c3-t65"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t65" headers="r1c1-t65">
 <p><code>javaType</code></p>
 </td>
 <td align="left" headers="r5c1-t65 r1c2-t65">
 <p>(Optional) The class of the object type. You must map this class with the <code><a href="#CBBDCAHG">@Struct</a></code> annotation.</p>
 </td>
 <td align="left" headers="r5c1-t65 r1c3-t65"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref307" name="sthref307"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Oracle PLSQL <code>RECORD</code> types are <em>structured</em> database types. Although JDBC does not provide a mechanism for returning these types, EclipseLink provides support to translate these types into <code>OBJECT</code> types. You must create an <code>OBJECT</code> type on the database to mirror the <code>RECORD</code> type and provide it as the <code>compatibileType</code> in the <code>@PLSQLRecord</code>.</p>
 <p>You can then map the <code>RECORD</code> to a Java class, map the Java class as an <code>@Embeddable</code>, use the <code>@Struct</code> annotations to map the Java class to the <code>OBJECT</code> type that mirrors the <code>RECORD</code> type.</p>
 <p>You can then call and return the Java class as parameters to the PLSQL stored procedure query.</p>
 <a id="sthref308" name="sthref308"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDJJCGF">Example 2-92</a> shows how to use this annotation.</p>
 <div class="example"><a id="CHDJJCGF" name="CHDJJCGF"></a><a id="TLJPA54025" name="TLJPA54025"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-92 Using @PLSQLRecord Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @NamedPLSQLStoredFunctionQuery(name="getEmployee", functionName="EMP_PKG.GET_EMP",
     returnParameter=@PLSQLParameter(name="RESULT", databaseType="EMP_PKG.EMP_REC"))
 @Embeddable
 @Struct(name="EMP_TYPE", fields={"F_NAME", "L_NAME", "SALARY"})
 @PLSQLRecord(name="EMP_PKG.EMP_REC", compatibleType="EMP_TYPE", javaType=Employee.class,
     fields={@PLSQLParameter(name="F_NAME"), @PLSQLParameter(name="L_NAME"), @PLSQLParameter(name="SALARY", databaseType="NUMERIC_TYPE")})
 public class Employee {
  ...
 }
 </pre></div>
 <!-- class="example" -->
 <a id="sthref309" name="sthref309"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Stored Procedures" in <em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p><a href="#BGBDHGJE2">"@NamedPLSQLStoredProcedureQuery"</a></p>
 </li>
 <li>
 <p><a href="#CHDBGAED4">"@PLSQLRecords"</a></p>
 </li>
 <li>
 <p>Oracle PL/SQL <code><a href="http://www.oracle.com/technetwork/database/features/plsql/index.html">http://www.oracle.com/technetwork/database/features/plsql/index.html</a></code></p>
 </li>
 <li>
 <p>PLSQL Stored Procedure Examples<code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/PLSQLStoredFunction">http://wiki.eclipse.org/EclipseLink/Examples/JPA/PLSQLStoredFunction</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDBGAED4" name="CHDBGAED4"></a><a id="TLJPA54026" name="TLJPA54026"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@PLSQLRecords</font></h2>
 <p>Use <code>@PLSQLRecords</code> to define multiple <code>PLSQLRecord</code>.</p>
 <a id="sthref310" name="sthref310"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDDABDB4">Table 2-56</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA54027" name="TLJPA54027"></a><a id="sthref311" name="sthref311"></a><a id="CHDDABDB4" name="CHDDABDB4"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-56 @PLSQLRecords Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@PLSQLRecords Annotation Elements" summary="This table describes the elements for the @PLSQLRecords annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="21%" />
 <col width="*" />
 <col width="13%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t66"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t66"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t66"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t66" headers="r1c1-t66">
 <p><code>value</code></p>
 </td>
 <td align="left" headers="r2c1-t66 r1c2-t66">
 <p>(Required) An array of named PLSQL records</p>
 </td>
 <td align="left" headers="r2c1-t66 r1c3-t66"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref312" name="sthref312"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CHDBGAED">"@PLSQLRecord"</a> for an example of how to use this annotation.</p>
 <a id="sthref313" name="sthref313"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Stored Procedures" in <em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p><a href="#BGBDHGJE2">"@NamedPLSQLStoredProcedureQuery"</a></p>
 </li>
 <li>
 <p><a href="#CHDBGAED">"@PLSQLRecord"</a></p>
 </li>
 <li>
 <p>Oracle PL/SQL <code><a href="http://www.oracle.com/technetwork/database/features/plsql/index.html">http://www.oracle.com/technetwork/database/features/plsql/index.html</a></code></p>
 </li>
 <li>
 <p>PLSQL Stored Procedure Examples<code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/PLSQLStoredFunction">http://wiki.eclipse.org/EclipseLink/Examples/JPA/PLSQLStoredFunction</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CACJBHHF" name="CACJBHHF"></a><a id="TLJPA54111" name="TLJPA54111"></a>
 <hr />
 <div class="refsect1"><!-- infolevel="all" infotype="General" -->
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@PLSQLTable</font></h2>
 <p>Use the <code>@PLSQLTable</code> annotation to define a database PLSQL <code>TABLE</code> type, which you can use within PLSQL procedure calls.</p>
 <a id="sthref314" name="sthref314"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CACBGCAJ">Table 2-57</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA54112" name="TLJPA54112"></a><a id="sthref315" name="sthref315"></a><a id="CACBGCAJ" name="CACBGCAJ"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-57 @PLSQLTable Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@PLSQLTable Annotation Elements" summary="This table describes the elements for the @PLSQL annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="20%" />
 <col width="*" />
 <col width="21%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t67"><font face="Arial, Helvetica, sans-serif"><strong>Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t67"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t67"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t67" headers="r1c1-t67">
 <p>name</p>
 </td>
 <td align="left" headers="r2c1-t67 r1c2-t67">
 <p>(Required) The name of the table type in the database</p>
 </td>
 <td align="left" headers="r2c1-t67 r1c3-t67"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t67" headers="r1c1-t67">
 <p>compatibilityType</p>
 </td>
 <td align="left" headers="r3c1-t67 r1c2-t67">
 <p>(Required) The name of the database <code>VARRAY</code> type that mirrors the structure of the table. The table is converted to and from this type so that it can be passed through JDBC.</p>
 </td>
 <td align="left" headers="r3c1-t67 r1c3-t67"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t67" headers="r1c1-t67">
 <p>nestedType</p>
 </td>
 <td align="left" headers="r4c1-t67 r1c2-t67">
 <p>(Required) The type of table, e.g. <code>TABLE</code> of <code>EMP_REC</code></p>
 </td>
 <td align="left" headers="r4c1-t67 r1c3-t67">
 <p><code>VARCHAR_TYPE</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t67" headers="r1c1-t67">
 <p>javaType</p>
 </td>
 <td align="left" headers="r5c1-t67 r1c2-t67">
 <p>(Optional) The Java <code>Collection</code> class to which the <code>VARRAY</code> is mapped. This class can be any valid <code>Collection</code> implementation.</p>
 </td>
 <td align="left" headers="r5c1-t67 r1c3-t67">
 <p><code>ArrayList</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t67" headers="r1c1-t67">
 <p>isNestedTable</p>
 </td>
 <td align="left" headers="r6c1-t67 r1c2-t67">
 <p>(Optional) Indicates a non-associative (nested) table. Typically, you use this method when generating a constructor for the collection in PL/SQL; the constructors for associative (<code>VARRAY</code>) arrays and non-associative (nested) tables differ.</p>
 </td>
 <td align="left" headers="r6c1-t67 r1c3-t67">
 <p><code>false</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref316" name="sthref316"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <div class="example"><a id="TLJPA54113" name="TLJPA54113"></a><a id="sthref317" name="sthref317"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-93 Using the @PLSQLTable Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Named PLSQLStoredProcedureQuery(
 name="getEmployee",
 functionName="EMP_PKG.GET_EMP",
 parameters={
    @PLSQLParamter(
      name="EMP_OUT",
      direction=Direction.OUT,
      databaseType="EMP_TABLE"
      )
    }
 )
 @Embeddable
 @Struct(name="EMP_TYPE", fields={"F_NAME",
 "L_NAME", "SALARY"})
 @PLSQLTable(
    name="EMP_PKG.EMP_TABLE",
    compatibilityType="EMP_VARRAY",
    nestedType="EMP_REC"
 )
 public class Employee{...}
 </pre></div>
 <!-- class="example" -->
 <a id="sthref318" name="sthref318"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BGBDHGJE2">"@NamedPLSQLStoredProcedureQuery"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CACCBFBC" name="CACCBFBC"></a><a id="TLJPA54114" name="TLJPA54114"></a>
 <hr />
 <div class="refsect1"><!-- infolevel="all" infotype="General" -->
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@PLSQLTables</font></h2>
 <p>Use the <code>@PLSQLTables</code> annotation to define mutiple PLSQL tables.</p>
 <a id="sthref319" name="sthref319"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CACCJCAH">Table 2-58</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA54115" name="TLJPA54115"></a><a id="sthref320" name="sthref320"></a><a id="CACCJCAH" name="CACCJCAH"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-58 @PLSQLTables Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@PLSQLTables Annotation Elements" summary="This table describes the elements for the @PLSQLTables annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="26%" />
 <col width="*" />
 <col width="14%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t68"><font face="Arial, Helvetica, sans-serif"><strong>Annotation</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t68"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t68"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t68" headers="r1c1-t68">
 <p>value</p>
 </td>
 <td align="left" headers="r2c1-t68 r1c2-t68">
 <p>(Required) An array of named PLSQL tables</p>
 </td>
 <td align="left" headers="r2c1-t68 r1c3-t68"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref321" name="sthref321"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CACJBHHF">"@PLSQLTable"</a> for examples of how to use this annotation.</p>
 <a id="sthref322" name="sthref322"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CACJBHHF">"@PLSQLTable"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BGEBBFJE" name="BGEBBFJE"></a><a id="TLJPA503" name="TLJPA503"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@PrimaryKey</font></h2>
 <p>Use <code>@PrimaryKey</code> to allow advanced configuration of the ID.</p>
 <p>A validation policy can be given that allows specifying if zero is a valid ID value. The set of primary key columns can also be specified precisely.</p>
 <a id="sthref323" name="sthref323"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BGEBGEAB">Table 2-59</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA504" name="TLJPA504"></a><a id="sthref324" name="sthref324"></a><a id="BGEBGEAB" name="BGEBGEAB"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-59 @PrimaryKey Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@PrimaryKey Annotation Elements" summary="This table describes the elements for the @PrimaryKey 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-t69"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t69"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t69"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t69" headers="r1c1-t69">
 <p><code>cacheKeyType</code></p>
 </td>
 <td align="left" headers="r2c1-t69 r1c2-t69">
 <p>(Optional) Configures the cache key type to store the object in the cache. This type can be the basic ID value for simple singleton IDs or an optimized CachedId type. This element can take the following values:</p>
 <ul>
 <li>
 <p><code>ID_VALUE</code> &#8211; This value can only be used for simple singleton Ids, suchas long/int/String. This is the default for simple singleton IDs.</p>
 </li>
 <li>
 <p><code>CACHE_ID</code> &#8211; Optimized cache key type that allows composite and complex values. This is the default for composite or complex IDs.</p>
 </li>
 <li>
 <p><code>AUTO</code> &#8211; The cache key type is automatically configured depending on what is optimial for the class.</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r2c1-t69 r1c3-t69">
 <p><code>AUTO</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t69" headers="r1c1-t69">
 <p><code>columns</code></p>
 </td>
 <td align="left" headers="r3c1-t69 r1c2-t69">
 <p>(Optional) Directly specifies the primary key columns. This can be used instead of <code>@Id</code> if the primary key includes a non basic field, such as a foreign key, or a inheritance discriminator, embedded, or transformation mapped field.</p>
 </td>
 <td align="left" headers="r3c1-t69 r1c3-t69"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t69" headers="r1c1-t69">
 <p><code>validation</code></p>
 </td>
 <td align="left" headers="r4c1-t69 r1c2-t69">
 <p>(Optional) Configures what ID validation is done:</p>
 <ul>
 <li>
 <p><code>NULL</code> &#8211; EclipseLink interprets zero values as zero. This permits primary keys to use a value of zero.</p>
 </li>
 <li>
 <p><code>ZERO</code> (default) &#8211; EclipseLink interprets zero as null.</p>
 </li>
 <li>
 <p><code>NEGATIVE</code> &#8211; EclipseLink interprets negative values as null.</p>
 </li>
 <li>
 <p><code>NONE</code> &#8211; EclipseLink does not validate the ID value.</p>
 </li>
 </ul>
 <p>By default <code>0</code> is not a valid ID value, this can be used to allow 0 ID values.</p>
 </td>
 <td align="left" headers="r4c1-t69 r1c3-t69">
 <p><code>ZERO</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref325" name="sthref325"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>By default, EclipseLink interprets zero as <code>null</code> for primitive types that cannot be null (such as <code>int</code> and <code>long</code>), causing zero to be an invalid value for primary keys. You can modify this setting by using the <code>@PrimaryKey</code> annotation to configure an <code>IdValidation</code> for an entity class. Use the <code>eclipselink.<a href="persistenceproperties_ref.htm#CACEEGCC">id-validation</a></code> property to configure an <code>IdValidation</code> for the entire persistence unit.</p>
 <p>Setting the <code>validation</code> element also affects how EclipseLink generates IDs: new IDs are generated only for IDs that are not valid (<code>null</code> or <code>0</code>, by default); setting to <code>NONE</code> disables ID generation.</p>
 <a id="sthref326" name="sthref326"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BGEJFGAG">Example 2-94</a> shows how to use this annotation.</p>
 <div class="example"><a id="BGEJFGAG" name="BGEJFGAG"></a><a id="TLJPA505" name="TLJPA505"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-94 Using @PrimaryKey Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>@PrimaryKey(validation=IdValidation.ZERO)</strong>
 public class Employee implements Serializable, Cloneable {
 ...
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BGEGDFHI">Example 2-95</a> shows how to use the <code>&lt;primary-key&gt;</code> element in your <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="BGEGDFHI" name="BGEGDFHI"></a><a id="TLJPA506" name="TLJPA506"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-95 Using @&lt;primary-key&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity name="Employee" class="foo.Employee" access="PROPERTY"&gt;
    <strong>&lt;primary-key validation="ZERO"/</strong>&gt;
 ...
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref327" name="sthref327"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"@Id"<code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Entities/Ids/Id">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Entities/Ids/Id</a></code></p>
 </li>
 <li>
 <p><a href="persistenceproperties_ref.htm#CACEEGCC">"id-validation"</a></p>
 </li>
 <li>
 <p><a href="#CACGCEIJ">"Entity Annotations"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDDDDAI" name="CHDDDDAI"></a><a id="TLJPA507" name="TLJPA507"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@PrivateOwned</font></h2>
 <p>Use <code>@PrivateOwned</code> to specify that a relationship is privately owned; target object is a dependent part of the source object and is not referenced by any other object and cannot exist on its own.</p>
 <a id="sthref328" name="sthref328"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p>The <code>@PrivateOwned</code> annotation does not have attributes.</p>
 <a id="sthref329" name="sthref329"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Using <code>@PrivateOwned</code> causes many operations to be cascaded across the relationship including delete, insert, refresh, and lock (when cascaded). It also ensures that private objects removed from collections are deleted and that objects added are inserted.</p>
 <p>You can specify <code>@PrivateOwned</code> on with <code>@OneToOne</code>, <code>@OneToMany</code> and <code>@VariableOneToOne</code> annotations. Private ownership is implied with the <code>@BasicCollection</code> and <code>@BasicMap</code> annotations.</p>
 <p>When the referenced object is privately owned, the referenced child object cannot exist without the parent object.</p>
 <a id="TLJPA508" name="TLJPA508"></a>
 <p><b><font face="arial, helvetica, sans-serif" color="#330099">Additional Information</font></b></p>
 <p>When indicating that a relationship is privately owned, you are specifying the following:</p>
 <ul>
 <li>
 <p>If the source of a privately owned relationship is deleted, then EclipseLink will delete the target. This is equivalent of setting <a href="#CIABIIEB">@CascadeOnDelete</a>.</p>
 </li>
 <li>
 <p>If you remove the reference to a target from a source, then EclipseLink will delete the target.</p>
 </li>
 </ul>
 <p>Normally, do not configure privately owned relationships on objects that might be shared. An object should not be the target in more than one relationship if it is the target in a privately owned relationship.</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>Referencing a privately owned object may produce undesired effects, as it is the application's responsibility to "clean up" references to the privately owned object.</p>
 <p>If the object becomes de-referenced and is deleted, other objects in the cache that continue to reference the deleted object may cause constraint violations, they may resurrect the object (if using cascade persist), or they may simply not reflect what is in the database.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref330" name="sthref330"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDIAFFA">Example 2-96</a> shows using <code>@PrivateOwned</code> to specify <code>Employee</code> field <code>phoneNumbers.</code> .</p>
 <div class="example"><a id="CHDIAFFA" name="CHDIAFFA"></a><a id="TLJPA509" name="TLJPA509"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-96 Using @PrivateOwned Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
  public class Employee implements Serializable {
    ...
    @OneToMany(cascade=ALL, mappedBy="employee")
    <strong>@PrivateOwned</strong>
    public Collection&lt;PhoneNumber&gt; getPhoneNumbers() {
       return phoneNumbers;
    }
    ...
  }
 </pre></div>
 <!-- class="example" -->
 <a id="sthref331" name="sthref331"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CIABIIEB">"@CascadeOnDelete"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABJHAFD" name="BABJHAFD"></a><a id="TLJPA510" name="TLJPA510"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Properties</font></h2>
 <p>Use <code>@Property</code> to specify a single user-defined property on a mapped attribute or its <code>get</code>/<code>set</code> method. Use the <code>@Properties</code> annotation to wrap multiple properties.</p>
 <p>Although not used by EclipseLink, you can specify mapping properties if an application or extension needs to extend EclipseLink metadata.</p>
 <a id="sthref332" name="sthref332"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABIHDFH">Table 2-60</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA511" name="TLJPA511"></a><a id="sthref333" name="sthref333"></a><a id="BABIHDFH" name="BABIHDFH"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-60 @Properties Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Properties Annotation Elements" summary="This table describes the elements for the @Properties 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-t71"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t71"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t71"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t71" headers="r1c1-t71">
 <p>Property</p>
 </td>
 <td align="left" headers="r2c1-t71 r1c2-t71">
 <p>Array of <code>Property</code> elements</p>
 </td>
 <td align="left" headers="r2c1-t71 r1c3-t71"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref334" name="sthref334"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You can specify <code>@Property</code> on a mapped attribute (or its <code>get</code>/<code>set</code> method) within an Entity, MappedSuperclass, or Embeddable class. You can also specify this annotation on an Entity, MappedSuperclass, or Embeddable class.</p>
 <p>Properties defined in MappedSuperclass are passed to all inheriting Entities and MappedSuperclasses. In case of a conflict, property values defined directly on a class always override values inherited from a class's parent.</p>
 <p>When using an <code>orm.xml</code> mapping file, EclipseLink ignores <code>@Property</code> and <code>@Properties</code> specified in annotations on mapped attributes; annotations on classes are merged with those specified i the <code>orm.xml</code> file, with the latter taking precedence in case of conflicts.</p>
 <a id="sthref335" name="sthref335"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABHECGF">Example 2-120</a> shows how to use the <code>@Properties</code> annotation within a <code>@Transformation</code> mapping. <a href="#BABHCBAG">Example 2-121</a> shows how to use the <code>&lt;properties&gt;</code> XML element within the <code>orm.xml</code> file.</p>
 <a id="sthref336" name="sthref336"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BGBCHEDG">"@Property"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BGBCHEDG" name="BGBCHEDG"></a><a id="TLJPA512" name="TLJPA512"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Property</font></h2>
 <p>Use <code>@Property</code> to specify a single user-defined property on a mapped attribute or its <code>get</code>/<code>set</code> method. Use the <code>@Properties</code> annotation to wrap multiple properties.</p>
 <a id="sthref337" name="sthref337"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BGBIGFCA">Table 2-61</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA513" name="TLJPA513"></a><a id="sthref338" name="sthref338"></a><a id="BGBIGFCA" name="BGBIGFCA"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-61 @Property Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Property Annotation Elements" summary="This table describes the @Property 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-t72"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t72"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t72"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t72" headers="r1c1-t72">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t72 r1c2-t72">
 <p>(Required) Name of the property</p>
 </td>
 <td align="left" headers="r2c1-t72 r1c3-t72"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t72" headers="r1c1-t72">
 <p><code>value</code></p>
 </td>
 <td align="left" headers="r3c1-t72 r1c2-t72">
 <p>(Required) String representation of the property <code>value</code>, converted to an instance of <code>valueType</code></p>
 </td>
 <td align="left" headers="r3c1-t72 r1c3-t72"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t72" headers="r1c1-t72">
 <p><code>valueType</code></p>
 </td>
 <td align="left" headers="r4c1-t72 r1c2-t72">
 <p>(Optional) Property value type, converted to valueType by <code>ConversionManager</code>. This must be a simple type that can be handled by the <code>ConversionManager</code>.</p>
 </td>
 <td align="left" headers="r4c1-t72 r1c3-t72">
 <p><code>String</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref339" name="sthref339"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You can specify <code>@Property</code> on a mapped attribute (or its <code>get</code>/<code>set</code> method) within an Entity, MappedSuperclass, or Embeddable class. You can also specify this annotation on an Entity, MappedSuperclass, or Embeddable class.</p>
 <p>Properties defined in MappedSuperclass are passed to all inheriting Entities and MappedSuperclasses. In case of a conflict, property values defined directly on a class always override values inherited from a class's parent.</p>
 <p>When using an <code>orm.xml</code> mapping file, EclipseLink ignores <code>@Property</code> and <code>@Properties</code> annotations on mapped attributes; annotations on classes are merged with those specified i the <code>orm.xml</code> file, with the latter taking precedence in case of conflicts.</p>
 <a id="sthref340" name="sthref340"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABHECGF">Example 2-120</a> shows how to use the <code>@Property</code> annotation within a <code>@Transformation</code> mapping. <a href="#BABHCBAG">Example 2-121</a> shows how to use the <code>&lt;property&gt;</code> XML element within the <code>orm.xml</code> file.</p>
 <a id="sthref341" name="sthref341"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BABJHAFD">"@Properties"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CIHCGHGA" name="CIHCGHGA"></a><a id="TLJPA514" name="TLJPA514"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@QueryRedirectors</font></h2>
 <p>Use @<code>QueryRedirectors</code> to intercept EclipseLink queries for pre- and post-processing, redirection, or performing some side effect such as auditing.</p>
 <a id="sthref342" name="sthref342"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CIHEBJBG">Table 2-62</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA515" name="TLJPA515"></a><a id="sthref343" name="sthref343"></a><a id="CIHEBJBG" name="CIHEBJBG"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-62 @QueryRedirectors Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@QueryRedirectors Annotation Elements" summary="This table describes the elements for the @QueryRedirectors annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="24%" />
 <col width="*" />
 <col width="20%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t73"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t73"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t73"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t73" headers="r1c1-t73">
 <p><code>allQueries</code></p>
 </td>
 <td align="left" headers="r2c1-t73 r1c2-t73">
 <p>This <code>AllQueries</code> Query Redirector will be applied to any executing object query that does not have a more precise redirector (like the <code>ReadObjectQuery</code> Redirector) or a redirector set directly on the query.</p>
 </td>
 <td align="left" headers="r2c1-t73 r1c3-t73">
 <p><code>void.class</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t73" headers="r1c1-t73">
 <p><code>delete</code></p>
 </td>
 <td align="left" headers="r3c1-t73 r1c2-t73">
 <p>A Default <code>Delete</code> Object Query Redirector will be applied to any executing <code>DeleteObjectQuery</code> or <code>DeleteAllQuery</code> that does not have a redirector set directly on the query.</p>
 </td>
 <td align="left" headers="r3c1-t73 r1c3-t73">
 <p><code>void.class</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t73" headers="r1c1-t73">
 <p>insert</p>
 </td>
 <td align="left" headers="r4c1-t73 r1c2-t73">
 <p>A Default <code>Insert</code> Query Redirector will be applied to any executing <code>InsertObjectQuery</code> that does not have a redirector set directly on the query.</p>
 </td>
 <td align="left" headers="r4c1-t73 r1c3-t73">
 <p><code>void.class</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t73" headers="r1c1-t73">
 <p>readAll</p>
 </td>
 <td align="left" headers="r5c1-t73 r1c2-t73">
 <p>A Default <code>ReadAll</code> Query Redirector will be applied to any executing <code>ReadAllQuery</code> that does not have a redirector set directly on the query.</p>
 <p>For users executing a JPA Query through the <code>getResultList()</code>, API this is the redirector that will be invoked</p>
 </td>
 <td align="left" headers="r5c1-t73 r1c3-t73">
 <p><code>void.class</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t73" headers="r1c1-t73">
 <p><code>readObject</code></p>
 </td>
 <td align="left" headers="r6c1-t73 r1c2-t73">
 <p>A Default <code>ReadObject</code> Query Redirector will be applied to any executing <code>ReadObjectQuery</code> that does not have a redirector set directly on the query.</p>
 <p>For users executing a JPA Query through the <code>getSingleResult()</code> API or <code>EntityManager.find()</code>, this is the redirector that will be invoked</p>
 </td>
 <td align="left" headers="r6c1-t73 r1c3-t73">
 <p><code>void.class</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r7c1-t73" headers="r1c1-t73">
 <p><code>report</code></p>
 </td>
 <td align="left" headers="r7c1-t73 r1c2-t73">
 <p>A Default <code>ReportQuery</code> Redirector will be applied to any executing <code>ReportQuery</code> that does not have a redirector set directly on the query.</p>
 <p>For users executing a JPA Query that contains aggregate functions or selects multiple entities this is the redirector that will be invoked</p>
 </td>
 <td align="left" headers="r7c1-t73 r1c3-t73">
 <p><code>void.class</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r8c1-t73" headers="r1c1-t73">
 <p><code>update</code></p>
 </td>
 <td align="left" headers="r8c1-t73 r1c2-t73">
 <p>A Default <code>Update</code> Query Redirector will be applied to any executing UpdateObjectQuery or <code>UpdateAllQuery</code> that does not have a redirector set directly on the query. In EclipseLink an <code>UpdateObjectQuery</code> is executed whenever flushing changes to the datasource.</p>
 </td>
 <td align="left" headers="r8c1-t73 r1c3-t73">
 <p><code>void.class</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref344" name="sthref344"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Use <code>@QueryRedirectors</code> to extend the standard EclipseLink query functionality.</p>
 <p>You can set a <code>QueryRedirector</code> through the Query Hint <code>eclipselink.query.redirector</code> or set as a default Redirector on an Entity.</p>
 <p><code>QueryRedirectors</code> are used when integrating EclipseLink Grid to redirect queries to the Coherence grid.</p>
 <a id="sthref345" name="sthref345"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CIHDHIIH">Example 2-97</a> shows how to use this annotation.</p>
 <div class="example"><a id="CIHDHIIH" name="CIHDHIIH"></a><a id="TLJPA516" name="TLJPA516"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-97 Using @QueryRedirectors Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>@QueryRedirectors</strong>(
     allQueries=org.queryredirectors.AllQueriesForEntity.class)
 @Entity
 public class
 ...
 </pre></div>
 <!-- class="example" -->
 <a id="sthref346" name="sthref346"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Database Queries" in the <em>Understanding EclipseLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABCFDAJ" name="BABCFDAJ"></a><a id="TLJPA517" name="TLJPA517"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@RangePartition</font></h2>
 <p>Use <code>@RangePartition</code> to create a specific range partition for a connection pool. Values within the range will be routed to the specified connection pool.</p>
 <a id="sthref347" name="sthref347"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABCAEJH">Table 2-63</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA518" name="TLJPA518"></a><a id="sthref348" name="sthref348"></a><a id="BABCAEJH" name="BABCAEJH"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-63 @RangePartition Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@RangePartition Annotation Elements" summary="This table describes the elements for the @RangePartition annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="31%" />
 <col width="*" />
 <col width="20%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t74"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t74"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t74"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t74" headers="r1c1-t74">
 <p><code>connectionPool</code></p>
 </td>
 <td align="left" headers="r2c1-t74 r1c2-t74">
 <p>The connection pool to which to route queries for the specified range</p>
 </td>
 <td align="left" headers="r2c1-t74 r1c3-t74"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t74" headers="r1c1-t74">
 <p><code>startValue</code></p>
 </td>
 <td align="left" headers="r3c1-t74 r1c2-t74">
 <p>The <code>String</code> representation of the range start value</p>
 </td>
 <td align="left" headers="r3c1-t74 r1c3-t74"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t74" headers="r1c1-t74">
 <p><code>endValue</code></p>
 </td>
 <td align="left" headers="r4c1-t74 r1c2-t74">
 <p>The <code>String</code> representation of the range end value</p>
 </td>
 <td align="left" headers="r4c1-t74 r1c3-t74"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref349" name="sthref349"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CEGJCEIH">"Using @RangePartitioning"</a> for an example of partitioning with EclipseLink.</p>
 <a id="sthref350" name="sthref350"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Data Partitioning"<code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning</a></code></p>
 </li>
 <li>
 <p><a href="#CHDDAHEB">"@Partitioned"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BCGCGEIH" name="BCGCGEIH"></a><a id="TLJPA519" name="TLJPA519"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@RangePartitioning</font></h2>
 <p>Use <code>@RangePartitioning</code> to partitions access to a database cluster by a field value from the object (such as the object's ID, location, or tenant).</p>
 <p>EclipseLink assigns each server a range of values. All write or read request for objects with a server's value are sent to that specific server. If a query does not include the field as a parameter, then it can either be sent to all server's and unioned, or left to the session's default behavior.</p>
 <a id="sthref351" name="sthref351"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BCGHJEBE">Table 2-64</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA520" name="TLJPA520"></a><a id="sthref352" name="sthref352"></a><a id="BCGHJEBE" name="BCGHJEBE"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-64 @RangePartitioning Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@RangePartitioning Annotation Elements" summary="This table describes the elements for the @RangePartitioning annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="28%" />
 <col width="*" />
 <col width="20%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t75"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t75"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t75"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t75" headers="r1c1-t75">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t75 r1c2-t75">
 <p>(Required) The name of the partition policy; must be unique for the persistence unit.</p>
 </td>
 <td align="left" headers="r2c1-t75 r1c3-t75"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t75" headers="r1c1-t75">
 <p><code>partitionColumn</code></p>
 </td>
 <td align="left" headers="r3c1-t75 r1c2-t75">
 <p>(Required) The database column or query parameter to partition queries by. This is the <em>table column name</em>, not the class attribute name. The column value must be included in the query and should normally be part of the object's ID.</p>
 <p>This can also be the name of a query parameter. If a query does not contain the field the query will not be partitioned.</p>
 </td>
 <td align="left" headers="r3c1-t75 r1c3-t75"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t75" headers="r1c1-t75">
 <p><code>partitions</code></p>
 </td>
 <td align="left" headers="r4c1-t75 r1c2-t75">
 <p>(Required) List of connection pool names to partition across</p>
 </td>
 <td align="left" headers="r4c1-t75 r1c3-t75"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t75" headers="r1c1-t75">
 <p><code>partitionValueType</code></p>
 </td>
 <td align="left" headers="r5c1-t75 r1c2-t75">
 <p>The type of the start and end values</p>
 </td>
 <td align="left" headers="r5c1-t75 r1c3-t75">
 <p><code>String</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t75" headers="r1c1-t75">
 <p><code>unionunpartionableQueries</code></p>
 </td>
 <td align="left" headers="r6c1-t75 r1c2-t75">
 <p>Defines if queries that do not contain the partition field should be sent to every database and have the result unioned.</p>
 </td>
 <td align="left" headers="r6c1-t75 r1c3-t75">
 <p><code>false</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref353" name="sthref353"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Partitioning can be enabled on an Entity, relationship, query, or session/persistence unit.</p>
 <p>Partition policies are globally named to allow reuse, the partitioning policy must also be set using the <code>@Partitioned</code> annotation to be used.</p>
 <p>The persistence unit properties support adding named connection pools in addition to the existing configuration for read/write/sequence. A named connection pool must be defined for each node in the database cluster.</p>
 <p>If a transaction modifies data from multiple partitions, you should use JTA ensure proper two-phase commit of the data. You can also configure an exclusive connection in the EntityManager to ensure that only a single node is used for a single transaction.</p>
 <a id="sthref354" name="sthref354"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BCGIJGHH">Example 2-98</a> shows how to use the <code>@RangePartitioning</code> annotation</p>
 <div class="example"><a id="BCGIJGHH" name="BCGIJGHH"></a><a id="TLJPA521" name="TLJPA521"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-98 Using @RangePartitioning Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Table(name="PART_PROJECT")
 <strong>@RangePartitioning</strong>(
   name="RangePartitioningByPROJ_ID",
   partitionColumn=@Column(name="PROJ_ID"),
   partitionValueType=Integer.class,
   unionUnpartitionableQueries=true,
   partitions={
     @RangePartition(connectionPool="default", startValue="0", endValue="1000"),
     @RangePartition(connectionPool="node2", startValue="1000", endValue="2000"),
     @RangePartition(connectionPool="node3", startValue="2000")
   })
 @Partitioned("RangePartitioningByPROJ_ID")
 public class Project implements Serializable {
 ...
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BCGIJGHH">Example 2-98</a> shows how to use the <code>&lt;range-partitioning&gt;</code> element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="TLJPA522" name="TLJPA522"></a><a id="sthref355" name="sthref355"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-99 Using &lt;range-partitioning&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity name="Project" class="Project" access="FIELD"&gt;
   &lt;table name="PART_PROJECT"/&gt;
   &lt;<strong>range-partitioning</strong> name="RangePartitioningByPROJ_ID" partition-value-type="java.lang.Integer" union-unpartitionable-queries="true"&gt;
     &lt;partition-column name="PROJ_ID"/&gt;
     &lt;partition connection-pool="default" start-value="0" end-value="1000"/&gt;
     &lt;partition connection-pool="node2" start-value="1000" end-value="2000"/&gt;
     &lt;partition connection-pool="node3" start-value="2000"/&gt;
   &lt;/range-partitioning&gt;
   &lt;partitioned&gt;RangePartitioningByPROJ_ID&lt;/partitioned&gt;
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref356" name="sthref356"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BABCFDAJ">"@RangePartition"</a></p>
 </li>
 <li>
 <p><a href="#CHDDAHEB">"@Partitioned"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BGBGEFBD" name="BGBGEFBD"></a><a id="TLJPA523" name="TLJPA523"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@ReadOnly</font></h2>
 <p>Use <code>@ReadOnly</code> to specify that a class is read-only.</p>
 <a id="sthref357" name="sthref357"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p>This annotation contains no elements.</p>
 <a id="sthref358" name="sthref358"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>It may be defined on an Entity or MappedSuperclass.</p>
 <p>In the case of inheritance, a <code>@ReadOnly</code> annotation can only be defined on the root of the inheritance hierarchy .</p>
 <p>You can also use <code>@ReadOnly</code> to bypass EclipseLink's persistence context to save heap space (such as if you need to load a large dataset).</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>You should not modify read-only entities. Doing so can corrupt the EclipseLink cache. To modify a read-only entity, it must cloned or serialized.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref359" name="sthref359"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BGBCIIDB">Example 2-100</a> shows how to use this annotation.</p>
 <div class="example"><a id="BGBCIIDB" name="BGBCIIDB"></a><a id="TLJPA524" name="TLJPA524"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-100 Using @ReadOnly Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>@ReadOnly</strong>
 @Entity
 @Table(name = "TMP_READONLY")
 public class ReadOnlyEntity {
 ...
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BGBCBHEE">Example 2-101</a> shows how to use the <code>&lt;read-only&gt;</code> element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="BGBCBHEE" name="BGBCBHEE"></a><a id="TLJPA525" name="TLJPA525"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-101 Using &lt;read-only&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity name="XMLReadOnlyClass" class="ReadOnlyClass" access="PROPERTY" <strong>read-only="true"</strong>&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref360" name="sthref360"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CACGCEIJ">"Entity Annotations"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDGHHBA" name="CHDGHHBA"></a><a id="TLJPA526" name="TLJPA526"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@ReadTransformer</font></h2>
 <p>Use <code>@ReadTransformer</code> with Transformation mappings to define the transformation of the database column values into attribute values (unless the mapping is write-only).</p>
 <a id="sthref361" name="sthref361"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDGCGID">Table 2-65</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA527" name="TLJPA527"></a><a id="sthref362" name="sthref362"></a><a id="CHDGCGID" name="CHDGCGID"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-65 @ReadTransformer Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@ReadTransformer Annotation Elements" summary="This table describes the elements for the @ReadTransformer annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="19%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t77"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t77"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t77"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t77" headers="r1c1-t77">
 <p><code>method</code></p>
 </td>
 <td align="left" headers="r2c1-t77 r1c2-t77">
 <p>The mapped class must have a method with this name which returns a value to be assigned to the attribute (not assigns the value to the attribute).</p>
 </td>
 <td align="left" headers="r2c1-t77 r1c3-t77"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t77" headers="r1c1-t77">
 <p>transformerClass</p>
 </td>
 <td align="left" headers="r3c1-t77 r1c2-t77">
 <p>User-defined class that implements the <code>org.eclipse.persistence.mappings.transformers.AttributeTransformer</code> interface</p>
 <p>The class will be instantiated, its <code>buildAttributeValue</code> will be used to create the value to be assigned to the attribute.</p>
 </td>
 <td align="left" headers="r3c1-t77 r1c3-t77">
 <p><code>void.class</code></p>
 </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 <strong>either</strong> a <code>method</code> or <code>transformerClass</code>, but not both.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref363" name="sthref363"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Also unless it's a read-only mapping, either <code>@WriteTransformer</code> annotation or <code>@WriteTransformers</code> annotation should be specified. Each <code>WriteTransformer</code> defines transformation of the attribute value to a single database column value (column is specified in the <code>WriteTransformer</code>).</p>
 <a id="sthref364" name="sthref364"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#BABHECGF">"Using @Transformation Annotation"</a> for an example of how to use the <code>@WriteTransformer annotation</code> with a Transformation mapping.</p>
 <a id="sthref365" name="sthref365"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BABCJGIG">"@Transformation"</a>.</p>
 </li>
 <li>
 <p><a href="#BGBGGAEA">"@WriteTransformer"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABJEFJH" name="BABJEFJH"></a><a id="TLJPA528" name="TLJPA528"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@ReplicationPartitioning</font></h2>
 <p>Use <code>@ReplicationPartitioning</code> to send requests to a set of connection pools. It is for replicating data across a cluster of database machines. Only modification queries are replicated.</p>
 <a id="sthref366" name="sthref366"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABJICDB">Table 2-66</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA529" name="TLJPA529"></a><a id="sthref367" name="sthref367"></a><a id="BABJICDB" name="BABJICDB"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-66 @ReplicationPartitioning Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@ReplicationPartitioning Annotation Elements" summary="This table describes the elements for the @ReplicationPartitioning 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-t79"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t79"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t79"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t79" headers="r1c1-t79">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t79 r1c2-t79">
 <p>The name of the partition policy; must be unique for the persistence unit</p>
 </td>
 <td align="left" headers="r2c1-t79 r1c3-t79"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t79" headers="r1c1-t79">
 <p><code>connectionPools</code></p>
 </td>
 <td align="left" headers="r3c1-t79 r1c2-t79">
 <p>List of connection pool names to replicate across</p>
 </td>
 <td align="left" headers="r3c1-t79 r1c3-t79">
 <p>All defined pools in the <code>ServerSession</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref368" name="sthref368"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Partitioning can be enabled on an Entity, relationship, query, or session/persistence unit.</p>
 <p>Partition policies are globally named to allow reuse, the partitioning policy must also be set using the <code>@Partitioned</code> annotation to be used.</p>
 <p>The persistence unit properties support adding named connection pools in addition to the existing configuration for read/write/sequence. A named connection pool must be defined for each node in the database cluster.</p>
 <p>If a transaction modifies data from multiple partitions, you should use JTA ensure proper two-phase commit of the data. You can also configure an exclusive connection in the EntityManager to ensure that only a single node is used for a single transaction.</p>
 <a id="sthref369" name="sthref369"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CEGHAIDJ">"Using Partitioning"</a> for an example of partitioning with EclipseLink.</p>
 <a id="sthref370" name="sthref370"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Data Partitioning"<code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning</a></code></p>
 </li>
 <li>
 <p><a href="#CHDDAHEB">"@Partitioned"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CIHHEGJE" name="CIHHEGJE"></a><a id="TLJPA530" name="TLJPA530"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@ReturnInsert</font></h2>
 <p>Use <code>@ReturnInsert</code> to cause <code>INSERT</code> operations to return values back into the object being written. This allows for table default values, trigger or stored procedures computed values to be set back into the object.</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>Returning is only supported with an Oracle Database and requires an <code>INSERT RETURNING</code> clause.</p>
 <p>To use returning with other databases, a stored procedure with output parameters is used for the insert query.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref371" name="sthref371"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CIHIAFFB">Table 2-67</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA531" name="TLJPA531"></a><a id="sthref372" name="sthref372"></a><a id="CIHIAFFB" name="CIHIAFFB"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-67 @ReturnInsert Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@ReturnInsert Annotation Elements" summary="This table describes the elements for the @ReturnInsert 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-t81"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t81"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t81"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t81" headers="r1c1-t81">
 <p><code>returnOnly</code></p>
 </td>
 <td align="left" headers="r2c1-t81 r1c2-t81">
 <p>(Optional) If specified (true), the mapping field will be excluded from the <code>INSERT</code> clause during SQL generation.</p>
 </td>
 <td align="left" headers="r2c1-t81 r1c3-t81">
 <p>false</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref373" name="sthref373"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>A <code>@ReturnInsert</code> annotation can only be specified on a <code>Basic</code> mapping.</p>
 <a id="sthref374" name="sthref374"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CIHDFAFD">Example 2-102</a> shows how to use the <code>@ReturnInsert</code> annotation. If you do not use an argument, EclipseLink accepts the default value, <code>false</code>.</p>
 <div class="example"><a id="CIHDFAFD" name="CIHDFAFD"></a><a id="TLJPA532" name="TLJPA532"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-102 Using @ReturnInsert Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>@ReturnInsert(returnOnly=true)</strong>
  public String getFirstName() {
      return firstName;
  }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CIHEJAJG">Example 2-103</a> shows how to use the <code>&lt;return-insert&gt;</code> element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="CIHEJAJG" name="CIHEJAJG"></a><a id="TLJPA533" name="TLJPA533"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-103 Using &lt;return-insert&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;basic name="firstName"&gt;
     &lt;column name="FIRST_NAME"/&gt;
     <strong>&lt;return-insert read-only="true"/&gt;</strong>
 &lt;/basic&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref375" name="sthref375"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CACHDFCF">"@ReturnUpdate"</a></p>
 </li>
 <li>
 <p><em>Understanding EclipseLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CACHDFCF" name="CACHDFCF"></a><a id="TLJPA534" name="TLJPA534"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@ReturnUpdate</font></h2>
 <p>Use <code>@ReturnUpdate</code> to cause <code>UPDATE</code> operations to return values back into the object being written. This allows for table default values, trigger or stored procedures computed values to be set back into the object.</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>Returning is only supported with an Oracle Database and requires an <code>INSERT RETURNING</code> clause.</p>
 <p>To use returning with other databases, a stored procedure with output parameters is used for the insert query.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref376" name="sthref376"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p>This annotation contains no elements.</p>
 <a id="sthref377" name="sthref377"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>A <code>@ReturnUpdate</code> annotation can only be specified on a <code>Basic</code> mapping.</p>
 <a id="sthref378" name="sthref378"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CACBJIIH">Example 2-104</a> shows how to use the <code>@ReturnUpdate</code> annotation. The annotation does not accept any arguments.</p>
 <div class="example"><a id="CACBJIIH" name="CACBJIIH"></a><a id="TLJPA535" name="TLJPA535"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-104 Using @ReturnUpdate Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>@ReturnUpdate</strong>
 public String getFirstName() {
     return firstName;
 }
 </pre>
 <p><a href="#CACJIJGE">Example 2-105</a> illustrates the same example as before, but uses the <code>&lt;return-update&gt;</code> element in the <code>eclipselink-orm.xml</code> mapping file.</p>
 </div>
 <!-- class="example" -->
 <div class="example"><a id="CACJIJGE" name="CACJIJGE"></a><a id="TLJPA536" name="TLJPA536"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-105 Using &lt;return-update&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;basic name="firstName"&gt;
     &lt;column name="F_NAME"/&gt;
     &lt;<strong>return-update</strong>/&gt;
 &lt;/basic&gt;

 </pre></div>
 <!-- class="example" -->
 <a id="sthref379" name="sthref379"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CIHHEGJE">"@ReturnInsert"</a></p>
 </li>
 <li>
 <p>Understanding EclipseLink</p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BCGBJGFF" name="BCGBJGFF"></a><a id="TLJPA537" name="TLJPA537"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@RoundRobinPartitioning</font></h2>
 <p>Use <code>@RoundRobinPartitioning</code> to send requests in a "round robin" fashion to the set of connection pools.</p>
 <a id="sthref380" name="sthref380"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BCGIBFHJ">Table 2-68</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA538" name="TLJPA538"></a><a id="sthref381" name="sthref381"></a><a id="BCGIBFHJ" name="BCGIBFHJ"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-68 @RoundRobinPartitioning Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@RoundRobinPartitioning Annotation Elements" summary="This table describes the elements for the @RoundRobinPartitioning annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="26%" />
 <col width="*" />
 <col width="25%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t83"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t83"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t83"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t83" headers="r1c1-t83">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t83 r1c2-t83">
 <p>(Required) Name of the partition policy. Names must be unique for the persistence unit.</p>
 </td>
 <td align="left" headers="r2c1-t83 r1c3-t83"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t83" headers="r1c1-t83">
 <p><code>connectionPools</code></p>
 </td>
 <td align="left" headers="r3c1-t83 r1c2-t83">
 <p>(Optional) List of connection pool names to load balance across</p>
 </td>
 <td align="left" headers="r3c1-t83 r1c3-t83">
 <p>All defined pools in the <code>ServerSession</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t83" headers="r1c1-t83">
 <p><code>replicateWrite</code></p>
 </td>
 <td align="left" headers="r4c1-t83 r1c2-t83">
 <p>(Optional) This allows for a set of database to be written to and kept in sync, and have reads load-balanced across the databases.</p>
 </td>
 <td align="left" headers="r4c1-t83 r1c3-t83">
 <p><code>false</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref382" name="sthref382"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Use the <code>@RoundRobinPartitioning</code> annotation for load-balancing read queries across a cluster of database machines. Using <code>@RoundRobinPartitioning</code> requires that the full database be replicated on each machine.</p>
 <p>The data should either be read-only, or writes should be replicated on the database.</p>
 <p>The persistence unit properties support adding named connection pools in addition to the existing configuration for read/write/sequence. A named connection pool must be defined for each node in the database cluster.</p>
 <p>If a transaction modifies data from multiple partitions, you should use JTA ensure proper two-phase commit of the data. You can also configure an exclusive connection in the EntityManager to ensure that only a single node is used for a single transaction.</p>
 <a id="sthref383" name="sthref383"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CHDDAHEB">"@Partitioned"</a> for an example of partitioning with EclipseLink.</p>
 <a id="sthref384" name="sthref384"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Data Partitioning"<code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning</a></code></p>
 </li>
 <li>
 <p><a href="#CHDDAHEB">"@Partitioned"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CACDCCIA" name="CACDCCIA"></a><a id="TLJPA54059" name="TLJPA54059"></a>
 <hr />
 <div class="refsect1"><!-- infolevel="all" infotype="General" -->
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@SerializedObject</font></h2>
 <p>Use an <code>@SerializedObject</code> annotation to set an <code>org.eclipse.persistence.descriptors.SerializedObjectPolicy</code> instance on an <code>Entity</code> object or <code>MappedSuperClass</code> object. If a serialized object policy is specified, a whole entity object is written with its privately-owned (and nested, privately-owned) entities and element collections into an additional field in the database.</p>
 <a id="sthref385" name="sthref385"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CACBBJAE">Table 2-69</a> describes this annotation's elements.</p>
 <div class="tblformalwide"><a id="TLJPA54060" name="TLJPA54060"></a><a id="sthref386" name="sthref386"></a><a id="CACBBJAE" name="CACBBJAE"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-69 @SerializedObject Attribute Elements</font></em></strong></p>
 <table class="FormalWide" title="@SerializedObject Attribute Elements" summary="This table describes the elements for the @SerializedObject attribute." dir="ltr" border="1" width="100%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
 <col width="21%" />
 <col width="*" />
 <col width="26%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t84"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t84"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t84"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t84" headers="r1c1-t84">
 <p><code>column</code></p>
 </td>
 <td align="left" headers="r2c1-t84 r1c2-t84">
 <p>(Optional) The column that holds the serialized object</p>
 </td>
 <td align="left" headers="r2c1-t84 r1c3-t84">
 <p>BLOB column named SOP in the entity's main table.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t84" headers="r1c1-t84">
 <p><code>value</code></p>
 </td>
 <td align="left" headers="r3c1-t84 r1c2-t84">
 <p>(Required) The Class that implements the <code><br />
 SerializedObjectPolicy</code> interface</p>
 </td>
 <td align="left" headers="r3c1-t84 r1c3-t84"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblformalwide" -->
 <a id="sthref387" name="sthref387"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Use an <code>@SerializedObject</code> annotation to read data from the database faster. The drawback to this usage is that writing to the database is slower. Use a serialized object policy for read-only and read-mostly applications for entities and element collections.</p>
 <p>If the serialized object column contains <code>null</code> or an obsolete version of the object, then a query using a serialized object policy would either throw an exception or, if all other fields have been read as well, build the object using these fields (exactly as in the case where a serialized object policy is not used).</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>Currently, no default implementation of the <code>SerializedObjectPolicy</code> interface is available. You must provide this class.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref388" name="sthref388"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CACFCAFF">Example 2-106</a> demonstrates how to use the @SerializedObject annotation to specify a serialized object policy and how to override the default column name.</p>
 <div class="example"><a id="CACFCAFF" name="CACFCAFF"></a><a id="TLJPA54098" name="TLJPA54098"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-106 Specifying a Serialized Object Policy</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @SerializedObject(MySerializedPolicy.class);
 public class Employee {...

 @Entity
 @SerializedObject(value = MySerializedObjectPolicy.class, column = @Column(name = "SERIALIZED"));
 public class Address (...
 </pre></div>
 <!-- class="example" -->
 <p>If an @SerializedObject annotation is set on an entity object, then read queries (in addition to find and refresh) that return the object use the serialized object policy by default.</p>
 <p><a href="#CACGIGIH">Example 2-107</a> demonstrates how to prevent using the serialized object policy in a query.</p>
 <div class="example"><a id="CACGIGIH" name="CACGIGIH"></a><a id="TLJPA54099" name="TLJPA54099"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-107 Preventing the Use of a Serialized Object Policy in a Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 Query query = em.createQuery("SELECT e FROM Employee e")
 .setHint(QueryHints.SERIALIZED_OBJECT, "false");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CACGFBHH">Example 2-108</a> demonstrates how to use a serialized object policy property to prevent searching for a serialized object. .</p>
 <div class="example"><a id="CACGFBHH" name="CACGFBHH"></a><a id="TLJPA54100" name="TLJPA54100"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-108 Preventing Search Using a Serialized Object Policy Property</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 Map hints = new HashMap();
 hints.put("eclipselink.serialized-object", "false");
 Address address = em.find(Address.class, id, hints);
 </pre></div>
 <!-- class="example" -->
 <a id="sthref389" name="sthref389"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information:</p>
 <ul>
 <li>
 <p><code>SerializedObjectPolicy</code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDDEBEC6" name="CHDDEBEC6"></a><a id="TLJPA5399" name="TLJPA5399"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@StoredProcedureParameter</font></h2>
 <p>Use <code>@StoredProcedureParameter</code> within a <code>NamedStoredProcedureQuery</code> annotation.</p>
 <a id="sthref390" name="sthref390"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDDEJEC6">Table 2-70</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA54000" name="TLJPA54000"></a><a id="sthref391" name="sthref391"></a><a id="CHDDEJEC6" name="CHDDEJEC6"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-70 @StoredProcedureParameter Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@StoredProcedureParameter Annotation Elements" summary="This table describes the elements for the @StoredProcedureParameter annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="21%" />
 <col width="*" />
 <col width="14%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t86"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t86"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t86"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t86" headers="r1c1-t86">
 <p><code>queryParameter</code></p>
 </td>
 <td align="left" headers="r2c1-t86 r1c2-t86">
 <p>(Required) The query parameter name</p>
 </td>
 <td align="left" headers="r2c1-t86 r1c3-t86"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t86" headers="r1c1-t86">
 <p><code>direction</code></p>
 </td>
 <td align="left" headers="r3c1-t86 r1c2-t86">
 <p>(Optional) The direction of the stored procedure parameter:</p>
 <ul>
 <li>
 <p><code>IN</code> &#8211; Input parameter</p>
 </li>
 <li>
 <p><code>IN_OUT</code> &#8211; Input and output parameters</p>
 </li>
 <li>
 <p><code>OUT</code> &#8211; Output parameter</p>
 </li>
 <li>
 <p><code>OUT_CURSOR</code> &#8211; Output cursor</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r3c1-t86 r1c3-t86">
 <p><code>IN</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t86" headers="r1c1-t86">
 <p><code>jdbcType</code></p>
 </td>
 <td align="left" headers="r4c1-t86 r1c2-t86">
 <p>(Optional) JDBC type code. This depends on the type returned from the procedure.</p>
 </td>
 <td align="left" headers="r4c1-t86 r1c3-t86">
 <p><code>-1</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t86" headers="r1c1-t86">
 <p><code>jdbcTypeName</code></p>
 </td>
 <td align="left" headers="r5c1-t86 r1c2-t86">
 <p>(Optional) JDBC type name. This may be required for <code>ARRAY</code> or <code>STRUCT</code> types.</p>
 </td>
 <td align="left" headers="r5c1-t86 r1c3-t86"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t86" headers="r1c1-t86">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r6c1-t86 r1c2-t86">
 <p>(Optional) Stored procedure parameter name</p>
 </td>
 <td align="left" headers="r6c1-t86 r1c3-t86"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r7c1-t86" headers="r1c1-t86">
 <p><code>optional</code></p>
 </td>
 <td align="left" headers="r7c1-t86 r1c2-t86">
 <p>(Optional) Specify if the parameter is required, or optional and defaulted by the procedure.</p>
 </td>
 <td align="left" headers="r7c1-t86 r1c3-t86">
 <p><code>false</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r8c1-t86" headers="r1c1-t86">
 <p><code>type</code></p>
 </td>
 <td align="left" headers="r8c1-t86 r1c2-t86">
 <p>(Optional) Type of Java class desired back from the procedure. This depends on the <code>type</code> returned from the procedure.</p>
 </td>
 <td align="left" headers="r8c1-t86 r1c3-t86">
 <p><code>void.class</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref392" name="sthref392"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#BGBGAEFF">"@NamedStoredProcedureQuery"</a> for an example using the <code>@StoredProcedureParameter</code> annotation.</p>
 <a id="sthref393" name="sthref393"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information:</p>
 <ul>
 <li>
 <p><a href="#BGBGAEFF">"@NamedStoredProcedureQuery"</a></p>
 </li>
 <li>
 <p>Stored Procedure Examples<code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/StoredProcedures">http://wiki.eclipse.org/EclipseLink/Examples/JPA/StoredProcedures</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CBBDCAHG" name="CBBDCAHG"></a><a id="TLJPA541" name="TLJPA541"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Struct</font></h2>
 <p>Use @Struct to define a class to map to a database <code>Struct</code> type. The class should normally be an Embeddable, but could also be an Entity if stored in a object table.</p>
 <a id="sthref394" name="sthref394"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CBBCGIHG">Table 2-71</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA542" name="TLJPA542"></a><a id="sthref395" name="sthref395"></a><a id="CBBCGIHG" name="CBBCGIHG"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-71 @Struct Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Struct Annotation Elements" summary="This table describes the elements for the @Struct 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-t87"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t87"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t87"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t87" headers="r1c1-t87">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t87 r1c2-t87">
 <p>(Required) The database name of the database structure type</p>
 </td>
 <td align="left" headers="r2c1-t87 r1c3-t87"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t87" headers="r1c1-t87">
 <p><code>fields</code></p>
 </td>
 <td align="left" headers="r3c1-t87 r1c2-t87">
 <p>(Optional) Defines the order of the fields contained in the database structure type.</p>
 </td>
 <td align="left" headers="r3c1-t87 r1c3-t87"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref396" name="sthref396"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p><code>Struct</code> types are extended object-relational data-types supported by some databases. Struct types are user define types in the database such as <code>OBJECT</code> types on Oracle. Structs normally contain Arrays (<code>VARRAY</code>) or other Struct types, and can be stored in a column or a table.</p>
 <p>You can also use <code>Struct</code> types to call PL/SQL stored procedures that use <code>RECORD</code> types in an Oracle Database.</p>
 <a id="sthref397" name="sthref397"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CACCGJAJ">Example 2-109</a> shows using the <code>@Struct</code> annotation to define a Java class to map to an <code>OBJECT</code> type.</p>
 <div class="example"><a id="CACCGJAJ" name="CACCGJAJ"></a><a id="TLJPA543" name="TLJPA543"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-109 Using @Struct Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Embeddable
 <strong>@Struct(name="EMP_TYPE", fields={"F_NAME", "L_NAME", "SALARY"})</strong>
 public class Employee {
  @Column(name="F_NAME")
  private String firstName;
  @Column(name="L_NAME")
  private String lastName;
  @Column(name="SALARY")
  private BigDecimal salary;
  ...
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CBBIEDGD">Example 2-110</a> shows how to use the <code>&lt;struct&gt;</code> element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="CBBIEDGD" name="CBBIEDGD"></a><a id="TLJPA544" name="TLJPA544"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-110 Using &lt;struct&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;embeddable class="Address" access="FIELD"&gt;
   <strong>&lt;struct name="PLSQL_P_PLSQL_ADDRESS_REC"&gt;</strong>
     &lt;field&gt;ADDRESS_ID&lt;/field&gt;
     &lt;field&gt;STREET_NUM&lt;/field&gt;
     &lt;field&gt;STREET&lt;/field&gt;
     &lt;field&gt;CITY&lt;/field&gt;
     &lt;field&gt;STATE&lt;/field&gt;
   <strong>&lt;/struct&gt;</strong>
   &lt;attributes&gt;
     &lt;basic name="id"&gt;
       &lt;column name="ADDRESS_ID"/&gt;
     &lt;/basic&gt;
     &lt;basic name="number"&gt;
       &lt;column name="STREET_NUM"/&gt;
     &lt;/basic&gt;
   &lt;/attributes&gt;
 &lt;/embeddable&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref398" name="sthref398"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CACIJAFA">"@Structure"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BGBJEBBB" name="BGBJEBBB"></a><a id="TLJPA545" name="TLJPA545"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@StructConverter</font></h2>
 <p>Use <code>@StructConverter</code> to enable custom processing of <code>java.sql.Struct</code> types to process complex database types, such as spatial datatypes.</p>
 <p>EclipseLink includes the <code>JGeometryConverter</code> class to convert the Oracle <code>JGeometry</code> spatial datatype.</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>Unlike other converters, <code>@StructConverter</code> has its own interface.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref399" name="sthref399"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABJIBGI">Table 2-72</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA546" name="TLJPA546"></a><a id="sthref400" name="sthref400"></a><a id="BABJIBGI" name="BABJIBGI"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-72 @StructConverter Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@StructConverter Annotation Elements" summary="This table describes the elements for the @StructConverter annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="16%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t89"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t89"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t89"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t89" headers="r1c1-t89">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t89 r1c2-t89">
 <p>The <code>String</code> name for your converter. Ensure that this name is unique across the persistence unit.</p>
 </td>
 <td align="left" headers="r2c1-t89 r1c3-t89">
 <p>none</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t89" headers="r1c1-t89">
 <p><code>converter</code></p>
 </td>
 <td align="left" headers="r3c1-t89 r1c2-t89">
 <p>The converter class as a <code>String</code>. This class must implement the <code>org.eclipse.persistence.platform.database.converters.StructConverter</code> interface.</p>
 </td>
 <td align="left" headers="r3c1-t89 r1c3-t89">
 <p>none</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref401" name="sthref401"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You can use the existing <code>@Convert</code> annotation with its value attribute set to the <code>StructConverter</code> name &#8211; in this case, the appropriate settings are applied to the mapping. This setting is required on all mappings that use a type for which a <code>StructConverter</code> has been defined. Failing to configure the mapping with the <code>@Convert</code> will cause an error.</p>
 <p>EclipseLink also includes additional converters, such as <code><a href="#BGBBDGAI">@ObjectTypeConverter</a></code> and <code><a href="#CHDHCCJF">@TypeConverter</a></code>.</p>
 <a id="sthref402" name="sthref402"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BGBJCJCC">Example 2-111</a> shows how to define the <code>@StructConverter</code> annotation.</p>
 <div class="example"><a id="BGBJCJCC" name="BGBJCJCC"></a><a id="TLJPA547" name="TLJPA547"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-111 Using @StructConverter Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @StructConverter(
      name="JGeometryConverter"
      converter=JGeometryConverter.class.getName())
 </pre></div>
 <!-- class="example" -->
 <p>You can specify the <code>@StructConverter</code> annotation anywhere in an Entity with the scope being the whole session. An exception is thrown if you add more than one <code>StructConverter</code> annotation that affects the same Java type. An <code>@StructConverter</code> annotation exists in the same namespaces as <code>@Converter</code>. A validation exception is thrown if you add an <code>@Converter</code> and an <code>@StructConverter</code> of the same name.</p>
 <a id="sthref403" name="sthref403"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CHDCJCDE">"@StructConverters"</a></p>
 </li>
 <li>
 <p>"Default Conversions and Converters" <code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters/StructConverter">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters/StructConverter</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDCJCDE" name="CHDCJCDE"></a><a id="TLJPA548" name="TLJPA548"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@StructConverters</font></h2>
 <p>Use <code>@StructConverters</code> to define multiple <code>@StructConverter</code> annotations.</p>
 <a id="sthref404" name="sthref404"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDJDFBJ">Table 2-73</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA549" name="TLJPA549"></a><a id="sthref405" name="sthref405"></a><a id="CHDJDFBJ" name="CHDJDFBJ"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-73 @StructConverters Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@StructConverters Annotation Elements" summary="This table describes the elements for the @StructConverters annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="30%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t90"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t90"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t90"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t90" headers="r1c1-t90">
 <p><code>StructConverter[]</code></p>
 </td>
 <td align="left" headers="r2c1-t90 r1c2-t90">
 <p>(Required) An array of struct converter</p>
 </td>
 <td align="left" headers="r2c1-t90 r1c3-t90"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref406" name="sthref406"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDHGDGH">Example 2-112</a> shows how to use the <code>@StructConverters</code> annotation to define multiple <code>@StructConverter</code> elements.</p>
 <div class="example"><a id="CHDHGDGH" name="CHDHGDGH"></a><a id="TLJPA550" name="TLJPA550"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-112 Using @StructConverters Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @StructConverters{{
   @StructConverter(name="StructConverter1", converter="foo.StructConverter1"),
   @StructConverter(name="StructConverter2", converter="foo.StructConverter2")
   })
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDHGABD">Example 2-113</a> shows how to use the <code>&lt;struct-converters&gt;</code> element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="CHDHGABD" name="CHDHGABD"></a><a id="TLJPA551" name="TLJPA551"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-113 Using &lt;struct-converters&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;struct-converters&gt;
   &lt;struct-converter name="StructConverter1" converter="foo.StructConverter1"/&gt;
   &lt;struct-converter name="StructConverter2" converter="foo.StructConverter2"/&gt;
 &lt;/struct-converters&gt;

 </pre></div>
 <!-- class="example" -->
 <a id="sthref407" name="sthref407"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BGBJEBBB">"@StructConverter"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CACIJAFA" name="CACIJAFA"></a><a id="TLJPA552" name="TLJPA552"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Structure</font></h2>
 <p>Use <code>@Structure</code> on a field/method to define a <code>StructureMapping</code> to an embedded <code>Struct</code> type. The target Embeddable must be mapped using the Struct annotation.</p>
 <a id="sthref408" name="sthref408"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p>This annotation contains no elements.</p>
 <a id="sthref409" name="sthref409"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Struct types are extended object-relational data-types supported by some databases. Struct types are user define types in the database such as <code>OBJECT</code> types on Oracle. Structs can normally contains Arrays (<code>VARRAY</code>) or other Struct types, and can be stored in a column or a table.</p>
 <a id="sthref410" name="sthref410"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CACDBBII">Example 2-114</a> shows how to use the <code>@Structure</code> annotation. See <a href="#CACCGJAJ">Example 2-109</a> to an example of using <code>@Struct</code> to map the target.</p>
 <div class="example"><a id="CACDBBII" name="CACDBBII"></a><a id="TLJPA553" name="TLJPA553"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-114 Using @Structure Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Structure
 protected Address address;

 </pre></div>
 <!-- class="example" -->
 <p>You can also define structure mappings in the <code>eclipselink-orm.xml</code> file by using the <code>&lt;structure&gt;</code> element.</p>
 <div class="example"><a id="TLJPA554" name="TLJPA554"></a><a id="sthref411" name="sthref411"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-115 Using &lt;structure&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;structure name="address"/&gt;

 </pre></div>
 <!-- class="example" -->
 <a id="sthref412" name="sthref412"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CBBDCAHG">"@Struct"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHECIDGH" name="CHECIDGH"></a><a id="TLJPA555" name="TLJPA555"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@TenantDiscriminatorColumn</font></h2>
 <p>The <code>@TenantDiscriminator</code> annotation is used with the <code>@Multitenant</code> annotation and the <code>SINGLE-TABLE</code> mulitenant type to limit what a persistence context can access in single-table mulitenancy.</p>
 <a id="sthref413" name="sthref413"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHEIBAFI">Table 2-74</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA556" name="TLJPA556"></a><a id="sthref414" name="sthref414"></a><a id="CHEIBAFI" name="CHEIBAFI"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-74 @TenantDiscriminatorColumn Properties</font></em></strong></p>
 <table class="HRuleFormalWide" title="@TenantDiscriminatorColumn Properties" summary="This table describes the attributes for the @TenantDiscriminatorColumn annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="33%" />
 <col width="32%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t91"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t91"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t91"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t91" headers="r1c1-t91">
 <p><code>java.lang.String</code> <code>columnDefinition</code></p>
 </td>
 <td align="left" headers="r2c1-t91 r1c2-t91">
 <p>(Optional) The SQL fragment that is used when generating the DDL for the discriminator column</p>
 </td>
 <td align="left" headers="r2c1-t91 r1c3-t91">
 <p>The provider-generated SQL to create a column of the specified discriminator type.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t91" headers="r1c1-t91">
 <p><code>java.lang.String</code> <code>contextProperty</code></p>
 </td>
 <td align="left" headers="r3c1-t91 r1c2-t91">
 <p>(Optional) The name of the context property to apply to the tenant discriminator column</p>
 </td>
 <td align="left" headers="r3c1-t91 r1c3-t91">
 <p><code>eclipselink.tenant-id</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t91" headers="r1c1-t91">
 <p><code>DiscriminatorType</code> <code>discriminatorType</code></p>
 </td>
 <td align="left" headers="r4c1-t91 r1c2-t91">
 <p>(Optional) The type of object/column to use as a class discriminator</p>
 </td>
 <td align="left" headers="r4c1-t91 r1c3-t91">
 <p><code>javax.persistence.DiscriminatorType.STRING</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t91" headers="r1c1-t91">
 <p><code>int</code> <code>length</code></p>
 </td>
 <td align="left" headers="r5c1-t91 r1c2-t91">
 <p>(Optional) The column length for String-based discriminator types</p>
 </td>
 <td align="left" headers="r5c1-t91 r1c3-t91">
 <p>The column length for String-based discriminator types. Ignored for other discriminator types.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t91" headers="r1c1-t91">
 <p><code>java.lang.String</code> <code>name</code></p>
 </td>
 <td align="left" headers="r6c1-t91 r1c2-t91">
 <p>(Optional) The name of column to be used for the tenant discriminator</p>
 </td>
 <td align="left" headers="r6c1-t91 r1c3-t91">
 <p><code>TENANT_ID</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r7c1-t91" headers="r1c1-t91">
 <p><code>boolean</code> <code>primaryKey</code></p>
 </td>
 <td align="left" headers="r7c1-t91 r1c2-t91">
 <p>Specifies that the tenant discriminator column is part of the primary key of the tables.</p>
 </td>
 <td align="left" headers="r7c1-t91 r1c3-t91">
 <p><code>false</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r8c1-t91" headers="r1c1-t91">
 <p><code>java.lang.String</code> <code>table</code></p>
 </td>
 <td align="left" headers="r8c1-t91 r1c2-t91">
 <p>(Optional) The name of the table that contains the column</p>
 </td>
 <td align="left" headers="r8c1-t91 r1c3-t91">
 <p>The name of the table that contains the column. If absent the column is assumed to be in the primary table. This attribute must be specified if the column is on a secondary table.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref415" name="sthref415"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>To configure single-table multi-tenancy, you must specify both of the following:</p>
 <ul>
 <li>
 <p>Annotate the entity or mapped superclass to use single-table multi-tenancy, using the <code>@Multitenant</code> annotation, for example:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Table(name=&#8221;EMP&#8221;)
 @Multitenant(SINGLE_TABLE)
 </pre>
 <p><code>SINGLE_TABLE</code> states that the table or tables (<code>Table</code> and <code>SecondaryTable</code>) associated with the given entity can be shared among tenants.</p>
 <div align="center">
 <div class="inftblnote"><br />
 <table class="Note oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
 <tbody>
 <tr>
 <td align="left">
 <p class="note"><img src="../../../dcommon/images/note_icon.png" width="16" height="16" alt="Note" style="vertical-align:middle;padding-right:5px;" />Note:</p>
 <p>The <code>@Table</code> annotation is not required, because the discriminator column is assumed to be on the primary table. However, if the discriminator column is defined on a secondary table, you must identify that table using <code>@SecondaryTable</code>.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 </li>
 <li>
 <p>Specify the column or columns to be used as the discriminator column, using the <code>@TenantDiscriminatorColumn</code> annotation, for example:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Table(name=&#8221;EMP&#8221;)
 @Multitenant(SINGLE_TABLE)
 @TenantDiscriminatorColumn(name = &#8221;TENANT_ID&#8221;)
 </pre>
 <p>You can specify multiple discriminator columns by using the <code>@TenantDiscriminatorColumns</code> annotation, for example:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Table(name = "EMPLOYEE")
 @Multitenant(SINGLE_TABLE)
 @TenantDiscriminatorColumns({
     @TenantDiscriminatorColumn(name = "TENANT_ID")
     @TenantDiscriminatorColumn(name = "TENANT_CODE" contextProperty="eclipselink.tenant-code")})
 </pre></li>
 </ul>
 <a id="sthref416" name="sthref416"></a>
 <p><strong><font face="arial, helvetica, sans-serif" color="#330099">Using Discriminator Columns</font></strong></p>
 <p>The following characteristics apply to discriminator columns:</p>
 <ul>
 <li>
 <p>On persist, the values of tenant discriminator columns are populated from their associated context properties.</p>
 </li>
 <li>
 <p>Tenant discriminator columns are application definable. That is, the discriminator column is not tied to a specific column for each shared entity table. You can use <code>TENANT_ID</code>, <code>T_ID</code>, etc.</p>
 </li>
 <li>
 <p>There is no limit on how many tenant discriminator columns an application can define.</p>
 </li>
 <li>
 <p>Any name can be used for a discriminator column.</p>
 </li>
 <li>
 <p>Tenant discriminator column(s) must always be used with @Multitenant(<code>SINGLE_TABLE</code>). You cannot specify the tenant discriminator column(s) only.</p>
 </li>
 <li>
 <p>Generated schemas can include specified tenant discriminator columns.</p>
 </li>
 <li>
 <p>Tenant discriminator columns can be mapped or unmapped:</p>
 <ul>
 <li>
 <p>When a tenant discriminator column is mapped, its associated mapping attribute must be marked as read only. With this restriction in place, a tenant discriminator column cannot be part of the entity identifier; it can only be part of the primary key specification on the database.</p>
 </li>
 </ul>
 </li>
 <li>
 <p>Both mapped and unmapped properties are used to form the additional criteria when issuing a <code>SELECT</code> query.</p>
 </li>
 </ul>
 <a id="sthref417" name="sthref417"></a>
 <p><strong><font face="arial, helvetica, sans-serif" color="#330099">Using Single-Table Multi-Tenancy in an Inheritance Hierarchy</font></strong></p>
 <p>Inheritance strategies are configured by specifying the inheritance type (see @javax.persistence.Inheritance). Single-table multi-tenancy can be used in an inheritance hierarchy, as follows:</p>
 <ul>
 <li>
 <p>Multi-tenant metadata can be applied only at the root level of the inheritance hierarchy when using a <code>SINGLE_TABLE</code> or <code>JOINED</code> inheritance strategy.</p>
 </li>
 <li>
 <p>You can also specify multi-tenant metadata within a <code>TABLE_PER_CLASS</code> inheritance hierarchy. In this case, every entity has its own table, with all its mapping data (which is not the case with <code>SINGLE_TABLE</code> or <code>JOINED</code> strategies). Consequently, in the <code>TABLE_PER_CLASS</code> strategy, some entities of the hierarchy may be multi-tenant, while others may not be. The other inheritance strategies can only specify multi-tenancy at the root level, because you cannot isolate an entity to a single table to build only its type.</p>
 </li>
 </ul>
 <a id="sthref418" name="sthref418"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHEJICEF">Table 2-74</a> shows a number of uses of tenant discriminator columns.</p>
 <div class="example"><a id="CHEJICEF" name="CHEJICEF"></a><a id="TLJPA557" name="TLJPA557"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-116 Using @TenantDiscriminatorColumn Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 /** Single tenant discriminator column **/

 @Entity
 @Table(name = "CUSTOMER")
 @Multitenant
 @TenantDiscriminatorColumn(name = "TENANT", contextProperty = "multi-tenant.id")
 public Customer() {
   ...
 }


 /** Multiple tenant discriminator columns using multiple tables **/

 @Entity
 @Table(name = "EMPLOYEE")
 @SecondaryTable(name = "RESPONSIBILITIES")
 @Multitenant(SINGLE_TABLE)
 @TenantDiscriminatorColumns({
     @TenantDiscriminatorColumn(name = "TENANT_ID", contextProperty = "employee-tenant.id", length = 20)
     @TenantDiscriminatorColumn(name = "TENANT_CODE", contextProperty = "employee-tenant.code", discriminatorType = STRING, table = "RESPONSIBILITIES")
   }
 )
 public Employee() {
   ...
 }


 /** Tenant discriminator column mapped as part of the primary key on the database **/

 @Entity
 @Table(name = "ADDRESS")
 @Multitenant
 @TenantDiscriminatorColumn(name = "TENANT", contextProperty = "tenant.id", primaryKey = true)
 public Address() {
   ...
 }


 /** Mapped tenant discriminator column **/

 @Entity
 @Table(name = "Player")
 @Multitenant
 @TenantDiscriminatorColumn(name = "AGE", contextProperty = "tenant.age")
 public Player() {
   ...

   @Basic
   @Column(name="AGE", insertable="false", updatable="false")
   public int age;
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHEDCDDF">Example 2-117</a> shows the same mappings, using the <code>&lt;tenant-disciminator-column&gt;</code> XML element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="CHEDCDDF" name="CHEDCDDF"></a><a id="TLJPA558" name="TLJPA558"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-117 Using &lt;tenant-discriminator-column&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;!-- Single tenant discriminator column --&gt;

 &lt;entity class="model.Customer"&gt;
   &lt;multitenant&gt;
     &lt;tenant-discriminator-column name="TENANT context-property="multi-tenant.id""/&gt;
   &lt;/multitenant&gt;
   &lt;table name="CUSTOMER"/&gt;
   ...
 &lt;/entity&gt;

 </pre>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;!-- Multiple tenant discriminator columns using multiple tables --&gt;

 &lt;entity class="model.Employee"&gt;
   &lt;multitenant type="SINGLE_TABLE"&gt;
     &lt;tenant-discriminator-column name="TENANT_ID" context-property="employee-tenant.id" length="20"/&gt;
     &lt;tenant-discriminator-column name="TENANT_CODE" context-property="employee-tenant.id" discriminator-type="STRING" table="RESPONSIBILITIES"/&gt;
   &lt;/multitenant&gt;
   &lt;table name="EMPLOYEE"/&gt;
   &lt;secondary-table name="RESPONSIBILITIES"/&gt;
   ...
 &lt;/entity&gt;

 </pre>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;!-- Tenant discriminator column mapped as part of the primary key on the database --&gt;

 &lt;entity class="model.Address"&gt;
   &lt;multitenant&gt;
     &lt;tenant-discriminator-column name="TENANT" context-property="multi-tenant.id" primary-key="true"/&gt;
   &lt;/multitenant&gt;
   &lt;table name="ADDRESS"/&gt;
   ...
 &lt;/entity&gt;
 </pre>
 <pre xml:space="preserve" class="oac_no_warn">

 &lt;!-- Mapped tenant discriminator column --&gt;

 &lt;entity class="model.Player"&gt;
   &lt;multi-tenant&gt;
     &lt;tenant-discriminator-column name="AGE" context-property="tenant.age"/&gt;
   &lt;/multi-tenant&gt;
   &lt;table name="PLAYER"/&gt;
   ...
   &lt;attributes&gt;
     &lt;basic name="age" insertable="false" updatable="false"&gt;
       &lt;column name="AGE"/&gt;
     &lt;/basic&gt;
     ...
   &lt;/attributes&gt;
   ...
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref419" name="sthref419"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <ul>
 <li>
 <p><a href="#BABIEJGD">"@Multitenant"</a></p>
 </li>
 <li>
 <p><a href="#CECBEBEA">"@TenantDiscriminatorColumns"</a></p>
 </li>
 <li>
 <p><a href="#CHDFJJEC">"@TenantTableDiscriminator"</a></p>
 </li>
 <li>
 <p>"Using Multitenancy" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 <li>
 <p>Multitenant Examples at <code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/Multitenant">http://wiki.eclipse.org/EclipseLink/Examples/JPA/Multitenant</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CECBEBEA" name="CECBEBEA"></a><a id="TLJPA559" name="TLJPA559"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@TenantDiscriminatorColumns</font></h2>
 <p>Specify multiple discriminator columns for single-table multitenancy by using the <code>@TenantDiscriminatorColumns</code> annotation to contain multiple <code>@TenantDiscriminatorColumn</code> annotations.</p>
 <a id="sthref420" name="sthref420"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CECFFDCB">Table 2-75</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA560" name="TLJPA560"></a><a id="sthref421" name="sthref421"></a><a id="CECFFDCB" name="CECFFDCB"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-75 @TenantDiscriminatorColumns Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@TenantDiscriminatorColumns Annotation Elements" summary="This table describes the elements for the @TenantDiscriminatorColumns annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="*" />
 <col width="32%" />
 <col width="32%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t93"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t93"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t93"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t93" headers="r1c1-t93">
 <p><code>TenantDiscriminatorColumn</code> <code>value</code></p>
 </td>
 <td align="left" headers="r2c1-t93 r1c2-t93">
 <p>(Optional) One or more <code>TenantDiscriminatorColumn</code> annotations</p>
 </td>
 <td align="left" headers="r2c1-t93 r1c3-t93">
 <p>none</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref422" name="sthref422"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You must use the <code>@TenantDiscriminatorColumns</code> annotation to contain multiple <code>@TenantDiscriminatorColumn</code> annotations. The <code>@TenantDiscriminatorColumns</code> annotation cannot be used alone, and multiple the <code>@TenantDiscriminatorColumn</code> annotations cannot be used alone, without <code>@TenantDiscriminatorColumns</code>.</p>
 <a id="sthref423" name="sthref423"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Table(name = "EMPLOYEE")
 @Multitenant(SINGLE_TABLE)
 @TenantDiscriminatorColumns({
     @TenantDiscriminatorColumn(name = "TENANT_ID", contextProperty = &#8221;tenant-id)
     @TenantDiscriminatorColumn(name = "TENANT_CODE", contextProperty = &#8221;tenant-code)})
 </pre>
 <p>See <a href="#CHECIDGH">"@TenantDiscriminatorColumn"</a> for more examples of <code>@TenantDiscriminatorColumns</code>.</p>
 <a id="sthref424" name="sthref424"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <ul>
 <li>
 <p><a href="#BABIEJGD">"@Multitenant"</a></p>
 </li>
 <li>
 <p><a href="#CHECIDGH">"@TenantDiscriminatorColumn"</a></p>
 </li>
 <li>
 <p><a href="#CHDFJJEC">"@TenantTableDiscriminator"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDFJJEC" name="CHDFJJEC"></a><a id="TLJPA561" name="TLJPA561"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@TenantTableDiscriminator</font></h2>
 <p>Table-per-tenant multitenancy allows multiple tenants of an application to isolate their data in one or more tenant-specific tables. The tenant table discriminator specifies how to discriminate the tenant's tables from the other tenants' tables in a table-per-tenant multitenancy strategy.</p>
 <a id="sthref425" name="sthref425"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDGDIIC">Table 2-76</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA562" name="TLJPA562"></a><a id="sthref426" name="sthref426"></a><a id="CHDGDIIC" name="CHDGDIIC"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-76 @TenantTableDiscriminator Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@TenantTableDiscriminator Annotation Elements" summary="This table describes the elements for the @TenantTableDiscriminator 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-t94"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t94"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t94"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t94" headers="r1c1-t94">
 <p><code>java.lang.String</code> <code>ContextProperty</code></p>
 </td>
 <td align="left" headers="r2c1-t94 r1c2-t94">
 <p>(Optional) Name of the context property to apply to as tenant table discriminator</p>
 </td>
 <td align="left" headers="r2c1-t94 r1c3-t94">
 <p><code>eclipselink.tenant-id</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t94" headers="r1c1-t94">
 <p><code>TenantTableDiscriminator type</code></p>
 </td>
 <td align="left" headers="r3c1-t94 r1c2-t94">
 <p>(Optional) Type of tenant table discriminator to use with the tables of the persistence unit:</p>
 <ul>
 <li>
 <p><code>SCHEMA</code></p>
 </li>
 <li>
 <p><code>SUFFIX</code></p>
 </li>
 <li>
 <p><code>PREFIX</code></p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r3c1-t94 r1c3-t94">
 <p><code>SUFFIX</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref427" name="sthref427"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>In table-per-tenant multitenancy, tenants' tables can be in the same schema, using a prefix or suffix naming pattern to distinguish them; or they can be in separate schemas. The tenant table discriminator identifies whether to use the prefix or suffix naming pattern or to use a separate schema to identify and isolate the tenant's tables from other tenants' tables. The types are:</p>
 <ul>
 <li>
 <p><strong>Schema</strong>: Applies the tenant table discriminator as a schema to all multitenant tables. This strategy requires appropriate database provisioning.</p>
 </li>
 <li>
 <p><strong>Suffix</strong>: Applies the tenant table discriminator as a suffix to all multitenant tables. This is the default strategy.</p>
 </li>
 <li>
 <p><strong>Prefix</strong>: Applies the tenant table discriminator as a prefix to all multitenant tables.</p>
 </li>
 </ul>
 <p>Tenant table discriminator can be specified at the entity or mapped superclass level and must always be used with <code>Multitenant(TABLE_PER_TENANT)</code>. It is not sufficient to specify only a tenant table discriminator.</p>
 <p>For more information about using <code>@TenantTableDiscriminator</code> and table-per-tenant multitenancy, see <a href="#BABIEJGD">"@Multitenant"</a>.</p>
 <a id="sthref428" name="sthref428"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>The following example shows a <code>SCHEMA</code>-type table discriminator.</p>
 <div class="example"><a id="TLJPA563" name="TLJPA563"></a><a id="sthref429" name="sthref429"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-118 Using @TenantTableDiscriminator Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Table(name=&#8221;EMP&#8221;)
 @Multitenant(TABLE_PER_TENANT)
 <strong>@TenantTableDiscriminator</strong>(type=SCHEMA, contextProperty="eclipselink.tenant-id")
 public class Employee {
     ...
 }

 </pre></div>
 <!-- class="example" -->
 <div class="example"><a id="TLJPA564" name="TLJPA564"></a><a id="sthref430" name="sthref430"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-119 Using <strong>&lt;tenant-table-discriminator</strong>&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity class="Employee"&gt;
   &lt;multitenant type="TABLE_PER_TENANT"&gt;
     &lt;<strong>tenant-table-discriminator</strong> type="SCHEMA" context-property="eclipselink.tenant-id"/&gt;
   &lt;/multitenant&gt;
   &lt;table name="EMP"&gt;
   ...
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref431" name="sthref431"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <ul>
 <li>
 <p><a href="#BABIEJGD">"@Multitenant"</a></p>
 </li>
 <li>
 <p><a href="#CHECIDGH">"@TenantDiscriminatorColumn"</a></p>
 </li>
 <li>
 <p><a href="#CECBEBEA">"@TenantDiscriminatorColumns"</a></p>
 </li>
 <li>
 <p>"Using Multitenancy" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 <li>
 <p>Multitenant Examples at <code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/Multitenant">http://wiki.eclipse.org/EclipseLink/Examples/JPA/Multitenant</a></code></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BGBGACHC" name="BGBGACHC"></a><a id="TLJPA565" name="TLJPA565"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@TimeOfDay</font></h2>
 <p>Use <code>@TimeOfDay</code> to specify a specific time of day using a <code>Calendar</code> instance which is to be used within an <code>@Cache</code> annotation.</p>
 <a id="sthref432" name="sthref432"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BGBFEGGF">Table 2-77</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA566" name="TLJPA566"></a><a id="sthref433" name="sthref433"></a><a id="BGBFEGGF" name="BGBFEGGF"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-77 @TimeOfDay Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@TimeOfDay Annotation Elements" summary="This table describes the elements for the @TimeOfDay annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="19%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t95"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t95"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t95"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t95" headers="r1c1-t95">
 <p><code>hour</code></p>
 </td>
 <td align="left" headers="r2c1-t95 r1c2-t95">
 <p>(Optional) Hour of the day</p>
 </td>
 <td align="left" headers="r2c1-t95 r1c3-t95">
 <p><code>0</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t95" headers="r1c1-t95">
 <p><code>millisecond</code></p>
 </td>
 <td align="left" headers="r3c1-t95 r1c2-t95">
 <p>(Optional) Millisecond of the day</p>
 </td>
 <td align="left" headers="r3c1-t95 r1c3-t95">
 <p><code>0</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t95" headers="r1c1-t95">
 <p><code>minute</code></p>
 </td>
 <td align="left" headers="r4c1-t95 r1c2-t95">
 <p>(Optional) Minute of the day</p>
 </td>
 <td align="left" headers="r4c1-t95 r1c3-t95">
 <p><code>0</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t95" headers="r1c1-t95">
 <p><code>second</code></p>
 </td>
 <td align="left" headers="r5c1-t95 r1c2-t95">
 <p>(Optional) Second of the day</p>
 </td>
 <td align="left" headers="r5c1-t95 r1c3-t95">
 <p><code>0</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t95" headers="r1c1-t95">
 <p><code>specified</code></p>
 </td>
 <td align="left" headers="r6c1-t95 r1c2-t95">
 <p>For internal use &#8211; do not modify</p>
 </td>
 <td align="left" headers="r6c1-t95 r1c3-t95">
 <p><code>true</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref434" name="sthref434"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CHDBBIHE">"@Cache"</a> for examples of using <code>@TimeOfDay</code>.</p>
 <a id="sthref435" name="sthref435"></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>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABCJGIG" name="BABCJGIG"></a><a id="TLJPA567" name="TLJPA567"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@Transformation</font></h2>
 <p>Use <code>@Transformation</code> with a Transformation mapping to define the transformation of database columns into attribute values (unless the Transformation mapping is write-only, in which case it should have a <code>@ReadTransformer</code> annotation).</p>
 <a id="sthref436" name="sthref436"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BABFBEDA">Table 2-78</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA568" name="TLJPA568"></a><a id="sthref437" name="sthref437"></a><a id="BABFBEDA" name="BABFBEDA"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-78 @Transformation Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@Transformation Annotation Elements" summary="This table describes the elements for the @Transformation annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="21%" />
 <col width="*" />
 <col width="9%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t96"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t96"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t96"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t96" headers="r1c1-t96">
 <p><code>fetch</code></p>
 </td>
 <td align="left" headers="r2c1-t96 r1c2-t96">
 <p>(Optional) Defines whether the value of the field or property should be lazily loaded or must be eagerly fetched.</p>
 <ul>
 <li>
 <p>The <code>EAGER</code> strategy is a requirement on the persistence provider runtime that the value must be eagerly fetched.</p>
 </li>
 <li>
 <p>The <code>LAZY</code> strategy is a hint to the persistence provider runtime.</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r2c1-t96 r1c3-t96">
 <p><code>EAGER</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t96" headers="r1c1-t96">
 <p><code>optional</code></p>
 </td>
 <td align="left" headers="r3c1-t96 r1c2-t96">
 <p>(Optional) A hint as to whether the value of the field or property may be <code>null</code>. It is disregarded for primitive types, which are considered non-optional.</p>
 </td>
 <td align="left" headers="r3c1-t96 r1c3-t96">
 <p><code>true</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref438" name="sthref438"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Unless it's a read-only mapping, either <code>WriteTransformer</code> annotation or <code>WriteTransformers</code> annotation should be specified. Each <code>WriteTransformer</code> defines transformation of the attribute value to a single database column value (column is specified in the <code>WriteTransformer</code>).</p>
 <a id="sthref439" name="sthref439"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABHECGF">Example 2-120</a> shows how to use the <code>@Transformation</code> annotation.</p>
 <div class="example"><a id="BABHECGF" name="BABHECGF"></a><a id="TLJPA569" name="TLJPA569"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-120 Using @Transformation Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>@Transformation(fetch=FecthType.LAZY, optional="true")</strong>
 @ReadTransformer(class=package.MyNormalHoursTransformer.class)
 @WriteTranformers({
    @WriteTranformer(column=@Column(name="START_TIME"),
       method="getStartDate"),
    @WriteTranformer(column=@Column(name="END_TIME"),
       class=package.MyTimeTransformer.class)
 })
 @Mutable
 @ReturnUpdate
 @Access(AccessType.PROPERTY)
 @AccessMethods(get="getNormalHours", set="setNormalHours")
 @Properties({
    @Property(name="x", value="y")
 })
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BABHCBAG">Example 2-121</a> shows the same mapping, using the <code>&lt;transformation&gt;</code> XML element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="BABHCBAG" name="BABHCBAG"></a><a id="TLJPA570" name="TLJPA570"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-121 Using &lt;transformation&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>&lt;transformation name="normalHours" fetch="LAZY" optional="true"&gt;</strong>
      &lt;read-transformer method="buildNormalHours"/&gt;
      &lt;write-transformer method="getStartTime"&gt;
              &lt;column name="START_TIME"/&gt;
      &lt;/write-transformer&gt;
      &lt;write-transformer class="package.MyTimeTransformer"&gt;
              &lt;column name="END_TIME"/&gt;
      &lt;/write-transformer&gt;
      &lt;mutable/&gt;
      &lt;return-update/&gt;
      &lt;access type="PROPERTY"/&gt;
      &lt;access-methods get="getNormalHours" set="setNormalHours"/&gt;
      &lt;properties&gt;
         &lt;property name="x" value="y"/&gt;
      &lt;/properties&gt;
 <strong>&lt;/transformation&gt;</strong>
 </pre></div>
 <!-- class="example" -->
 <a id="sthref440" name="sthref440"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BGBGGAEA">"@WriteTransformer"</a></p>
 </li>
 <li>
 <p><a href="#CHDGHHBA">"@ReadTransformer"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDHCCJF" name="CHDHCCJF"></a><a id="TLJPA571" name="TLJPA571"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@TypeConverter</font></h2>
 <p>Use <code>@TypeConverter</code> to modify data values during the reading and writing of a mapped attribute.</p>
 <a id="sthref441" name="sthref441"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDIIHBI">Table 2-79</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA572" name="TLJPA572"></a><a id="sthref442" name="sthref442"></a><a id="CHDIIHBI" name="CHDIIHBI"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-79 @TypeConverter Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@TypeConverter Annotation Elements" summary="This table describes the @TypeConverter 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-t97"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t97"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t97"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t97" headers="r1c1-t97">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t97 r1c2-t97">
 <p>(Required) The <code>String</code> name for your converter. This name must be unique across the persistence unit.</p>
 </td>
 <td align="left" headers="r2c1-t97 r1c3-t97">
 <p>none</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t97" headers="r1c1-t97">
 <p><code>dataType</code></p>
 </td>
 <td align="left" headers="r3c1-t97 r1c2-t97">
 <p>(Optional) The <code>type</code> stored in the database</p>
 </td>
 <td align="left" headers="r3c1-t97 r1c3-t97">
 <p><code>void.class</code><a id="CEGBJCIH" name="CEGBJCIH" href="#CEGBJCIH" onclick='footdisplay(1,"The default is inferred from the type of the persistence field or property.")'><sup><font size="-3">Foot&nbsp;</font>1&nbsp;</sup></a></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t97" headers="r1c1-t97">
 <p><code>objectType</code></p>
 </td>
 <td align="left" headers="r4c1-t97 r1c2-t97">
 <p>(Optional) The <code>type</code> stored on the entity</p>
 </td>
 <td align="left" headers="r4c1-t97 r1c3-t97">
 <p><code>void.class</code><a id="sthref443" name="sthref443" href="#sthref443" onclick='footdisplay(1,"The default is inferred from the type of the persistence field or property.")'><sup><font size="-3">Footref&nbsp;</font>1</sup></a></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <font size="-1"><sup><font size="1">Footnote&nbsp;</font>1&nbsp;</sup>The default is inferred from the type of the persistence field or property.<br /></font><a id="sthref444" name="sthref444"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Each <code>TypeConverter</code> must be uniquely named and can be defined at the class, field and property level and can be specified within an Entity, MappedSuperclass and Embeddable class. A <code>TypeConverter</code> is always specified by using an <code>@Convert</code> annotation</p>
 <p>You can place a <code>@TypeConverter</code> on a <code>Basic</code>, <code>BasicMap</code> or <code>BasicCollection</code> mapping.</p>
 <p>EclipseLink also includes <code><a href="#BGBBDGAI">@ObjectTypeConverter</a></code> and <code><a href="#BGBJEBBB">@StructConverter</a></code> converters.</p>
 <a id="sthref445" name="sthref445"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDEHGEF">Example 2-122</a> shows how to use the <code>@TypeConverter</code> annotation to convert the <code>Double</code> value stored in the database to a <code>Float</code> value stored in the entity.</p>
 <div class="example"><a id="CHDEHGEF" name="CHDEHGEF"></a><a id="TLJPA573" name="TLJPA573"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-122 Using the @TypeConverter Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 public class Employee implements Serializable{

 ...

   <strong>@TypeConverter</strong> (
     name="doubleToFloat",
     dataType=Double.class,
     objectType=Float.class,
   )
   @Convert("doubleToFloat")
   public Number getGradePointAverage() {
     return gradePointAverage;
   }

 ...
 }
 </pre></div>
 <!-- class="example" -->
 <a id="sthref446" name="sthref446"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BEHGJHCD">"@Convert"</a></p>
 </li>
 <li>
 <p><a href="#BCFBEIAE">"@TypeConverters"</a></p>
 </li>
 <li>
 <p><a href="#CBBJAJCH">"@ConversionValue"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BCFBEIAE" name="BCFBEIAE"></a><a id="TLJPA574" name="TLJPA574"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@TypeConverters</font></h2>
 <p>Use <code>@TypeConverters</code> to define multiple <code>TypeConverter</code> elements.</p>
 <a id="sthref447" name="sthref447"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CIHJAIHB">Table 2-80</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA575" name="TLJPA575"></a><a id="sthref448" name="sthref448"></a><a id="CIHJAIHB" name="CIHJAIHB"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-80 @TypeConverters Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@TypeConverters Annotation Elements" summary="This table describes the elements for the @TypeConverters 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-t98"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t98"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t98"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t98" headers="r1c1-t98">
 <p><code>TypeConverter[]</code></p>
 </td>
 <td align="left" headers="r2c1-t98 r1c2-t98">
 <p>(Required) An array of type converter</p>
 </td>
 <td align="left" headers="r2c1-t98 r1c3-t98"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref449" name="sthref449"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BCFEHCDH">Example 2-123</a> shows how to use this annotation.</p>
 <div class="example"><a id="BCFEHCDH" name="BCFEHCDH"></a><a id="TLJPA576" name="TLJPA576"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-123 Using @TypeConverters Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 <strong>@TypeConverters</strong>({
     @TypeConverter(name="BigIntegerToString",dataType=String.class,objectType=BigInteger.class)
     })
 public class Parameters implements Serializable {
     private static final long serialVersionUID = -1979843739878183696L;
     @Column(name="maxValue", nullable=false, length=512)
     @Convert("BigIntegerToString")
     private BigInteger maxValue;
 ...
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BCFEHCDH">Example 2-123</a> shows how to use the <code>&lt;type-converters&gt;</code> element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="TLJPA577" name="TLJPA577"></a><a id="sthref450" name="sthref450"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-124 Using &lt;type-converters&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>&lt;type-converters&gt;</strong>
     &lt;type-converter name="Long2String" data-type="String" object-type="Long"/&gt;
     &lt;type-converter name="String2String" data-type="String" object-type="String"/&gt;
 &lt;/type-converters&gt;
 &lt;entity class="Employee"&gt;
 ...
 &lt;/entity&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref451" name="sthref451"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CHDHCCJF">"@TypeConverter"</a></p>
 </li>
 <li>
 <p><a href="#BEHGJHCD">"@Convert"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BCGEJFAH" name="BCGEJFAH"></a><a id="TLJPA583" name="TLJPA583"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@UnionPartitioning</font></h2>
 <p>Use <code>@UnionPartitioning</code> to send queries to all connection pools and then union the results. This can be used for queries or relationships that span partitions when partitioning is used, such as on a ManyToMany cross partition relationship.</p>
 <a id="sthref452" name="sthref452"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BCGFGGCI">Table 2-81</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA584" name="TLJPA584"></a><a id="sthref453" name="sthref453"></a><a id="BCGFGGCI" name="BCGFGGCI"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-81 @UnionPartitioning Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@UnionPartitioning Annotation Elements" summary="This table describes the elements for the @UnionPartitioning annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="24%" />
 <col width="*" />
 <col width="26%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t99"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t99"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t99"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t99" headers="r1c1-t99">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t99 r1c2-t99">
 <p>Name of the partition policy. Names must be unique for the persistence unit.</p>
 </td>
 <td align="left" headers="r2c1-t99 r1c3-t99"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t99" headers="r1c1-t99">
 <p><code>connectionPools</code></p>
 </td>
 <td align="left" headers="r3c1-t99 r1c2-t99">
 <p>List of connection pool names to load balance across</p>
 </td>
 <td align="left" headers="r3c1-t99 r1c3-t99">
 <p>Defaults to all defined pools in the <code>ServerSession</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t99" headers="r1c1-t99">
 <p><code>replicateWrite</code></p>
 </td>
 <td align="left" headers="r4c1-t99 r1c2-t99">
 <p>Defines if write queries should be replicated.</p>
 <p>Writes are normally not replicated when unioning, but can be for ManyToMany relationships, when the join table needs to be replicated.</p>
 </td>
 <td align="left" headers="r4c1-t99 r1c3-t99">
 <p><code>false</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref454" name="sthref454"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Partitioning can be enabled on an Entity, relationship, query, or session/persistence unit. Partition policies are globally named to allow reuse, the partitioning policy must also be set using the <code>@Partitioned</code> annotation to be used.</p>
 <p>The persistence unit properties support adding named connection pools in addition to the existing configuration for read/write/sequence. A named connection pool must be defined for each node in the database cluster.</p>
 <p>If a transaction modifies data from multiple partitions, you should use JTA ensure proper two-phase commit of the data. You can also configure an exclusive connection in the EntityManager to ensure that only a single node is used for a single transaction.</p>
 <a id="sthref455" name="sthref455"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CEGHAIDJ">"Using Partitioning"</a> for an example of partitioning with EclipseLink.</p>
 <a id="sthref456" name="sthref456"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Data Partitioning"<code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning</a></code></p>
 </li>
 <li>
 <p><a href="#CHDDAHEB">"@Partitioned"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CFAFIIFC" name="CFAFIIFC"></a><a id="TLJPA578" name="TLJPA578"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@UuidGenerator</font></h2>
 <p>Use <code>@UuidGenerator</code> to defines a primary key generator that may be referenced by name when a generator element is specified for the <code>@GeneratedValue</code> annotation. A UUID (universally unique identifier) generator may be specified on the entity class or on the primary key field or property.</p>
 <p>The generator name is global to the persistence unit (that is, across all generator types).</p>
 <a id="sthref457" name="sthref457"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CFAIAHJG">Table 2-82</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA579" name="TLJPA579"></a><a id="sthref458" name="sthref458"></a><a id="CFAIAHJG" name="CFAIAHJG"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-82 @UuidGenerator Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@UuidGenerator Annotation Elements" summary="This table describes the elements for the @UuidGenerator annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="21%" />
 <col width="*" />
 <col width="17%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t100"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t100"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t100"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t100" headers="r1c1-t100">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t100 r1c2-t100">
 <p>Name of the UUID generator, which must be unique for the persistence unit</p>
 </td>
 <td align="left" headers="r2c1-t100 r1c3-t100"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref459" name="sthref459"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CFADJAIF">Example 2-125</a> shows how to use this annotation.</p>
 <div class="example"><a id="CFADJAIF" name="CFADJAIF"></a><a id="TLJPA580" name="TLJPA580"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-125 Using @UuidGenerator Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 <strong>@UuidGenerator(name="EMP_ID_GEN")</strong>
 public class Employee {
     @Id
     @GeneratedValue(generator="EMP_ID_GEN")
     private String id;
 }
 </pre></div>
 <!-- class="example" -->
 <p>You can also specify the <code>SessionCustomizer</code> and configure the named sequence in your <code>eclipselink-orm.xml</code> file, as shown in <a href="#CFAGEJHJ">Example 2-126</a>.</p>
 <div class="example"><a id="CFAGEJHJ" name="CFAGEJHJ"></a><a id="TLJPA581" name="TLJPA581"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-126 Using &lt;generated-value&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;id name="id"&gt;
     &lt;column name="PROJ_ID" /&gt;
     &lt;<strong>generated-value</strong> generator="system-uuid"/&gt;
 &lt;/id&gt;
 </pre></div>
 <!-- class="example" -->
 <p>You can also specify the named sequence at the persistence unit level (in the <code>persistence.xml</code> file) as shown in <a href="#CFAJEEEJ">Example 2-127</a>.</p>
 <div class="example"><a id="CFAJEEEJ" name="CFAJEEEJ"></a><a id="TLJPA582" name="TLJPA582"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-127 Specifying Generator in persistence.xml</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;property name="eclipselink.session.customizer" value="eclipselink.example.UUIDSequence"/&gt;

 </pre></div>
 <!-- class="example" -->
 <a id="sthref460" name="sthref460"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>@Generated Value<code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Entities/Ids/GeneratedValue">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Entities/Ids/GeneratedValue</a></code></p>
 </li>
 <li>
 <p><a href="#CACGCEIJ">"Entity Annotations"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="TLJPA54063" name="TLJPA54063"></a>
 <hr />
 <div class="refsect1"><a id="sthref461" name="sthref461"></a>
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@UnionPartitioning</font></h2>
 <p>Use <code>@UnionPartitioning</code> to send queries to all connection pools and then union the results. This can be used for queries or relationships that span partitions when partitioning is used, such as on a ManyToMany cross partition relationship.</p>
 <a id="sthref462" name="sthref462"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BCGFGGCI">Table 2-81</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA54064" name="TLJPA54064"></a><a id="sthref463" name="sthref463"></a><a id="sthref464" name="sthref464"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-83 @UnionPartitioning Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@UnionPartitioning Annotation Elements" summary="This table describes the elements for the @UnionPartitioning annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="24%" />
 <col width="*" />
 <col width="26%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t101"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t101"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t101"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t101" headers="r1c1-t101">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t101 r1c2-t101">
 <p>Name of the partition policy. Names must be unique for the persistence unit.</p>
 </td>
 <td align="left" headers="r2c1-t101 r1c3-t101"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t101" headers="r1c1-t101">
 <p><code>connectionPools</code></p>
 </td>
 <td align="left" headers="r3c1-t101 r1c2-t101">
 <p>List of connection pool names to load balance across</p>
 </td>
 <td align="left" headers="r3c1-t101 r1c3-t101">
 <p>Defaults to all defined pools in the <code>ServerSession</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t101" headers="r1c1-t101">
 <p><code>replicateWrite</code></p>
 </td>
 <td align="left" headers="r4c1-t101 r1c2-t101">
 <p>Defines if write queries should be replicated.</p>
 <p>Writes are normally not replicated when unioning, but can be for ManyToMany relationships, when the join table needs to be replicated.</p>
 </td>
 <td align="left" headers="r4c1-t101 r1c3-t101">
 <p><code>false</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref465" name="sthref465"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Partitioning can be enabled on an Entity, relationship, query, or session/persistence unit. Partition policies are globally named to allow reuse, the partitioning policy must also be set using the <code>@Partitioned</code> annotation to be used.</p>
 <p>The persistence unit properties support adding named connection pools in addition to the existing configuration for read/write/sequence. A named connection pool must be defined for each node in the database cluster.</p>
 <p>If a transaction modifies data from multiple partitions, you should use JTA ensure proper two-phase commit of the data. You can also configure an exclusive connection in the EntityManager to ensure that only a single node is used for a single transaction.</p>
 <a id="sthref466" name="sthref466"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CEGHAIDJ">"Using Partitioning"</a> for an example of partitioning with EclipseLink.</p>
 <a id="sthref467" name="sthref467"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Data Partitioning"<code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning</a></code></p>
 </li>
 <li>
 <p><a href="#CHDDAHEB">"@Partitioned"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CJHFCGEJ" name="CJHFCGEJ"></a><a id="TLJPA585" name="TLJPA585"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@ValuePartition</font></h2>
 <p>Use <code>@ValuePartition</code> to represent a specific value partition that will be routed to a specific connection pool.</p>
 <a id="sthref468" name="sthref468"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CACBHEHI">Table 2-84</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA586" name="TLJPA586"></a><a id="sthref469" name="sthref469"></a><a id="CACBHEHI" name="CACBHEHI"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-84 @ValuePartition Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@ValuePartition Annotation Elements" summary="This table describes the elements for the @ValuePartition 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-t102"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t102"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t102"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t102" headers="r1c1-t102">
 <p><code>connectionPool</code></p>
 </td>
 <td align="left" headers="r2c1-t102 r1c2-t102">
 <p>The connection pool to which to route queries to for the <code>value</code></p>
 </td>
 <td align="left" headers="r2c1-t102 r1c3-t102"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t102" headers="r1c1-t102">
 <p><code>value</code></p>
 </td>
 <td align="left" headers="r3c1-t102 r1c2-t102">
 <p>The <code>String</code> representation of the value</p>
 </td>
 <td align="left" headers="r3c1-t102 r1c3-t102"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref470" name="sthref470"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CJHFDJAC">Example 2-128</a> shows how to use the <code>@ValuePartition</code> and <code>@ValuePartitioning</code> annotations.</p>
 <div class="example"><a id="CJHFDJAC" name="CJHFDJAC"></a><a id="TLJPA587" name="TLJPA587"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-128 Using @ValuePartition Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 @Table(name = "PART_EMPLOYEE")
 @IdClass(EmployeePK.class)
 <strong>@ValuePartitioning</strong>(
   name="ValuePartitioningByLOCATION",
   partitionColumn=@Column(name="LOCATION"),
   unionUnpartitionableQueries=true,
   defaultConnectionPool="default",
   partitions={
     <strong>@ValuePartition</strong>(connectionPool="node2", value="Ottawa"),
     <strong>@ValuePartition</strong>(connectionPool="node3", value="Toronto")
   })
 @Partitioned("ValuePartitioningByLOCATION")
 public class Employee implements Serializable, Cloneable {
 ...
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CJHBEIGD">Example 2-129</a> shows how to use the <code>&lt;partition&gt;</code> element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="CJHBEIGD" name="CJHBEIGD"></a><a id="TLJPA588" name="TLJPA588"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-129 Using &lt;partition&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;entity name="Employee" class="Employee" access="FIELD"&gt;
   &lt;table name="PART_EMPLOYEE"/&gt;
   &lt;id-class class="EmployeePK"/&gt;
   &lt;<strong>value-partitioning</strong> name="ValuePartitioningByLOCATION" union-unpartitionable-queries="true" default-connection-pool="default"&gt;
     &lt;partition-column name="LOCATION"/&gt;
     &lt;partition connection-pool="node2" value="Ottawa"/&gt;
     &lt;partition connection-pool="node3" value="Toronto"/&gt;
   &lt;/value-partitioning&gt;
 &lt;partitioned&gt;ValuePartitioningByLOCATION&lt;/partitioned&gt;
 </pre></div>
 <!-- class="example" -->
 <a id="sthref471" name="sthref471"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CHDDAHEB">"@Partitioned"</a></p>
 </li>
 <li>
 <p><a href="#CEGHFJDJ">"@ValuePartitioning"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CEGHFJDJ" name="CEGHFJDJ"></a><a id="TLJPA589" name="TLJPA589"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@ValuePartitioning</font></h2>
 <p>Use <code>@ValuePartitioning</code> to partition access to a database cluster by a field value from the object (such as the object's location or tenant). Each value is assigned a specific server. All write or read request for object's with that value are sent to the server. If a query does not include the field as a parameter, then it can either be sent to all server's and unioned, or left to the session's default behavior.</p>
 <a id="sthref472" name="sthref472"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CEGEGCEA">Table 2-85</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA590" name="TLJPA590"></a><a id="sthref473" name="sthref473"></a><a id="CEGEGCEA" name="CEGEGCEA"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-85 @ValuePartitioning Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@ValuePartitioning Annotation Elements" summary="This table describes the elements for the @ValuePartitioning annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <col width="12%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t103"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t103"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t103"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t103" headers="r1c1-t103">
 <p><code>name</code></p>
 </td>
 <td align="left" headers="r2c1-t103 r1c2-t103">
 <p>(Required) Name of the partition policy. Names must be unique for the persistence unit.</p>
 </td>
 <td align="left" headers="r2c1-t103 r1c3-t103"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t103" headers="r1c1-t103">
 <p><code>partitionColumn</code></p>
 </td>
 <td align="left" headers="r3c1-t103 r1c2-t103">
 <p>(Required) The database column or query parameter to partition queries by</p>
 <p>This is the table column name, not the class attribute name. The column value must be included in the query and should normally be part of the object's ID. This can also be the name of a query parameter.</p>
 <p>If a query does not contain the field the query will not be partitioned.</p>
 </td>
 <td align="left" headers="r3c1-t103 r1c3-t103"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t103" headers="r1c1-t103">
 <p><code>partitions</code></p>
 </td>
 <td align="left" headers="r4c1-t103 r1c2-t103">
 <p>(Required) Store the value partitions. Each partition maps a value to a <code>connectionPool</code>.</p>
 </td>
 <td align="left" headers="r4c1-t103 r1c3-t103"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t103" headers="r1c1-t103">
 <p><code>defaultConnectionPool</code></p>
 </td>
 <td align="left" headers="r5c1-t103 r1c2-t103">
 <p>(Optional) The default connection pool is used for any unmapped values</p>
 </td>
 <td align="left" headers="r5c1-t103 r1c3-t103"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t103" headers="r1c1-t103">
 <p><code>partitionValueType</code></p>
 </td>
 <td align="left" headers="r6c1-t103 r1c2-t103">
 <p>(Optional) The <code>type</code> of the start and end values</p>
 </td>
 <td align="left" headers="r6c1-t103 r1c3-t103">
 <p><code>String</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r7c1-t103" headers="r1c1-t103">
 <p><code>unionUnpartitionableQueries</code></p>
 </td>
 <td align="left" headers="r7c1-t103 r1c2-t103">
 <p>(Optional) Defines if queries that do not contain the partition field should be sent to every database and have the result unioned.</p>
 </td>
 <td align="left" headers="r7c1-t103 r1c3-t103">
 <p><code>false</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref474" name="sthref474"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Partitioning can be enabled on an Entity, relationship, query, or session/persistence unit. Partition policies are globally named to allow reuse, the partitioning policy must also be set using the <code>@Partitioned</code> annotation to be used.</p>
 <p>The persistence unit properties support adding named connection pools in addition to the existing configuration for read/write/sequence. A named connection pool must be defined for each node in the database cluster.</p>
 <p>If a transaction modifies data from multiple partitions, you should use JTA ensure proper two-phase commit of the data. You can also configure an exclusive connection in the EntityManager to ensure that only a single node is used for a single transaction.</p>
 <a id="sthref475" name="sthref475"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#CEGHAIDJ">"Using Partitioning"</a> for an example of partitioning with EclipseLink.</p>
 <a id="sthref476" name="sthref476"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Data Partitioning"<code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Data_Partitioning</a></code></p>
 </li>
 <li>
 <p><a href="#CHDDAHEB">"@Partitioned"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDDFDGF" name="CHDDFDGF"></a><a id="TLJPA591" name="TLJPA591"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@VariableOneToOne</font></h2>
 <p>Use <code>@VariableOneToOne</code> to represent a pointer references between a java object and an implementer of an interface. This mapping is usually represented by a single pointer (stored in an instance variable) between the source and target objects. In the relational database tables, these mappings are normally implemented using a foreign key and a type code.</p>
 <a id="sthref477" name="sthref477"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CHDGHCBF">Table 2-86</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA592" name="TLJPA592"></a><a id="sthref478" name="sthref478"></a><a id="CHDGHCBF" name="CHDGHCBF"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-86 @VariableOneToOne Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@VariableOneToOne Annotation Elements" summary="This table describes the elements for the @VariableOneToOne annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="23%" />
 <col width="*" />
 <col width="36%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t104"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t104"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t104"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t104" headers="r1c1-t104">
 <p><code>CascadeType</code></p>
 </td>
 <td align="left" headers="r2c1-t104 r1c2-t104">
 <p>(Optional) Array of operations that must be cascaded to the target of the association</p>
 </td>
 <td align="left" headers="r2c1-t104 r1c3-t104"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t104" headers="r1c1-t104">
 <p><code>DiscriminatorClasses</code></p>
 </td>
 <td align="left" headers="r3c1-t104 r1c2-t104">
 <p>(Optional) Array of discriminator types that can be used with this mapping</p>
 </td>
 <td align="left" headers="r3c1-t104 r1c3-t104">
 <p>If none are specified, EclipseLink adds entities within the persistence unit that implement the target interface.</p>
 <p>If <code>DiscriminatorColumn</code> is <code>STRING</code>, EclipseLink uses <code>Entity.name()</code>.</p>
 <p>If <code>DiscriminatorColumn</code> is <code>CHAR</code>, EclipseLink uses the first letter of the entity class.</p>
 <p>If <code>DiscriminatorColumn</code> is <code>INTEGER</code>, EclipseLink uses the next integer after the highest integer explicitly stated.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t104" headers="r1c1-t104">
 <p><code>DiscriminatorColumn</code></p>
 </td>
 <td align="left" headers="r4c1-t104 r1c2-t104">
 <p>(Optional) The discriminator column that contains the type identifiers</p>
 </td>
 <td align="left" headers="r4c1-t104 r1c3-t104">
 <p><code>DTYPE</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t104" headers="r1c1-t104">
 <p><code>FetchType</code></p>
 </td>
 <td align="left" headers="r5c1-t104 r1c2-t104">
 <p>(Optional) Specify how the value of the field or property should be loaded:</p>
 <ul>
 <li>
 <p><strong>Eager</strong>: Requires that the persistence provider runtime must eagerly fetch the value</p>
 </li>
 <li>
 <p><strong>Lazy</strong>: Hints that the persistence provider should lazily load the value</p>
 </li>
 </ul>
 </td>
 <td align="left" headers="r5c1-t104 r1c3-t104">
 <p><code>Eager</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t104" headers="r1c1-t104">
 <p><code>Optional</code></p>
 </td>
 <td align="left" headers="r6c1-t104 r1c2-t104">
 <p>(Optional) Specify if the association is optional.</p>
 </td>
 <td align="left" headers="r6c1-t104 r1c3-t104"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r7c1-t104" headers="r1c1-t104">
 <p><code>OrphanRemoval</code></p>
 </td>
 <td align="left" headers="r7c1-t104 r1c2-t104">
 <p>(Optional) Specify if interface class that is the target of this mapping.</p>
 </td>
 <td align="left" headers="r7c1-t104 r1c3-t104"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r8c1-t104" headers="r1c1-t104">
 <p><code>TargetInterface</code></p>
 </td>
 <td align="left" headers="r8c1-t104 r1c2-t104">
 <p>(Optional) The interface class that is the target of this mapping</p>
 </td>
 <td align="left" headers="r8c1-t104 r1c3-t104">
 <p>If none is specified, EclipseLink will infer the interface class based on the type of object being referenced.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref479" name="sthref479"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You can specify <code>@VariableOneToOne</code> on an Entity, MappedSuperclass, or Embeddable class.</p>
 <a id="sthref480" name="sthref480"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDJDIJD">Example 2-130</a> shows how to use the <code>@VariableOneToOne</code> annotation.</p>
 <div class="example"><a id="CHDJDIJD" name="CHDJDIJD"></a><a id="TLJPA593" name="TLJPA593"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-130 Using @VariableOneToOne Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>@VariableOneToOne</strong>(
     cascade={ALL},
     fetch=LAZY,
     discriminatorColumn=@DiscriminatorColumn(name="CONTACT_TYPE"),
     discriminatorClasses={
         @DiscriminatorClass(discriminator="E", value="Email.class"),
         @DiscriminatorClass(discriminator="P", value="Phone.class")
     }
 }
 @JoinColumn(name="CONTACT_ID", referencedColumnName="C_ID")
 @PrivateOwned
 @JoinFetch(INNER)
 public Contact getContact() {
     return contact;
 }
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDCBGAF">Example 2-131</a> shows the same mapping using the <code>&lt;variable-one-to-one&gt;</code> XML element in the <code>eclipselink-orm.xml</code> file.</p>
 <div class="example"><a id="CHDCBGAF" name="CHDCBGAF"></a><a id="TLJPA594" name="TLJPA594"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-131 Using &lt;variable-one-to-one&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 <strong>&lt;variable-one-to-one name="contact" fetch="LAZY"&gt;</strong>
     &lt;cascade&gt;
         &lt;cascade-all/&gt;
     &lt;/cascade&gt;
     &lt;discriminator-column name="CONTACT_TYPE"/&gt;
     &lt;discriminator-class discriminator="E" value="Email.class"/&gt;
     &lt;discriminator-class discriminator="P" value="Phone.class"/&gt;
     &lt;join-column name="CONTACT_ID" referenced-column-name="C_ID"/&gt;
     &lt;private-owned/&gt;
     &lt;join-fetch&gt;INNER&lt;/join-fetch&gt;
 <strong>&lt;/variable-one-to-one&gt;</strong>
 </pre></div>
 <!-- class="example" -->
 <a id="sthref481" name="sthref481"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CIHGDDED">"@DiscriminatorClass"</a></p>
 </li>
 <li>
 <p><a href="#CHDDDDAI">"@PrivateOwned"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CIHFBCFI" name="CIHFBCFI"></a><a id="TLJPA595" name="TLJPA595"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@VirtualAccessMethods</font></h2>
 <p>Use <code>@VirtualAccessMethods</code> to specify that a specific class contains virtual methods.</p>
 <a id="sthref482" name="sthref482"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#CIHCCFIH">Table 2-87</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA596" name="TLJPA596"></a><a id="sthref483" name="sthref483"></a><a id="CIHCCFIH" name="CIHCCFIH"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-87 @VirtualAccessMethods Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@VirtualAccessMethods Annotation Elements" summary="This table describes the elements for the @VirtualAccessMethods 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-t105"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t105"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t105"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t105" headers="r1c1-t105">
 <p><code>get</code></p>
 </td>
 <td align="left" headers="r2c1-t105 r1c2-t105">
 <p>(Optional) Name of the <code>getter</code> method to use for the virtual property. This method must take a single <code>java.lang.String</code> parameter and return a <code>java.lang.Object</code>.</p>
 <p>If <code>get</code> is specified, you must also specify <code>set</code>.</p>
 </td>
 <td align="left" headers="r2c1-t105 r1c3-t105">
 <p><code>get</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t105" headers="r1c1-t105">
 <p>set</p>
 </td>
 <td align="left" headers="r3c1-t105 r1c2-t105">
 <p>(Optional) Name of the <code>setter</code> method to use for the virtual property. This method must take a <code>java.lang.String</code> parameter and a <code>java.lang.Object</code> parameter.</p>
 <p>If <code>set</code> is specified, you must also specify <code>get</code>.</p>
 </td>
 <td align="left" headers="r3c1-t105 r1c3-t105">
 <p><code>set</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref484" name="sthref484"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Use the <code>@VirtualAccessMethods</code> annotation to define access methods for mappings with in which <code>accessType</code>=VIRTUAL.</p>
 <a id="sthref485" name="sthref485"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CIHCCFIH">Table 2-87</a> shows an entity using property access.</p>
 <div class="example"><a id="TLJPA597" name="TLJPA597"></a><a id="sthref486" name="sthref486"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-132 Using @VirtualAccessMethods Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @Entity
 <strong>  @VirtualAccessMethods</strong>
   public class Customer{

     @Id
     private int id;
 ...

     @Transient
     private Map&lt;String, Object&gt; extensions;

     public &lt;T&gt; T get(String name) {
         return (T) extensions.get(name);
     }

     public Object set(String name, Object value) {
         return extensions.put(name, value);
     }
 </pre></div>
 <!-- class="example" -->
 <p>In addition to using the <code>@VirtualAccessMethods</code> annotation, you can use the <code>&lt;access&gt;</code> and <code>&lt;access-method&gt;</code> elements in your <code>eclipselink-orm.xml</code> file, as shown in <a href="#CIHCJCJE">Example 2-133</a>.</p>
 <div class="example"><a id="CIHCJCJE" name="CIHCJCJE"></a><a id="TLJPA598" name="TLJPA598"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 2-133 Using &lt;access&gt; and &lt;access-methods&gt; XML</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;access&gt;VIRTUAL&lt;/access&gt;&lt;access-methods get-method="get" set-method="set"/&gt;@Entity
 </pre></div>
 <!-- class="example" -->
 <a id="sthref487" name="sthref487"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Extensible Entities"<code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Extensible_Entities">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Extensible_Entities</a></code></p>
 </li>
 <li>
 <p>"Making JPA Entities and JAXB Beans Extensible" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BGBGGAEA" name="BGBGGAEA"></a><a id="TLJPA599" name="TLJPA599"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@WriteTransformer</font></h2>
 <p>Use <code>@WriteTransformer</code> on a <code>TranformationMapping</code> to transform a single attribute value to a single database column value. Use the <code>@WriteTransformers</code> annotation to wrap multiple transformations.</p>
 <a id="sthref488" name="sthref488"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BGBEGIEE">Table 2-88</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA600" name="TLJPA600"></a><a id="sthref489" name="sthref489"></a><a id="BGBEGIEE" name="BGBEGIEE"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-88 @WriteTransformer Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@WriteTransformer Annotation Elements" summary="This table describes the elements for the @WriteTransformer annotation." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="19%" />
 <col width="*" />
 <col width="29%" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t106"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t106"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t106"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t106" headers="r1c1-t106">
 <p><code>column</code></p>
 </td>
 <td align="left" headers="r2c1-t106 r1c2-t106">
 <p>(Optional) The column into which the value should be written</p>
 <p>If a single <code>WriteTransfomer</code> annotates an attribute, the attribute's name will be used as the column name.</p>
 </td>
 <td align="left" headers="r2c1-t106 r1c3-t106">
 <p><code>@javax.persistence.Column</code></p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t106" headers="r1c1-t106">
 <p><code>method</code></p>
 </td>
 <td align="left" headers="r3c1-t106 r1c2-t106">
 <p>(Optional) The <code>String</code> method name that the mapped class must have. This method returns the value to be written into the database column.</p>
 <p><strong>Note</strong>: To support DDL generation and returning policy, the method should be defined to return a particular type, not just an <code>Object</code>. For example:<code>public Time getStartTime()</code></p>
 <p>The method may require <code>@Transient</code> to avoid being mapped as a <code>Basic</code> by default.</p>
 </td>
 <td align="left" headers="r3c1-t106 r1c3-t106"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t106" headers="r1c1-t106">
 <p><code>transformerClass</code></p>
 </td>
 <td align="left" headers="r4c1-t106 r1c2-t106">
 <p>(Optional) User-defined class that implements the <code>FieldTransformer</code> interface. This will instantiate the class and use its <code>buildFieldValue</code> method to create the value to be written into the database column.</p>
 <p><strong>Note</strong>: To support DDL generation and returningpolicy, the method <code>buildFieldValue</code> in the class should be defined to return the relevant Java type, not just <code>Object</code> as defined in the interface. For example:<code>public Time buildFieldValue(Object instance, String fieldName, Session session).</code></p>
 </td>
 <td align="left" headers="r4c1-t106 r1c3-t106">
 <p><code>void.class</code></p>
 </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 <code>transformerClass</code> <em>or</em> <code>method</code> , but not both.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref490" name="sthref490"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You cannot define a <code>@WriteTransforme</code>r for a read-only mapping.</p>
 <p>Unless the <code>TransformationMapping</code> is write-only, it should include a <code>ReadTransformer</code> that defines the transformation of the database column values into attribute values.</p>
 <a id="sthref491" name="sthref491"></a>
 <p><strong><font face="arial, helvetica, sans-serif" color="#330099">Configuring Field Transformer Associations</font></strong></p>
 <p>Using a <code>FieldTransformer</code> is non-intrusive; your domain object does not need to implement an EclipseLink interface or provide a special transformation method.</p>
 <p>You can configure a method-based field transformer using <code>AbstractTransformationMapping</code> method <code>addFieldTransformation</code>, passing in the name of the database field and the name of the domain object method to use.</p>
 <p>You can configure a class-based field transformer using <code>AbstractTransformationMapping</code> method <code>addFieldTransformer</code>, passing in the name of the database field and an instance of <code>org.eclipse.persistence.mappings.Transfomers.FieldTransformer</code>.</p>
 <p>A convenient way to create a <code>FieldTransformer</code> is to extend <code>FieldTransformerAdapter</code>.</p>
 <a id="sthref492" name="sthref492"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#BABHECGF">"Using @Transformation Annotation"</a> for an example of how to use the <code>@WriteTransformer annotation</code> with a Transformation mapping.</p>
 <a id="sthref493" name="sthref493"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BCFCCEJF">"@WriteTransformers"</a></p>
 </li>
 <li>
 <p><a href="#BABCJGIG">"@Transformation"</a>.</p>
 </li>
 <li>
 <p>http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Print_Version#How_to_Use_the_.40Transformation_Annotation</p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BCFCCEJF" name="BCFCCEJF"></a><a id="TLJPA601" name="TLJPA601"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">@WriteTransformers</font></h2>
 <p>Use <code>@WriteTransformer</code> on a <code>TranformationMapping</code> to transform a single attribute value to a single database column value. Use the <code>@WriteTransformers</code> annotation to wrap multiple transformations.</p>
 <a id="sthref494" name="sthref494"></a>
 <p><strong><br /><span class="refsubsect">Annotation Elements</span></strong></p>
 <p><a href="#BCFBFAIF">Table 2-89</a> describes this annotation's elements.</p>
 <div class="tblhruleformalwide"><a id="TLJPA602" name="TLJPA602"></a><a id="sthref495" name="sthref495"></a><a id="BCFBFAIF" name="BCFBFAIF"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 2-89 @WriteTransformers Annotation Elements</font></em></strong></p>
 <table class="HRuleFormalWide" title="@WriteTransformers Annotation Elements" summary="This table describes the elements for the @WriteTransformers 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-t108"><font face="Arial, Helvetica, sans-serif"><strong>Annotation Element</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t108"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 <th align="left" valign="bottom" id="r1c3-t108"><font face="Arial, Helvetica, sans-serif"><strong>Default</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t108" headers="r1c1-t108">
 <p><code>WriteTransformer</code></p>
 </td>
 <td align="left" headers="r2c1-t108 r1c2-t108">
 <p>An array of <code>WriteTransformer</code></p>
 </td>
 <td align="left" headers="r2c1-t108 r1c3-t108"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref496" name="sthref496"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You cannot use <code>@WriteTransforme</code>rs for a read-only mapping.</p>
 <a id="sthref497" name="sthref497"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p>See <a href="#BABHECGF">"Using @Transformation Annotation"</a> for an example of how to use the <code>@WriteTransformer annotation</code> with a Transformation mapping.</p>
 <a id="sthref498" name="sthref498"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BGBGGAEA">"@WriteTransformer"</a>.</p>
 </li>
 <li>
 <p><a href="#BABCJGIG">"@Transformation"</a>.</p>
 </li>
 <li>
 <p>http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Print_Version#How_to_Use_the_.40Transformation_Annotation</p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" --></div>
 <!-- class="ind" -->
 <!-- Start Footer -->
 <div class="footer">
 <hr />
 <table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
 <col width="33%" />
 <col width="*" />
 <col width="33%" />
 <tr>
 <td valign="bottom">
 <table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
 <col width="*" />
 <col width="48%" />
 <col width="48%" />
 <tr>
 <td>&nbsp;</td>
 <td align="center"><a href="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>
 </tr>
 </table>
 </td>
 <td align="center" width="34%"><a href="http://www.eclipse.org/eclipselink/" title="EclipseLink home"><img src="../../../dcommon/images/ellogo.png" alt="EclipseLink" width="150" border="0" /></a><br />
 <font size="-2">Copyright&nbsp;&#169;&nbsp;2014,&nbsp;Oracle&nbsp;and/or&nbsp;its&nbsp;affiliates.&nbsp;All&nbsp;rights&nbsp;reserved.</font> <a href="../../../dcommon/html/cpyr.htm"><br />

 <td valign="bottom" align="right">
 <table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="225">
 <tr>
 <td>&nbsp;</td>
 <td align="center" valign="top"><a href="toc.htm"><img src="../../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
 </td><td>&nbsp;</td><td align="center"><a href="../../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../../eclipselink_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>
 </div>
 <!-- class="footer" -->
 <div id="copyright">Copyright &copy; 2014 by The Eclipse Foundation under the <a href="http://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License (EPL)</a><br /> <script type="text/javascript">var LastUpdated = document.lastModified;document.writeln ("Updated: " + LastUpdated);</script> </div><!-- START: Analytics --><script type="text/javascript">		  var _gaq = _gaq || [];		  _gaq.push(['_setAccount', 'UA-1608008-2']);		  _gaq.push(['_trackPageview']);				  (function() {		    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;		    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';		    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);		  })();				</script><!-- END: Analytics --><!-- START: Sharethis --><script>var options={ "publisher": "e2fe9e07-fab6-4f84-83ea-0991b429842c", "position": "right", "ad": { "visible": false, "openDelay": 5, "closeDelay": 0}};var st_hover_widget = new sharethis.widgets.hoverbuttons(options);</script><!-- END: Sharethis --></body>
 </html>