Overview

In some cases, the memory capacity of an individual application is not capable of holding all the information in the local application memory. When this happens, the desired solution will be to hold only a portion of the information in the application's memory and the rest in a separate process(s). This mode is also known as two-level cache. In this mode, the cache is divided into two components, local cache and master cache. The local cache always resides in the physical address space of the application and the master cache runs in a different process. The master cache is used to share data among the different embedded local caches running within other application instances. The application instances can be different instances of a J2EE application server from the same vendor, different instances of J2EE application servers from different vendors, plain Java applications, or a combination of Java, .Net and C++ applications sharing the same data using a Master-Local cache topology.
In this mode, when a read/get operation is called, a matching object is first looked up in the local embedded cache. If the object is not found in the local cache, it will be searched for in the master cache. If it is not found in the master cache, it will reload the data from the data source. Updates on the central cache will be propagated into all local embedded cache instances in either pull or push mode, using unicast or multicast protocol.

With the master-local space, the master cache itself can be configured to be either replicated space or partitioned space. It can run embedded within the same process where the local cache is running (this makes sense mostly in partitioned cache mode) or remotely on a separate machine. Moving from one configuration to another is transparent to the application and can be done through a single configuration setting at the client side.

The space local view proxy maintains a subset of the master space's data, allowing the client to read distributed data without any remote operations. For more details, refer to the Space Local View section.

Non-Supported Methods The local cache Map API implementation does not support the containsValue() method. The local cache Space API implementation does not support the clear() method.

Standard Local Cache

The standard cache was designed to support the entire range of APIs: Map, JavaSpaces, JDBC and JMS. This local cache provides security, transaction semantics, optimistic locking, query capabilities and all other space capabilities. The standard cache is configured from one central configuration file.

Light Local Cache

The light cache was designed to provide high performance and low footprint compared to the standard cache when using the Map API. It is effectively a distributed Hash Table where the get operation would be equivalent to the standard Hash Table performance with minimal memory footprint overhead at the client side.
The light cache provides advanced eviction policies and notifications, and is configured from one central configuration file.

The Entry Search Algorithm

The SpaceFinder/CacheFinder returns a space/cache proxy. This proxy configuration is retrieved from the master space or from a local location that overrides the master space configuration. The created proxy contains a reference to the local cache, and a reference to the master space that maintains the entire cached data.

The caching algorithm is based on a lazy caching algorithm, meaning that information is loaded to the local cache on demand. Every read/get operation performed on the proxy is initially directed to the local cache. If the desired object is not located in the local cache, it will be searched in the master space. If the object is not located in the master space, the application loads it from an external data source (using the cacheLoader interface).
Once the required information is retrieved, either from the master space or from the data source, the information is kept in the local cache so that subsequent read/get operations on that same Entry are performed using the local cache.

To speed up the first get operation using the Map API of a specified key, you can put the object into the local cache when calling the put method using the <put-first>true</put-first> at the local cache configuration file.

Local Cache Update Modes

The local cache update policy defines the behavior of the cache when an update on an Entry, shared among multiple-cache instances, has been performed.
Two update policies are provided: the pull update policy and the push update policy.

The Push Update Policy

The push model pushes the updates to the local cache, which holds a reference to the same updated object.

The Pull Update Policy (invalidate)

With this policy, each update triggers an invalidation event at every cache instance. The invalidate event marks the object in the local cache instances as invalid. Therefore, an attempt to read this object triggers a reload process in the master space. This configuration is useful in cases where objects are updated frequently, but the updated value is required by the application less frequently.

How Local Cache Works The local cache is implemented using the command pattern, such that each operation made on the master space generates a command object which is then sent to all local cache clients which have the affected object in their local cache. In order for the command pattern to be generated, the client which performs the operation must also be configured to have local cache. That means that if a client which performs the operation does not use local cache, the command object will never be created and other local cache clients will never be updated

Local Cache Configuration

One of the goals of the Master-Local topology is to provide a zero maintenance cache configuration on the one hand, and a high level of granularity and flexibility in the way the local cache can be controlled, on the other.
In general, you do not have to define any configuration in order to use the master-local space topology. You can use the default master-local space configuration provided as part of the distribution. The master-local configuration can be managed through one centralized location that is applied in all local cache instances. When the master space is clustered, all cluster members have one common client local cache configuration. The default configuration can be modified per cluster, per master space, or per client local cache basis.

The following sections describe the local cache configuration environment in detail.

XML Local Cache Configuration File

The cache configuration is stored as part of the XML file. This file is based on the standard GigaSpaces space configuration and controls the local cache behavior that runs implicitly within the application memory address space.

The Default Cache Configuration File

In general, every master space is associated with a default local cache configuration. This configuration can be shared among multiple master caches. This file is called: DefaultConfig-DCache.xml and many cases located at located under the /config directory. If this file does not exist at the /config directory, it will be loaded from the JSpaces.jar library.

You can provide a different cache configuration based on your specific requirements. This will be named, for example, MyLocalCache. For this configuration, GigaSpaces will look for a file called MyLocalCache_DCache.xml. This will hold your local cache configuration and will be retrieved when running your application in a master-local space topology.

Cache Configuration File Search Path

The order of the cache configuration file search path is described below:

1. In the classpath of the client application under /config/_Dcache.xml.
2. In the current directory/config of the client application.
3. If the master space is clustered: in the {{}} tag defined as part of the cluster configuration file. The search will use space CLASSPATH.
4. If the cache is not clustered: at the {{}} tag defined as part of the master cache configuration file. The search will use space CLASSPATH.

The cache configuration file name convention is: _DCache.xml. The cache name is defined as part of the space configuration file or cluster configuration file.

Centralized Cache Configuration User Interface

The centralized-cache configuration user interface is provided as part of the space browser. The user interface provides the cache configuration for clients that use this space as a master space in a master-local topology.

Associating a Cache configuration with a Space

Each local cache can use a separate configuration when the default cache configuration is not sufficient. The master space configuration file should contain the following tag under the space-config tag:

<dist-cache>
    <config-name>DefaultConfig</config-name>
</dist-cache>

Where DefaultConfig can be replaced with your customized cache configuration file.

Associating a Cache configuration with a Cluster

A clustered master space retrieves the local cache configuration file via the cluster configuration file. In this case, the cache configuration must be accessible to all machines running the cluster space members.
The cluster configuration file contains the following tag under the cluster-config tag:

<dist-cache>
    <config-name>DefaultConfig</config-name>
</dist-cache>

Where DefaultConfig can be replaced with your customized cache configuration file.

The cache configuration file must be accessible to all machines running the cluster space members. In this way, it is guaranteed that the cache configuration will be available as long as the cluster configuration is available.

The Cache Configuration Management Console

GigaSpaces provides a single point of access to the cache configuration through the space browser. The Master-Local Cache tab in the GigaSpaces Browser's space configuration panel provides a centralized interface for controlling the local cache configuration. Clients load this cache configuration when creating an initial connection with the master space.

To use the cache configuration interface:

1. Open the space browser.
2. Make sure that the master space is running.
3. Select the master space in the browser, select Advanced, and click the Master-Local Cache tab.

The following panel appears:

Standard Cache

Light Cache

The light cache can be used only with the Map API.

The Local Light Cache (Map API) supports the following Eviction Strategies:

All Eviction Strategies implement the EvictionStrategy class (com.j_spaces.javax.cache.EvictionStrategy; see Javadoc).

Memory Utilization

The Memory Utilization parameters define how the local cache uses memory:

The Cache Configuration File Structure

The local cache configuration file includes all regular space XML tags. In addition, it includes the following tags:

...
<dist-cache>
	<!--PULL = 1, PUSH = 2-->
	<update-mode>1</update-mode>
	<!-- true - optimistic lock enabled, otherwise false -->
	<versioned>true</versioned>
	<!-- maximum COMMAND entries timeout (ms~) in master space -->
	<command-object-timeout>60000</command-object-timeout>
	<!-- maximum object timeout (ms~) for entries in cache -->
	<max-object-timeout>300000</max-object-timeout>
	<!--number of retries to find the master space-->
	<retry-connections>3</retry-connections>
	<!-- delay between retries in ms -->
	<delay-between-retries>5000</delay-between-retries>
	<!-- eviction strategy -->
	<eviction-strategy>com.j_spaces.map.eviction.FIFOEvictionStrategy</eviction-strategy>
	<!-- true - use multicast as network layer for cache update notification, default: false -->
	<multicast-notify>false</multicast-notify>
	<!-- true - save the first put to cache, otherwise false -->
	<put-first>true</put-first>
	<!-- NONE = 0 , ZIP = 1, default: 0 -->
	<compression>0</compression>
	<events>
		<!-- default value: true (enabled)-->
		<enabled>true</enabled>
		<!-- default value: 60000L (60sec)-->
		<lease>60000</lease>
		<batch>
			<!-- default value: 0 -->
			<size>0</size>
			<!-- default value: 0 -->
			<timeout>0</timeout>
		</batch>
		<lease-renew>
			<!-- default value: Lease.FOREVER -->
			<expiration>9223372036854775807</expiration>
			<!-- default value: 60000L (60sec)-->
			<duration>60000</duration>
			<!-- default value: 10000L (10sec)-->
			<round-trip-time>10000</round-trip-time>
		</lease-renew>
	</events>
</dist-cache>
...

Configuring Events

The following block allows you to control events sent from the master space to the local space. Splitting the received events into batches (using the batch element) allows you to significantly reduce network load (although that this can be costly in terms of performance).

The events block is new in GigaSpaces version 6.0.2, and is part of the default master-local configuration.

<dist-cache>
...
	<events>
		<!-- default value: true (enabled)-->
		<enabled>true</enabled>
		<!-- default value: 60000L (60sec)-->
		<lease>60000</lease>
		<batch>
			<!-- default value: 0 -->
			<size>0</size>
			<!-- default value: 0 -->
			<timeout>0</timeout>
		</batch>
		<lease-renew>
			<!-- default value: Lease.FOREVER -->
			<expiration>9223372036854775807</expiration>
			<!-- default value: 60000L (60sec)-->
			<duration>60000</duration>
			<!-- default value: 10000L (10sec)-->
			<round-trip-time>10000</round-trip-time>
		</lease-renew>
	</events>
</dist-cache>

The enabled element, if true (by default), specifies that no events are received in the local space.

To learn how to configure the other elements above, see the LeaseRenewalManager class.

Running Master-Local Space

Local Cache OpenSpaces Configuration The below examples show how to use the local cache in a non-OpenSpaces environment. If you are using OpenSpaces and need to configure local cache please refer to this page.

When the application uses the Master-Local topology it instantiates the local cache by using the CacheFinder/SpaceFinder class with the following URL.

?useLocalCache&updateMode=

• • The standard space URL.
• useLocalCache - Specifies that a local cache should be instantiated.
• updateMode - Indicates whether to use a PUSH or a PULL update mode. 1 indicates PULL mode, and 2, PUSH mode. This value overrides the value provided as part of the local cache configuration.

Examples:
The following example locates a master space (named "mySpace" for the JavaSpace API and "mySpace" for the Map API) using the Jini Lookup and creates a local-cache instance:
JavaSpace API:

IJSpace space =
(IJSpace)SpaceFinder.find("jini://*/./mySpace?useLocalCache&updateMode=1");

Map API:

IMap cache =
(IMap)CacheFinder.find("jini://*/./mySpace?useLocalCache&updateMode=1");

The following example locates a master using the RMI discovery protocol and creates a light local-cache instance:

JavaSpace API:

IJSpace space=
(IJSpace)SpaceFinder.find("rmi://localhost/./mySpace?useLocalCache");

Map API:

IMap cache =
(IMap)CacheFinder.find("rmi://localhost/./mySpace?useLocalCache");

The following example locates a master using the jini lookup and creates a standard local-cache instance:

JavaSpace API:

IJSpace space=
(IJSpace)SpaceFinder.find ("jini://*/*/mySpace?useLocalCache");

Map API:

IMap cache =
(IMap)CacheFinder.find("jini://*/*/mySpace?useLocalCache");

In Master-Local topology, the proxy includes a reference to the local cache and the remote master space. In this case, the URL should use either the Jini or RMI discovery protocols to look up the master space.