Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Cache Annotation"

m
Line 1: Line 1:
 +
{{EclipseLink_UserGuide|info=y
 +
|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 Annotation==
 
==@Cache Annotation==
  
Line 8: Line 16:
 
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.
 
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.
  
−
''''' Attributes of the @Cache Annotation'''''
+
{{EclipseLink_AttributeTable
−
 
+
|caption=@Cache Annotation Attributes
−
{|class="RuleFormalWideMax" width ="100" dir="ltr" title="Attributes of the @Cache Annotation" summary="This table lists the attributes of EclipseLink JPA Cache annotation" border="3" frame="border" rules="all" cellpadding="3"
+
|content=
−
|- align="left" valign="top"
+
<tr>
−
! id="r1c1-t19" align="left" valign="bottom" | '''Attribute'''
+
<td><tt>type</tt></td>
−
! id="r1c2-t19" align="left" valign="bottom" | '''Description'''
+
<td>Set this attribute to the type (<tt>org.eclipse.persistence.annotations.CacheType</tt> enumerated type) of the cache that you will be using:
−
! id="r1c3-t19" align="left" valign="bottom" | '''Default'''
+
−
! id="r1c4-t19" align="left" valign="bottom" | '''Required or Optional'''
+
−
! id="r1c5-t19" align="left" valign="bottom" | '''Override with Persistence Unit Property'''
+
−
|- align="left" valign="top"
+
−
| id="r2c1-t19" headers="r1c1-t19" align="left" |
+
−
<tt>type</tt>
+
−
| headers="r2c1-t19 r1c2-t19" align="left" |
+
−
Set this attribute to the type (<tt>org.eclipse.persistence.annotations.CacheType</tt> enumerated type) of the cache that you will be using:
+
 
*FULL
 
*FULL
 
*WEAK
 
*WEAK
Line 29: Line 29:
 
*CACHE (not recommended)
 
*CACHE (not recommended)
 
*NONE (not recommended, use shared=false instead)
 
*NONE (not recommended, use shared=false instead)
−
| headers="r2c1-t19 r1c3-t19" align="left" |
+
 
−
<tt>CacheType.SOFT_WEAK</tt>
+
You can override this attribute with these persistence unit properties:
−
| headers="r2c1-t19 r1c4-t19" align="left" |
+
−
optional
+
−
| headers="r2c1-t19 r1c5-t19" align="left" |
+
 
* <tt>eclipselink.cache.type.<ENTITY></tt>
 
* <tt>eclipselink.cache.type.<ENTITY></tt>
 
* <tt>eclipselink.cache.type.default</tt>
 
* <tt>eclipselink.cache.type.default</tt>
−
|- align="left" valign="top"
+
</td>
−
| id="r3c1-t19" headers="r1c1-t19" align="left" |
+
<td><tt>CacheType.SOFT_WEAK</tt></td>
−
<tt>size</tt>
+
<td>Optional</td>
−
| headers="r3c1-t19 r1c2-t19" align="left" |
+
</tr>
−
Set this attribute to an <tt>int</tt> value to define the size of cache to use (number of objects).
+
<tr>
−
| headers="r3c1-t19 r1c3-t19" align="left" |
+
<td><tt>size</tt></td>
−
100
+
<td>Set this attribute to an <tt>int</tt> value to define the size of cache to use (number of objects)</td>
−
| headers="r3c1-t19 r1c4-t19" align="left" | <br>
+
<td>100</td>
−
| headers="r3c1-t19 r1c5-t19" align="left" | <br>
+
<td></td>
−
|- align="left" valign="top"
+
</tr>
−
| id="r4c1-t19" headers="r1c1-t19" align="left" |
+
<tr>
−
<tt>shared</tt>
+
<td><tt>shared</tt></td>
−
| headers="r4c1-t19 r1c2-t19" align="left" |
+
<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.
−
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>true</tt> - use shared cache for cached instances;
−
* <tt>false</tt> - use client isolated cache for cached instances (no L2 cache).
+
* <tt>false</tt> - use client isolated cache for cached instances (no L2 cache).</td>
−
| headers="r4c1-t19 r1c3-t19" align="left" |
+
<td><tt>true</tt></td>
−
<tt>true</tt>
+
<td>Optional</td>
−
| headers="r4c1-t19 r1c4-t19" align="left" |
+
</tr>
−
optional
+
<tr>
−
| headers="r4c1-t19 r1c5-t19" align="left" | <br>
+
<td><tt>expiry</tt></td>
−
|- align="left" valign="top"
+
<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>
−
| id="r5c1-t19" headers="r1c1-t19" align="left" |
+
<td>-1 (no expiry)</td>
−
<tt>expiry</tt>
+
<td>Optional</td>
−
| headers="r5c1-t19 r1c2-t19" align="left" |
+
</tr>
−
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.
+
<tr>
−
| headers="r5c1-t19 r1c3-t19" align="left" |
+
<td><tt>expiryTimeOfDay</tt></td>
−
-1 (no expiry)
+
<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>
−
| headers="r5c1-t19 r1c4-t19" align="left" |
+
<td>
−
optional
+
<tt>@TimeOfDay(specified=false)</tt></td>
−
| headers="r5c1-t19 r1c5-t19" align="left" | <br>
+
<td>Optional</td>
−
|- align="left" valign="top"
+
</tr>
−
| id="r6c1-t19" headers="r1c1-t19" align="left" |
+
<tr>
−
<tt>expiryTimeOfDay</tt>
+
<td><tt>alwaysRefresh</tt></td>
−
| headers="r6c1-t19 r1c2-t19" align="left" |
+
<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>
−
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><tt>false</tt></td>
−
| headers="r6c1-t19 r1c3-t19" align="left" |
+
<td>Optional</td>
−
<tt>@TimeOfDay(specified=false)</tt>
+
</tr>
−
| headers="r6c1-t19 r1c4-t19" align="left" |
+
<tr>
−
optional
+
<td><tt>refreshOnlyIfNewer</tt></td>
−
| headers="r6c1-t19 r1c5-t19" align="left" | <br>
+
<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).
−
|- align="left" valign="top"
+
−
| id="r7c1-t19" headers="r1c1-t19" align="left" |
+
−
<tt>alwaysRefresh</tt>
+
−
| headers="r7c1-t19 r1c2-t19" align="left" |
+
−
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.
+
−
| headers="r7c1-t19 r1c3-t19" align="left" |
+
−
<tt>false</tt>
+
−
| headers="r7c1-t19 r1c4-t19" align="left" |
+
−
optional
+
−
| headers="r7c1-t19 r1c5-t19" align="left" | <br>
+
−
|- align="left" valign="top"
+
−
| id="r8c1-t19" headers="r1c1-t19" align="left" |
+
−
<tt>refreshOnlyIfNewer</tt>
+
−
| headers="r8c1-t19 r1c2-t19" align="left" |
+
−
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: 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.
+
Note: A version field is necessary to apply this feature.</td>
−
| headers="r8c1-t19 r1c3-t19" align="left" |
+
<td><tt>false</tt></td>
−
<tt>false</tt>
+
<td>Optional</td>
−
| headers="r8c1-t19 r1c4-t19" align="left" |
+
</tr><tr>
−
optional
+
<td><tt>disableHits</tt></td>
−
| headers="r8c1-t19 r1c5-t19" align="left" | <br>
+
<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.
−
|- align="left" valign="top"
+
</td>
−
| id="r9c1-t19" headers="r1c1-t19" align="left" |
+
<td><tt>false</tt></td>
−
<tt>disableHits</tt>
+
<td>Optional</td>
−
| headers="r9c1-t19 r1c2-t19" align="left" |
+
</tr><tr>
−
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><tt>coordinationType</tt></td>
−
| headers="r9c1-t19 r1c3-t19" align="left" |
+
<td>Set this attribute to the cache coordination mode (<tt>org.eclipse.persistence.annotations.CacheCoordinationType</tt> enumerated type).</td>
−
<tt>false</tt>
+
<td><tt>CacheCoordinationType.SEND_OBJECT_CHANGES</tt></td>
−
| headers="r9c1-t19 r1c4-t19" align="left" |
+
<td>Optional</td>
−
optional
+
</tr>
−
| headers="r9c1-t19 r1c5-t19" align="left" | <br>
+
}}
−
|- align="left" valign="top"
+
−
| id="r10c1-t19" headers="r1c1-t19" align="left" |
+
−
<tt>coordinationType</tt>
+
−
| headers="r10c1-t19 r1c2-t19" align="left" |
+
−
Set this attribute to the cache coordination mode (<tt>org.eclipse.persistence.annotations.CacheCoordinationType</tt> enumerated type).
+
−
| headers="r10c1-t19 r1c3-t19" align="left" |
+
−
<tt>CacheCoordinationType.SEND_OBJECT_CHANGES</tt>
+
−
| headers="r10c1-t19 r1c4-t19" align="left" |
+
−
optional
+
−
| headers="r10c1-t19 r1c5-t19" align="left" | <br>
+
−
|}
+
−
 
+
  
−
'''''Example of @Cache Annotation '''''
+
======''@Cache Annotation Example''====
 
<span id="Example_of_@Cache Annotation"></span>
 
<span id="Example_of_@Cache Annotation"></span>
 
<source lang="java">
 
<source lang="java">

Revision as of 12:29, 31 March 2011


Eclipselink-logo.gif
EclipseLink
Website
Download
Community
Mailing List • Forums • IRC • mattermost
Issues
Open • Help Wanted • Bug Day
Contribute
Browse Source

Elug api package icon.png Key API

Elug example icon.png Examples

@Cache Annotation

You can 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.

@Cache Annotation Attributes
Attribute Description Default Required?
type Set this attribute to the type (org.eclipse.persistence.annotations.CacheType 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:

  • eclipselink.cache.type.<ENTITY>
  • eclipselink.cache.type.default
 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). This allows the shared cache (L2 cache) to be disabled.
  • true - use shared cache for cached instances;
  • false - use client isolated cache for cached instances (no L2 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

==@Cache Annotation Example

...
@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 {
  ...
}

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

Retrieved from "https://wiki.eclipse.org/index.php?title=EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Cache_Annotation&oldid=244788"

Back to the top