|
|
| Line 1: |
Line 1: |
| − | {{EclipseLink_UserGuide|info=y
| + | #REDIRECT[[EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Configuring]] |
| − | |api=y
| + | |
| − | |apis=
| + | |
| − | *[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/Cache.html @Cache]
| + | |
| − | |examples=y
| + | |
| − | |example=
| + | |
| − | *[[EclipseLink/Examples/JPA/Caching|Caching]]
| + | |
| − | }}
| + | |
| − | ==@Cache==
| + | |
| − | | + | |
| − | The Cache annotation is used to configure the EclipseLink object cache. By default EclipseLink uses a shared object cache to cache all objects. The caching type and options can be configured on a per class basis to allow optimal caching.
| + | |
| − | | + | |
| − | You can define the <tt>@Cache</tt> annotation on the following:
| + | |
| − | * <tt>@Entity</tt>
| + | |
| − | * <tt>@MappedSuperclass</tt>
| + | |
| − | * the root of the inheritance hierarchy (if applicable)<br>
| + | |
| − | | + | |
| − | If you define the <tt>@Cache</tt> annotation on an inheritance subclass, the annotation will be ignored. If you define the <tt>@Cache</tt> annotation on <tt>@Embeddable</tt> EclipseLink will throw an exception.
| + | |
| − | | + | |
| − | {{EclipseLink_AttributeTable
| + | |
| − | |caption=@Cache Annotation Attributes
| + | |
| − | |content=
| + | |
| − | <tr>
| + | |
| − | <td><tt>type</tt></td>
| + | |
| − | <td>Set this attribute to the type (<tt>org.eclipse.persistence.annotations.CacheType</tt> enumerated type) of the cache that you will be using:
| + | |
| − | *FULL
| + | |
| − | *WEAK
| + | |
| − | *SOFT
| + | |
| − | *SOFT_WEAK
| + | |
| − | *HARD_WEAK
| + | |
| − | *CACHE (not recommended)
| + | |
| − | *NONE (not recommended, use shared=false instead)
| + | |
| − | | + | |
| − | You can override this attribute with these persistence unit properties:
| + | |
| − | * <tt>eclipselink.cache.type.<ENTITY></tt>
| + | |
| − | * <tt>eclipselink.cache.type.default</tt>
| + | |
| − | </td>
| + | |
| − | <td><tt>CacheType.SOFT_WEAK</tt></td>
| + | |
| − | <td>Optional</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td><tt>size</tt></td>
| + | |
| − | <td>Set this attribute to an <tt>int</tt> value to define the size of cache to use (number of objects)</td>
| + | |
| − | <td>100</td>
| + | |
| − | <td></td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td><tt>shared</tt></td>
| + | |
| − | <td>Indicate whether cached instances should be in the shared cache or in a client isolated cache (see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Isolated Client Session Cache|Isolated Client Session Cache]]). This allows the shared cache (L2 cache) to be disabled.
| + | |
| − | * <tt>true</tt> - use shared cache for cached instances;
| + | |
| − | * <tt>false</tt> - use client isolated cache for cached instances (no L2 cache).</td>
| + | |
| − | <td><tt>true</tt></td>
| + | |
| − | <td>Optional</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td><tt>expiry</tt></td>
| + | |
| − | <td>The <tt>int</tt> 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.</td>
| + | |
| − | <td>-1 (no expiry)</td>
| + | |
| − | <td>Optional</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td><tt>expiryTimeOfDay</tt></td>
| + | |
| − | <td>Specific time of day (<tt>org.eclipse.persistence.annotations.TimeOfDay</tt>) when the cached instance will expire. Queries executed against the cache after this will be forced back to the database for a refreshed copy.</td>
| + | |
| − | <td>
| + | |
| − | <tt>@TimeOfDay(specified=false)</tt></td>
| + | |
| − | <td>Optional</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td><tt>alwaysRefresh</tt></td>
| + | |
| − | <td>Set to a <tt>boolean</tt> value of <tt>true</tt> to force all queries that go to the database to always refresh the cache.</td>
| + | |
| − | <td><tt>false</tt></td>
| + | |
| − | <td>Optional</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td><tt>refreshOnlyIfNewer</tt></td>
| + | |
| − | <td>Set to a <tt>boolean</tt> value of <tt>true</tt> 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 <tt>alwaysRefresh</tt>, is already enabled.
| + | |
| − | | + | |
| − | Note: A version field is necessary to apply this feature.</td>
| + | |
| − | <td><tt>false</tt></td>
| + | |
| − | <td>Optional</td>
| + | |
| − | </tr><tr>
| + | |
| − | <td><tt>disableHits</tt></td>
| + | |
| − | <td>Set to a <tt>boolean</tt> value of <tt>true</tt> 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.
| + | |
| − | </td>
| + | |
| − | <td><tt>false</tt></td>
| + | |
| − | <td>Optional</td>
| + | |
| − | </tr><tr>
| + | |
| − | <td><tt>coordinationType</tt></td>
| + | |
| − | <td>Set this attribute to the cache coordination mode (<tt>org.eclipse.persistence.annotations.CacheCoordinationType</tt> enumerated type).</td>
| + | |
| − | <td><tt>CacheCoordinationType.SEND_OBJECT_CHANGES</tt></td>
| + | |
| − | <td>Optional</td>
| + | |
| − | </tr>
| + | |
| − | }}
| + | |
| − | | + | |
| − | ======''@Cache Annotation Example''======
| + | |
| − | <span id="Example_of_@Cache Annotation"></span>
| + | |
| − | <source lang="java">
| + | |
| − | ...
| + | |
| − | @Entity
| + | |
| − | @Cache(
| + | |
| − | type=CacheType.SOFT, // Cache everything until the JVM decides memory is low.
| + | |
| − | size=64000 // Use 64,000 as the initial cache size.
| + | |
| − | expiry=36000000, // 10 minutes
| + | |
| − | coordinationType=CacheCoordinationType.INVALIDATE_CHANGED_OBJECTS // if cache coordination is used, only send invalidation messages.
| + | |
| − | )
| + | |
| − | public class Employee {
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | {{EclipseLink_JPA
| + | |
| − | |previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Caching Overview|Caching Overview]]
| + | |
| − | |next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Shared and Isolated|Shared and Isolated Cache]]
| + | |
| − | |up=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development|Caching]]
| + | |
| − | |version=2.2.0 DRAFT}}
| + | |
