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.
Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Configuring"
m |
|||
(32 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
+ | ---- | ||
+ | |||
+ | |||
+ | '''[[Image:Elug_draft_icon.png|Warning]] This page is obsolete. Please see "Understanding Caching" in the ''[http://www.eclipse.org/eclipselink/documentation/ Understanding EclipseLink (Concepts Guide)]'' and "Object Caching" in the ''[http://www.eclipse.org/eclipselink/documentation/ EclipseLink Solutions Guide]''for current information.''' | ||
+ | |||
+ | |||
+ | ---- | ||
+ | |||
+ | |||
+ | |||
+ | |||
{{EclipseLink_UserGuide|info=y | {{EclipseLink_UserGuide|info=y | ||
|toc=y | |toc=y | ||
|api=y | |api=y | ||
|apis= | |apis= | ||
+ | *[http://www.eclipse.org/eclipselink/api/latest/javax/persistence/Cacheable.html @Cacheable] | ||
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/Cache.html @Cache] | *[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/Cache.html @Cache] | ||
+ | *[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/TimeOfDay.html @TimeOfDay] | ||
+ | *[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/CacheType.html CacheType] | ||
+ | *[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/CacheIsolationType.html CacheIsolationType] | ||
+ | *[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/CacheCoordinationType.html CacheCoordinationType] | ||
+ | *[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/DatabaseChangeNotificationType.html DatabaseChangeNotificationType] | ||
+ | *[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/PersistenceUnitProperties.html @PersistenceUnitProperties] | ||
+ | |nativeapi=y | ||
+ | |nativeapis= | ||
+ | *[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/descriptors/CachePolicy.html CachePolicy] | ||
|examples=y | |examples=y | ||
|example= | |example= | ||
Line 10: | Line 31: | ||
= Configuring Caching = | = Configuring Caching = | ||
+ | EclipseLink enables a shared (L2) object cache by default on all entity objects. The shared cache can be disabled, or configured through standard JPA 2 configuration or through EclipseLink specific configuration. The EclipseLink cache configuration allows for the configuration of EclipseLink extended cache functionality. | ||
− | + | Caching can be configured in EclipseLink through the following mechanisms: | |
+ | * JPA 2 persistence.xml elements | ||
+ | * JPA 2 @Cacheable annotation and ORM XML element | ||
+ | * EclipseLink @Cache annotation and ORM XML element | ||
+ | * EclipseLink persistence unit properties | ||
− | + | == JPA 2 persistence.xml Cache Configuration == | |
+ | JPA 2 allows caching to be enabled or disabled through the <code>persistence.xml</code> element <code><shared-cache-mode></code>. This configures the default caching mode for the entire persistence unit. The default cache mode can be overridden for a specific class using the <code>@Cacheable</code> or <code>@Cache</code> annotations. | ||
+ | |||
+ | The valid values for <code><shared-cache-mode></code> are defined in the <code>SharedCacheMode</code> enum as: | ||
+ | * ALL - enable caching for all entities (overrides any <code>@Cacheable</code> annotation settings) | ||
+ | * NONE - disable caching for all entities (overrides any <code>@Cacheable</code> annotation settings) | ||
+ | * ENABLE_SELECTIVE - disable caching for all entities (<code>@Cacheable</code> can be used to enable caching) | ||
+ | * DISABLE_SELECTIVE - enable caching for all entities (<code>@Cacheable</code> can be used to disable caching) | ||
+ | |||
+ | ======''JPA 2 persistence.xml cache configuration example''====== | ||
+ | <source lang="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> | ||
+ | <shared-cache-mode>ENABLE_SELECTIVE</shared-cache-mode> | ||
+ | </persistence-unit> | ||
+ | </persistence> | ||
+ | </source> | ||
+ | |||
+ | ==@Cacheable== | ||
+ | The JPA 2 <code>@Cacheable</code> annotation or <code>cacheable</code> XML attribute can be used to selectively enable or disabling caching for a specific entity class. | ||
+ | |||
+ | You can define the <tt>@Cacheable</tt> annotation on the following: | ||
+ | * <tt>@Entity</tt> | ||
+ | * <tt>@MappedSuperclass</tt> | ||
+ | |||
+ | If you define the <tt>@Cacheable</tt> annotation on an entity inheritance subclass, the annotation will be ignored. The <tt>@Cacheable</tt> annotation is not supported on an <tt>@Embeddable</tt>. | ||
+ | |||
+ | ======''@Cacheable annotation example''====== | ||
+ | <source lang="java"> | ||
+ | ... | ||
+ | @Entity | ||
+ | @Cacheable(false) | ||
+ | public class Employee { | ||
+ | ... | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | EclipseLink allows entities that are cached to have relationships to entities that are not cached. However, the relationships themselves from cached entities to non-cached entities will not be cached. Entities that are not cached are considered <code>ISOLATED</code> in EclipseLink, entities that are cached are considered <code>SHARED</code>, and cached entities that have relationships to non-cached entities are considered <code>PROTECTED</code>. This can also be configured using the <code>isolation</code> attribute of the EclipseLink <code>@Cache</code> annotation. | ||
+ | |||
+ | ==@Cache== | ||
+ | The <code>@Cache</code> annotation or <code><cache></code> XML element can be used to configure caching for a specific entity class. | ||
You can define the <tt>@Cache</tt> annotation on the following: | You can define the <tt>@Cache</tt> annotation on the following: | ||
* <tt>@Entity</tt> | * <tt>@Entity</tt> | ||
* <tt>@MappedSuperclass</tt> | * <tt>@MappedSuperclass</tt> | ||
− | |||
− | 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 an inheritance subclass, the annotation will be ignored. The <tt>@Cache</tt> annotation is not supported on an <tt>@Embeddable</tt>. |
{{EclipseLink_AttributeTable | {{EclipseLink_AttributeTable | ||
Line 27: | Line 98: | ||
<tr> | <tr> | ||
<td><tt>type</tt></td> | <td><tt>type</tt></td> | ||
− | <td>Set this attribute to the type (<tt> | + | <td>Set this attribute to the type (<tt>CacheType</tt> enumerated type) of the cache that you will be using: |
*FULL | *FULL | ||
*WEAK | *WEAK | ||
Line 33: | Line 104: | ||
*SOFT_WEAK | *SOFT_WEAK | ||
*HARD_WEAK | *HARD_WEAK | ||
− | |||
− | |||
− | + | There are also types, CACHE and NONE but these are not recommended, and should not be used, to disable caching set isolation=ISOLATED instead. | |
− | + | ||
− | + | ||
</td> | </td> | ||
<td><tt>CacheType.SOFT_WEAK</tt></td> | <td><tt>CacheType.SOFT_WEAK</tt></td> | ||
Line 47: | Line 114: | ||
<td>Set this attribute to an <tt>int</tt> value to define the size of cache to use (number of objects)</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>100</td> | ||
− | <td></td> | + | <td>Optional</td> |
</tr> | </tr> | ||
<tr> | <tr> | ||
− | <td><tt> | + | <td><tt>isolation</tt></td> |
− | <td> | + | <td>Set the cache isolation. This allows the shared cache to be enabled or disabled. |
− | * <tt> | + | * <tt>SHARED</tt> - enable shared cache |
− | * <tt> | + | * <tt>ISOLATED</tt> - disable shared cache |
− | <td><tt> | + | * <tt>PROTECTED</tt> - enable shared cache and allow relationships to isolated entities |
+ | </td> | ||
+ | <td><tt>SHARED</tt></td> | ||
<td>Optional</td> | <td>Optional</td> | ||
</tr> | </tr> | ||
Line 60: | Line 129: | ||
<td><tt>expiry</tt></td> | <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>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> | + | <td>no expiry</td> |
<td>Optional</td> | <td>Optional</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td><tt>expiryTimeOfDay</tt></td> | <td><tt>expiryTimeOfDay</tt></td> | ||
− | <td>Specific time of day (<tt> | + | <td>Specific time of day (<tt>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> | + | <td>no expiry</td> |
− | + | ||
<td>Optional</td> | <td>Optional</td> | ||
</tr> | </tr> | ||
Line 93: | Line 161: | ||
</tr><tr> | </tr><tr> | ||
<td><tt>coordinationType</tt></td> | <td><tt>coordinationType</tt></td> | ||
− | <td>Set this attribute to the cache coordination mode (<tt> | + | <td>Set this attribute to the cache coordination mode (<tt>CacheCoordinationType</tt> enumerated type).<br/> |
+ | Note: cache coordination must also be configured in the persistence.xml.</td> | ||
<td><tt>CacheCoordinationType.SEND_OBJECT_CHANGES</tt></td> | <td><tt>CacheCoordinationType.SEND_OBJECT_CHANGES</tt></td> | ||
+ | <td>Optional</td> | ||
+ | </tr><tr> | ||
+ | <td><tt>databaseChangeNotificationType</tt></td> | ||
+ | <td>Set this attribute to the database change notification mode (<tt>DatabaseChangeNotificationType</tt> enumerated type).<br/> | ||
+ | Note: database change notification must also be configured in the persistence.xml.<br/> | ||
+ | Requires EclipseLink 2.4</td> | ||
+ | <td><tt>DatabaseChangeNotificationType.INVALIDATE</tt></td> | ||
<td>Optional</td> | <td>Optional</td> | ||
</tr> | </tr> | ||
}} | }} | ||
− | ======''@Cache | + | ======''@Cache annotation example''====== |
− | + | ||
<source lang="java"> | <source lang="java"> | ||
... | ... | ||
Line 113: | Line 188: | ||
... | ... | ||
} | } | ||
+ | </source> | ||
+ | |||
+ | ======''Cache XML example''====== | ||
+ | <source lang="xml"> | ||
+ | <?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> | ||
+ | </source> | ||
+ | |||
+ | == EclipseLink Cache Persistence Unit Properties == | ||
+ | EclipseLink defines several persistence unit properties that can be used the configure caching defaults, and caching for specific entities. | ||
+ | |||
+ | The caching persistence unit properties include: | ||
+ | * <code>"eclipselink.cache.shared.default"</code> - enable or disable the shared cache default | ||
+ | * <code>"eclipselink.cache.shared.<entity-name>"</code> - enable or disable the shared cache for a specific entity | ||
+ | * <code>"eclipselink.cache.type.default"</code> - set the default cache type | ||
+ | ** Valid values are defined in the config <code>CacheType</code> class, <code>"Soft", "Hard", "Weak", "SoftCache", "HardCache", "None"</code>. | ||
+ | ** A value of <code>"None"</code> is not recommend and should not be used, use <code>shared=false</code> instead. | ||
+ | * <code>"eclipselink.cache.type.<entity-name>"</code> - set the cache type for a specific entity | ||
+ | * <code>"eclipselink.cache.size.default"</code> - set the default cache size | ||
+ | * <code>"eclipselink.cache.size.<entity-name>"</code> - set the cache size for a specific entity | ||
+ | |||
+ | ======''EclipseLink persistence.xml cache configuration example''====== | ||
+ | <source lang="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="10000"/> | ||
+ | </properties> | ||
+ | </persistence-unit> | ||
+ | </persistence> | ||
</source> | </source> | ||
{{EclipseLink_JPA | {{EclipseLink_JPA | ||
|previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Caching Overview|Caching Overview]] | |previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Caching Overview|Caching Overview]] | ||
− | |next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Shared and Isolated|Shared, Isolated | + | |next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Shared and Isolated|Shared, Isolated, Protected, Weak, and Read-only Cache]] |
|up=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development|Caching]] | |up=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development|Caching]] | ||
|version=2.4 DRAFT}} | |version=2.4 DRAFT}} |
Latest revision as of 13:55, 5 February 2013
This page is obsolete. Please see "Understanding Caching" in the Understanding EclipseLink (Concepts Guide) and "Object Caching" in the EclipseLink Solutions Guidefor current information.
EclipseLink | |
Website | |
Download | |
Community | |
Mailing List • Forums • IRC • mattermost | |
Issues | |
Open • Help Wanted • Bug Day | |
Contribute | |
Browse Source |
Key API
Native API
Examples
Contents
Configuring Caching
EclipseLink enables a shared (L2) object cache by default on all entity objects. The shared cache can be disabled, or configured through standard JPA 2 configuration or through EclipseLink specific configuration. The EclipseLink cache configuration allows for the configuration of EclipseLink extended cache functionality.
Caching can be configured in EclipseLink through the following mechanisms:
- JPA 2 persistence.xml elements
- JPA 2 @Cacheable annotation and ORM XML element
- EclipseLink @Cache annotation and ORM XML element
- EclipseLink persistence unit properties
JPA 2 persistence.xml Cache Configuration
JPA 2 allows caching to be enabled or disabled through the persistence.xml
element <shared-cache-mode>
. This configures the default caching mode for the entire persistence unit. The default cache mode can be overridden for a specific class using the @Cacheable
or @Cache
annotations.
The valid values for <shared-cache-mode>
are defined in the SharedCacheMode
enum as:
- ALL - enable caching for all entities (overrides any
@Cacheable
annotation settings) - NONE - disable caching for all entities (overrides any
@Cacheable
annotation settings) - ENABLE_SELECTIVE - disable caching for all entities (
@Cacheable
can be used to enable caching) - DISABLE_SELECTIVE - enable caching for all entities (
@Cacheable
can be used to disable caching)
JPA 2 persistence.xml cache configuration example
<?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> <shared-cache-mode>ENABLE_SELECTIVE</shared-cache-mode> </persistence-unit> </persistence>
@Cacheable
The JPA 2 @Cacheable
annotation or cacheable
XML attribute can be used to selectively enable or disabling caching for a specific entity class.
You can define the @Cacheable annotation on the following:
- @Entity
- @MappedSuperclass
If you define the @Cacheable annotation on an entity inheritance subclass, the annotation will be ignored. The @Cacheable annotation is not supported on an @Embeddable.
@Cacheable annotation example
... @Entity @Cacheable(false) public class Employee { ... }
EclipseLink allows entities that are cached to have relationships to entities that are not cached. However, the relationships themselves from cached entities to non-cached entities will not be cached. Entities that are not cached are considered ISOLATED
in EclipseLink, entities that are cached are considered SHARED
, and cached entities that have relationships to non-cached entities are considered PROTECTED
. This can also be configured using the isolation
attribute of the EclipseLink @Cache
annotation.
@Cache
The @Cache
annotation or <cache>
XML element can be used to configure caching for a specific entity class.
You can define the @Cache annotation on the following:
- @Entity
- @MappedSuperclass
If you define the @Cache annotation on an inheritance subclass, the annotation will be ignored. The @Cache annotation is not supported on an @Embeddable.
Attribute | Description | Default | Required? |
---|---|---|---|
type | Set this attribute to the type (CacheType enumerated type) of the cache that you will be using:
There are also types, CACHE and NONE but these are not recommended, and should not be used, to disable caching set isolation=ISOLATED instead. |
CacheType.SOFT_WEAK | Optional |
size | Set this attribute to an int value to define the size of cache to use (number of objects) | 100 | Optional |
isolation | Set the cache isolation. This allows the shared cache to be enabled or disabled.
|
SHARED | 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. | no expiry | Optional |
expiryTimeOfDay | Specific time of day (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. | no expiry | 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 (CacheCoordinationType enumerated type). Note: cache coordination must also be configured in the persistence.xml. |
CacheCoordinationType.SEND_OBJECT_CHANGES | Optional |
databaseChangeNotificationType | Set this attribute to the database change notification mode (DatabaseChangeNotificationType enumerated type). Note: database change notification must also be configured in the persistence.xml. |
DatabaseChangeNotificationType.INVALIDATE | 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 { ... }
Cache XML example
<?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>
EclipseLink Cache Persistence Unit Properties
EclipseLink defines several persistence unit properties that can be used the configure caching defaults, and caching for specific entities.
The caching persistence unit properties include:
-
"eclipselink.cache.shared.default"
- enable or disable the shared cache default -
"eclipselink.cache.shared.<entity-name>"
- enable or disable the shared cache for a specific entity -
"eclipselink.cache.type.default"
- set the default cache type- Valid values are defined in the config
CacheType
class,"Soft", "Hard", "Weak", "SoftCache", "HardCache", "None"
. - A value of
"None"
is not recommend and should not be used, useshared=false
instead.
- Valid values are defined in the config
-
"eclipselink.cache.type.<entity-name>"
- set the cache type for a specific entity -
"eclipselink.cache.size.default"
- set the default cache size -
"eclipselink.cache.size.<entity-name>"
- set the cache size for a specific entity
EclipseLink persistence.xml cache configuration example
<?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="10000"/> </properties> </persistence-unit> </persistence>