Summary: A local cache allows the client application to cache recently used data at the client memory address and have it updated automatically by the space when that data changes.
SummaryA Local Cache is a client side cache that maintains a subset of the master space's data based on the client application's recent activity. The local cache is created empty, and whenever the client application executes a query the local cache first tries to fulfill it from the cache, otherwise it executes it on the master space and caches the result locally for future queries.
UsageCreating a local cache is similar to creating a GigaSpace, except that we wrap the space with a local cache before handing it to the GigaSpace. The local cache can be configured at design time using LocalCacheSpaceFactoryBean, or at runtime using LocalCacheSpaceConfigurer. For exmaple:
Spring Namespace Configuration
<os-core:space id="space" url="jini://*/*/mySpace" /> <os-core:local-cache id="localCacheSpace" space="space"/> <os-core:giga-space id="localCache" space="localCacheSpace"/> Plain Spring XML <bean id="space" class="org.openspaces.core.space.UrlSpaceFactoryBean"> <property name="url" value="jini://*/*/space" /> </bean> <bean id="localCacheSpace" class="org.openspaces.core.space.cache.LocalCacheSpaceFactoryBean"> <property name="space" ref="space" /> </bean> Code // Initialize remote space configurer: UrlSpaceConfigurer urlConfigurer = new UrlSpaceConfigurer("jini://*/*/mySpace"); // Initialize local cache configurer LocalCacheSpaceConfigurer localCacheConfigurer = new LocalCacheSpaceConfigurer(urlConfigurer); // Create local cache: GigaSpace localCache = new GigaSpaceConfigurer(localCacheConfigurer).gigaSpace(); Transactional OperationsTransactional operations are always executed on the master space. External Data SourceThe local cache uses the entry's version to determine whether the local entry is up-to-date or stale when handling updates. Usually this mechanism is transparent to the user and does not require declaring a version property, since the master space and local cache maintain version information for each entry implicitly. The exception is a master space with an External Data Source - Suppose that an entry in the master space has version 7, and gets cached in the local cache, then evicted from the master space and later reloaded from the external data source. If the version is not persisted and reloaded, it will be set to 1 and the local cache will ignore upcoming updates on that entry since its cached version is 7. In that case it is the user's responsibility to make sure that the entry's version is persisted and loaded in the external data source, using the following rules:
Multiple Cache Instances within the Same ClientRunning multiple local cache instances (for different master spaces) within the same client may cause problems unless you allocate reasonable headroom for the local cache to operate. Such issues will be manifested in MemoryShortageException being thrown sporadically. The main reason for such issues is the interdependency each cache has on the other caches' utilized memory. Since the MemoryShortageException is thrown when the virtual machine's total utilized memory is above a threshold (and not when a specific cache's utilized memory is above a given threshold), an "over-utilized" cache may impact other caches running within the same client. The recommended approach to ensure a deterministic behavior is to limit the local cache size (the default size is very large and may not be appropriate for all situations). For example: Client X uses two local cache instances, LC1 for master space A, with the local cache containing 100,000 objects, and LC2 for master space B, with the local cache containing 100 objects. An external client (client Y) writes data into space A. LC1 receives these updates automatically (via notifications). In some point, other clients write data into space B. LC2 is also updated with these objects. If client X's JVM's available memory breaches the write_only_block_percentage threshold, and the client tries to read 1000 objects from Space B that were not cached in LC2, existing LC2 objects will be evicted to clear some memory for the loaded objects. Since there are only 100 objects to clear from LC2, not all of the 1000 objects that are read from space B will be loaded into LC2. A MemoryShortageException might be thrown in such a case if the client tries to perform rapid and repeated reads from space B. Operations FlowRead Operations
ReadMultiple Operations
Take/TakeMultiple OperationsTake is always executed on both the local space and the master space. Blocking Take (take with timeout > 0) will block until an object is available on the master space, just like regular take. Write/Update OperationsWrites are always executed on the master space. Updates are executed both on the master space and the local cache, to make sure the cache is consistent if the object is cached.
SynchronizationUpdate PolicyEach change on the master space triggers a notification at the local cache. The change is processed according to one of the following update policies:
In general, Push is usually recommended for applications that perform more reads than updates (when reducing cache misses is important), whereas Pull is usually recommended for applications that perform more updates than reads (when protecting the cache from abundant updates is important and cache misses are acceptable). The update policy can be configured using LocalCacheSpaceFactoryBean for Spring, or using LocalCacheSpaceConfigurer at runtime. The default update policy is "pull." For example: <os-core:local-cache id="localCacheSpace" space="space" update-mode="PULL"/>
Batch SynchronizationChanges in the server are grouped and sent to the client in batches. The following configuration settings control synchronization batching:
Setting lower values for batch size and timeout will reduce data staleness but increase network load, and vice versa. Batch settings can be configured using LocalCacheSpaceFactoryBean for Spring, or using LocalCacheSpaceConfigurer at runtime. For example: <os-core:local-cache id="localCacheSpace" space="space" batch-size="1000" batch-timeout="100"/> Recovering From DisconnectionWhen the connection between a local cache and remote master space is disrupted, the local cache starts trying to reconnect with the remote space. If the disconnection duration exceeds the maximum disconnection duration, the local cache enters a disconnected state, wherein each operation throws an exception stating the cache is disconnected. When the connection to the remote master space is restored, the local cache restarts with an empty cache (same as in the initialization process) before restoring the state to connected, ensuring the cache does not contain stale data after reconnection. The maximum disconnection duration can be configured using LocalCacheSpaceFactoryBean for Spring, or using LocalCacheSpaceConfigurer at runtime (default is one minute, or 60000 milliseconds). For example: <!-- duration time is given in milliseconds --> <os-core:local-cache id="localCacheSpace" space="space" max-disconnection-duration="60000"/> Advanced NotificationThe round-trip-time setting can be configured using the space-config.dist-cache.events.lease-renew.round-trip-time custom property. For more information about this setting refer to Session Based Messaging API. Memory EvictionCache PolicyWhen using a local cache with GigaSpace, the cache policy is hard-writed to LRU and cannot be changed. When using the local cache with GigaMap, the default cache policy is com.j_spaces.map.eviction.FIFOEvictionStrategy, and other policies may be used by setting the space-config.dist-cache.eviction-strategy custom property. For more details refer to the Map Component local cache section. Memory Configuration PropertiesIn order to properly configure the local cache eviction mechanism, you should consider tuning the following configuration elements:
See the Memory Management Facilities for additional details on these configuration properties.
Handling Memory ShortageThere might be cases when the local cache would not be able to evict its data fast enough. This will result in an exception thrown on the client side. The reasons for this behavior might be very large objects stored within the local cache, large amount of concurrent access to the local cache or relatively small JVM heap. In such a case a RemoteException will be thrown. You should catch this Exception and check its cause. If the cause is MemoryShortageException you should sleep for a while and let the client JVM release the evicted memory and retry the operation. See below an example for this: GigaSpace gigaspace; while(true) { try { Object obj = gigaspace.read(template); break; } catch (Exception e){ if (e.getCause() instanceof MemoryShortageException) Thread.sleep(1000); } } Monitoring the Client Local Cache EvictionThe Client Local Cache eviction can be monitored by setting the client application com.gigaspaces.core.memorymanager logging entry level to FINE. Once changed, log entries will be displayed when objects are evicted from the local cache (starting, during, and when completing the eviction cycle), and when waiting for incoming activities.
Local Cache PerformanceBelow is the result of a simple benchmark comparing Ehcache's get() operation with the local cache using the GigaSpace.readById() operation. With this benchmark the local cache/ehcache size can accommodate the entire data set for the application.
Upgrading From Previous VersionsThis section is intended to summarize the changes in 8.0.5 for users upgrading from previous versions. Maximum Disconnection DurationIn previous versions the max disconnection duration was configured by setting the space-config.dist-cache.events.lease and/or space-config.dist-cache.events.lease-renew.duration custom properties. Configuring the max disconnection duration using these custom properties is still supported, but starting with 8.0.5 it is deprecated. In addition, since the reconnect mechanism has been improved in 8.0.5, the custom properties space-config.dist-cache.retry-connections and space-config.dist-cache.delay-between-retries are no longer required and will be ignored. Batch Size & TimeoutIn previous versions the batch size and timeout were configured by setting the space-config.dist-cache.events.batch.size and space-config.dist-cache.events.batch.timeout custom properties, respectively. Configuring the batch size and timeout using these custom properties is still supported, but starting with 8.0.5 it is deprecated. Summary of Configuration ChangesThe following table summarizes the configuration changes made in 8.0.5:
Local Cache Properties
XAP 8.0.4 and older
XAP 8.0.5 and above
|
![]() |
GigaSpaces.com - Legal Notice - 3rd Party Licenses - Site Map - API Docs - Forum - Downloads - Blog - White Papers - Contact Tech Writing - Gen. by Atlassian Confluence |