Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Querying/Query Hints"

From Eclipsepedia

Jump to: navigation, search
m (Query Type)
m
 
(29 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{EclipseLink_Toc}}
+
'''[[Image:Elug_draft_icon.png|Warning]] See [http://www.eclipse.org/eclipselink/documentation/2.4/jpa/extensions/queryhints.htm Java Persistence API (JPA) Extensions Reference for EclipseLink, EclipseLink 2.4]
 +
'''
 +
 
 +
{{EclipseLink_UserGuide
 +
|info=y
 +
|toc=n
 +
|eclipselink=y
 +
|eclipselinktype=JPA
 +
|api=y
 +
|apis=
 +
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/QueryHints.html QueryHints]
 +
}}
 +
 
 
=EclipseLink JPA Query Hints=
 
=EclipseLink JPA Query Hints=
The [[#Table 19-30|EclipseLink JPA Query Hints]] table lists the EclipseLink JPA query hints that you can specify when you construct a JPA query, as the [[#Example 19-24|Specifying an EclipseLink JPA Query Hint]] example shows, or when you specify a JPA query using the <tt>@QueryHint</tt> annotation, as the [[#Example 19-25|Specifying an EclipseLink JPA Query Hint with @QueryHint]] example shows.
+
 
 +
You can use a query hint to customize or optimize a JPA query. All EclipseLink query hints are defined in the <tt>QueryHints</tt> class in the <tt>org.eclipse.persistence.config</tt> package.
 +
 
 
{{EclipseLink_Spec
 
{{EclipseLink_Spec
|section=Section 8.3.1 "NamedQuery Annotation"}}
+
|section=Section 10.3.1 "NamedQuery Annotation"}}
  
All EclipseLink query hints are defined in the <tt>QueryHints</tt> class in the <tt>org.eclipse.persistence.config</tt> package.
+
Use EclipseLink JPA query hints to:
 +
* Construct a JPA query (for example, see [[#Example 19-24|Specifying an EclipseLink JPA Query Hint]], below)
 +
* Specify a JPA query using the <tt>@QueryHint</tt> annotation (for example, see [[#Example 19-25|Specifying an EclipseLink JPA Query Hint with @QueryHint]], below)
  
 
The EclipseLink query hints include the following:
 
The EclipseLink query hints include the following:
Line 29: Line 45:
 
* <tt>QueryType</tt>
 
* <tt>QueryType</tt>
  
The [[#Example 19-24|Specifying an EclipseLink JPA Query Hint]] and [[#Example 19-25|Specifying an EclipseLink JPA Query Hint with @QueryHint]] examples show how to set the value of hint <tt>eclipselink.jdbc.bind-parameters</tt> using the <tt>QueryHints</tt> configuration class to set the name of the hint, and the <tt>HintValues</tt> configuration class to set the value.
+
The following examples show how to set the value of hint <tt>eclipselink.jdbc.bind-parameters</tt> using the <tt>QueryHints</tt> configuration class to set the name of the hint, and the <tt>HintValues</tt> configuration class to set the value.
  
 
<span id="Example 19-24"></span>
 
<span id="Example 19-24"></span>
Line 64: Line 80:
  
 
EclipseLink JPA uses a shared cache mechanism that is scoped to the entire persistence unit. When operations are completed in a particular persistence context, the results are merged back into the shared cache so that other persistence contexts can use them. This happens regardless of whether the entity manager and persistence context are created in Java SE or Java EE. Any entity persisted or removed using the entity manager will always be kept consistent with the cache.
 
EclipseLink JPA uses a shared cache mechanism that is scoped to the entire persistence unit. When operations are completed in a particular persistence context, the results are merged back into the shared cache so that other persistence contexts can use them. This happens regardless of whether the entity manager and persistence context are created in Java SE or Java EE. Any entity persisted or removed using the entity manager will always be kept consistent with the cache.
 
For more information, see the following:
 
* [[Introduction%20to%20Cache%20(ELUG)#Session Cache|Session Cache]]
 
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#How to Use In-Memory Queries|How to Use In-Memory Queries]]
 
 
  
 
{{EclipseLink_ValidValuesTable
 
{{EclipseLink_ValidValuesTable
Line 94: Line 105:
 
<tr>
 
<tr>
 
  <td>'''<tt>ConformResultsInUnitOfWork</tt>'''</td>
 
  <td>'''<tt>ConformResultsInUnitOfWork</tt>'''</td>
  <td>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.<br>For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using Conforming Queries and Descriptors|Using Conforming Queries and Descriptors]].</td>
+
  <td>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.</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
 
  <td>'''<tt>UseEntityDefault</tt>'''</td>
 
  <td>'''<tt>UseEntityDefault</tt>'''</td>
  <td>Use the cache configuration as specified by the EclipseLink descriptor API for this entity.
+
  <td>Use the cache configuration as specified by the EclipseLink descriptor API for this entity. <br />
 +
'''Default'''
 
{{EclipseLink_Note
 
{{EclipseLink_Note
 
|note=The entity default value is to not check the cache (<tt>DoNotCheckCache</tt>). 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.}}</td>
 
|note=The entity default value is to not check the cache (<tt>DoNotCheckCache</tt>). 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.}}</td>
 
</tr>}}
 
</tr>}}
 
 
Default usage:
 
<tt>CacheUsage.UseEntityDefault</tt>
 
{{EclipseLink_Note
 
|note=The default is <tt>DoNotCheckCache</tt>.}}
 
 
For more information, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Configuring Cache Usage for In-Memory Queries|Configuring Cache Usage for In-Memory Queries]].
 
  
  
Line 126: Line 130:
 
</source>
 
</source>
  
====Query Type====
+
==Query Type==
 
The <tt>eclipselink.query-type</tt> hint specifies the EclipseLink query type to use for the query.  
 
The <tt>eclipselink.query-type</tt> hint specifies the EclipseLink query type to use for the query.  
  
 
For most JP QL queries, the <tt>org.eclipse.persistence.queries.ReportQuery</tt> or <tt>org.eclipse.persistence.queries.ReadAllQuery</tt> are used. The <tt>eclipselink.query-type</tt> hint lets you use other query types, such as <tt>org.eclipse.persistence.queries.ReadObjectQuery</tt> for queries that are know to return a single object.
 
For most JP QL queries, the <tt>org.eclipse.persistence.queries.ReportQuery</tt> or <tt>org.eclipse.persistence.queries.ReadAllQuery</tt> are used. The <tt>eclipselink.query-type</tt> hint lets you use other query types, such as <tt>org.eclipse.persistence.queries.ReadObjectQuery</tt> for queries that are know to return a single object.
 
For more information, see the following:
 
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Object-Level Read Query|Object-Level Read Query]]
 
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Data-Level Modify Query|Data-Level Modify Query]]
 
  
 
{{EclipseLink_ValidValuesTable
 
{{EclipseLink_ValidValuesTable
Line 143: Line 143:
 
<tr>
 
<tr>
 
  <td>'''<tt>ReadAll</tt>'''</td>
 
  <td>'''<tt>ReadAll</tt>'''</td>
  <td>Use the [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#ReadAllQuery|ReadAllQuery]] type for the query.</td>
+
  <td>Use the <tt>ReadAllQuery</tt> type for the query.</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
 
  <td>'''<tt>ReadObject</tt>'''</td>
 
  <td>'''<tt>ReadObject</tt>'''</td>
  <td>Use the [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#|ReadObjectQuery]] type for the query.</td>
+
  <td>Use the <tt>ReadObjectQuery</tt> type for the query.</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
 
  <td>'''<tt>Report</tt>'''</td>
 
  <td>'''<tt>Report</tt>'''</td>
  <td>Use the [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Report Query|Report Query]] type for the query.</td>
+
  <td>Use the <tt>Report Query</tt> type for the query.</td>
 
</tr>}}
 
</tr>}}
  
Line 169: Line 169:
 
</source>
 
</source>
  
====Bind Parameters====
+
==Bind Parameters==
 
The <tt>eclipselink.jdbc.bind-parameters</tt> hint controls whether or not the query uses parameter binding.
 
The <tt>eclipselink.jdbc.bind-parameters</tt> hint controls whether or not the query uses parameter binding.
  
For more information, see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)#How to Use Parameterized SQL (Parameter Binding) and Prepared Statement Caching for Optimization|How to Use Parameterized SQL (Parameter Binding) and Prepared Statement Caching for Optimization]].
+
{{EclipseLink_ValidValuesTable
 
+
|caption=Valid values for the <tt>org.eclipse.persistence.config.HintValues</tt>
The following are the valid values for the <tt>org.eclipse.persistence.config.HintValues</tt><nowiki>:</nowiki>
+
|content=<tr>
* <tt>TRUE</tt> – bind all parameters.
+
<td>'''<tt>TRUE</tt>'''</td>
* <tt>FALSE</tt> – do not bind all parameters.
+
<td>Bind all parameters.</td>
* <tt>PERSISTENCE_UNIT_DEFAULT</tt> – use the parameter binding setting made in your EclipseLink session's database login, which is <tt>true</tt> by default.<br><br>For more information, see [[Configuring%20a%20Database%20Login%20(ELUG)#Configuring JDBC Options|Configuring JDBC Options]].
+
</tr>
 
+
<tr>
Default: <tt>HintValues.PERSISTENCE_UNIT_DEFAULT</tt>
+
<td>'''<tt>FALSE</tt>'''</td>
 +
<td>Do not bind all parameters.</td>
 +
</tr>
 +
<tr>
 +
<td>'''<tt>PERSISTENCE_UNIT_DEFAULT</tt>'''</td>
 +
<td>Use the parameter binding setting made in your EclipseLink session's database login, which is <tt>true</tt> by default.
 +
'''Default'''</td>
 +
</tr>}}
  
 
'''Example'''<nowiki>: JPA Query API</nowiki>  
 
'''Example'''<nowiki>: JPA Query API</nowiki>  
 +
<source lang="java">
 
  import org.eclipse.persistence.config.HintValues;
 
  import org.eclipse.persistence.config.HintValues;
 
  import org.eclipse.persistence.config.QueryHints;
 
  import org.eclipse.persistence.config.QueryHints;
 
  query.setHint(QueryHints.BIND_PARAMETERS, HintValues.TRUE);
 
  query.setHint(QueryHints.BIND_PARAMETERS, HintValues.TRUE);
 +
</source>
  
 
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>  
 
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>  
 +
<source lang="java">
 
  import org.eclipse.persistence.config.HintValues;
 
  import org.eclipse.persistence.config.HintValues;
 
  import org.eclipse.persistence.config.TargetDatabase;
 
  import org.eclipse.persistence.config.TargetDatabase;
 
  @QueryHint(name=QueryHints.BIND_PARAMETERS, value=HintValues.TRUE);
 
  @QueryHint(name=QueryHints.BIND_PARAMETERS, value=HintValues.TRUE);
 +
</source>
  
====Fetch Size====
+
==Fetch Size==
 
The <tt>eclipselink.jdbc.fetch-size</tt> hint specifies the number of rows that should be fetched from the database when more rows are needed<sup>1</sup>
 
The <tt>eclipselink.jdbc.fetch-size</tt> hint specifies the number of rows that should be fetched from the database when more rows are needed<sup>1</sup>
  
 
For large 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. Most JDBC drivers default to 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. Note that if you are unsure of the result set size, incorrectly setting a fetch size too large or too small can decrease performance.
 
For large 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. Most JDBC drivers default to 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. Note that if you are unsure of the result set size, incorrectly setting a fetch size too large or too small can decrease performance.
 +
<br><span style="font-size:0.8em;font-style:italic"><sup>1</sup> This property is dependent on the JDBC driver support.</span>
  
A value of 0 means the JDBC driver default will be used.
+
{{EclipseLink_ValidValuesTable
 
+
|caption=
Valid values: 0 to <tt>Integer.MAX_VALUE</tt> (depending on your JDBC driver) as a <tt>String</tt>.
+
|content=<tr>
 +
<td>0 to <tt>Integer.MAX_VALUE</tt></td>
 +
<td>As a <tt>String</tt>, depending on your JDBC driver. A value of 0 means the JDBC driver default will be used.<br />Default = '''0'''.
 +
}}
  
Default: 0
+
==Timeout==
 
+
Note: this value indicates that the JDBC driver default will be used.
+
 
+
<br><sup>1</sup> This property is dependent on the JDBC driver support.
+
 
+
====Timeout====
+
 
The <tt>eclipselink.jdbc.timeout</tt> hint specifies the number of seconds EclipseLink will wait on a query before throwing a <tt>DatabaseException</tt><sup>1</sup>
 
The <tt>eclipselink.jdbc.timeout</tt> hint specifies the number of seconds EclipseLink will wait on a query before throwing a <tt>DatabaseException</tt><sup>1</sup>
 +
<span style="font-size:0.8em;font-style:italic"><br><sup>1</sup> This property is dependent on the JDBC driver support.</span>
 +
{{EclipseLink_ValidValuesTable
 +
|caption=
 +
|content=<tr>
 +
<td>0 to <tt>Integer.MAX_VALUE</tt></td>
 +
<td>As a <tt>String</tt>, depending on your JDBC driver. A value of 0 means EclipseLink will never time-out a query. <br />Default = '''0'''.
 +
}}
  
A value of 0 means EclipseLink will never time-out a query.
+
==Pessimistic Lock==
 
+
Valid values: 0 to <tt>Integer.MAX_VALUE</tt> (depending on your JDBC driver) as a <tt>String</tt>.
+
 
+
Default: 0
+
 
+
<br><sup>1</sup> This property is dependent on the JDBC driver support.
+
 
+
====Pessimistic Lock====
+
 
The <tt>eclipselink.pessimistic-lock</tt> hint controls whether or not pessimistic locking is used.
 
The <tt>eclipselink.pessimistic-lock</tt> hint controls whether or not pessimistic locking is used.
  
The following are the valid values for the <tt>org.eclipse.persistence.config.PessimisticLock</tt><nowiki>:</nowiki>
+
{{EclipseLink_ValidValuesTable
* <tt>NoLock</tt> – pessimistic locking is not used.
+
|caption=Valid values for the <tt>org.eclipse.persistence.config.PessimisticLock</tt>
* <tt>Lock</tt> EclipseLink issues a <tt>SELECT .... FOR UPDATE</tt>.
+
|content=<tr>
* <tt>LockNoWait</tt> EclipseLink issues a <tt>SELECT .... FOR UPDATE NO WAIT</tt>.
+
<td>'''<tt>NoLock</tt></td>
 
+
<td>Pessimistic locking is not used.<br>
Default: <tt>NoLock</tt>
+
'''Default'''</td>
 +
</tr>
 +
<tr>
 +
<td>'''<tt>Lock</tt>'''</td>
 +
<td>EclipseLink issues a <tt>SELECT .... FOR UPDATE</tt>.</td>
 +
</tr>
 +
<tr>
 +
<td>'''<tt>LockNoWait</tt>'''</td>
 +
<td>EclipseLink issues a <tt>SELECT .... FOR UPDATE NO WAIT</tt>.</td>
 +
</tr>
 +
}}
  
 
'''Example'''<nowiki>: JPA Query API</nowiki>  
 
'''Example'''<nowiki>: JPA Query API</nowiki>  
 +
<source lang="java">
 
  import org.eclipse.persistence.config.PessimisticLock;
 
  import org.eclipse.persistence.config.PessimisticLock;
 
  import org.eclipse.persistence.config.QueryHints;
 
  import org.eclipse.persistence.config.QueryHints;
 
  query.setHint(QueryHints.PESSIMISTIC_LOCK, PessimisticLock.LockNoWait);
 
  query.setHint(QueryHints.PESSIMISTIC_LOCK, PessimisticLock.LockNoWait);
 +
</source>
  
 
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>  
 
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>  
 +
<source lang="java">
 
  import org.eclipse.persistence.config.PessimisticLock;
 
  import org.eclipse.persistence.config.PessimisticLock;
 
  import org.eclipse.persistence.config.QueryHints;
 
  import org.eclipse.persistence.config.QueryHints;
 
  @QueryHint(name=QueryHints.PESSIMISTIC_LOCK, value=PessimisticLock.LockNoWait);
 
  @QueryHint(name=QueryHints.PESSIMISTIC_LOCK, value=PessimisticLock.LockNoWait);
 +
</source>
  
====Batch====
+
==Batch==
 
The <tt>eclipselink.batch</tt> hint supplies 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. Batch reading is more efficient than joining because it avoids reading duplicate data.
 
The <tt>eclipselink.batch</tt> hint supplies 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. Batch reading is more efficient than joining because it avoids reading duplicate data.
  
Line 244: Line 266:
 
Valid values: a single-valued relationship path expression.
 
Valid values: a single-valued relationship path expression.
  
Note: use dot notation to access nested attributes. For example, to batch-read an employee's manager's address, specify <tt>e.manager.address</tt>
+
{{EclipseLink_Note
 +
|note=Use dot notation to access nested attributes. For example, to batch-read an employee's manager's address, specify <tt>e.manager.address</tt>}}
  
  
 
'''Example'''<nowiki>: JPA Query API</nowiki>  
 
'''Example'''<nowiki>: JPA Query API</nowiki>  
 +
<source lang="java">
 
  import org.eclipse.persistence.config.HintValues;
 
  import org.eclipse.persistence.config.HintValues;
 
  import org.eclipse.persistence.config.QueryHints;
 
  import org.eclipse.persistence.config.QueryHints;
 
  query.setHint("eclipselink.batch", "e.address");
 
  query.setHint("eclipselink.batch", "e.address");
 +
</source>
 +
 
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>  
 
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>  
 +
<source lang="java">
 
  import org.eclipse.persistence.config.HintValues;
 
  import org.eclipse.persistence.config.HintValues;
 
  import org.eclipse.persistence.config.QueryHints;
 
  import org.eclipse.persistence.config.QueryHints;
 
  @QueryHint(name=QueryHints.BATCH, value="e.address");
 
  @QueryHint(name=QueryHints.BATCH, value="e.address");
 +
</source>
  
====Join Fetch====
+
==Join Fetch==
The <tt>eclipselink.join-fetch</tt> hint allows joining of the attributes.
+
The <tt>eclipselink.join-fetch</tt> hint allows joining of the attributes.  
 
+
*This is similar to [[#Batch|<tt>eclipselink.batch</tt><nowiki>]], subsequent queries of related objects can be optimized in batches instead of being retrieved in one large joined read.</nowiki>
This is similar to <tt>eclipselink.batch</tt><nowiki>: subsequent queries of related objects can be optimized in batches instead of being retrieved in one large joined read.</nowiki>
+
*This is different from JP QL joining because it allows multilevel fetch joins.
 
+
{{EclipseLink_Spec
This is different from JP QL joining because it allows multilevel fetch joins.
+
|section=Section 4.4.5.3 "Fetch Joins"}}
 
+
For more information, see Section 4.4.5.3 "Fetch Joins" of JPA specification.
+
  
 
Valid values: a relationship path expression.
 
Valid values: a relationship path expression.
  
Note: use dot notation to access nested attributes.
+
{{EclipseLink_Note
 +
|note=Use dot notation to access nested attributes.}}
  
  
 
'''Example'''<nowiki>: JPA Query API</nowiki>  
 
'''Example'''<nowiki>: JPA Query API</nowiki>  
 +
<source lang="java">
 
  import org.eclipse.persistence.config.HintValues;
 
  import org.eclipse.persistence.config.HintValues;
 
  import org.eclipse.persistence.config.QueryHints;
 
  import org.eclipse.persistence.config.QueryHints;
 
  query.setHint("eclipselink.join-fetch", "e.address");
 
  query.setHint("eclipselink.join-fetch", "e.address");
 +
</source>
  
 
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>  
 
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>  
 +
<source lang="java">
 
  import org.eclipse.persistence.config.HintValues;
 
  import org.eclipse.persistence.config.HintValues;
 
  import org.eclipse.persistence.config.QueryHints;
 
  import org.eclipse.persistence.config.QueryHints;
 
  @QueryHint(name=QueryHints.FETCH, value="e.address");
 
  @QueryHint(name=QueryHints.FETCH, value="e.address");
 +
</source>
  
====Refresh====
+
==Refresh==
 
The <tt>eclipselink.refresh</tt> hint controls whether or not to update the EclipseLink session cache with objects that the query returns.
 
The <tt>eclipselink.refresh</tt> hint controls whether or not to update the EclipseLink session cache with objects that the query returns.
  
The following are the valid values for the <tt>org.eclipse.persistence.config.HintValues</tt><nowiki>:</nowiki>
+
{{EclipseLink_ValidValuesTable
* <tt>TRUE</tt> – refresh cache.
+
|caption=Valid values for the <tt>org.eclipse.persistence.config.HintValues</tt>
* <tt>FALSE</tt> – do not refresh cache.
+
|content=
+
<tr>
Default: <tt>FALSE</tt>
+
<td>'''<tt>TRUE</tt>'''</td>
 +
<td>Refresh cache.</td>
 +
</tr>
 +
<tr>
 +
<td>'''<tt>FALSE</tt>'''</td>
 +
<td>Do not refresh cache. <br>'''Default'''</td>
 +
</tr>
 +
}}
 +
 
  
 
'''Example'''<nowiki>: JPA Query API</nowiki>  
 
'''Example'''<nowiki>: JPA Query API</nowiki>  
 +
<source lang="java">
 
  import org.eclipse.persistence.config.HintValues;
 
  import org.eclipse.persistence.config.HintValues;
 
  import org.eclipse.persistence.config.QueryHints;
 
  import org.eclipse.persistence.config.QueryHints;
 
  query.setHint(QueryHints.REFRESH, HintValues.TRUE);
 
  query.setHint(QueryHints.REFRESH, HintValues.TRUE);
 +
</source>
  
 
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>  
 
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>  
 +
<source lang="java">
 
  import org.eclipse.persistence.config.HintValues;
 
  import org.eclipse.persistence.config.HintValues;
 
  import org.eclipse.persistence.config.QueryHints;
 
  import org.eclipse.persistence.config.QueryHints;
 
  @QueryHint(name=QueryHints.REFRESH, value=HintValues.TRUE);
 
  @QueryHint(name=QueryHints.REFRESH, value=HintValues.TRUE);
 +
</source>
  
====Maintain Cache====
+
==Maintain Cache==
 
The <tt>eclipselink.maintain-cache</tt> hint controls whether or not query results are cached in the session cache and provides a way to query the current database contents without affecting the current persistence context.  It configures the query to return unmanaged instances so any updates to entities queried using this hint would have to be merged into the persistence context.  
 
The <tt>eclipselink.maintain-cache</tt> hint controls whether or not query results are cached in the session cache and provides a way to query the current database contents without affecting the current persistence context.  It configures the query to return unmanaged instances so any updates to entities queried using this hint would have to be merged into the persistence context.  
 
+
{{EclipseLink_ValidValuesTable
The following are the valid values for the <tt>org.eclipse.persistence.config.HintValues</tt><nowiki>:</nowiki>
+
|caption=Valid values for the <tt>org.eclipse.persistence.config.HintValues</tt>
* <tt>TRUE</tt> – maintain cache.
+
|content=<tr>
* <tt>FALSE</tt> – do not maintain cache.
+
<td>'''<tt>TRUE</tt>'''</td>
+
<td>Maintain cache.</td>
Default: <tt>FALSE</tt>
+
</tr>
 +
<tr>
 +
<td>'''<tt>FALSE</tt>'''</td>
 +
<td>Do not maintain cache.<br>'''Default'''</td>
 +
</tr>
 +
}}
  
 
'''Example'''<nowiki>: JPA Query API</nowiki>  
 
'''Example'''<nowiki>: JPA Query API</nowiki>  
Line 322: Line 370:
 
</source>
 
</source>
  
====Read Only====
+
==Read Only==
 
The <tt>eclipselink.read-only</tt> hint retrieves read-only results back from the query: on nontransactional read operations, where the requested entity types are stored in the shared cache, you can request that the shared instance be returned instead of a detached copy.
 
The <tt>eclipselink.read-only</tt> hint retrieves read-only results back from the query: on nontransactional read operations, where the requested entity types are stored in the shared cache, you can request that the shared instance be returned instead of a detached copy.
 
{{EclipseLink_Note
 
{{EclipseLink_Note
 
|note=You should never modify objects returned from the shared cache.}}
 
|note=You should never modify objects returned from the shared cache.}}
 
+
{{EclipseLink_ValidValuesTable
The following are the valid values for the <tt>org.eclipse.persistence.config.HintValues</tt><nowiki>:</nowiki>
+
|caption=Valid values for the <tt>org.eclipse.persistence.config.HintValues</tt>
* <tt>TRUE</tt> – retrieve read-only results back from the query;
+
|content=<tr>
* <tt>FALSE</tt> – do not retrieve read-only results back from the query.
+
<td>'''<tt>TRUE</tt>'''</td>
 
+
<td>Retrieve read-only results back from the query</td>
Default: <tt>FALSE</tt>
+
</tr>
 +
<tr>
 +
<td>'''<tt>FALSE</tt></td>
 +
<td>Do not retrieve read-only results back from the query.<br />'''Default'''</td>
 +
</tr>
 +
}}
  
 
'''Example'''<nowiki>: JPA Query API</nowiki>  
 
'''Example'''<nowiki>: JPA Query API</nowiki>  
Line 338: Line 391:
 
  import org.eclipse.persistence.config.QueryHints;
 
  import org.eclipse.persistence.config.QueryHints;
 
  query.setHint(QueryHints.READ_ONLY, HintValues.TRUE);
 
  query.setHint(QueryHints.READ_ONLY, HintValues.TRUE);
</sourced>
+
</source>
 
   
 
   
 
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>  
 
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>  
Line 347: Line 400:
 
</source>
 
</source>
  
====Result Collection Type====
+
==Result Collection Type==
 
The <tt>eclipselink.result-collection-type</tt> hint configures the concrete class that EclipseLink should use to return its query result.
 
The <tt>eclipselink.result-collection-type</tt> hint configures the concrete class that EclipseLink should use to return its query result.
  
Line 378: Line 431:
  
 
{{EclipseLink_JPA
 
{{EclipseLink_JPA
|previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Native|Native]]
+
|previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Native|Native SQL Queries]]
|next=    [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Transactions|Transactions]]
+
|next=    [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/Query_Casting|Query Casting]]
 
|up=      [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying|Querying]]
 
|up=      [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying|Querying]]
 +
|version=2.2.0 DRAFT}}

Latest revision as of 12:46, 6 December 2012

Warning See Java Persistence API (JPA) Extensions Reference for EclipseLink, EclipseLink 2.4


EclipseLink JPA

link="http://wiki.eclipse.org/EclipseLink"
EclipseLink
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source

Elug api package icon.png Key API


[edit] EclipseLink JPA Query Hints

You can use a query hint to customize or optimize a JPA query. All EclipseLink query hints are defined in the QueryHints class in the org.eclipse.persistence.config package.

Elug javaspec icon.gif

For more information, see Section 10.3.1 "NamedQuery Annotation" in the JPA Specification.

Use EclipseLink JPA query hints to:

The EclipseLink query hints include the following:

When you set a hint, you can set the value using the public static final field in the appropriate configuration class in org.eclipse.persistence.config package, including the following:

  • HintValues
  • CacheUsage
  • PessimisticLock
  • QueryType

The following examples show how to set the value of hint eclipselink.jdbc.bind-parameters using the QueryHints configuration class to set the name of the hint, and the HintValues configuration class to set the value.

Specifying an EclipseLink JPA Query Hint

 import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 
 Customer customer = (Customer)entityMgr.createNamedQuery("findCustomerBySSN").
     setParameter("SSN", "123-12-1234").
     setHint(QueryHints.BIND_PARAMETERS, HintValues.PERSISTENCE_UNIT_DEFAULT).
     getSingleResult();

Specifying an EclipseLink JPA Query Hint with @QueryHint

 import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 
 @Entity
 @NamedQuery(
     name="findEmployeeByDept",
     query="SELECT e FROM Employee e WHERE e.dept=:deptNum",
     hints=@QueryHint(name=QueryHints.BIND_PARAMETERS, value=HintValues.TRUE)
 )
 public class Employee implements Serializable {
     ...
 }

[edit] Cache Usage

The eclipselink.cache-usage hint specifies how the query should interact with the EclipseLink cache.

EclipseLink JPA uses a shared cache mechanism that is scoped to the entire persistence unit. When operations are completed in a particular persistence context, the results are merged back into the shared cache so that other persistence contexts can use them. This happens regardless of whether the entity manager and persistence context are created in Java SE or Java EE. Any entity persisted or removed using the entity manager will always be kept consistent with the cache.

Valid values for org.eclipse.persistence.config.CacheUsage
Value Description
DoNotCheckCache Always go to the database.
CheckCacheByExactPrimaryKey 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
CheckCacheByPrimaryKey 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.
CheckCacheThenDatabase You can configure any read-object query to check the cache completely before you resort to accessing the database.
CheckCacheOnly 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.
ConformResultsInUnitOfWork 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.
UseEntityDefault Use the cache configuration as specified by the EclipseLink descriptor API for this entity.

Default

Elug note icon.png

Note: The entity default value is to not check the cache (DoNotCheckCache). 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.


Example: JPA Query API

 import org.eclipse.persistence.config.CacheUsage;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.CACHE_USAGE, CacheUsage.CheckCacheOnly);

Example: @QueryHint

 import org.eclipse.persistence.config.CacheUsage;
 import org.eclipse.persistence.config.TargetDatabase;
 @QueryHint(name=QueryHints.CACHE_USAGE, value=CacheUsage.CheckCacheOnly);

[edit] Query Type

The eclipselink.query-type hint specifies the EclipseLink query type to use for the query.

For most JP QL queries, the org.eclipse.persistence.queries.ReportQuery or org.eclipse.persistence.queries.ReadAllQuery are used. The eclipselink.query-type hint lets you use other query types, such as org.eclipse.persistence.queries.ReadObjectQuery for queries that are know to return a single object.

Valid values for the org.eclipse.persistence.config.QueryType
Value Description
Auto EclipseLink chooses the type of query to use.
Default
ReadAll Use the ReadAllQuery type for the query.
ReadObject Use the ReadObjectQuery type for the query.
Report Use the Report Query type for the query.


Example: JPA Query API

 import org.eclipse.persistence.config.QueryType;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.QUERY_TYPE, QueryType.ReadObject);

Example: @QueryHint

 import org.eclipse.persistence.config.QueryType;
 import org.eclipse.persistence.config.TargetDatabase;
 @QueryHint(name=QueryHints.QUERY_TYPE, value=QueryType.ReadObject);

[edit] Bind Parameters

The eclipselink.jdbc.bind-parameters hint controls whether or not the query uses parameter binding.

Valid values for the org.eclipse.persistence.config.HintValues
Value Description
TRUE Bind all parameters.
FALSE Do not bind all parameters.
PERSISTENCE_UNIT_DEFAULT Use the parameter binding setting made in your EclipseLink session's database login, which is true by default. Default

Example: JPA Query API

 import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.BIND_PARAMETERS, HintValues.TRUE);

Example: @QueryHint

 import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.TargetDatabase;
 @QueryHint(name=QueryHints.BIND_PARAMETERS, value=HintValues.TRUE);

[edit] Fetch Size

The eclipselink.jdbc.fetch-size hint specifies the number of rows that should be fetched from the database when more rows are needed1

For large 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. Most JDBC drivers default to 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. Note that if you are unsure of the result set size, incorrectly setting a fetch size too large or too small can decrease performance.
1 This property is dependent on the JDBC driver support.

Value Description
0 to Integer.MAX_VALUE As a String, depending on your JDBC driver. A value of 0 means the JDBC driver default will be used.
Default = 0.

[edit] Timeout

The eclipselink.jdbc.timeout hint specifies the number of seconds EclipseLink will wait on a query before throwing a DatabaseException1
1 This property is dependent on the JDBC driver support.

Value Description
0 to Integer.MAX_VALUE As a String, depending on your JDBC driver. A value of 0 means EclipseLink will never time-out a query.
Default = 0.

[edit] Pessimistic Lock

The eclipselink.pessimistic-lock hint controls whether or not pessimistic locking is used.

Valid values for the org.eclipse.persistence.config.PessimisticLock
Value Description
NoLock Pessimistic locking is not used.
Default
Lock EclipseLink issues a SELECT .... FOR UPDATE.
LockNoWait EclipseLink issues a SELECT .... FOR UPDATE NO WAIT.

Example: JPA Query API

 import org.eclipse.persistence.config.PessimisticLock;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.PESSIMISTIC_LOCK, PessimisticLock.LockNoWait);

Example: @QueryHint

 import org.eclipse.persistence.config.PessimisticLock;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.PESSIMISTIC_LOCK, value=PessimisticLock.LockNoWait);

[edit] Batch

The eclipselink.batch hint supplies 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. Batch reading is more efficient than joining because it avoids reading duplicate data.

Batching is only allowed on queries that have a single object in their select clause.

Valid values: a single-valued relationship path expression.

Elug note icon.png

Note: Use dot notation to access nested attributes. For example, to batch-read an employee's manager's address, specify e.manager.address


Example: JPA Query API

 import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.batch", "e.address");

Example: @QueryHint

 import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.BATCH, value="e.address");

[edit] Join Fetch

The eclipselink.join-fetch hint allows joining of the attributes.

  • This is similar to [[#Batch|eclipselink.batch]], subsequent queries of related objects can be optimized in batches instead of being retrieved in one large joined read.
  • This is different from JP QL joining because it allows multilevel fetch joins.
Elug javaspec icon.gif

For more information, see Section 4.4.5.3 "Fetch Joins" in the JPA Specification.

Valid values: a relationship path expression.

Elug note icon.png

Note: Use dot notation to access nested attributes.


Example: JPA Query API

 import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.join-fetch", "e.address");

Example: @QueryHint

 import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.FETCH, value="e.address");

[edit] Refresh

The eclipselink.refresh hint controls whether or not to update the EclipseLink session cache with objects that the query returns.

Valid values for the org.eclipse.persistence.config.HintValues
Value Description
TRUE Refresh cache.
FALSE Do not refresh cache.
Default


Example: JPA Query API

 import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.REFRESH, HintValues.TRUE);

Example: @QueryHint

 import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.REFRESH, value=HintValues.TRUE);

[edit] Maintain Cache

The eclipselink.maintain-cache hint controls whether or not query results are cached in the session cache and provides a way to query the current database contents without affecting the current persistence context. It configures the query to return unmanaged instances so any updates to entities queried using this hint would have to be merged into the persistence context.

Valid values for the org.eclipse.persistence.config.HintValues
Value Description
TRUE Maintain cache.
FALSE Do not maintain cache.
Default

Example: JPA Query API

 import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.MAINTAIN_CACHE, HintValues.FALSE);

Example: @QueryHint

 import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.MAINTAIN_CACHE, value=HintValues.FALSE);

[edit] Read Only

The eclipselink.read-only hint retrieves read-only results back from the query: on nontransactional read operations, where the requested entity types are stored in the shared cache, you can request that the shared instance be returned instead of a detached copy.

Elug note icon.png

Note: You should never modify objects returned from the shared cache.

Valid values for the org.eclipse.persistence.config.HintValues
Value Description
TRUE Retrieve read-only results back from the query
FALSE Do not retrieve read-only results back from the query.
Default

Example: JPA Query API

 import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint(QueryHints.READ_ONLY, HintValues.TRUE);

Example: @QueryHint

 import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.READ_ONLY, value=HintValues.TRUE);

[edit] Result Collection Type

The eclipselink.result-collection-type hint configures the concrete class that EclipseLink should use to return its query result.

This lets you specify the type of collection in which the result will be returned.

Valid values: Java Class that implements the Collection interface.

Elug note icon.png

Note: Typically, you would execute these queries by calling the getResultsList method, which returns the java.util.List, on the Query. This means that the class specified in this hint must implement the List interface, if you are invoking it using the getResultsList method.

Elug note icon.png

Note: Specify the class without the ".class" notation. For example, java.util.Vector would work, not java.util.Vector.classEclipseLink will throw an exception, if you use this hint with a class that does not implement the Collection interface.

Default:java.util.Vector

Example: JPA Query API

 import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 query.setHint("eclipselink.result-collection-type", java.util.ArrayList.class);

Example: @QueryHint

 import org.eclipse.persistence.config.HintValues;
 import org.eclipse.persistence.config.QueryHints;
 @QueryHint(name=QueryHints.RESULT_COLLECTION_TYPE, value="java.util.ArrayList");


Eclipselink-logo.gif
Version: 2.2.0 DRAFT
Other versions...