|
|
| Line 12: |
Line 12: |
| | | | |
| | *[[EclipseLink/UserGuide/JPA/sandbox/caching/Cache Coordination|Cache Coordination]] | | *[[EclipseLink/UserGuide/JPA/sandbox/caching/Cache Coordination|Cache Coordination]] |
| − | *[[EclipseLink/UserGuide/JPA/sandbox/caching/Cache Architecture|Cache API]] | + | *[[EclipseLink/UserGuide/JPA/sandbox/caching/Cache API|Cache API]] |
| − | | + | |
| − | | + | |
| − | | + | |
| − | ===Cache Coordination===
| + | |
| − | The need to maintain up-to-date data for all applications is a key design challenge for building a distributed application. The difficulty of this increases as the number of servers within an environment increases. EclipseLink provides a distributed cache coordination feature that ensures data in distributed applications remains current.
| + | |
| − | | + | |
| − | Cache coordination reduces the number of optimistic lock exceptions encountered in a distributed architecture, and decreases the number of failed or repeated transactions in an application. However, cache coordination in no way eliminates the need for an effective locking policy. To effectively ensure working with up-to-date data, cache coordination must be used with optimistic or pessimistic locking. We recommend that you use cache coordination with an optimistic locking policy (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Locking Policy|Configuring Locking Policy]]).
| + | |
| − | | + | |
| − | You can use cache invalidation to improve cache coordination efficiency. For more information, see [[#Cache Invalidation|Cache Invalidation]].
| + | |
| − | | + | |
| − | | + | |
| − | ===Cache Isolation===
| + | |
| − | Isolated client sessions provide a mechanism for disabling the shared server session cache. Any classes marked as isolated only cache objects relative to the life cycle of their client session. These classes never utilize the shared server session cache. This is the best mechanism to prevent caching as it is configured on a per-class basis allowing caching for some classes, and denying for others.
| + | |
| − | | + | |
| − | For more information, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated Client Sessions|Isolated Client Sessions]].
| + | |
| − | | + | |
| − | | + | |
| − | ===Cache Locking and Transaction Isolation===
| + | |
| − | By default, EclipseLink optimizes concurrency to minimize cache locking during read or write operations. Use the default EclipseLink transaction isolation configuration unless you have a very specific reason to change it.
| + | |
| − | | + | |
| − | For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)|Database Transaction Isolation Levels]].
| + | |
| − | | + | |
| − | | + | |
| − | ===Cache Optimization===
| + | |
| − | Tune the EclipseLink cache for each class to help eliminate the need for distributed cache coordination. Always tune these settings before implementing cache coordination.
| + | |
| − | | + | |
| − | For more information, see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)|Optimizing Cache]].
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | ==Cache Coordination==
| + | |
| − | As the following figure shows, cache coordination is a session feature that allows multiple, possibly distributed, instances of a session to broadcast object changes among each other so that each session's cache is either kept up-to-date or notified that the cache must update an object from the data source the next time it is read.
| + | |
| − | | + | |
| − | | + | |
| − | {| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| + | |
| − | | align="left" |
| + | |
| − | '''Note:''' You cannot use isolated client sessions (see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated Client Sessions|Isolated Client Sessions]]) with cache coordination.
| + | |
| − | |}
| + | |
| − | | + | |
| − | | + | |
| − | <span id="Figure 98-2"></span>
| + | |
| − | ''''' Cache Coordination'''''
| + | |
| − | | + | |
| − | [[Image:cachcord.gif|Cache Coordination]]<br /><br />
| + | |
| − | | + | |
| − | When sessions are distributed, that is, when an application contains multiple sessions (in the same JVM, in multiple JVMs, possibly on different servers), as long as the servers hosting the sessions are interconnected on the network, sessions can participate in cache coordination. Coordinated cache types that require discovery services also require the servers to support User Datagram Protocol (UDP) communication and multicast configuration (for more information, see [[#Coordinated Cache Architecture|Coordinated Cache Architecture]]).
| + | |
| − | | + | |
| − | This section describes the following:
| + | |
| − | * [[#When to Use Cache Coordination|When to Use Cache Coordination]]
| + | |
| − | * [[#Coordinated Cache Architecture|Coordinated Cache Architecture]]
| + | |
| − | * [[#Coordinated Cache|Coordinated Cache Types]]
| + | |
| − | * [[#Custom Coordinated Cache|Custom Coordinated Cache]]
| + | |
| − | | + | |
| − | For more information, see [[Configuring%20a%20Coordinated%20Cache%20(ELUG)|Configuring a Coordinated Cache]].
| + | |
| − | | + | |
| − | | + | |
| − | ===When to Use Cache Coordination===
| + | |
| − | Cache coordination can enhance performance and reduce the likelihood of stale data for applications that have the following characteristics:
| + | |
| − | * Changes are all being performed by the same Java application operating with multiple, distributed sessions
| + | |
| − | * Primarily read-based
| + | |
| − | * Regularly requests and updates the same objects
| + | |
| − | | + | |
| − | To maximize performance, avoid cache coordination for applications that do not have these characteristics. For more information about alternatives to cache coordination, see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Optimizing Cache|Optimizing Cache]].
| + | |
| − | | + | |
| − | Cache coordination enhances performance mainly by avoiding data source access.
| + | |
| − | | + | |
| − | Cache coordination reduces the occurrence of stale data by increasing the likelihood that distributed caches are kept up-to-date with changes and are notified when one of the distributed caches must update an object from the data source the next time it is read.
| + | |
| − | | + | |
| − | Cache coordination reduces the number of optimistic lock exceptions encountered in a distributed architecture, and decreases the number of failed or repeated transactions in an application. However, cache coordination in no way eliminates the need for an effective locking policy. To effectively ensure working with up-to-date data, cache coordination must be used with optimistic or pessimistic locking. We recommend that you use cache coordination with an optimistic locking policy (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Locking Policy|Configuring Locking Policy]]).
| + | |
| − | | + | |
| − | For other options to reduce the likelihood of stale data, see [[#Stale Data|Stale Data]].
| + | |
| − | | + | |
| − | | + | |
| − | ===Coordinated Cache Architecture===
| + | |
| − | EclipseLink provides coordinated cache implementations that perform discovery and message transport services using various technologies including the following:
| + | |
| − | * Java Message Service (JMS) – See [[#JMS Coordinated Cache|JMS Coordinated Cache]]
| + | |
| − | * Remote Method Invocation (RMI) – See [[#RMI Coordinated Cache|RMI Coordinated Cache]]
| + | |
| − | * Common Object Request Broker Architecture (CORBA) – See [[#CORBA Coordinated Cache|CORBA Coordinated Cache]]
| + | |
| − | | + | |
| − | Regardless of the type of discovery and message transport you choose to use, the following are the principal objects that provide coordinated cache functionality:
| + | |
| − | * [[#Session|Session]]
| + | |
| − | * [[#Descriptor|Descriptor]]
| + | |
| − | * [[#Unit of Work|Unit of Work]]
| + | |
| − | | + | |
| − | | + | |
| − | ====Session====
| + | |
| − | When you enable a session for change propagation, the session provides discovery and message transport services using either JMS, RMI, CORBA, or Oracle Application Server 10g Cluster.
| + | |
| − | | + | |
| − | Discovery services ensure that sessions announce themselves to other sessions participating in cache coordination. Discovery services use UDP communication and multicast configuration to monitor sessions as they join and leave the coordinated cache. All coordinated cache types (except JMS) require discovery services.
| + | |
| − | | + | |
| − | Message transport services allow the session to broadcast object change notifications to other sessions participating in cache coordination when a unit of work from this session commits a change.
| + | |
| − | | + | |
| − | ====Descriptor====
| + | |
| − | You can configure how object changes are broadcast on a descriptor-by-descriptor basis. This lets you fine-tune the type of notification to make.
| + | |
| − | | + | |
| − | For example, for an object with few attributes, you can configure its descriptor to send object changes. For an object with many attributes, it may be more efficient to configure its descriptor so that the object is flagged as invalid (so that other sessions will know to update the object from the data source the next time it is read).
| + | |
| − | | + | |
| − | | + | |
| − | ====Unit of Work====
| + | |
| − | Only changes committed by a unit of work are subject to propagation when cache coordination is enabled. The unit of work computes the appropriate change set based on the descriptor configuration of affected objects.
| + | |
| − | | + | |
| − | ===Coordinated Cache Types===
| + | |
| − | You can create the following types of coordinated cache:
| + | |
| − | * [[#JMS Coordinated Cache|JMS Coordinated Cache]]
| + | |
| − | * [[#RMI Coordinated Cache|RMI Coordinated Cache]]
| + | |
| − | * [[#CORBA Coordinated Cache|CORBA Coordinated Cache]]
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | ====JMS Coordinated Cache====
| + | |
| − | For a JMS coordinated cache, when a particular session's coordinated cache starts up, it uses its JNDI naming service information to locate and create a connection to the JMS server. The coordinated cache is ready when all participating sessions are connected to the same topic on the same JMS server. At this point, sessions can start sending and receiving object change messages. You can then configure all sessions that are participating in the same coordinated cache with the same JMS and JNDI naming service information.
| + | |
| − | | + | |
| − | Because you must supply the necessary information to connect to the JMS Topic, a JMS coordinated cache does not use a discovery service.
| + | |
| − | | + | |
| − | If you do use cache coordination, we recommend that you use JMS cache coordination: JMS is robust, easy to configure, and provides efficient support for asynchronous change propagation.
| + | |
| − | | + | |
| − | For more information, see [[Configuring%20a%20JMS%20Coordinated%20Cache%20(ELUG)#Configuring a JMS Coordinated Cache|Configuring a JMS Coordinated Cache]].
| + | |
| − | | + | |
| − | For more information on configuring JMS, refer to your see JMS provider's documentation.
| + | |
| − | | + | |
| − | ====RMI Coordinated Cache====
| + | |
| − | For an RMI coordinated cache, when a particular session's coordinated cache starts up, the session binds its connection in its naming service (either an RMI registry or JNDI), creates an announcement message (that includes its own naming service information), and broadcasts the announcement to its multicast group (see [[Configuring%20a%20Coordinated%20Cache%20(ELUG)#Configuring a Multicast Group Address|Configuring a Multicast Group Address]] and [[Configuring%20a%20Coordinated%20Cache%20(ELUG)#Configuring a Multicast Port|Configuring a Multicast Port]]). When a session that belongs to the same multicast group receives this announcement, it uses the naming service information in the announcement message to establish bidirectional connections with the newly announced session's coordinated cache. The coordinated cache is ready when all participating sessions are interconnected in this way, at which point sessions can start sending and receiving object change messages. You can then configure each session with naming information that identifies the host on which the session is deployed.
| + | |
| − | | + | |
| − | If you do use cache coordination, we recommend that you use RMI cache coordination only if you require synchronous change propagation (see [[Configuring%20a%20Coordinated%20Cache%20(ELUG)#Configuring the Synchronous Change Propagation Mode|Configuring the Synchronous Change Propagation Mode]]).
| + | |
| − | | + | |
| − | EclipseLink also supports cache coordination using RMI over the Internet Inter-ORB Protocol (IIOP). An RMI/IIOP coordinated cache uses RMI (and a JNDI naming service) for discovery and message transport services.
| + | |
| − | | + | |
| − | | + | |
| − | {| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| + | |
| − | | align="left" |
| + | |
| − | '''Note:''' If you use an RMI coordinated cache, we recommend that you use RMI/IIOP only if absolutely necessary.
| + | |
| − | |}
| + | |
| − | | + | |
| − | | + | |
| − | For more information, see [[Configuring%20an%20RMI%20Coordinated%20Cache%20(ELUG)#Configuring an RMI Coordinated Cache|Configuring an RMI Coordinated Cache]].
| + | |
| − | | + | |
| − | | + | |
| − | ====CORBA Coordinated Cache====
| + | |
| − | For a CORBA coordinated cache, when a particular session's coordinated cache starts up, the session binds its connection in JNDI, creates an announcement message (that includes its own JNDI naming service information), and broadcasts the announcement to its multicast group (see [[Configuring%20a%20Coordinated%20Cache%20(ELUG)#Configuring a Multicast Group Address|Configuring a Multicast Group Address]] and [[Configuring%20a%20Coordinated%20Cache%20(ELUG)#Configuring a Multicast Port|Configuring a Multicast Port]]). When a session that belongs to the same multicast group receives this announcement, it uses the naming service information in the announcement message to establish bidirectional connections with the newly announced session's coordinated cache. The coordinated cache is ready when all participating sessions are interconnected in this way, at which point, sessions can start sending and receiving object change messages. You can then configure each session with naming information that identifies the host on which the session is deployed.
| + | |
| − | | + | |
| − | Currently, EclipseLink provides support for the Sun Object Request Broker.
| + | |
| − | | + | |
| − | For more information on configuring a CORBA coordinated cache, see [[Configuring%20a%20CORBA%20Coordinated%20Cache%20(ELUG)|Configuring a CORBA Coordinated Cache]].
| + | |
| − | | + | |
| − | ===Custom Coordinated Cache===
| + | |
| − | Using the classes in <tt>org.eclipse.persistence.sessions.coordination</tt> package, you can define your own coordinated cache for custom solutions.
| + | |
| − | | + | |
| − | Once you have created the required cache coordination classes, for more information on configuring a user-defined coordinated cache, see [[Configuring%20a%20Custom%20Coordinated%20Cache%20(ELUG)|Configuring a Custom Coordinated Cache]].
| + | |
| − | | + | |
| − | ==Cache API==
| + | |
| − | To configure the EclipseLink cache, you use the appropriate API in the following objects:
| + | |
| − | * [[#Object Identity API|Object Identity API]]
| + | |
| − | * [[#Cache Refresh API|Cache Refresh API]]
| + | |
| − | * [[#Cache Invalidation API|Cache Invalidation API]]
| + | |
| − | * [[#Cache Coordination API|Cache Coordination API]]
| + | |
| − | | + | |
| − | | + | |
| − | ===Object Identity API===
| + | |
| − | You configure object identity using the following <tt>ClassDescriptor</tt> API:
| + | |
| − | | + | |
| − | | + | |
| − | <span id="Example 98-1"></span>
| + | |
| − | useCacheIdentityMap()
| + | |
| − |
| + | |
| − | useFullIdentityMap()
| + | |
| − |
| + | |
| − | useHardCacheWeakIdentityMap()
| + | |
| − |
| + | |
| − | useNoIdentityMap()
| + | |
| − |
| + | |
| − | useSoftCacheWeakIdentityMap()
| + | |
| − |
| + | |
| − | useWeakIdentityMap()
| + | |
| − |
| + | |
| − | useSoftIdentityMap()
| + | |
| − | | + | |
| − | For more information, see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Cache Type and Size at the Descriptor Level|Configuring Cache Type and Size at the Descriptor Level]].
| + | |
| − | | + | |
| − | ===Cache Refresh API===
| + | |
| − | You configure cache refresh using the following <tt>ClassDescriptor</tt> API:
| + | |
| − | | + | |
| − | | + | |
| − | <span id="Example 98-2"></span>
| + | |
| − | alwaysRefreshCache()
| + | |
| − |
| + | |
| − | alwaysRefreshCacheOnRemote()
| + | |
| − |
| + | |
| − | disableCacheHits()
| + | |
| − |
| + | |
| − | disableCacheHitsOnRemote()
| + | |
| − |
| + | |
| − | onlyRefreshCacheIfNewerVersion()
| + | |
| − | | + | |
| − | | + | |
| − | You can also configure cache refresh using the following API calls:
| + | |
| − | * <tt>Session</tt><nowiki>: </nowiki><tt>refreshObject</tt> method
| + | |
| − | * <tt>DatabaseSession</tt> and <tt>UnitOfWork: refreshAndLockObject</tt> methods
| + | |
| − | * <tt>ObjectLevelReadQuery: refreshIdentityMapResult</tt> and <tt>refreshRemoteIdentityMapResult</tt> methods
| + | |
| − | | + | |
| − | For more information, see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Cache Refreshing|Configuring Cache Refreshing]].
| + | |
| − | | + | |
| − | | + | |
| − | ===Cache Invalidation API===
| + | |
| − | You configure cache invalidation using <tt>ClassDescriptor</tt> methods <tt>getCacheInvalidationPolicy</tt> and <tt>setCacheInvalidationPolicy</tt> to configure an <tt>org.eclipse.persistence.descriptors.invalidation.CacheInvalidationPolicy</tt>.
| + | |
| − | | + | |
| − | You can use any of the following <tt>CacheInvalidationPolicy</tt> instances:
| + | |
| − | * <tt>DailyCacheInvalidationPolicy</tt><nowiki>: The object is automatically flagged as invalid at a specified time of day.</nowiki>
| + | |
| − | * <tt>NoExpiryCacheInvalidationPolicy</tt><nowiki>: The object can only be flagged as invalid by explicitly calling </nowiki><tt>org.eclipse.persistence.sessions.IdentityMapAccessor</tt> method <tt>invalidateObject</tt>.
| + | |
| − | * <tt>TimeToLiveCacheInvalidationPolicy</tt><nowiki>: The object is automatically flagged as invalid after a specified time period has elapsed since the object was read.</nowiki>
| + | |
| − | | + | |
| − | You can also configure cache invalidation using a variety of API calls accessible through the <tt>Session</tt>. The <tt>org.eclipse.persistence.sessions.IdentityMapAccessor</tt> provides the following methods:
| + | |
| − | * <tt>getRemainingValidTime</tt><nowiki>: Returns the remaining life of the specified object. This time represents the difference between the next expiry time of the object and its read time.</nowiki>
| + | |
| − | * <tt>invalidateAll</tt><nowiki>: Sets all objects for all classes to be invalid in EclipseLink identity maps.</nowiki>
| + | |
| − | * <tt>invalidateClass(Class klass)</tt> and <tt>invalidateClass(Class klass, boolean recurse)</tt><nowiki>: Set all objects of a specified class to be invalid in EclipseLink identity maps.</nowiki>
| + | |
| − | * <tt>invalidateObject(Object object)</tt>, <tt>invalidateObject(Record rowWithPrimaryKey, Class klass)</tt> and <tt>invalidateObject(Vector primaryKey, Class klass)</tt><nowiki>: Set an object to be invalid in EclipseLink identity maps.</nowiki>
| + | |
| − | * <tt>invalidateObjects(Expression selectionCriteria)</tt> and <tt>invalidateObjects(Vector collection)</tt><nowiki>: Set all objects from the specified Expression/collection to be invalid in EclipseLink identity maps.</nowiki>
| + | |
| − | * <tt>isValid(Record recordContainingPrimaryKey, Class theClass)</tt>, <tt>isValid(Object object)</tt> and <tt>isValid(java.util.Vector primaryKey, Class theClass)</tt><nowiki>: Return </nowiki><tt>true</tt> if the object is valid in EclipseLink identity maps.
| + | |
| − | | + | |
| − | For more information, see the following:
| + | |
| − | * [[Configuring%20a%20Project%20(ELUG)#Configuring Cache Expiration at the Project Level|Configuring Cache Expiration at the Project Level]]
| + | |
| − | * [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Cache Expiration at the Descriptor Level|Configuring Cache Expiration at the Descriptor Level]]
| + | |
| − | * [[Using%20Advanced%20Query%20API%20(ELUG)#How to Configure Cache Expiration at the Query Level|How to Configure Cache Expiration at the Query Level]]
| + | |
| − | | + | |
| − | ===Cache Coordination API===
| + | |
| − | Configure cache coordination using the following <tt>Session</tt> methods:
| + | |
| − | | + | |
| − | | + | |
| − | <span id="Example 98-3"></span>
| + | |
| − | Session.getCommandManager().
| + | |
| − | setShouldPropagateAsynchronously(boolean)
| + | |
| − |
| + | |
| − | Session.getCommandManager().getDiscoveryManager().
| + | |
| − | setAnnouncementDelay()
| + | |
| − | setMulticastGroupAddress()
| + | |
| − | setMulticastPort()
| + | |
| − | setPacketTimeToLive()
| + | |
| − |
| + | |
| − | Session.getCommandManager().getTransportManager().
| + | |
| − | setEncryptedPassword()
| + | |
| − | setInitialContextFactoryName()
| + | |
| − | setLocalContextProperties(Hashtable)
| + | |
| − | setNamingServiceType() ''passing in one of:''
| + | |
| − | TransportManager.JNDI_NAMING_SERVICE
| + | |
| − | TransportManager.REGISTRY_NAMING_SERVICE
| + | |
| − | setPassword()
| + | |
| − | setRemoteContextProperties(Hashtable)
| + | |
| − | setShouldRemoveConnectionOnError()
| + | |
| − | setUserName()
| + | |
| − | | + | |
| − | You configure how object changes are propagated using the following <tt>ClassDescriptor</tt> methods:
| + | |
| − | | + | |
| − | | + | |
| − | <span id="Example 98-4"></span>
| + | |
| − | setCacheSynchronizationType() ''passing in one of:''
| + | |
| − | ClassDescriptor.DO_NOT_SEND_CHANGES
| + | |
| − | ClassDescriptor.INVALIDATE_CHANGED_OBJECTS
| + | |
| − | ClassDescriptor.SEND_NEW_OBJECTS_WITH_CHANGES
| + | |
| − | ClassDescriptor.SEND_OBJECT_CHANGES
| + | |
| − | | + | |
| − | For more information, see [[Configuring%20a%20Coordinated%20Cache%20(ELUG)#i1128398|Configuring Common Coordinated Cache Options]].
| + | |
| − | | + | |
| − | | + | |
| − | ----
| + | |
| − | ''[[EclipseLink User's Guide Copyright Statement|Copyright Statement]]''
| + | |
| − | | + | |
| − | | + | |
| − | [[Category: EclipseLink User's Guide]]
| + | |
| − | [[Category: Release 1]]
| + | |
| − | [[Category: Concept]]
| + | |
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:
