Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Query Options"
(→JPA Cache Query Hints) |
(→EclipseLink cache query hint examples) |
||
(11 intermediate revisions by the same user not shown) | |||
Line 7: | Line 7: | ||
|apis= | |apis= | ||
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/QueryHints.html QueryHints] | *[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/QueryHints.html QueryHints] | ||
+ | *[http://www.eclipse.org/eclipselink/api/latest/javax/persistence/CacheRetrieveMode.html CacheRetrieveMode] | ||
+ | *[http://www.eclipse.org/eclipselink/api/latest/javax/persistence/CacheStoreMode.html CacheStoreMode] | ||
+ | *[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/CascadePolicy.html CascadePolicy] | ||
+ | *[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/CacheUsage.html CacheUsage] | ||
|nativeapi=y | |nativeapi=y | ||
|nativeapis= | |nativeapis= | ||
Line 34: | Line 38: | ||
==JPA Cache Query Hints== | ==JPA Cache Query Hints== | ||
− | JPA | + | The JPA query hints allow for queries or the <tt>find()</tt> operation to bypass, or refresh the shared cache. JPA cache query hints can be set on named or dynamic queries, or set in the properties map passed to the <tt>find()</tt> operation. |
+ | |||
+ | JPA 2.0 defines the following query hints to configure a queries interaction with the shared cache: | ||
{{EclipseLink_HintTable | {{EclipseLink_HintTable | ||
|caption=JPA Cache Query Hints | |caption=JPA Cache Query Hints | ||
Line 70: | Line 76: | ||
==EclipseLink Cache Query Hints== | ==EclipseLink Cache Query Hints== | ||
− | EclipseLink defines the following query hints to configure a queries interaction with the | + | The EclipseLink cache query hints allow for queries or the <tt>find()</tt> operation to interact with the cache is the following ways: |
+ | * Bypass the cache check and force accessing the database, but still resolve with the cache. | ||
+ | * Refresh the cache from the database results. | ||
+ | * Bypass the cache and persistence unit and return detached objects. | ||
+ | * Bypass the persistence context and return read-only objects. | ||
+ | * Allow queries that use Id fields, and other fields to obtain cache hits. | ||
+ | * Query the cache first, and only access the database if the object is not found. | ||
+ | * Only query the cache, and avoid accessing the database. | ||
+ | * Conform a query with non-flushed changes in a persistence context. | ||
+ | |||
+ | Queries that access the cache have the following restrictions: | ||
+ | * Sub-selects are not supported. | ||
+ | * Certain database functions are not supported. | ||
+ | * Queries must return a single set of objects. | ||
+ | * Grouping is not supported. | ||
+ | * Uninstantiated lazy relationships may not be able to be queried. | ||
+ | |||
+ | EclipseLink defines the following query hints to configure a queries interaction with the cache: | ||
{{EclipseLink_HintTable | {{EclipseLink_HintTable | ||
|caption=EclipseLink Cache Query Hints | |caption=EclipseLink Cache Query Hints | ||
Line 83: | Line 106: | ||
<tr> | <tr> | ||
<td><tt>eclipselink.refresh.cascade</tt></td> | <td><tt>eclipselink.refresh.cascade</tt></td> | ||
− | <td> | + | <td>Configures how refreshing is cascaded to relationships, if the query has been configured to refresh. |
+ | Valid values are defined in <tt>CascadePolicy</tt>: | ||
* <tt>NoCascading</tt> - Do not cascade the refresh to relationships. | * <tt>NoCascading</tt> - Do not cascade the refresh to relationships. | ||
* <tt>CascadePrivateParts</tt> - Only cascade the refresh to private (orphan-removal) relationships. | * <tt>CascadePrivateParts</tt> - Only cascade the refresh to private (orphan-removal) relationships. | ||
Line 90: | Line 114: | ||
</td> | </td> | ||
<td><tt>CascadeByMapping</tt></td> | <td><tt>CascadeByMapping</tt></td> | ||
+ | <td>Optional</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td><tt>eclipselink.cache-usage</tt></td> | ||
+ | <td>Configures in-memory querying and cache usage. | ||
+ | Valid values are defined in <tt>CacheUsage</tt>: | ||
+ | * <tt>DoNotCheckCache</tt> - Do not check the cache before accessing the database. The cache is still used to resolve rows. | ||
+ | * <tt>CheckCacheByExactPrimaryKey</tt> - Only check the cache if the query is on only the Id or cache indexed fields. | ||
+ | * <tt>CheckCacheByPrimaryKey</tt> - Check the cache if the query is on any Id or cache index field. Conform the query in memory to ensure the object matches the query criteria. | ||
+ | * <tt>CheckCacheThenDatabase</tt> - Check the cache first before accessing the database. If any object is found in the cache matching the query criteria then return it. Only for use with single result queries. | ||
+ | * <tt>CheckCacheOnly</tt> - Only check the cache and do not access the database. Return all objects found in the cache that match the query criteria. Note that not all queries can be conformed in memory. | ||
+ | * <tt>ConformResultsInUnitOfWork</tt> - Access the database, but conform the results with any un-flushed in-memory changes made in the persistence context. Include any un-flushed new objects and exclude and un-flushed removed objects. | ||
+ | * <tt>NoCache</tt> - For update and delete queries only. Do not invalidate the cache for the queries modified data. | ||
+ | * <tt>Invalidate</tt> - For update and delete queries only. Invalidate the cache for the queries modified data (default). | ||
+ | </td> | ||
+ | <td><tt>CheckCacheByExactPrimaryKey</tt></td> | ||
+ | <td>Optional</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td><tt>eclipselink.maintain-cache</tt></td> | ||
+ | <td>Configure the query to bypass both the shared and the persistence context cache. This returns detached objects. | ||
+ | Depending on the cascade mode, the detached objects relationships may be managed or also detached. | ||
+ | </td> | ||
+ | <td><tt>true</tt></td> | ||
+ | <td>Optional</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td><tt>eclipselink.read-only</tt></td> | ||
+ | <td>Configure the query to return read-only objects, and bypass the persistence context cache. | ||
+ | Read-only objects are from the shared cache (depending on the cache isolation), and must not be modified. | ||
+ | </td> | ||
+ | <td><tt>false</tt></td> | ||
<td>Optional</td> | <td>Optional</td> | ||
</tr> | </tr> | ||
}} | }} | ||
− | ======'' | + | ======''EclipseLink cache query hint examples''====== |
<source lang="java"> | <source lang="java"> | ||
+ | // This avoids accessing the database a returns the first employee with the name from the cache. | ||
Query query = em.createQuery("Select e from Employee e where e.firstName like :firstName and e.lastName like :lastName"); | Query query = em.createQuery("Select e from Employee e where e.firstName like :firstName and e.lastName like :lastName"); | ||
− | query.setParameter("firstName", " | + | query.setHint("eclipselink.cache-usage", "CheckCacheThenDatabase"); |
+ | query.setParameter("firstName", "Bob"); | ||
+ | query.setParameter("lastName", "Smith"); | ||
+ | List<Employee> employees = query.getResultList(); | ||
+ | </source> | ||
+ | |||
+ | <source lang="java"> | ||
+ | // This avoids accessing the database a returns all of the employees with the last name from the cache. | ||
+ | Query query = em.createQuery("Select e from Employee e where e.lastName like :lastName"); | ||
+ | query.setHint("eclipselink.cache-usage", "CheckCacheOnly"); | ||
query.setParameter("lastName", "S%"); | query.setParameter("lastName", "S%"); | ||
+ | List<Employee> employees = query.getResultList(); | ||
+ | </source> | ||
+ | |||
+ | <source lang="java"> | ||
+ | // This retrieves the old state of the employee, without its changes made in the persistence context. | ||
+ | Query query = em.createQuery("Select e from Employee e where e.id = :id"); | ||
+ | query.setHint("eclipselink.maintain-cache", "false"); | ||
+ | query.setParameter("id", id); | ||
+ | Employee stateInDatabase = (Employee)query.getSingleResult(); | ||
+ | </source> | ||
+ | |||
+ | <source lang="java"> | ||
+ | // This improves performance by avoiding copying and change tracking the objects. | ||
+ | Query query = em.createQuery("Select e from Employee e"); | ||
+ | query.setHint("eclipselink.read-only", "true"); | ||
+ | List<Employee> employees = query.getResultList(); | ||
+ | </source> | ||
+ | |||
+ | <source lang="java"> | ||
+ | // This query will include new object from the persistence context, without requiring flush to be called. | ||
+ | Query query = em.createQuery("Select e from Employee e"); | ||
+ | query.setHint("eclipselink.cache-usage", "ConformResultsInUnitOfWork"); | ||
List<Employee> employees = query.getResultList(); | List<Employee> employees = query.getResultList(); | ||
</source> | </source> | ||
Line 104: | Line 192: | ||
{{EclipseLink_JPA | {{EclipseLink_JPA | ||
|previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Query Cache|Query Results Cache]] | |previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Query Cache|Query Results Cache]] | ||
− | |next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/ | + | |next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Cache API|Cache API]] |
|up=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching|Caching]] | |up=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching|Caching]] | ||
|version=2.4 DRAFT}} | |version=2.4 DRAFT}} |
Latest revision as of 14:21, 30 May 2012
EclipseLink JPA
EclipseLink | |
Website | |
Download | |
Community | |
Mailing List • Forums • IRC • mattermost | |
Issues | |
Open • Help Wanted • Bug Day | |
Contribute | |
Browse Source |
Native API
Contents
Query Cache 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
The JPA query hints allow for queries or the find() operation to bypass, or refresh the shared cache. JPA cache query hints can be set on named or dynamic queries, or set in the properties map passed to the find() operation.
JPA 2.0 defines the following query hints to configure a queries interaction with the shared cache:
Hint | Description | Default | Required? |
---|---|---|---|
javax.persistence.cache.retrieveMode | Configure how the shared cache is accessed.
Valid values are defined in CacheRetrieveMode enum:
|
USE | Optional |
javax.persistence.cache.storeMode | Configure how the shared cache is modified.
Valid values are defined in CacheStoreMode enum:
|
USE | Optional |
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();
EclipseLink Cache Query Hints
The EclipseLink cache query hints allow for queries or the find() operation to interact with the cache is the following ways:
- Bypass the cache check and force accessing the database, but still resolve with the cache.
- Refresh the cache from the database results.
- Bypass the cache and persistence unit and return detached objects.
- Bypass the persistence context and return read-only objects.
- Allow queries that use Id fields, and other fields to obtain cache hits.
- Query the cache first, and only access the database if the object is not found.
- Only query the cache, and avoid accessing the database.
- Conform a query with non-flushed changes in a persistence context.
Queries that access the cache have the following restrictions:
- Sub-selects are not supported.
- Certain database functions are not supported.
- Queries must return a single set of objects.
- Grouping is not supported.
- Uninstantiated lazy relationships may not be able to be queried.
EclipseLink defines the following query hints to configure a queries interaction with the cache:
Hint | Description | Default | Required? |
---|---|---|---|
eclipselink.refresh | Configure the query to refresh the objects in both the shared cache and/or the persistence context cache with the database row data. | false | Optional |
eclipselink.refresh.cascade | Configures how refreshing is cascaded to relationships, if the query has been configured to refresh.
Valid values are defined in CascadePolicy:
|
CascadeByMapping | Optional |
eclipselink.cache-usage | Configures in-memory querying and cache usage.
Valid values are defined in CacheUsage:
|
CheckCacheByExactPrimaryKey | Optional |
eclipselink.maintain-cache | Configure the query to bypass both the shared and the persistence context cache. This returns detached objects.
Depending on the cascade mode, the detached objects relationships may be managed or also detached. |
true | Optional |
eclipselink.read-only | Configure the query to return read-only objects, and bypass the persistence context cache.
Read-only objects are from the shared cache (depending on the cache isolation), and must not be modified. |
false | Optional |
EclipseLink cache query hint examples
// This avoids accessing the database a returns the first employee with the name from the cache. Query query = em.createQuery("Select e from Employee e where e.firstName like :firstName and e.lastName like :lastName"); query.setHint("eclipselink.cache-usage", "CheckCacheThenDatabase"); query.setParameter("firstName", "Bob"); query.setParameter("lastName", "Smith"); List<Employee> employees = query.getResultList();
// This avoids accessing the database a returns all of the employees with the last name from the cache. Query query = em.createQuery("Select e from Employee e where e.lastName like :lastName"); query.setHint("eclipselink.cache-usage", "CheckCacheOnly"); query.setParameter("lastName", "S%"); List<Employee> employees = query.getResultList();
// This retrieves the old state of the employee, without its changes made in the persistence context. Query query = em.createQuery("Select e from Employee e where e.id = :id"); query.setHint("eclipselink.maintain-cache", "false"); query.setParameter("id", id); Employee stateInDatabase = (Employee)query.getSingleResult();
// This improves performance by avoiding copying and change tracking the objects. Query query = em.createQuery("Select e from Employee e"); query.setHint("eclipselink.read-only", "true"); List<Employee> employees = query.getResultList();
// This query will include new object from the persistence context, without requiring flush to be called. Query query = em.createQuery("Select e from Employee e"); query.setHint("eclipselink.cache-usage", "ConformResultsInUnitOfWork"); List<Employee> employees = query.getResultList();