|
|
Line 1: |
Line 1: |
− | {{EclipseLink_TLJPA
| + | #REDIRECT [[EclipseLink/UserGuide/JPA/2.4/toc]] |
− | |info=n
| + | |
− | |toc=n
| + | |
− | |category=JPA
| + | |
− | |release=2.4.x
| + | |
− | |title=TLJPA}}
| + | |
− | <span class="metaname"> </span>
| + | |
− | | + | |
− | {| class="simple oac_no_warn" width="100%"
| + | |
− | | align="left" valign="top" |
| + | |
− | | width="185" align="right" valign="bottom" |
| + | |
− | {| class="simple oac_no_warn" width="100%"
| + | |
− | |
| + | |
− | | align="center" valign="top" |
| + | |
− | [[Image:Elug_Magnifier.png|Search]][http://www.google.com/cse/home?cx=016171230611334810008:y5kxq4rqd8s&hl=en Search]
| + | |
− | | align="center" valign="top" |
| + | |
− | [[Image:Elug_guide_icon.png|Contents]][[EclipseLink/UserGuide/JPA/2.4/toc| Contents]]
| + | |
− | |}
| + | |
− | |}
| + | |
− | | + | |
− | ----
| + | |
− | | + | |
− | {| width="165"
| + | |
− | | align="center" |
| + | |
− | [[EclipseLink/UserGuide/JPA/2.4/a_batchfetch| Previous ]]<span class="previouslink">[[Image:Elug_previous_icon.png|Previous]]</span>
| + | |
− | | align="center" |
| + | |
− | [[EclipseLink/UserGuide/JPA/2.4/a_cacheindex| Next ]][[Image:Elug_next_icon.png|Next]]
| + | |
− | |
| + | |
− | |}
| + | |
− | | + | |
− | [[Image:Elug_draft_icon.png|Warning]]Beta Draft: 2012-06-18
| + | |
− | | + | |
− | <span id="CHDBBIHE"></span>
| + | |
− | | + | |
− | ----
| + | |
− | | + | |
− | ==@Cache==
| + | |
− | | + | |
− | Use <code>@Cache</code>) to configure the EclipseLink object cache. By default, EclipseLink uses a shared object cache to cache all objects. You can configure the caching type and options on a per class basis to allow optimal caching.
| + | |
− | | + | |
− | <span id="sthref33"></span>
| + | |
− | | + | |
− | ''' '''
| + | |
− | | + | |
− | ===Annotation Elements===
| + | |
− | | + | |
− | [[#CDEJJHDG|Table 2-4]] describes this annotation's elements.
| + | |
− | | + | |
− | <span id="sthref34"></span><span id="CDEJJHDG"></span>
| + | |
− | | + | |
− | '''''Table 2-4 @Cache Annotation Elements'''''
| + | |
− | | + | |
− | {| class="HRuleFormalWide" dir="ltr" title="@Cache Annotation Elements" summary="This table describes the list of attributes for this annotation." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
| + | |
− | |- align="left" valign="top"
| + | |
− | ! id="r1c1-t7" align="left" valign="bottom" | '''Annotation Element'''
| + | |
− | ! id="r1c2-t7" align="left" valign="bottom" | '''Description'''
| + | |
− | ! id="r1c3-t7" align="left" valign="bottom" | '''Default'''
| + | |
− | |- align="left" valign="top"
| + | |
− | | id="r2c1-t7" headers="r1c1-t7" align="left" |
| + | |
− | <code>type</code>
| + | |
− | | headers="r2c1-t7 r1c2-t7" align="left" |
| + | |
− | (Optional) Set this attribute to the type (org.eclipse.persistence.annotations.CacheType enumerated type) of the cache that you will be using:
| + | |
− | | + | |
− | * <code>FULL</code>
| + | |
− | * <code>WEAK</code>
| + | |
− | * <code>SOFT</code>
| + | |
− | * <code>SOFT_WEAK</code>
| + | |
− | * <code>HARD_WEAK</code>
| + | |
− | * <code>CACHE</code> (not recommended)
| + | |
− | * <code>NONE</code> (not recommended, use <code>shared=false</code> instead)
| + | |
− | | + | |
− | You can override this attribute with these persistence unit properties:
| + | |
− | | + | |
− | * <code>eclipselink.cache.type.<</code>''<code>ENTITY</code>''<code>></code>
| + | |
− | * <code>eclipselink.cache.type.default</code>
| + | |
− | | headers="r2c1-t7 r1c3-t7" align="left" |
| + | |
− | <code>CacheType.SOFT_WEAK</code>
| + | |
− | |- align="left" valign="top"
| + | |
− | | id="r3c1-t7" headers="r1c1-t7" align="left" |
| + | |
− | <code>size</code>
| + | |
− | | headers="r3c1-t7 r1c2-t7" align="left" |
| + | |
− | (Optional) Set this attribute to an int value to define the size of cache to use (number of objects).
| + | |
− | | headers="r3c1-t7 r1c3-t7" align="left" |
| + | |
− | <code>100</code>
| + | |
− | |- align="left" valign="top"
| + | |
− | | id="r4c1-t7" headers="r1c1-t7" align="left" |
| + | |
− | <code>shared</code>
| + | |
− | | headers="r4c1-t7 r1c2-t7" align="left" |
| + | |
− | (Optional) 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.
| + | |
− | | + | |
− | * <code>true</code> —use shared cache for cached instances.
| + | |
− | * <code>false</code>—use client isolated cache for cached instances (no L2 cache).
| + | |
− | | headers="r4c1-t7 r1c3-t7" align="left" |
| + | |
− | <code>true</code>
| + | |
− | |- align="left" valign="top"
| + | |
− | | id="r5c1-t7" headers="r1c1-t7" align="left" |
| + | |
− | <code>expiry</code>
| + | |
− | | headers="r5c1-t7 r1c2-t7" align="left" |
| + | |
− | (Optional) 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.
| + | |
− | | headers="r5c1-t7 r1c3-t7" align="left" |
| + | |
− | .<code>-1</code> (no expiry)
| + | |
− | |- align="left" valign="top"
| + | |
− | | id="r6c1-t7" headers="r1c1-t7" align="left" |
| + | |
− | <code>expiryTimeOfDay</code>
| + | |
− | | headers="r6c1-t7 r1c2-t7" align="left" |
| + | |
− | (Optional) 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.
| + | |
− | | headers="r6c1-t7 r1c3-t7" align="left" |
| + | |
− | <code>@TimeOfDay(specified=false)</code>
| + | |
− | |- align="left" valign="top"
| + | |
− | | id="r7c1-t7" headers="r1c1-t7" align="left" |
| + | |
− | <code>alwaysRefresh</code>
| + | |
− | | headers="r7c1-t7 r1c2-t7" align="left" |
| + | |
− | (Optional) Set to a boolean value of true to force all queries that go to the database to always refresh the cache
| + | |
− | | headers="r7c1-t7 r1c3-t7" align="left" |
| + | |
− | <code>false</code>
| + | |
− | |- align="left" valign="top"
| + | |
− | | id="r8c1-t7" headers="r1c1-t7" align="left" |
| + | |
− | <code>refreshOnlyIfNewer</code>
| + | |
− | | headers="r8c1-t7 r1c2-t7" align="left" |
| + | |
− | (Optional) 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).
| + | |
− | | + | |
− | [[Image:Elug_note_icon.png|Note]] '''Note:'''
| + | |
− | | + | |
− | * This option only applies if one of the other refreshing options, such as alwaysRefresh, is already enabled.
| + | |
− | * A version field is necessary to apply this feature.
| + | |
− | | headers="r8c1-t7 r1c3-t7" align="left" |
| + | |
− | <code>false</code>
| + | |
− | |- align="left" valign="top"
| + | |
− | | id="r9c1-t7" headers="r1c1-t7" align="left" |
| + | |
− | <code>disableHits</code>
| + | |
− | | headers="r9c1-t7 r1c2-t7" align="left" |
| + | |
− | (Optional) 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.
| + | |
− | | headers="r9c1-t7 r1c3-t7" align="left" |
| + | |
− | <code>false</code>
| + | |
− | |- align="left" valign="top"
| + | |
− | | id="r10c1-t7" headers="r1c1-t7" align="left" |
| + | |
− | <code>coordinationType</code>
| + | |
− | | headers="r10c1-t7 r1c2-t7" align="left" |
| + | |
− | (Optional) Set this attribute to the cache coordination mode (<code>org.eclipse.persistence.annotations.CacheCoordinationType</code> enumerated type).
| + | |
− | | headers="r10c1-t7 r1c3-t7" align="left" |
| + | |
− | <code>CacheCoordinationType.SEND_OBJECT_CHANGES</code>
| + | |
− | |}
| + | |
− | | + | |
− | <br />
| + | |
− | | + | |
− | <span id="sthref35"></span>
| + | |
− | | + | |
− | ''' '''
| + | |
− | | + | |
− | ===Usage===
| + | |
− | | + | |
− | You can define the <code>@Cache</code> annotation on the following:
| + | |
− | | + | |
− | * <code>@Entity</code>
| + | |
− | * <code>@MappedSuperclass</code>
| + | |
− | * the root of the inheritance hierarchy (if applicable)
| + | |
− | | + | |
− | If you define the <code>@Cache</code> annotation on an inheritance subclass, the annotation will be ignored. If you define the <code>@Cache</code> annotation on <code>@Embeddable</code> EclipseLink will throw an exception.
| + | |
− | | + | |
− | <span id="sthref36"></span>
| + | |
− | | + | |
− | '''Caching in EclipseLink'''
| + | |
− | | + | |
− | The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and primary key values. EclipseLink uses the cache to do the following:
| + | |
− | | + | |
− | * Improve performance by holding recently read or written objects and accessing them in-memory to minimize database access.
| + | |
− | * Manage locking and isolation level.
| + | |
− | * Manage object identity.
| + | |
− | | + | |
− | For more information about the EclipseLink cache and its default behavior, see:
| + | |
− | | + | |
− | * "Caching Overview" <code>http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Caching Overview</code>
| + | |
− | * <code>http://wiki.eclipse.org/Introduction_to_Cache_%28ELUG%29</code>
| + | |
− | | + | |
− | EclipseLink defines the following entity caching annotations:
| + | |
− | | + | |
− | * <code>@Cache</code>
| + | |
− | * <code>[[EclipseLink/UserGuide/JPA/2.4/a_timeofday|@TimeOfDay]]</code>
| + | |
− | * <code>[[EclipseLink/UserGuide/JPA/2.4/a_existencechecking|@ExistenceChecking]]</code>
| + | |
− | | + | |
− | EclipseLink also provides a number of persistence unit properties that you can specify to configure the EclipseLink cache. These properties may compliment or provide an alternative to the usage of annotations.
| + | |
− | | + | |
− | For more information, see the following:
| + | |
− | | + | |
− | * How to Use the Persistence Unit Properties for Caching <code>http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#How_to_Use_the_Persistence_Unit_Properties_for_Caching</code>
| + | |
− | * What You May Need to Know About Overriding Annotations in JPA <code>http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#What_You_May_Need_to_Know_About_Overriding_Annotations_in_JPA</code>
| + | |
− | * What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties <code>http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#What_You_May_Need_to_Know_About_Using_EclipseLink_JPA_Persistence_Unit_Properties</code>
| + | |
− | | + | |
− | <span id="sthref37"></span>
| + | |
− | | + | |
− | ''' '''
| + | |
− | | + | |
− | ===Examples===
| + | |
− | | + | |
− | [[#CHDEEGCI|Example 2-10]] illustrates an <code>@Cache</code> annotation.
| + | |
− | | + | |
− | <span id="CHDEEGCI"></span>
| + | |
− | | + | |
− | '''''Example 2-10 Using @Cache Annotation'''''
| + | |
− | | + | |
− |
| + | |
− | ...
| + | |
− | @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 {
| + | |
− | ...
| + | |
− | }
| + | |
− | | + | |
− | [[#CDEJDBFJ|Example 2-11]] shows how to use this annotation in the <code>eclipselink-orm.xml</code> file.
| + | |
− | | + | |
− | <span id="CDEJDBFJ"></span>
| + | |
− | | + | |
− | '''''Example 2-11 Using <cache> Element'''''
| + | |
− | | + | |
− |
| + | |
− | <?xml version="1.0"?>
| + | |
− | <entity-mappings
| + | |
− | xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/orm"
| + | |
− | xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
| + | |
− | xsi:schemaLocation="http://www.eclipse.org/eclipselink/xsds/persistence/orm
| + | |
− | http://www.eclipse.org/eclipselink/xsds/eclipselink_orm_2_4.xsd"
| + | |
− | version="2.4">
| + | |
− | <entity name="Employee" class="org.acme.Employee" access="FIELD">
| + | |
− | <cache type="SOFT" size="64000" expiry="36000000" coordination-type="INVALIDATE_CHANGED_OBJECTS"/>
| + | |
− | </entity>
| + | |
− | </entity-mappings>
| + | |
− | | + | |
− | You can also specify caching properties at the persistence unit level (in the <code>persistence.xml</code> file) as shown here:
| + | |
− | | + | |
− | <span id="sthref38"></span>
| + | |
− | | + | |
− | '''''Example 2-12 Specifying Caching in persistence.xml'''''
| + | |
− | | + | |
− |
| + | |
− | <?xml version="1.0" encoding="UTF-8"?>
| + | |
− | <persistence xmlns="http://java.sun.com/xml/ns/persistence"
| + | |
− | xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
| + | |
− | xsi:schemaLocation="http://java.sun.com/xml/ns/persistence persistence_2_0.xsd"
| + | |
− | version="2.0">
| + | |
− | <persistence-unit name="acme" transaction-type="RESOURCE_LOCAL">
| + | |
− | <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
| + | |
− | <exclude-unlisted-classes>false</exclude-unlisted-classes>
| + | |
− | <properties>
| + | |
− | <property name="eclipselink.cache.shared.default" value="false"/>
| + | |
− | <property name="eclipselink.cache.shared.Employee" value="true"/>
| + | |
− | <property name="eclipselink.cache.type.Employee" value="SOFT"/>
| + | |
− | <property name="eclipselink.cache.size.Employee" value="64000"/>
| + | |
− | </properties>
| + | |
− | </persistence-unit>
| + | |
− | </persistence>
| + | |
− | | + | |
− | <span id="sthref39"></span>
| + | |
− | | + | |
− | ''' '''
| + | |
− | | + | |
− | ===See Also===
| + | |
− | | + | |
− | For more information, see:
| + | |
− | | + | |
− | * [[EclipseLink/UserGuide/JPA/2.4/a_existencechecking|"@ExistenceChecking"]]
| + | |
− | * [[EclipseLink/UserGuide/JPA/2.4/a_timeofday|"@TimeOfDay"]]
| + | |
− | * [[EclipseLink/UserGuide/JPA/2.4/a_cacheinterceptor|"@CacheInterceptor"]]
| + | |
− | * "Configuring Caching" <code></code>
| + | |
− | | + | |
− | <span id="footerspace"> </span>
| + | |
− | | + | |
− | ----
| + | |
− | | + | |
− | {| class="simple oac_no_warn" width="100%"
| + | |
− | |-
| + | |
− | | valign="bottom" |
| + | |
− | {| width="165"
| + | |
− | |-
| + | |
− | |
| + | |
− | | align="center" |
| + | |
− | [[EclipseLink/UserGuide/JPA/2.4/a_batchfetch| Previous ]]<span class="previouslink">[[Image:Elug_previous_icon.png|Previous]]</span>
| + | |
− | | align="center" |
| + | |
− | [[EclipseLink/UserGuide/JPA/2.4/a_cacheindex| Next ]][[Image:Elug_next_icon.png|Next]]
| + | |
− | |}
| + | |
− | | width="34%" align="center" |
| + | |
− | [[Image:Eclipselink-logo.gif|150px|EclispeLink]]<br />[[Image:Elug_home_icon.png|EclipseLink logo]] [http://www.eclipse.org/eclipselink/ EclipseLink Home] • [[Image:Elug_pdf.png|PDF]] PDF (coming soon)<br />
| + | |
− | | align="right" valign="bottom" |
| + | |
− | {| class="simple oac_no_warn" width="225"
| + | |
− | |
| + | |
− | | align="center" valign="top" |
| + | |
− | [[Image:Elug_Magnifier.png|Search]][http://www.google.com/cse/home?cx=016171230611334810008:y5kxq4rqd8s&hl=en Search]
| + | |
− | | align="center" valign="top" |
| + | |
− | [[Image:Elug_guide_icon.png|Contents]][[EclipseLink/UserGuide/JPA/2.4/toc| Contents]]
| + | |
− | |}
| + | |
− | |}
| + | |