Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Query Options"

From Eclipsepedia

Jump to: navigation, search
(Query Options and In-memory Querying)
(Query Options and In-memory Querying)
Line 20: Line 20:
 
Entities can be accessed through JPA using either <tt>find()</tt> or queries.  <tt>find()</tt> will first check the persistence context cache (L1) for the Id, if the object is not found it will check the shared persistence unit cache (L2), if the object is still not found it will access the database.  By default all queries will access the database, unless querying by Id or by cache indexed fields.  Once the query retrieves the rows from the database, it will resolve each row with the cache.  If the object is already in the cache, then the row will be discarded, and the object will be used.  If the object is not in the shared cache, then it will be built from the row and put into the shared cache.  A copy will also be put in the persistence context cache and returned as the query result.
 
Entities can be accessed through JPA using either <tt>find()</tt> or queries.  <tt>find()</tt> will first check the persistence context cache (L1) for the Id, if the object is not found it will check the shared persistence unit cache (L2), if the object is still not found it will access the database.  By default all queries will access the database, unless querying by Id or by cache indexed fields.  Once the query retrieves the rows from the database, it will resolve each row with the cache.  If the object is already in the cache, then the row will be discarded, and the object will be used.  If the object is not in the shared cache, then it will be built from the row and put into the shared cache.  A copy will also be put in the persistence context cache and returned as the query result.
  
This is the general process, but it differs if the transaction is <i>dirty</i>.  If the transaction is diry then the shared cache will be ignored and objects will be built directly from the row data.
+
This is the general process, but it differs if the transaction is <i>dirty</i>.  If the transaction is diry then the shared persistence unit cache will be ignored and objects will be built directly into the persistence context cache.
  
 
A transaction is considered dirty in the following circumstances:
 
A transaction is considered dirty in the following circumstances:
Line 33: Line 33:
 
Entities can also be configured to be isolated, or non cacheable, in which case they will never be placed in the shared cache (see [[EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Shared and Isolated|Shared, Isolated, Protected, Weak and Read-only Cache]]).
 
Entities can also be configured to be isolated, or non cacheable, in which case they will never be placed in the shared cache (see [[EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Shared and Isolated|Shared, Isolated, Protected, Weak and Read-only Cache]]).
  
==Configuring Query Results Cache==
+
==JPA Cache Query Hints==
The query results cache is configured through query hints.
+
JPA 2.0 defines the following query hints to configure a queries interaction with the shared cache:
 
+
 
{{EclipseLink_HintTable
 
{{EclipseLink_HintTable
|caption=Query Results Cache Query Hints
+
|caption=JPA Cache Query Hints
 
|content=
 
|content=
 
<tr>
 
<tr>
  <td><tt>eclipselink.query-results-cache</tt></td>
+
  <td><tt>javax.persistence.cache.retrieveMode</tt></td>
  <td>Enable query results cache for the named query.</td>
+
  <td>Configure how the shared cache is accessed.
<td>no cached results</td>
+
Valid values are defined in <tt>CacheRetrieveMode</tt> enum:
<td>Required</td>
+
* <tt>BYPASS</tt> : Ignore the shared persistence unit cache, and build the object directly into the persistence context cache.
</tr>
+
* <tt>USE</tt> : Use the shared persistence unit cache. If the object is already in the shared cache, use the object.
<tr>
+
</td>
<td><tt>eclipselink.query-results-cache.size</tt></td>
+
  <td><tt>USE</tt></td>
<td>Sets the fixed size of the query results cache for the named query.  The size is the number of queries with unique parameters to cache.
+
If the query has no parameters, a value of 1 should be used.</td>
+
  <td><tt>100</tt></td>
+
 
  <td>Optional</td>
 
  <td>Optional</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
  <td><tt>eclipselink.query-results-cache.expiry</tt></td>
+
  <td><tt>javax.persistence.cache.storeMode</tt></td>
  <td>Sets the expiry time in milliseconds of the cached results.</td>
+
  <td>Configure how the shared cache is modified.
<td>no expiry</td>
+
Valid values are defined in <tt>CacheStoreMode</tt> enum:
<td>Optional</td>
+
* <tt>BYPASS</tt> : Do not put any object build from the row data into the shared cache.
</tr>
+
* <tt>REFRESH</tt> : If the object is in the shared cache, refresh its data from the database row data.
<tr>
+
* <tt>USE</tt> : If the object is not in the shared cache, then build it from the database row data and put it into the shared cache.
<td><tt>eclipselink.query-results-cache.expiry-time-of-day</tt></td>
+
<td>Configures the time of day expiry.  Valid values are string time format, "HH:MM:SS".</td>
+
<td>no expiry</td>
+
<td>Optional</td>
+
</tr>
+
<tr>
+
<td><tt>eclipselink.query-results-cache.randomize-expiry</tt></td>
+
<td>Set if the expiry time should be randomized by 10% of the set expiry time. This can be used to avoid a bottleneck on a fixed expiry time.</td>
+
<td><tt>false</tt></td>
+
<td>Optional</td>
+
</tr>
+
<tr>
+
<td><tt>eclipselink.query-results-cache.type</tt></td>
+
<td>Set the cache type.  Valid values are defined in the <tt>CacheType</tt> enum. Normally an LRU fixed sized <tt>CACHE</tt> is used, a <tt>FULL</tt>, <tt>WEAK</tt> or <tt>SOFT</tt> cache can also be used.</td>
+
<td><tt>CACHE</tt></td>
+
<td>Optional</td>
+
 
</tr>
 
</tr>
 
}}
 
}}
 +
 +
======''Refresh query hint example''======
 +
<source lang="java">
 +
Query query = em.createQuery("Select e from Employee e where e.address.city = :city");
 +
query.setHint("javax.persistence.cache.storeMode, REFRESH);
 +
query.setParameter("city", "Ottawa");
 +
List<Employee> employees = query.getResultList();
 +
</source>
  
 
======''In-memory query example''======
 
======''In-memory query example''======

Revision as of 14:07, 29 May 2012

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

Contents


Query Options and In-memory Querying

JPA defines standard query hints for configuring how a query interacts with the shared persistence unit cache (L2). EclipseLink also provides some additional query hints for configuring the cache usage.

Entities can be accessed through JPA using either find() or queries. find() will first check the persistence context cache (L1) for the Id, if the object is not found it will check the shared persistence unit cache (L2), if the object is still not found it will access the database. By default all queries will access the database, unless querying by Id or by cache indexed fields. Once the query retrieves the rows from the database, it will resolve each row with the cache. If the object is already in the cache, then the row will be discarded, and the object will be used. If the object is not in the shared cache, then it will be built from the row and put into the shared cache. A copy will also be put in the persistence context cache and returned as the query result.

This is the general process, but it differs if the transaction is dirty. If the transaction is diry then the shared persistence unit cache will be ignored and objects will be built directly into the persistence context cache.

A transaction is considered dirty in the following circumstances:

  • A flush() has written changes to the database.
  • A pessimistic lock query has been executed.
  • An update or delete query has been executed.
  • A native SQL query has been executed.
  • This persistence unit property "eclipselink.transaction.join-existing" is used.
  • The JDBC connection has been unwrapped from the EntityManager.
  • The UnitOfWork API beginEarlyTransaction has been called.

Entities can also be configured to be isolated, or non cacheable, in which case they will never be placed in the shared cache (see Shared, Isolated, Protected, Weak and Read-only Cache).

JPA Cache Query Hints

JPA 2.0 defines the following query hints to configure a queries interaction with the shared cache:

JPA Cache Query Hints
Hint Description Default Required?
javax.persistence.cache.retrieveMode Configure how the shared cache is accessed.

Valid values are defined in CacheRetrieveMode enum:

  • BYPASS : Ignore the shared persistence unit cache, and build the object directly into the persistence context cache.
  • USE : Use the shared persistence unit cache. If the object is already in the shared cache, use the object.
USE Optional
javax.persistence.cache.storeMode Configure how the shared cache is modified.

Valid values are defined in CacheStoreMode enum:

  • BYPASS : Do not put any object build from the row data into the shared cache.
  • REFRESH : If the object is in the shared cache, refresh its data from the database row data.
  • USE : If the object is not in the shared cache, then build it from the database row data and put it into the shared cache.
Refresh query hint example
Query query = em.createQuery("Select e from Employee e where e.address.city = :city");
query.setHint("javax.persistence.cache.storeMode, REFRESH);
query.setParameter("city", "Ottawa");
List<Employee> employees = query.getResultList();
In-memory query example
Query query = em.createQuery("Select e from Employee e where e.firstName like :firstName and e.lastName like :lastName");
query.setParameter("firstName", "B%");
query.setParameter("lastName", "S%");
List<Employee> employees = query.getResultList();

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