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

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
 <meta http-equiv="Content-Style-Type" content="text/css" />
 <meta http-equiv="Content-Script-Type" content="text/javascript" />
 <title>JPA Query Customization Extensions | 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:49Z" />
 <meta name="description" content="This chapter describes how to specify EcpliseLink query hints (JPA query extensions). You can specify EclipseLink query hints (JPA query extensions) by:" />
 <meta name="robots" content="noarchive" />
 <meta name="doctitle" content="JPA Query Customization Extensions" />
 <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="jpql.htm" title="Previous" type="text/html" />
 <link rel="next" href="persistenceproperties_ref.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="jpql.htm"><img src="../../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
 <td align="center"><a href="persistenceproperties_ref.htm"><img src="../../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
 <td>&nbsp;</td>
 </tr>
 </table>
 </div>
 <!-- class="header" -->
 <div class="ind"><!-- End Header --><a id="TLJPA634" name="TLJPA634"></a> <a id="sthref533" name="sthref533"></a>
 <h1 class="chapter"><font face="arial, helvetica, sans-serif" color="#330099"><span class="secnum">4</span> JPA Query Customization Extensions</font></h1>
 <a id="TLJPA54068" name="TLJPA54068"></a>
 <p>This chapter describes how to specify EcpliseLink query hints (JPA query extensions). You can specify EclipseLink query hints (JPA query extensions) by:</p>
 <ul>
 <li>
 <p>Using the <code>@QueryHint</code> annotation</p>
 </li>
 <li>
 <p>Including the hints in the <code>orm.xml</code> or <code>eclipselink-orm.xml</code> file</p>
 </li>
 <li>
 <p>Using the <code>setHint()</code> method when executing a named or dynamic query (JPQL or Criteria)</p>
 </li>
 </ul>
 <p>EclipseLink supplies the following query hints:</p>
 <ul>
 <li>
 <p><code><a href="#batch">batch</a></code></p>
 </li>
 <li>
 <p><code><a href="#BABHCJIH">batch.size</a></code></p>
 </li>
 <li>
 <p><code><a href="#BABFGHAA">batch.type</a></code></p>
 </li>
 <li>
 <p><code><a href="#cacheusage">cache-usage</a></code></p>
 </li>
 <li>
 <p><code><a href="#BABDBIDI">cache-usage.indirection-policy</a></code></p>
 </li>
 <li>
 <p><code><a href="#BABBGFJA">cursor</a></code></p>
 </li>
 <li>
 <p><code><a href="#CHDDFIDC">composite-unit.member</a></code></p>
 </li>
 <li>
 <p><code><a href="#CHDJJCHG">cursor.initial-size</a></code></p>
 </li>
 <li>
 <p><code><a href="#CACIGJGE">cursor.page-size</a></code></p>
 </li>
 <li>
 <p><code><a href="#BABJFGGC">exclusive-connection</a></code></p>
 </li>
 <li>
 <p><code><a href="#CBHFHGEB">flush</a></code></p>
 </li>
 <li>
 <p><code><a href="#CACDJCBE">history.as-of</a></code></p>
 </li>
 <li>
 <p><code><a href="#BDCBGEJG">history.as-of.scn</a></code></p>
 </li>
 <li>
 <p><code><a href="#BABEDHJB">inheritance.outer-join</a></code></p>
 </li>
 <li>
 <p><code><a href="#bindparameters">jdbc.bind-parameters</a></code></p>
 </li>
 <li>
 <p><code><a href="#BABCHAFD">jdbc.cache-statement</a></code></p>
 </li>
 <li>
 <p><code><a href="#fetchsize">jdbc.fetch-size</a></code></p>
 </li>
 <li>
 <p><code><a href="#BHAGGAIA">jdbc.first-result</a></code></p>
 </li>
 <li>
 <p><code><a href="#maxrows">jdbc.max-rows</a></code></p>
 </li>
 <li>
 <p><code><a href="#CACCHBBG">jdbc.native-connection</a></code></p>
 </li>
 <li>
 <p><code><a href="#CHDEBFHE">jdbc.parameter-delimiter</a></code></p>
 </li>
 <li>
 <p><code><a href="#timeout">jdbc.timeout</a></code></p>
 </li>
 <li>
 <p><code><a href="#fetch">join-fetch</a></code></p>
 </li>
 <li>
 <p><code><a href="#CHDEFDDC">left-join-fetch</a></code></p>
 </li>
 <li>
 <p><code><a href="#BABIJCGD">load-group</a></code></p>
 </li>
 <li>
 <p><code><a href="#CACEDHDG">load-group.attribute</a></code></p>
 </li>
 <li>
 <p><code><a href="#maintaincache">maintain-cache</a></code></p>
 </li>
 <li>
 <p><code><a href="#pessimisticlock">pessimistic-lock</a></code></p>
 </li>
 <li>
 <p><code><a href="#CHDGDECH">prepare</a></code></p>
 </li>
 <li>
 <p><code><a href="#CHDGEADJ">query-results-cache</a></code></p>
 </li>
 <li>
 <p><code><a href="#BABHGIHG">query-results-cache.expiry</a></code></p>
 </li>
 <li>
 <p><code><a href="#CBAFBFJA">query-results-cache.expiry-time-of-day</a></code></p>
 </li>
 <li>
 <p><code><a href="#CHDHGGBD">query-results-cache.ignore-null</a></code></p>
 </li>
 <li>
 <p><code><a href="#BEIGHCEF">query-results-cache.randomize-expiry</a></code></p>
 </li>
 <li>
 <p><code><a href="#CACJDDDG">query-results-cache.size</a></code></p>
 </li>
 <li>
 <p><code><a href="#CACCFFDA">query-results-cache.type</a></code></p>
 </li>
 <li>
 <p><code><a href="#querytype">query-type</a></code></p>
 </li>
 <li>
 <p><code><a href="#readonly">read-only</a></code></p>
 </li>
 <li>
 <p><code><a href="#refresh">refresh</a></code></p>
 </li>
 <li>
 <p><code><a href="#refreshcache">refresh.cascade</a></code></p>
 </li>
 <li>
 <p><code><a href="#BABCJADG">result-collection-type</a></code></p>
 </li>
 <li>
 <p><code><a href="#CIHHAEDE">sql.hint</a></code></p>
 </li>
 </ul>
 <p>All EclipseLink query hints are defined in the <code>QueryHints</code> class in the <code>org.eclipse.persistence.config package</code>. When you set a hint, you can set the value using the public static final field in the appropriate configuration class in <code>org.eclipse.persistence.config</code> package, including the following:</p>
 <ul>
 <li>
 <p><code>HintValues</code></p>
 </li>
 <li>
 <p><code>CacheUsage</code></p>
 </li>
 <li>
 <p><code>PessimisticLock</code></p>
 </li>
 <li>
 <p><code>QueryType</code></p>
 </li>
 </ul>
 <p>For more information, see Section 10.3.1 "NamedQuery Annotation" in the JPA Specification (<code><a href="http://jcp.org/en/jsr/detail?id=317">http://jcp.org/en/jsr/detail?id=317</a></code>).</p>
 <a id="batch" name="batch"></a><a id="TLJPA635" name="TLJPA635"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">batch</font></h2>
 <p>Use <code>eclipselink.batch</code> to supply EclipseLink with batching information so subsequent queries of related objects can be optimized in batches, instead of being retrieved one-by-one or in one large joined read.</p>
 <a id="sthref534" name="sthref534"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p>This query hint accepts a single-valued, relationship path expression.</p>
 <a id="sthref535" name="sthref535"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Using the <code>eclipselink.batch</code> hint is more efficient than joining, because EclipseLink avoids reading duplicate data.</p>
 <p>You can only batch queries that have a single object in the select clause.</p>
 <p>Valid values: a single-valued relationship path expression.</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>Use <em>dot notation</em> to access nested attributes. For example, to batch-read an employee's manager's address, use <code>e.manager.address</code>.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref536" name="sthref536"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CBHCBIJB">Example 4-1</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CBHCBIJB" name="CBHCBIJB"></a><a id="TLJPA636" name="TLJPA636"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-1 Using batch in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.batch", "e.address");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CBHJEGBF">Example 4-2</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="CBHJEGBF" name="CBHJEGBF"></a><a id="TLJPA637" name="TLJPA637"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-2 Using batch in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.BATCH, value="e.address");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref537" name="sthref537"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"EclipseLink" JPA Query Hints <code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Query_Hints">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Query_Hints</a></code></p>
 </li>
 <li>
 <p><a href="#fetch">"join-fetch"</a></p>
 </li>
 <li>
 <p><a href="#BABHCJIH">"batch.size"</a></p>
 </li>
 <li>
 <p><a href="#BABFGHAA">"batch.type"</a></p>
 </li>
 <li>
 <p>"Querying" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABHCJIH" name="BABHCJIH"></a><a id="TLJPA723" name="TLJPA723"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">batch.size</font></h2>
 <p>Use <code>eclipselink.batch.size</code> to configure the batch size when using <code><a href="#BABFGHAA">batch.type</a></code> set to <code>IN</code>.</p>
 <a id="sthref538" name="sthref538"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#BABEJGHF">Table 4-1</a> describes this persistence property's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA724" name="TLJPA724"></a><a id="sthref539" name="sthref539"></a><a id="BABEJGHF" name="BABEJGHF"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-1 Valid Values for batch.size</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for batch.size" summary="This table describes the valid values for the batch.size extension." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t3"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t3"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t3" headers="r1c1-t3">
 <p>Size</p>
 </td>
 <td align="left" headers="r2c1-t3 r1c2-t3">
 <p>The number of keys in each <code>IN</code> clause</p>
 <p>Default: <strong>256</strong> or the query's <code>pageSize</code> (for cursor queries)</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref540" name="sthref540"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABHIGJA">Example 4-3</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="BABHIGJA" name="BABHIGJA"></a><a id="TLJPA54028" name="TLJPA54028"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-3 Using batch.size in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.BATCH_SIZE", "3");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BABIHJJH">Example 4-4</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="BABIHJJH" name="BABIHJJH"></a><a id="TLJPA54029" name="TLJPA54029"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-4 Using batch.size in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.BATCH_SIZE, value="3");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref541" name="sthref541"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#batch">"batch"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABFGHAA" name="BABFGHAA"></a><a id="TLJPA727" name="TLJPA727"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">batch.type</font></h2>
 <p>Use <code>eclipselink.batch.type</code> to specify the type of batch fetching the query should use for any batch-fetched relationships.</p>
 <a id="sthref542" name="sthref542"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#CBAEHJEE">Table 4-2</a> describes this query hint's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA728" name="TLJPA728"></a><a id="sthref543" name="sthref543"></a><a id="CBAEHJEE" name="CBAEHJEE"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-2 Valid Values for batch.type</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for batch.type" summary="This table describes the valid values for the batch.type extension." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t4"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t4"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t4" headers="r1c1-t4">
 <p><code>JOIN</code></p>
 </td>
 <td align="left" headers="r2c1-t4 r1c2-t4">
 <p>(Default) The original query's selection criteria is joined with the batch query.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t4" headers="r1c1-t4">
 <p><code>EXISTS</code></p>
 </td>
 <td align="left" headers="r3c1-t4 r1c2-t4">
 <p>Uses an SQL <code>EXISTS</code> and a sub-select in the batch query instead of a join.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t4" headers="r1c1-t4">
 <p><code>IN</code></p>
 </td>
 <td align="left" headers="r4c1-t4 r1c2-t4">
 <p>Uses an SQL <code>IN</code> clause in the batch query passing in the source object IDs.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref544" name="sthref544"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABGBHFC">Example 4-5</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="BABGBHFC" name="BABGBHFC"></a><a id="TLJPA54030" name="TLJPA54030"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-5 Using batch.type in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.BATCH_TYPE", "EXISTS");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BABFGECF">Example 4-6</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="BABFGECF" name="BABFGECF"></a><a id="TLJPA54031" name="TLJPA54031"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-6 Using batch.type in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.BATCH_TYPE, value="EXISTS");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref545" name="sthref545"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#batch">"batch"</a></p>
 </li>
 <li>
 <p><a href="annotations_ref.htm#CHDCCIDA">"@BatchFetch"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="cacheusage" name="cacheusage"></a><a id="TLJPA638" name="TLJPA638"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">cache-usage</font></h2>
 <p>Use <code>eclipselink.cache-usage</code> to specify how the query should interact with the EclipseLink cache.</p>
 <a id="sthref546" name="sthref546"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#BABEIJAE">Table 4-3</a> describes this query hint's valid values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA639" name="TLJPA639"></a><a id="sthref547" name="sthref547"></a><a id="BABEIJAE" name="BABEIJAE"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-3 Valid Values for org.eclipse.persistence.config.CacheUsage</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for org.eclipse.persistence.config.CacheUsage" summary="This table describes the valid values for the org.eclipse.persistence.config.CacheUsage query hint." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t5"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t5"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t5" headers="r1c1-t5">
 <p><code>DoNotCheckCache</code></p>
 </td>
 <td align="left" headers="r2c1-t5 r1c2-t5">
 <p>Always go to the database.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t5" headers="r1c1-t5">
 <p><code>CheckCacheByExactPrimaryKey</code></p>
 </td>
 <td align="left" headers="r3c1-t5 r1c2-t5">
 <p>If a read-object query contains an expression where the primary key is the only comparison, you can obtain a cache hit if you process the expression against the object in memory</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t5" headers="r1c1-t5">
 <p><code>CheckCacheByPrimaryKey</code></p>
 </td>
 <td align="left" headers="r4c1-t5 r1c2-t5">
 <p>If a read-object query contains an expression that compares at least the primary key, you can obtain a cache hit if you process the expression against the objects in memory.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t5" headers="r1c1-t5">
 <p><code>CheckCacheThenDatabase</code></p>
 </td>
 <td align="left" headers="r5c1-t5 r1c2-t5">
 <p>You can configure any read-object query to check the cache completely before you resort to accessing the database.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r6c1-t5" headers="r1c1-t5">
 <p><code>CheckCacheOnly</code></p>
 </td>
 <td align="left" headers="r6c1-t5 r1c2-t5">
 <p>You can configure any read-all query to check only the parent session cache (shared cache) and return the result from it without accessing the database.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r7c1-t5" headers="r1c1-t5">
 <p><code>ConformResultsInUnitOfWork</code></p>
 </td>
 <td align="left" headers="r7c1-t5 r1c2-t5">
 <p>You can configure any read-object or read-all query within the context of a unit of work to conform the results with the changes to the object made within that unit of work. This includes new objects, deleted objects and changed objects.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r8c1-t5" headers="r1c1-t5">
 <p><code>UseEntityDefault</code></p>
 </td>
 <td align="left" headers="r8c1-t5 r1c2-t5">
 <p>(Default) Use the cache configuration as specified by the EclipseLink descriptor API for this entity.</p>
 <p><strong>Note</strong>: The entity default value is to not check the cache (<code>DoNotCheckCache</code>). The query will access the database and synchronize with the cache. Unless refresh has been set on the query, the cached objects will be returned without being refreshed from the database. EclipseLink does not support the cache usage for native queries or queries that have complex result sets such as returning data or multiple objects.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref548" name="sthref548"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>EclipseLink JPA uses a shared cache assessed across the entire persistence unit. After completing an operation in a particular persistence context, EclipseLink merges the results into the shared cache, so that other persistence contexts can use the results <em>regardless of whether the entity manager and persistence context are created in Java SE or Java EE</em>.</p>
 <p>Any entity persisted or removed using the entity manager will always consistently maintained with the cache.</p>
 <a id="sthref549" name="sthref549"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABCBJAH">Example 4-7</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="BABCBJAH" name="BABCBJAH"></a><a id="TLJPA640" name="TLJPA640"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-7 Using cache-usage in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.CacheUsage;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint(QueryHints.CACHE_USAGE, CacheUsage.CheckCacheOnly);
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BABBFCGD">Example 4-8</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="BABBFCGD" name="BABBFCGD"></a><a id="TLJPA641" name="TLJPA641"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-8 Using cache-usage in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.CacheUsage;
  import org.eclipse.persistence.config.TargetDatabase;
  @QueryHint(name=QueryHints.CACHE_USAGE, value=CacheUsage.CheckCacheOnly);

 </pre></div>
 <!-- class="example" -->
 <a id="sthref550" name="sthref550"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"EclipseLink Caches" in <em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p>"Querying" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 <li>
 <p>"Enhancing Performance" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 <li>
 <p><a href="#BABDBIDI">"cache-usage.indirection-policy"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABDBIDI" name="BABDBIDI"></a><a id="TLJPA731" name="TLJPA731"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">cache-usage.indirection-policy</font></h2>
 <p>Use <code>eclipselink.cache-usage.indirection-policy</code> (with <a href="#cacheusage">cache-usage</a>) to configure in-memory querying and conforming's treatment of uninstantiated indirection/lazy relationships.</p>
 <a id="sthref551" name="sthref551"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#CBAHAACF">Table 4-4</a> describes this query hint's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA732" name="TLJPA732"></a><a id="sthref552" name="sthref552"></a><a id="CBAHAACF" name="CBAHAACF"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-4 Valid Values for cache-usage.indirection-policy</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for cache-usage.indirection-policy" summary="This table describes the valid values for the cache-usage.indirection-policy extension." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t6"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t6"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t6" headers="r1c1-t6">
 <p><code>Conform</code></p>
 </td>
 <td align="left" headers="r2c1-t6 r1c2-t6">
 <p>If conforming encounters an uninstantiated indirection/lazy object, it is assumed to conform.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t6" headers="r1c1-t6">
 <p><code>Exception</code></p>
 </td>
 <td align="left" headers="r3c1-t6 r1c2-t6">
 <p>(Default) If conforming encounters an uninstantiated indirection/lazy object an exception is thrown.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t6" headers="r1c1-t6">
 <p><code>NotConform</code></p>
 </td>
 <td align="left" headers="r4c1-t6 r1c2-t6">
 <p>If conforming encounters an uninstantiated indirection/lazy object it is assumed to not conform.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r5c1-t6" headers="r1c1-t6">
 <p><code>Trigger</code></p>
 </td>
 <td align="left" headers="r5c1-t6 r1c2-t6">
 <p>If conforming encounters an uninstantiated indirection/lazy object it is triggered.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref553" name="sthref553"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>This hint applies only when the query traverses a <code>join</code> across a lazy relationship.</p>
 <a id="sthref554" name="sthref554"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDGHCAF">Example 4-9</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CHDGHCAF" name="CHDGHCAF"></a><a id="TLJPA733" name="TLJPA733"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-9 Using cache-usage.indirection-policy in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 query.setHint(QueryHints.INDIRECTION_POLICY, CacheUsageIndirectionPolicy.Trigger);
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDEFCID">Example 4-10</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="CHDEFCID" name="CHDEFCID"></a><a id="TLJPA734" name="TLJPA734"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-10 Using cache-usage.indirection-policy in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 @QueryHint(name=QueryHints.INDIRECTION_POLICY, value=CacheUsageIndirectionPolicy.Trigger)
 </pre></div>
 <!-- class="example" -->
 <a id="sthref555" name="sthref555"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"EclipseLink" JPA Query Hints <code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Query_Hints">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Query_Hints</a></code></p>
 </li>
 <li>
 <p>"EclipseLink Caches" in <em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p>"Querying" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 <li>
 <p><a href="#cacheusage">"cache-usage"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABBGFJA" name="BABBGFJA"></a><a id="TLJPA735" name="TLJPA735"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">cursor</font></h2>
 <p>Use <code>eclipselink.cursor</code> to configure the query to return a <code>CursoredStream</code>.</p>
 <a id="sthref556" name="sthref556"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#BABDGGBI">Table 4-5</a> describes this persistence property's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA736" name="TLJPA736"></a><a id="sthref557" name="sthref557"></a><a id="BABDGGBI" name="BABDGGBI"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-5 Valid Values for cursor</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for cursor" summary="This table describes the valid values for the cursor extension." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t7"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t7"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t7" headers="r1c1-t7">
 <p><code>true</code></p>
 </td>
 <td align="left" headers="r2c1-t7 r1c2-t7"><br /></td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t7" headers="r1c1-t7">
 <p><code>false</code></p>
 </td>
 <td align="left" headers="r3c1-t7 r1c2-t7">
 <p>(Default)</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref558" name="sthref558"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>A <em>Cursor</em> is a stream of the JDBC <code>ResultSet</code>. Cursors are useful for large results sets, or when you only need the few results of a query.</p>
 <p>A cursor implements <code>Enumeration</code>, when the each <code>next()</code> will fetch the next from the JDBC <code>ResultSet</code>, and builds the resulting Object or value. A Cursor requires, and will keep, a live JDBC connection. You must use <code>close()</code> to free the Cursor's resources.</p>
 <p>You can access a Cursor from a JPA Query through <code>getSingleResult()</code>, or from <code>JpaQuery</code> using <code>getResultCursor()</code>.</p>
 <div align="center">
 <div class="inftblnotealso"><br />
 <table class="NoteAlso 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>Tip:</strong></font></p>
 <p>You can use <code>MAX_ROWS</code> and <code>FIRST_RESULT</code> instead of a Cursor to obtain a page of results.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnotealso" --></div>
 <a id="sthref559" name="sthref559"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABHFHEG">Example 4-11</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="BABHFHEG" name="BABHFHEG"></a><a id="TLJPA54032" name="TLJPA54032"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-11 Using cursor in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.cursor", "TRUE");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BABFADCA">Example 4-12</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="BABFADCA" name="BABFADCA"></a><a id="TLJPA54033" name="TLJPA54033"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-12 Using cursor in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.CURSOR, value="TRUE");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref560" name="sthref560"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CHDJJCHG">"cursor.initial-size"</a></p>
 </li>
 <li>
 <p><a href="#CACIGJGE">"cursor.page-size"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDDFIDC" name="CHDDFIDC"></a><a id="TLJPA54134" name="TLJPA54134"></a>
 <hr />
 <div class="refsect1"><!-- infolevel="all" infotype="General" -->
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">composite-unit.member</font></h2>
 <p>The ecliplselink.composite-unit.member query hint specifies the name of the composite member persistence unit on which you want to execute the query. You must use it on a native query executed on a composite persistence unit.</p>
 <a id="sthref561" name="sthref561"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#CHDIAHAB">Table 4-6</a> describes this persistence property's values.</p>
 <div class="tblformalwide"><a id="TLJPA54135" name="TLJPA54135"></a><a id="sthref562" name="sthref562"></a><a id="CHDIAHAB" name="CHDIAHAB"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-6 Valid Values for composite-unit.member</font></em></strong></p>
 <table class="FormalWide" title="Valid Values for composite-unit.member" summary="This table describes the valid values for the composite-unit.member persistence property." dir="ltr" border="1" width="100%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
 <col width="25%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t9"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t9"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t9" headers="r1c1-t9">
 <p>value</p>
 </td>
 <td align="left" headers="r2c1-t9 r1c2-t9">
 <p>The name of the composite persistence unit.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblformalwide" -->
 <a id="sthref563" name="sthref563"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDEJEAE">Example 4-13</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CHDEJEAE" name="CHDEJEAE"></a><a id="TLJPA54136" name="TLJPA54136"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-13 Using composite-unit.member in a JPA query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.composite-unit.member", "mypersistentunit");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDDJEAA">Example 4-14</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="CHDDJEAA" name="CHDDJEAA"></a><a id="TLJPA54137" name="TLJPA54137"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-14 Using composite-unit.member in an @QueryHint annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.COMPOSITE_UNIT_MEMBER,
 value="mypersistentunit");
 </pre></div>
 <!-- class="example" --></div>
 <!-- class="refsect1" -->
 <a id="CHDJJCHG" name="CHDJJCHG"></a><a id="TLJPA739" name="TLJPA739"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">cursor.initial-size</font></h2>
 <p>Use <code>eclipselink.cursor.initial-size</code> to configure the query to return a CursoredStream with the specified initial size.</p>
 <a id="sthref564" name="sthref564"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#CHDBDJEA">Table 4-7</a> describes this query hint's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA740" name="TLJPA740"></a><a id="sthref565" name="sthref565"></a><a id="CHDBDJEA" name="CHDBDJEA"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-7 Valid Values for cursor.initial-size</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for cursor.initial-size" summary="This table describes the valid values for the cursor.initial-size extension." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t10"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t10"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t10" headers="r1c1-t10">
 <p><code>Integer</code> or <code>Strings</code> that can be parsed to <code>int</code> values</p>
 </td>
 <td align="left" headers="r2c1-t10 r1c2-t10">
 <p>The initial number of objects that are prebuilt for the stream before a <code>next()</code> is called</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref566" name="sthref566"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDIIBJH">Example 4-15</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CHDIIBJH" name="CHDIIBJH"></a><a id="TLJPA741" name="TLJPA741"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-15 Using cursor.initial-size in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.cursor_initial_size", "10");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDIHGDI">Example 4-16</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="CHDIHGDI" name="CHDIHGDI"></a><a id="TLJPA742" name="TLJPA742"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-16 Using cursor.initial-size in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.CURSOR_INITIAL_SIZE, value="10");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref567" name="sthref567"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BABBGFJA">"cursor"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CACIGJGE" name="CACIGJGE"></a><a id="TLJPA54069" name="TLJPA54069"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">cursor.page-size</font></h2>
 <p>Use <code>eclipselink.cursor.page-size</code> to configure the query to return a <code>CursoredStream</code> with the specified page size.</p>
 <a id="sthref568" name="sthref568"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#BABEBBJJ">Table 4-8</a> describes this query hint's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA54070" name="TLJPA54070"></a><a id="sthref569" name="sthref569"></a><a id="BABEBBJJ" name="BABEBBJJ"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-8 Valid Values for cursor.page-size</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for cursor.page-size" summary="This table describes the valid values for the cursor.page-size extension." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t11"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t11"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t11" headers="r1c1-t11">
 <p><code>Integer</code> or <code>Strings</code> that can be parsed to <code>int</code> values</p>
 </td>
 <td align="left" headers="r2c1-t11 r1c2-t11">
 <p>The number of objects that are fetched from the stream on a <code>next()</code> call, if the buffer of objects is empty</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref570" name="sthref570"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDIAFBG">Example 4-17</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CHDIAFBG" name="CHDIAFBG"></a><a id="TLJPA54071" name="TLJPA54071"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-17 Using cursor.page-size in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.CURSOR_PAGE_SIZE", "10");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDIACBG">Example 4-18</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="CHDIACBG" name="CHDIACBG"></a><a id="TLJPA54072" name="TLJPA54072"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-18 Using cursor.page-size in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.CURSOR_PAGE_SIZE, value="10");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref571" name="sthref571"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BABBGFJA">"cursor"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABJFGGC" name="BABJFGGC"></a><a id="TLJPA747" name="TLJPA747"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">exclusive-connection</font></h2>
 <p>Use <code>eclipselink.exclusive-connection</code> to specify if the query should use the exclusive (transactional/write) connection.</p>
 <a id="sthref572" name="sthref572"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#BABGGEAH">Table 4-9</a> describes this query hint's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA748" name="TLJPA748"></a><a id="sthref573" name="sthref573"></a><a id="BABGGEAH" name="BABGGEAH"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-9 Valid Values for exclusive-connection</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for exclusive-connection" summary="This table describes the valid values for the exclusive-connection extension." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t12"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t12"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t12" headers="r1c1-t12">
 <p>true</p>
 </td>
 <td align="left" headers="r2c1-t12 r1c2-t12">
 <p>The query is executed through the exclusive connection.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t12" headers="r1c1-t12">
 <p>false</p>
 </td>
 <td align="left" headers="r3c1-t12 r1c2-t12"><br /></td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref574" name="sthref574"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>This is valid only when an <code>EXCLUSIVE_CONNECTION_MODE</code> property has been set for the persistence unit (such as VPD). If a <code><a href="persistenceproperties_ref.htm#CACBICGG2">jdbc.exclusive-connection.mode</a></code> has been configured, use this query hint to ensure that the query is executed through the exclusive connection.</p>
 <p>This may be required in certain cases, such as when database security prevents a query joining to a secure table from returning the correct results, when executed through the shared connection.</p>
 <a id="sthref575" name="sthref575"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDHHEGA">Example 4-19</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CHDHHEGA" name="CHDHHEGA"></a><a id="TLJPA749" name="TLJPA749"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-19 Using exclusive-connection in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.EXCLUSIVE_CONNECTION", "TRUE");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDIGEII">Example 4-20</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="CHDIGEII" name="CHDIGEII"></a><a id="TLJPA750" name="TLJPA750"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-20 Using exclusive-connection in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.EXCLUSIVE_CONNECTION, value="TRUE");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref576" name="sthref576"></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#CACBICGG2">"jdbc.exclusive-connection.mode"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CBHFHGEB" name="CBHFHGEB"></a><a id="TLJPA751" name="TLJPA751"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">flush</font></h2>
 <p>Use <code>eclipselink.flush</code> to specify if the query should flush the persistence context before executing.</p>
 <a id="sthref577" name="sthref577"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#CBAGCCIH">Table 4-10</a> describes this query hint's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA752" name="TLJPA752"></a><a id="sthref578" name="sthref578"></a><a id="CBAGCCIH" name="CBAGCCIH"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-10 Valid Values for flush</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for flush" summary="This table describes the valid values for the flush extension." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t13"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t13"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t13" headers="r1c1-t13">
 <p><code>true</code></p>
 </td>
 <td align="left" headers="r2c1-t13 r1c2-t13">
 <p>The query triggers a flush of the persistence context before execution</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t13" headers="r1c1-t13">
 <p><code>false</code></p>
 </td>
 <td align="left" headers="r3c1-t13 r1c2-t13">
 <p>(Default)</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref579" name="sthref579"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>If the query may access objects that have been changed in the persistence context, you must trigger a flush in order for the query to see the changes. If the query does not require seeing the changes, you should avoid the flush in order to improve performance.</p>
 <p>You can also configure the flush-mode as a persistence unit property. See <a href="persistenceproperties_ref.htm#CDEJGBEI">"flush-clear.cache"</a> for more information.</p>
 <p>You can also use conforming to query changes without requiring a flush. See <a href="#cacheusage">"cache-usage"</a> for more information.</p>
 <a id="sthref580" name="sthref580"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDGGHHG">Example 4-21</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CHDGGHHG" name="CHDGGHHG"></a><a id="TLJPA753" name="TLJPA753"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-21 Using flush in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.FLUSH", "TRUE");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDHDACD">Example 4-22</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="CHDHDACD" name="CHDHDACD"></a><a id="TLJPA754" name="TLJPA754"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-22 Using flush in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.FLUSH, value="TRUE");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref581" name="sthref581"></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#BABDHEEB">"persistence-context.flush-mode"</a></p>
 </li>
 <li>
 <p><a href="persistenceproperties_ref.htm#CDEJGBEI">"flush-clear.cache"</a></p>
 </li>
 <li>
 <p>"EclipseLink" JPA Query Hints <code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Query_Hints">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Query_Hints</a></code></p>
 </li>
 <li>
 <p>"EclipseLink Caches" in <em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p>"Querying" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 <li>
 <p><a href="#BABDBIDI">"cache-usage.indirection-policy"</a></p>
 </li>
 <li>
 <p><a href="#cacheusage">"cache-usage"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CACDJCBE" name="CACDJCBE"></a><a id="TLJPA755" name="TLJPA755"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">history.as-of</font></h2>
 <p>Configures the query to query the state of the object as-of a point in time.</p>
 <a id="sthref582" name="sthref582"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#CACFHAJC">Table 4-11</a> describes this query hint's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA756" name="TLJPA756"></a><a id="sthref583" name="sthref583"></a><a id="CACFHAJC" name="CACFHAJC"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-11 Valid Values for history.as-of</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for history.as-of" summary="This table describes the valid values for the history.as-of extension." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t14"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t14"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t14" headers="r1c1-t14">
 <p>Timestamp</p>
 </td>
 <td align="left" headers="r2c1-t14 r1c2-t14">
 <p>Timestamp, in the form: <code>YYYY/MM/DD HH:MM:SS.n</code></p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref584" name="sthref584"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Both the query execution and result will conform to the database as it existed based on the database SCN.</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>This query hint requires a class with historical support or when using Oracle Flashback.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref585" name="sthref585"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDGCFEI">Example 4-23</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CHDGCFEI" name="CHDGCFEI"></a><a id="TLJPA757" name="TLJPA757"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-23 Using history.as-of in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.AS_OF", "2012/10/15 11:21:18.2");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDIEAIC">Example 4-24</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="CHDIEAIC" name="CHDIEAIC"></a><a id="TLJPA758" name="TLJPA758"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-24 Using history.as-of in @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.AS_OF, value="2012/10/15 11:21:18.2");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref586" name="sthref586"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BDCBGEJG">"history.as-of.scn"</a></p>
 </li>
 <li>
 <p>"Using Oracle Flashback Technology" in <em>Oracle Database Advanced Application Developer's Guide</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BDCBGEJG" name="BDCBGEJG"></a><a id="TLJPA759" name="TLJPA759"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">history.as-of.scn</font></h2>
 <p>Use <code>eclipselink.history.as-of.scn</code> to configure the query to query the state of the object as-of a database SCN (System Change Number).</p>
 <a id="sthref587" name="sthref587"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#CBACAFGG">Table 4-12</a> describes this query hint's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA760" name="TLJPA760"></a><a id="sthref588" name="sthref588"></a><a id="CBACAFGG" name="CBACAFGG"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-12 Valid Values for history.as-of.scn</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for history.as-of.scn" summary="This table describes the valid values for the history.as-of.scn extension." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t16"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t16"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t16" headers="r1c1-t16">
 <p>value</p>
 </td>
 <td align="left" headers="r2c1-t16 r1c2-t16">
 <p>Integer SCN value</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref589" name="sthref589"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></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>This query hint requires Oracle Flashback support.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref590" name="sthref590"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDGAJAB">Example 4-25</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CHDGAJAB" name="CHDGAJAB"></a><a id="TLJPA761" name="TLJPA761"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-25 Using history.as-of.scn in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.AS_OF_SCN", "3");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDIHCFG">Example 4-26</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="CHDIHCFG" name="CHDIHCFG"></a><a id="TLJPA762" name="TLJPA762"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-26 Using history.as-of.scn in @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.AS_OF_SCN, value="3");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref591" name="sthref591"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CACDJCBE">"history.as-of"</a></p>
 </li>
 <li>
 <p>"Using Oracle Flashback Technology" in <em>Oracle Database Advanced Application Developer's Guide</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABEDHJB" name="BABEDHJB"></a><a id="TLJPA763" name="TLJPA763"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">inheritance.outer-join</font></h2>
 <p>Use <code>eclipselink.inheritance.outer-join</code> to configure the query to use an outer-join for all subclasses.</p>
 <a id="sthref592" name="sthref592"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#CBAGHABJ">Table 4-13</a> describes this query hint's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA764" name="TLJPA764"></a><a id="sthref593" name="sthref593"></a><a id="CBAGHABJ" name="CBAGHABJ"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-13 Valid Values for inheritance.outer-join</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for inheritance.outer-join" summary="This table describes the valid values for the inheritance.outer-join extension." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t18"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t18"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t18" headers="r1c1-t18">
 <p><code>true</code></p>
 </td>
 <td align="left" headers="r2c1-t18 r1c2-t18">
 <p>Use outer-join.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t18" headers="r1c1-t18">
 <p><code>false</code></p>
 </td>
 <td align="left" headers="r3c1-t18 r1c2-t18">
 <p>(Default) Do not use outer-join; execute a separate query for each subclass.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref594" name="sthref594"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>This query hint can be used queries to root or branch inherited classes.</p>
 <p>You can also configure this behavior by using a <code>DescriptorCustomizer</code> (see <a href="persistenceproperties_ref.htm#CCHIEAIA">"descriptor.customizer"</a>).</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>This is required for correct ordering, <code>firstResult</code>, <code>maxResult</code>, and cursors.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref595" name="sthref595"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDICAFC">Example 4-27</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CHDICAFC" name="CHDICAFC"></a><a id="TLJPA765" name="TLJPA765"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-27 Using inheritance.outer-join in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.INHERITANCE_OUTER_JOIN", "TRUE");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDIFIJJ">Example 4-28</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="CHDIFIJJ" name="CHDIFIJJ"></a><a id="TLJPA54034" name="TLJPA54034"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-28 Using inheritance.outer-join in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.INHERITANCE_OUTER_JOIN, value="TRUE");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref596" name="sthref596"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Inheritance" in <em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p>"Enhancing Performance" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="bindparameters" name="bindparameters"></a><a id="TLJPA642" name="TLJPA642"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">jdbc.bind-parameters</font></h2>
 <p>Use <code>eclipselink.jdbc.bind-parameters</code> to specify if the query uses parameter binding (parameterized SQL).</p>
 <a id="sthref597" name="sthref597"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#BABHJFEJ">Table 4-14</a> describes this query hint's valid values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA643" name="TLJPA643"></a><a id="sthref598" name="sthref598"></a><a id="BABHJFEJ" name="BABHJFEJ"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-14 Valid Values for org.eclipse.persistence.config.HintValues</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for org.eclipse.persistence.config.HintValues" summary="This table describes the valid values for the org.eclipse.persistence.config.HintValues query hint." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t20"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t20"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t20" headers="r1c1-t20">
 <p><code>TRUE</code></p>
 </td>
 <td align="left" headers="r2c1-t20 r1c2-t20">
 <p>Bind all parameters.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t20" headers="r1c1-t20">
 <p><code>FALSE</code></p>
 </td>
 <td align="left" headers="r3c1-t20 r1c2-t20">
 <p>Do not bind all parameters.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t20" headers="r1c1-t20">
 <p><code>PERSISTENCE_UNIT_DEFAULT</code></p>
 </td>
 <td align="left" headers="r4c1-t20 r1c2-t20">
 <p>(Default) Use the parameter binding setting made in your EclipseLink session's database login, which is true by default.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref599" name="sthref599"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>By default, EclipseLink enables parameter binding and statement caching. This causes EclipseLink to use a prepared statement, binding all SQL parameters and caching the prepared statement. When you re-execute this query, you avoid the SQL preparation, which improves performance.</p>
 <p>You can also configure parameter binding for the persistence unit in the <code>persistence.xml</code> file (when used in a Java SE environment).</p>
 <a id="sthref600" name="sthref600"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABGDCJA">Example 4-29</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="BABGDCJA" name="BABGDCJA"></a><a id="TLJPA644" name="TLJPA644"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-29 Using bind-parameters in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint(QueryHints.BIND_PARAMETERS, HintValues.TRUE);
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BABIHAEJ">Example 4-30</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="BABIHAEJ" name="BABIHAEJ"></a><a id="TLJPA645" name="TLJPA645"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-30 Using bind-parameters in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.TargetDatabase;
  @QueryHint(name=QueryHints.BIND_PARAMETERS, value=HintValues.TRUE);
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BABFBBJD">Example 4-31</a> shows how to configure parameter binding in the persistence unit <code>persistence.xml</code> file.</p>
 <div class="example"><a id="BABFBBJD" name="BABFBBJD"></a><a id="TLJPA646" name="TLJPA646"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-31 Specifying Parameter Binding Persistence Unit Property</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 &lt;property name="eclipselink.jdbc.bind-parameters" value="false"/&gt;
 </pre>
 <p>Or by importing a <code>property</code> map:</p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.PersistenceUnitProperties;
 propertiesMap.put(PersistenceUnitProperties.NATIVE_SQL, "true");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref601" name="sthref601"></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#CHDHAFAA">"jdbc.cache-statements"</a></p>
 </li>
 <li>
 <p><a href="persistenceproperties_ref.htm#CIHJADHF">"jdbc.batch-writing.size"</a></p>
 </li>
 <li>
 <p>"Parameterized SQL and Statement Caching" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABCHAFD" name="BABCHAFD"></a><a id="TLJPA766" name="TLJPA766"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">jdbc.cache-statement</font></h2>
 <p>Specify if the query caches its JDBC statement.</p>
 <a id="sthref602" name="sthref602"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#CHDIBGGB">Table 4-15</a> describes this query hint's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA767" name="TLJPA767"></a><a id="sthref603" name="sthref603"></a><a id="CHDIBGGB" name="CHDIBGGB"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-15 Valid Values for jdbc.cache-statement</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for jdbc.cache-statement" summary="This table describes the valid values for the jdbc.cache-statement extension." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t21"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t21"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t21" headers="r1c1-t21">
 <p><code>true</code></p>
 </td>
 <td align="left" headers="r2c1-t21 r1c2-t21">
 <p>The query will cache its JDBC statement.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t21" headers="r1c1-t21">
 <p><code>false</code></p>
 </td>
 <td align="left" headers="r3c1-t21 r1c2-t21">
 <p>(Default)</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref604" name="sthref604"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>This allows queries to use parameterized SQL with statement caching. It also allows a specific query to not cache its statement, if statement caching is enable for the persistence unit.</p>
 <div align="center">
 <div class="inftblnotealso"><br />
 <table class="NoteAlso 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>Tip:</strong></font></p>
 <p>Normally, you should set statement caching for the entire persistence unit (see <a href="persistenceproperties_ref.htm#CHDHAFAA">"jdbc.cache-statements"</a>) instead of each query.</p>
 <p>When using a <code>DataSource</code>, you must set statement caching in the <code>DataSource</code> configuration.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnotealso" --></div>
 <a id="sthref605" name="sthref605"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDIAHFI">Example 4-32</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CHDIAHFI" name="CHDIAHFI"></a><a id="TLJPA54035" name="TLJPA54035"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-32 Using jdbc.cache-statement in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.CACHE_STATEMENT", "TRUE");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDHEDDG">Example 4-33</a> shows how to use this hint in the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="CHDHEDDG" name="CHDHEDDG"></a><a id="TLJPA54036" name="TLJPA54036"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-33 Using jdbc.cache-statement in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.CACHE_STATEMENT, value="TRUE");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref606" name="sthref606"></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#CHDHAFAA">"jdbc.cache-statements"</a></p>
 </li>
 <li>
 <p>"Enhancing Performance" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="fetchsize" name="fetchsize"></a><a id="TLJPA647" name="TLJPA647"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">jdbc.fetch-size</font></h2>
 <p>Use <code>eclipselink.jdbc.fetch-size</code> to specify the number of rows to be fetched from the database when additional rows are needed.</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>This property requires JDBC driver support.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref607" name="sthref607"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#CHDHHCFG">Table 4-16</a> describes this query hint's valid values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA648" name="TLJPA648"></a><a id="sthref608" name="sthref608"></a><a id="CHDHHCFG" name="CHDHHCFG"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-16 Valid Values for eclipselink.jdbc.fetch-size</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for eclipselink.jdbc.fetch-size" summary="This table describes the valid values for the eclipselink.jdbc.fetch-size query hint." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t24"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t24"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t24" headers="r1c1-t24">
 <p>from <code>0</code> to <code>Integer.MAX_VALUE</code></p>
 </td>
 <td align="left" headers="r2c1-t24 r1c2-t24">
 <p>(Default = <code>0</code>) As a <code>String</code>, depending on your JDBC driver.</p>
 <p>If 0, the JDBC driver default will be used.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref609" name="sthref609"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>For queries that return a large number of objects, you can configure the row fetch size used in the query to improve performance by reducing the number database hits required to satisfy the selection criteria.</p>
 <p>By default, most JDBC drivers use a fetch size of 10. , so if you are reading 1000 objects, increasing the fetch size to 256 can significantly reduce the time required to fetch the query's results. The optimal fetch size is not always obvious. Usually, a fetch size of one half or one quarter of the total expected result size is optimal.</p>
 <p>If you are unsure of the result set size, incorrectly setting a fetch size too large or too small can decrease performance.</p>
 <a id="sthref610" name="sthref610"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDBEBDE">Example 4-34</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CHDBEBDE" name="CHDBEBDE"></a><a id="TLJPA649" name="TLJPA649"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-34 Using jdbc.fetch-size in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.JDBC_FETCH_SIZE", "100");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDHFAHJ">Example 4-35</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="CHDHFAHJ" name="CHDHFAHJ"></a><a id="TLJPA650" name="TLJPA650"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-35 Using jdbc.fetch-size in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.JDBC_FETCH_SIZE, value="100");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref611" name="sthref611"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"EclipseLink" JPA Query Hints <code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Query_Hints">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Query_Hints</a></code></p>
 </li>
 <li>
 <p>"Querying" and "Enhancing Performance" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 <li>
 <p>"EclipseLink Caches" in <em>Understanding EclipseLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BHAGGAIA" name="BHAGGAIA"></a><a id="TLJPA770" name="TLJPA770"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">jdbc.first-result</font></h2>
 <p>Use <code>eclipselink.jdbc.first-result</code> to specify if the query should skip the specified number of rows in the result.</p>
 <a id="sthref612" name="sthref612"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#BHAGFHHH">Table 4-17</a> describes this query hint's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA771" name="TLJPA771"></a><a id="sthref613" name="sthref613"></a><a id="BHAGFHHH" name="BHAGFHHH"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-17 Valid Values for jdbc.first-result</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for jdbc.first-result" summary="This table describes the valid values for the jdbc.first-result extension." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t25"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t25"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t25" headers="r1c1-t25">
 <p>Integer</p>
 </td>
 <td align="left" headers="r2c1-t25 r1c2-t25">
 <p><code>Integer</code> or <code>String</code> value that can be parsed to an <code>int</code> value.</p>
 <p>The position of the first result to retrieve.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref614" name="sthref614"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>This query hint is similar to JPA Query <code>setFirstResults()</code>, but can be set in metadata for <code>NamedQuerys</code>.</p>
 <a id="sthref615" name="sthref615"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDIFCDA">Example 4-36</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CHDIFCDA" name="CHDIFCDA"></a><a id="TLJPA772" name="TLJPA772"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-36 Using jdbc.first-result in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.JDBC_FIRST_RESULT", "10");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref616" name="sthref616"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"Query Concepts" in <em>Understanding EclipseLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="maxrows" name="maxrows"></a><a id="TLJPA651" name="TLJPA651"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">jdbc.max-rows</font></h2>
 <p>Use <code>eclipselink.jdbc.max-rows</code> to specify the maximum number of rows to be returned. If the query returns more rows than specified, the trailing rows will not be returned.</p>
 <a id="sthref617" name="sthref617"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#BACJCJHA">Table 4-18</a> describes this query hint's valid values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA652" name="TLJPA652"></a><a id="sthref618" name="sthref618"></a><a id="BACJCJHA" name="BACJCJHA"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-18 Valid Values for eclipselink.jdbc.max-rows</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for eclipselink.jdbc.max-rows" summary="This table describes the valid values for the eclipselink.jdbc.max-rows query hint." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t26"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t26"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t26" headers="r1c1-t26">
 <p><code>Int</code> or <code>String</code> (that can be parsed to <code>Int</code> values)</p>
 </td>
 <td align="left" headers="r2c1-t26 r1c2-t26">
 <p>Configures the JDBC maximum number of rows.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref619" name="sthref619"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>This hint is similar to JPQL <code>setMaxResults()</code>, but can be specified within the metadata for <code>NamedQueries</code>.</p>
 <a id="sthref620" name="sthref620"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BACJHHJB">Example 4-37</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="BACJHHJB" name="BACJHHJB"></a><a id="TLJPA653" name="TLJPA653"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-37 Using jdbc.max-rows in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.JDBC_MAX_ROWS", "100");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BACEDDBB">Example 4-38</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="BACEDDBB" name="BACEDDBB"></a><a id="TLJPA654" name="TLJPA654"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-38 Using jdbc.max-rows in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.JDBC_MAX_ROWS, value="100");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref621" name="sthref621"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>EclipseLink Pagination Example http://wiki.eclipse.org/EclipseLink/Examples/JPA/Pagination</p>
 </li>
 <li>
 <p>"Query Concepts" in <em>Understanding EclipseLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CACCHBBG" name="CACCHBBG"></a><a id="TLJPA773" name="TLJPA773"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">jdbc.native-connection</font></h2>
 <p>Use <code>eclipselink.jdbc.native-connection</code> to specify if the query requires a native JDBC connection.</p>
 <a id="sthref622" name="sthref622"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#CBAFCGCJ">Table 4-19</a> describes this persistence property's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA774" name="TLJPA774"></a><a id="sthref623" name="sthref623"></a><a id="CBAFCGCJ" name="CBAFCGCJ"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-19 Valid Values for jdbc.native-connection</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for jdbc.native-connection" summary="This table describes the valid values for the jdbc.native-connection extension." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t27"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t27"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t27" headers="r1c1-t27">
 <p><code>true</code></p>
 </td>
 <td align="left" headers="r2c1-t27 r1c2-t27">
 <p>Require native connection.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t27" headers="r1c1-t27">
 <p><code>false</code></p>
 </td>
 <td align="left" headers="r3c1-t27 r1c2-t27">
 <p>(Default) Do not require native connection.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref624" name="sthref624"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>This may be required for some queries on some server platforms that have <code>DataSource</code> implementations that wrap the JDBC connection in their own proxy. If the query requires custom JDBC access, it may require a native connection.</p>
 <p>A <code>ServerPlatform</code> is required to be set as a persistence property to be able to use a native connection. For features that EclipseLink already knows require a native connection, eclipselink.jdbc.native-connection will default to <code>true</code>.</p>
 <a id="sthref625" name="sthref625"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDIGECJ">Example 4-39</a> shows how to use the hint in a JPA Query.</p>
 <div class="example"><a id="CHDIGECJ" name="CHDIGECJ"></a><a id="TLJPA775" name="TLJPA775"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-39 Using jdbc.native-connection in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.NATIVE_CONNECTION", "TRUE");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref626" name="sthref626"></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#target-server">"target-server"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDEBFHE" name="CHDEBFHE"></a><a id="TLJPA776" name="TLJPA776"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">jdbc.parameter-delimiter</font></h2>
 <p>Use <code>eclipselink.jdbc.parameter-delimiter</code> to specify a custom parameter binding character (instead of the default hash <strong>#</strong> character).</p>
 <a id="sthref627" name="sthref627"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#CBAJJADC">Table 4-20</a> describes this query hint's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA777" name="TLJPA777"></a><a id="sthref628" name="sthref628"></a><a id="CBAJJADC" name="CBAJJADC"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-20 Valid Values for jdbc.parameter-delimiter</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for jdbc.parameter-delimiter" summary="This table describes the valid values for the jdbc.parameter-delimiter extension." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t28"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t28"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t28" headers="r1c1-t28">
 <p>Character</p>
 </td>
 <td align="left" headers="r2c1-t28 r1c2-t28">
 <p>Any valid, single character. Do not use "".</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref629" name="sthref629"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDCICJE">Example 4-40</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CHDCICJE" name="CHDCICJE"></a><a id="TLJPA54037" name="TLJPA54037"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-40 Using jdbc.parameter-delimiter in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.PARAMETER_DELIMITER", ",");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDFCEBI">Example 4-41</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="CHDFCEBI" name="CHDFCEBI"></a><a id="TLJPA54038" name="TLJPA54038"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-41 Using jdbc.parameter-delimiter in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.PARAMETER_DELIMITER, value=",");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref630" name="sthref630"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#bindparameters">"jdbc.bind-parameters"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="timeout" name="timeout"></a><a id="TLJPA656" name="TLJPA656"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">jdbc.timeout</font></h2>
 <p>Use <code>eclipselink.jdbc.timeout</code> to specify number of seconds EclipseLink will wait (time out) for a query result, before throwing a <code>DatabaseExcpetion</code>.</p>
 <div align="center">
 <div class="inftblnote"><br />
 <table class="Note oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
 <tbody>
 <tr>
 <td align="left">
 <p class="note"><img src="../../../dcommon/images/note_icon.png" width="16" height="16" alt="Note" style="vertical-align:middle;padding-right:5px;" />Note:</p>
 <p>This property requires JDBC driver support.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref631" name="sthref631"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#CHDHBCIE">Table 4-21</a> describes this query hint's valid values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA657" name="TLJPA657"></a><a id="sthref632" name="sthref632"></a><a id="CHDHBCIE" name="CHDHBCIE"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-21 Valid Values for eclipselink.jdbc.timeout</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for eclipselink.jdbc.timeout" summary="This table describes the valid values for the eclipselink.jdbc.timeout query hint." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t30"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t30"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t30" headers="r1c1-t30">
 <p>from <code>0</code> to <code>Integer.MAX_VALUE</code></p>
 </td>
 <td align="left" headers="r2c1-t30 r1c2-t30">
 <p>(Default = <code>0</code>) As a <code>String</code>, depending on your JDBC driver.</p>
 <p>If 0, EclipseLink will never time out waiting for a query.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref633" name="sthref633"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>Some database platforms may not support lock timeouts, so you may consider setting a <code>JDBC_TIMEOUT</code> hint for these platforms.</p>
 <a id="sthref634" name="sthref634"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDGCDAG">Example 4-42</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CHDGCDAG" name="CHDGCDAG"></a><a id="TLJPA658" name="TLJPA658"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-42 Using jdbc.timeout in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.CacheUsage;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint(QueryHints.<strong>JDBC_TIMEOUT</strong>, "100");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDHICEC">Example 4-43</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="CHDHICEC" name="CHDHICEC"></a><a id="TLJPA659" name="TLJPA659"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-43 Using jdbc.timeout in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.CacheUsage;
  import org.eclipse.persistence.config.TargetDatabase;
  @QueryHint(name=QueryHints.<strong>JDBC_TIMEOUT</strong>, value="100");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref635" name="sthref635"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#querytype">"query-type"</a></p>
 </li>
 <li>
 <p>"About JPA Query Hints" in <em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p>"Enhancing Performance" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="fetch" name="fetch"></a><a id="TLJPA660" name="TLJPA660"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">join-fetch</font></h2>
 <p>Use <code>eclipselink.join-fetch hint</code> to join attributes in a query.</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>Use <em>dot notation</em> to access nested attributes. For example, to batch-read an employee's manager's address, use <code>e.manager.address</code>.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref636" name="sthref636"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#BABHECAC">Table 4-22</a> describes this query hint's valid values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA661" name="TLJPA661"></a><a id="sthref637" name="sthref637"></a><a id="BABHECAC" name="BABHECAC"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-22 Valid Values for eclipselink.join-fetch hint</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for eclipselink.join-fetch hint" summary="This table lists the valid value for the eclipselink.join-fetch query hint." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t32"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t32" headers="r1c1-t32">
 <p>A relationship path expression</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref638" name="sthref638"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>This hint is similar to <code>eclipselink.<a href="#batch">batch</a></code>. Subsequent queries of related objects can be optimized in batches instead of being retrieved in one large joined read</p>
 <p>The <code>eclipselink.join-fetch</code> hint differs from JPQL joining in that it allows multilevel fetch joins.</p>
 <a id="sthref639" name="sthref639"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABJAJBE">Example 4-44</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="BABJAJBE" name="BABJAJBE"></a><a id="TLJPA662" name="TLJPA662"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-44 Using join-fetch in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.<strong>join-fetch</strong>", "e.address");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BABCAFGJ">Example 4-45</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="BABCAFGJ" name="BABCAFGJ"></a><a id="TLJPA663" name="TLJPA663"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-45 Using join-fetch in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.FETCH, value="e.address");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref640" name="sthref640"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p>"EclipseLink" JPA Query Hints <code><a href="http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Query_Hints">http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Query_Hints</a></code></p>
 </li>
 <li>
 <p>EclipseLink Examples <code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/QueryOptimization">http://wiki.eclipse.org/EclipseLink/Examples/JPA/QueryOptimization</a></code></p>
 </li>
 <li>
 <p>"Optimizing Queries" in <em>Understanding EclipseLink</em>.</p>
 </li>
 <li>
 <p>"Fetch Joins" in the JPA Specification (<code><a href="http://jcp.org/en/jsr/detail?id=317">http://jcp.org/en/jsr/detail?id=317</a></code>)</p>
 </li>
 <li>
 <p><a href="#batch">"batch"</a></p>
 </li>
 <li>
 <p><a href="#CHDEFDDC">"left-join-fetch"</a></p>
 </li>
 <li>
 <p>"Enhancing Performance" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CHDEFDDC" name="CHDEFDDC"></a><a id="TLJPA779" name="TLJPA779"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">left-join-fetch</font></h2>
 <p>Use <code>eclipselink.left-join-fetch</code> to optimize the query: related objects will be joined into the query instead of being queries separately.</p>
 <a id="sthref641" name="sthref641"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#CBADFCGG">Table 4-23</a> describes this query hint's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA780" name="TLJPA780"></a><a id="sthref642" name="sthref642"></a><a id="CBADFCGG" name="CBADFCGG"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-23 Valid Values for left-join-fetch</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for left-join-fetch" summary="This table describes the valid values for the left-join-fetch extension." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t33"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t33"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t33" headers="r1c1-t33">
 <p>String</p>
 </td>
 <td align="left" headers="r2c1-t33 r1c2-t33">
 <p>JPQL-style navigations to a relationship</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref643" name="sthref643"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You can use this query hint to create nested join fetches, which is not supported by JPQL. You can also use <code>eclipselink.left-join-fetch</code> to create join fetches with native queries.</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>This uses an <code>OUTER</code> join to allow null or empty values.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="inftblnote" --></div>
 <a id="sthref644" name="sthref644"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDCBHBD">Example 4-46</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CHDCBHBD" name="CHDCBHBD"></a><a id="TLJPA54039" name="TLJPA54039"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-46 Using left-join-fetch in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.LEFT_FETCH", "<em>STRING</em>");
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDECBHE">Example 4-47</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="CHDECBHE" name="CHDECBHE"></a><a id="TLJPA54040" name="TLJPA54040"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-47 Using left-join-fetch in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.LEFT_FETCH, value="<em>STRING</em>");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref645" name="sthref645"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <ul>
 <li>
 <p>EclipseLink Examples <code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/QueryOptimization">http://wiki.eclipse.org/EclipseLink/Examples/JPA/QueryOptimization</a></code></p>
 </li>
 <li>
 <p>"Fetch Joins" in the JPA Specification (<code><a href="http://jcp.org/en/jsr/detail?id=317">http://jcp.org/en/jsr/detail?id=317</a></code>)</p>
 </li>
 <li>
 <p><a href="#batch">"batch"</a></p>
 </li>
 <li>
 <p><a href="#fetch">"join-fetch"</a></p>
 </li>
 <li>
 <p>"Enhancing Performance" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="BABIJCGD" name="BABIJCGD"></a><a id="TLJPA782" name="TLJPA782"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">load-group</font></h2>
 <p>Use <code>eclipselink.load-group</code> to configures a query to use the load group object.</p>
 <a id="sthref646" name="sthref646"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#CBAFAEGI">Table 4-24</a> describes this persistence property's values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA783" name="TLJPA783"></a><a id="sthref647" name="sthref647"></a><a id="CBAFAEGI" name="CBAFAEGI"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-24 Valid Values for load-group</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for load-group" summary="Valid values for this extensiont" dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t35"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t35"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t35" headers="r1c1-t35">
 <p><code>load-group</code> classname</p>
 </td>
 <td align="left" headers="r2c1-t35 r1c2-t35">
 <p>An instance of <code>LoadGroup</code>.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref648" name="sthref648"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>With load groups, EclipseLink ensures that all relational attributes for a group are loaded. LoadGroups are only supported for queries returning objects (only a single alias can be the select clause).</p>
 <a id="sthref649" name="sthref649"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CHDDJICH">Example 4-48</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CHDDJICH" name="CHDDJICH"></a><a id="TLJPA54041" name="TLJPA54041"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-48 Using load-group in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint("eclipselink.LOAD_GROUP", MyLoadGroup);
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CHDFJAGD">Example 4-49</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="CHDFJAGD" name="CHDFJAGD"></a><a id="TLJPA54042" name="TLJPA54042"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-49 Using load-group in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.LOAD_GROUP, value="lg");
 </pre></div>
 <!-- class="example" -->
 <a id="sthref650" name="sthref650"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#CACEDHDG">"load-group.attribute"</a></p>
 </li>
 <li>
 <p>"AttributeGroup Types and Operations" in <em>Understanding EclipseLink</em></p>
 </li>
 <li>
 <p>EclipseLink Attribute Group example:<code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/AttributeGroup">http://wiki.eclipse.org/EclipseLink/Examples/JPA/AttributeGroup</a></code></p>
 </li>
 <li>
 <p><a href="annotations_ref.htm#BABJBDEG">"@FetchGroup"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="CACEDHDG" name="CACEDHDG"></a><a id="TLJPA785" name="TLJPA785"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">load-group.attribute</font></h2>
 <p>Use <code>eclipselink.load-group.attribute</code> to specify if the query uses a <a href="#BABIJCGD">load-group</a> that includes a list of attributes.</p>
 <a id="sthref651" name="sthref651"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>You must define each attribute using a separate hint. The query loads all relational attributes defined in the load group.</p>
 <p>LoadGroups are only supported for queries returning objects (only a single alias can be the select clause). Both local and nested attributes are supported.</p>
 <a id="sthref652" name="sthref652"></a>
 <p><strong><br /><span class="refsubsect">See Also</span></strong></p>
 <p>For more information, see:</p>
 <ul>
 <li>
 <p><a href="#BABIJCGD">"load-group"</a></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="maintaincache" name="maintaincache"></a><a id="TLJPA54073" name="TLJPA54073"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">maintain-cache</font></h2>
 <p>Use <code>eclipselink.maintain-cache</code> to controls whether or not query results are cached in the session cache</p>
 <a id="sthref653" name="sthref653"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#BABEHGHI">Table 4-25</a> describes this query hint's valid values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA54074" name="TLJPA54074"></a><a id="sthref654" name="sthref654"></a><a id="BABEHGHI" name="BABEHGHI"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-25 Valid Values for org.eclipselink.maintain-cache</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for org.eclipselink.maintain-cache" summary="This table describes the valid values for the org.eclipselink.maintain-cache query hint." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t36"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t36"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t36" headers="r1c1-t36">
 <p><code>TRUE</code></p>
 </td>
 <td align="left" headers="r2c1-t36 r1c2-t36">
 <p>Maintain cache.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t36" headers="r1c1-t36">
 <p><code>FALSE</code></p>
 </td>
 <td align="left" headers="r3c1-t36 r1c2-t36">
 <p>(Default) Do not maintain cache.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref655" name="sthref655"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>The <code>eclipselink.maintain-cache</code> hint provides a way to query the current database contents <em>without affecting the current persistence context</em>. It configures the query to return un-managed instances so any updates to entities queried using this hint would have to be merged into the persistence context.</p>
 <a id="sthref656" name="sthref656"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#BABJCJGF">Example 4-50</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="BABJCJGF" name="BABJCJGF"></a><a id="TLJPA54075" name="TLJPA54075"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-50 Using maintain-cache in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint(QueryHints.MAINTAIN_CACHE, HintValues.FALSE);
 </pre></div>
 <!-- class="example" -->
 <p><a href="#BABBHIDI">Example 4-51</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a id="BABBHIDI" name="BABBHIDI"></a><a id="TLJPA54076" name="TLJPA54076"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-51 Using maintain-cache in a @QueryHint Annotation</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.HintValues;
  import org.eclipse.persistence.config.QueryHints;
  @QueryHint(name=QueryHints.MAINTAIN_CACHE, value=HintValues.FALSE);
 </pre></div>
 <!-- class="example" -->
 <a id="sthref657" name="sthref657"></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>
 <li>
 <p>"Enhancing Performance" in <em>Solutions Guide for EclispeLink</em></p>
 </li>
 <li>
 <p>"EclipseLink Caches" in <em>Understanding EclipseLink</em></p>
 </li>
 </ul>
 </div>
 <!-- class="refsect1" -->
 <a id="pessimisticlock" name="pessimisticlock"></a><a id="TLJPA668" name="TLJPA668"></a>
 <hr />
 <div class="refsect1">
 <h2 class="refsect1"><font face="arial, helvetica, sans-serif" color="#330099">pessimistic-lock</font></h2>
 <p>Use <code>eclipselink.pessimistic-lock</code> to specify if EclipseLink uses pessimistic locking.</p>
 <a id="sthref658" name="sthref658"></a>
 <p><strong><br /><span class="refsubsect">Values</span></strong></p>
 <p><a href="#CIHDEEDF">Table 4-26</a> describes this query hint's valid values.</p>
 <div class="tblhruleformalwide"><a id="TLJPA669" name="TLJPA669"></a><a id="sthref659" name="sthref659"></a><a id="CIHDEEDF" name="CIHDEEDF"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Table 4-26 Valid Values for org.eclipse.persistence.config.PessimisticLock</font></em></strong></p>
 <table class="HRuleFormalWide" title="Valid Values for org.eclipse.persistence.config.PessimisticLock" summary="This table describes the valid values for the org.eclipse.persistence.config.PessimisticLock query hint." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
 <col width="29%" />
 <col width="*" />
 <thead>
 <tr align="left" valign="top">
 <th align="left" valign="bottom" id="r1c1-t37"><font face="Arial, Helvetica, sans-serif"><strong>Value</strong></font></th>
 <th align="left" valign="bottom" id="r1c2-t37"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
 </tr>
 </thead>
 <tbody>
 <tr align="left" valign="top">
 <td align="left" id="r2c1-t37" headers="r1c1-t37">
 <p><code>NoLock</code></p>
 </td>
 <td align="left" headers="r2c1-t37 r1c2-t37">
 <p>(Default) Do not use pessimistic locking.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r3c1-t37" headers="r1c1-t37">
 <p><code>Lock</code></p>
 </td>
 <td align="left" headers="r3c1-t37 r1c2-t37">
 <p>EclipseLink issues <code>SELECT .... FOR UPDATE</code> statements.</p>
 </td>
 </tr>
 <tr align="left" valign="top">
 <td align="left" id="r4c1-t37" headers="r1c1-t37">
 <p><code>LockNoWait</code></p>
 </td>
 <td align="left" headers="r4c1-t37 r1c2-t37">
 <p>EclipseLink issues <code>SELECT .... FOR UPDATE NO WAIT</code> statements.</p>
 </td>
 </tr>
 </tbody>
 </table>
 <br /></div>
 <!-- class="tblhruleformalwide" -->
 <a id="sthref660" name="sthref660"></a>
 <p><strong><br /><span class="refsubsect">Usage</span></strong></p>
 <p>The primary advantage of using pessimistic locking is that you are assured, once the lock is obtained, of a successful edit. This is desirable in highly concurrent applications in which optimistic locking may cause too many optimistic locking errors.</p>
 <p>One drawback of pessimistic locking is that it requires additional database resources, requiring the database transaction and connection to be maintained for the duration of the edit. Pessimistic locking may also cause deadlocks and lead to concurrency issues.</p>
 <a id="sthref661" name="sthref661"></a>
 <p><strong><br /><span class="refsubsect">Examples</span></strong></p>
 <p><a href="#CIHGEJFF">Example 4-52</a> shows how to use this hint in a JPA query.</p>
 <div class="example"><a id="CIHGEJFF" name="CIHGEJFF"></a><a id="TLJPA670" name="TLJPA670"></a>
 <p><strong><em><font face="arial, helvetica, sans-serif">Example 4-52 Using pessimistic-lock in a JPA Query</font></em></strong></p>
 <pre xml:space="preserve" class="oac_no_warn">
 import org.eclipse.persistence.config.PessimisticLock;
  import org.eclipse.persistence.config.QueryHints;
  query.setHint(QueryHints.PESSIMISTIC_LOCK, PessimisticLock.LockNoWait);
 </pre></div>
 <!-- class="example" -->
 <p><a href="#CIHIAFGH">Example 4-53</a> shows how to use this hint with the <code>@QueryHint</code> annotation.</p>
 <div class="example"><a<