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/Examples/JPA/Caching"
(→How to use EclispeLink Caching) |
|||
| Line 6: | Line 6: | ||
By default EclipseLink uses a shared object cache, that caches a subset of all objects read and persisted for the persistence unit. | By default EclipseLink uses a shared object cache, that caches a subset of all objects read and persisted for the persistence unit. | ||
| − | The EclipseLink shared cache differs from the local EntityManager cache. The shared cache exists for the duration of the persistence unit (EntityManagerFactory, or server) and is shared by all EntityManagers and users of the persistence unit. The local EntityManager cache | + | The EclipseLink shared cache differs from the local EntityManager cache. The shared cache exists for the duration of the persistence unit (EntityManagerFactory, or server) and is shared by all EntityManagers and users of the persistence unit. The local EntityManager cache is not shared, and only exists for the duration of the EntityManager or transaction. |
The benefit of the shared cache, is that once an object has been read, if it is read again by <code>Id</code>, the database does not need to be accessed. | The benefit of the shared cache, is that once an object has been read, if it is read again by <code>Id</code>, the database does not need to be accessed. | ||
| Line 222: | Line 222: | ||
| headers="r10c1-t19 r1c5-t19" align="left" | <br> | | headers="r10c1-t19 r1c5-t19" align="left" | <br> | ||
|} | |} | ||
| − | |||
== Caching in Clustered Environments == | == Caching in Clustered Environments == | ||
==Relevant API== | ==Relevant API== | ||
Revision as of 16:46, 24 November 2009
In progress
Contents
How to use EclispeLink Caching
By default EclipseLink uses a shared object cache, that caches a subset of all objects read and persisted for the persistence unit. The EclipseLink shared cache differs from the local EntityManager cache. The shared cache exists for the duration of the persistence unit (EntityManagerFactory, or server) and is shared by all EntityManagers and users of the persistence unit. The local EntityManager cache is not shared, and only exists for the duration of the EntityManager or transaction.
The benefit of the shared cache, is that once an object has been read, if it is read again by Id, the database does not need to be accessed.
The limitation of the shared cache, is that if the database is changed directly through JDBC, or by another application or server, the objects in the shared cache will be stale.
EclipseLink offers several mechanism to deal with stale data including:
- Refreshing
- Invalidation
- Optimistic locking
- Cache coordination
The shared cache can also be disabled. This can be done using the persistence unit property:
"eclipselink.cache.shared.default"="false"
Or can be selectively enabled/disabled using the @Cache annotation.
EclipseLink also offers several different caching strategies, the configure how many objects are cached, and how much memory is used.
Note, the CacheType NONE should not be used to disable the cache, instead shared should be set to false.
| Option (Identity Map) | Caching | Guaranteed Identity | Memory Use |
|---|---|---|---|
|
Full Identity Map |
Yes |
Yes |
Very High |
|
Weak Identity Map |
Yes |
Yes |
Low |
|
Soft Identity Map |
Yes |
Yes |
High |
|
Soft Cache Weak Identity Map |
Yes |
Yes |
Medium-high |
|
No Identity Map |
No |
No |
None |
See the documentation for details on these types.
Using the @Cache Annotation
You may define the @Cache annotation on the following:
- @Entity
- @MappedSuperclass;
- the root of the inheritance hierarchy (if applicable).
If you define the @Cache annotation on an inheritance subclass, the annotation will be ignored. If you define the @Cache annotation on @Embeddable EclipseLink will throw an exception.
Example of @Cache Annotation
@Target({TYPE}) @Retention(RUNTIME) public @interface Cache { CacheType type() default SOFT_WEAK; int size() default 100; boolean shared() default true; int expiry() default -1; TimeOfDay expiryTimeOfDay() default @TimeOfDay(specified=false); boolean alwaysRefresh() default false; boolean refreshOnlyIfNewer() default false; boolean disableHits() default false; CacheCoordinationType coordinationType() default SEND_OBJECT_CHANGES; }
Attributes of the @Cache Annotation
| Attribute | Description | Default | Required or Optional | Override with Persistence Unit Property |
|---|---|---|---|---|
|
type |
Set this attribute to the type (org.eclipse.persistence.annotations.CacheType enumerated type) of the cache that you will be using:
|
CacheType.SOFT_WEAK |
optional |
|
|
size |
Set this attribute to an int value to define the size of cache to use (number of objects). |
100 |
|
|
|
shared |
Indicate whether cached instances should be in the shared cache or in a client isolated cache (see Isolated Client Session Cache).
|
true |
optional |
|
|
expiry |
The int value to enable the expiration of the cached instance after a fixed period of time (milliseconds). Queries executed against the cache after this will be forced back to the database for a refreshed copy. |
-1 (no expiry) |
optional |
|
|
expiryTimeOfDay |
Specific time of day (org.eclipse.persistence.annotations.TimeOfDay) when the cached instance will expire. Queries executed against the cache after this will be forced back to the database for a refreshed copy. |
@TimeOfDay(specified=false) |
optional |
|
|
alwaysRefresh |
Set to a boolean value of true to force all queries that go to the database to always refresh the cache. |
false |
optional |
|
|
refreshOnlyIfNewer |
Set to a boolean value of true to force all queries that go to the database to refresh the cache only if the data received from the database by a query is newer than the data in the cache (as determined by the optimistic locking field). Note: This option only applies if one of the other refreshing options, such as alwaysRefresh, is already enabled. Note: A version field is necessary to apply this feature. |
false |
optional |
|
|
disableHits |
Set to a boolean value of true to force all queries to bypass the cache for hits, but still resolve against the cache for identity. This forces all queries to hit the database. |
false |
optional |
|
|
coordinationType |
Set this attribute to the cache coordination mode (org.eclipse.persistence.annotations.CacheCoordinationType enumerated type). |
CacheCoordinationType.SEND_OBJECT_CHANGES |
optional |
|