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"
(→@Cacheable) |
m |
||
(25 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 | ||
Line 5: | Line 16: | ||
*[http://www.eclipse.org/eclipselink/api/latest/javax/persistence/Cacheable.html @Cacheable] | *[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] | *[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 21: | Line 40: | ||
== JPA 2 persistence.xml Cache Configuration == | == 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> | + | 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: | 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 @Cacheable annotation settings) | + | * ALL - enable caching for all entities (overrides any <code>@Cacheable</code> annotation settings) |
− | * NONE - disable caching for all entities (overrides any @Cacheable annotation settings) | + | * NONE - disable caching for all entities (overrides any <code>@Cacheable</code> annotation settings) |
− | * ENABLE_SELECTIVE - disable caching for all entities (@Cacheable can be used to enable caching) | + | * ENABLE_SELECTIVE - disable caching for all entities (<code>@Cacheable</code> can be used to enable caching) |
− | * DISABLE_SELECTIVE - enable caching for all entities (@Cacheable can be used to disable caching) | + | * DISABLE_SELECTIVE - enable caching for all entities (<code>@Cacheable</code> can be used to disable caching) |
======''JPA 2 persistence.xml cache configuration example''====== | ======''JPA 2 persistence.xml cache configuration example''====== | ||
Line 46: | Line 65: | ||
==@Cacheable== | ==@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. | 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''====== | ======''@Cacheable annotation example''====== | ||
Line 57: | Line 82: | ||
</source> | </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 ISOLATED in EclipseLink, entities that are cached are considered SHARED, and cached entities that have relationships to non-cached entities are considered PROTECTED. This | + | 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== | ==@Cache== | ||
− | + | The <code>@Cache</code> annotation or <code><cache></code> XML element can be used to configure caching for a specific entity class. | |
− | The Cache annotation | + | |
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 75: | 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 81: | 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 95: | 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 108: | 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 141: | 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> | ||
Line 148: | Line 176: | ||
======''@Cache annotation example''====== | ======''@Cache annotation example''====== | ||
− | |||
<source lang="java"> | <source lang="java"> | ||
... | ... | ||
Line 161: | 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> | </source> | ||
== EclipseLink Cache Persistence Unit Properties == | == 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> | ||
{{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>