Use Native Serialization mode When running a local cache/view you should use Native Serialization mode with the master space. Running in any other serialization mode might impact the speed of reading objects from the local cache/view and the client Memory utilization behavior.

Local View

OpenSpaces allows you to easily configure and use the space local view using the LocalViewSpaceFactoryBean component. The factory exposes the same IJSpace implementation that a regular space component exposes, with the additional feature of having a local view.

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. Data is streamed into the client view in an implicit manner - as opposed to local cache data, that is loaded into the client on-demand, and later updated or evicted. The local view is defined via a filter - regular template or SQLQuery - as opposed to the local cache that caches data at the client side only after the data has been read.

The following is an example of how a local view can be configured:

<os-core:space id="space" url="jini://*/*/space" />

<os-core:local-view id="localViewSpace" space="space">
    <os-core:view-query where="processed = true" class="com.example.Message"/>
</os-core:local-view>

<os-core:giga-space id="gigaSpace" space="localViewSpace"/>

<bean id="space" class="org.openspaces.core.space.UrlSpaceFactoryBean">
    <property name="url" value="jini://*/*/space" />
</bean>

<bean id="viewSpace" class="org.openspaces.core.space.cache.LocalViewSpaceFactoryBean">
    <property name="space" ref="space" />
    <property name="localViews">
        <list>
          <bean class="com.j_spaces.core.client.view.View">
                <constructor-arg index="0" value="com.example.Message" />
                <constructor-arg index="1" value="processed = true" />
            </bean>
        </list>
    </property>
</bean>

IJSpace space = // get Space either by injection or code creation
IJSpace localViewProxy = new LocalViewSpaceConfigurer(space).addView(new View("com.example.Message", "processed = true"))
                                                       .localView();
GigaSpace gigaspace = new GigaSpaceConfigurer(localViewProxy).gigaSpace();

Streaming Space Subset Data into Client

Once the local view is constructed, data is pre-loaded into the client based on the view filter criteria (as opposed to the local cache that does not have a pre-load phase).

The local view is continuously updated by the master space in an asynchronous mode (using notifications). Both write and update operations are delivered into the client based on the view filter criteria (as opposed to the local cache that delivers only update operations to the client).
All read operations (including readMultiple) use the local view proxy only (as opposed to the local cache that might read data from a remote master space).
Data is not evicted from the local view - The cache policy is hard coded to ALL_IN_CACHE mode.

Local View Considerations

Local View is a Read-Only Feature

The following operations are not supported when using local view, and should be performed directly on the master space:

• write
• writeMultiple
• update
• updateMultiple
• replace
• clear
• Any operation under a transaction
• take

Local Cache

OpenSpaces also allows you to configure a master-local space, simply by using the LocalCacheSpaceFactoryBean component. The factory exposes the same IJSpace implementation that a regular space component exposes, with the additional feature of having a local cache.

The following is an example of how a local cache can be configured:

<os-core:space id="space" url="jini://*/*/mySpace" />

<os-core:local-cache id="localCacheSpace" space="space" update-mode="PULL" >
    <os-core:properties>
        <props>
            <prop key="space-config.engine.cache_size">5000000</prop>
            <prop key="space-config.engine.memory_usage.high_watermark_percentage">75</prop>
            <prop key="space-config.engine.memory_usage.write_only_block_percentage">73</prop>
            <prop key="space-config.engine.memory_usage.write_only_check_percentage">71</prop>
            <prop key="space-config.engine.memory_usage.low_watermark_percentage">45</prop>
            <prop key="space-config.engine.memory_usage.eviction_batch_size">1000</prop>
            <prop key="space-config.engine.memory_usage.retry_yield_time">100</prop>
            <prop key="space-config.engine.memory_usage.retry_count">20</prop>
        </props>
    </os-core:properties>
</os-core:local-cache>
<os-core:giga-space id="gigaSpace" space="localCacheSpace"/>

<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" />
    <property name="updateMode" value="PULL" />
</bean>

UrlSpaceConfigurer urlSpaceConfigurer = new UrlSpaceConfigurer("jini://*/*/space");
IJSpace localSpaceProxy = new LocalCacheSpaceConfigurer(urlSpaceConfigurer.space()).updateMode(UpdateMode.PULL).localCache();
GigaSpace gigaspace = new GigaSpaceConfigurer(localSpaceProxy).gigaSpace();

When using local cache with the GigaSpace API, the caching policy is LRU mode and can't be changed. When using the local cache with the GigaMap API , the default cache policy is com.j_spaces.map.eviction.FIFOEvictionStrategy. You may use other policies. See the com.j_spaces.map.eviction package for additional options.

Local Cache Considerations

Local Cache with External Data Source

When using the Master Local Space configuration with an EDS, it is important to make sure the following steps are accomplished:
1. Each POJO class should contain a SpaceVersion property.
2. In the database, you should add a VERSION_ID column to the corresponding tables. If you are using Hibernate, add the versionId property to the HBM file.
3. When running a data grid having an EDS and a client configured to use Local Cache (that is implicitly running in Optimistic locking mode) you should load data into the data grid (via the EDS com.gigaspaces.datasource.DataIterator) where the version ID of the object is 1 or larger. This will "imitate" what is happening when writing a new object into data grid when a client running in Optimistic locking mode - its initial Version ID value is ZERO and incremented by one at the space. This will allow a client running a local cache to load an object into its local cache correctly once there is a cache miss within the local cache when a read operation is called.
4. When clearing or taking objects you should make sure the template used , have the version ID field as ZERO. This will make sure the space will not try to remove a matching object with the same version ID , but will simply remove the matching objects ignoring their existing Version ID (which is what you would like to happen in most cases).

Local Cache Memory Eviction

In order to configure the Local cache Eviction mechanism you should have the following tuned:

space-config.engine.cache_size
space-config.engine.memory_usage.high_watermark_percentage
space-config.engine.memory_usage.write_only_block_percentage
space-config.engine.memory_usage.write_only_check_percentage
space-config.engine.memory_usage.low_watermark_percentage
space-config.engine.memory_usage.eviction_batch_size
space-config.engine.memory_usage.retry_count
space-config.engine.memory_usage.explicit-gc
space-config.engine.memory_usage.retry_yield_time

See the Memory Management Facilities for additional details how to configure the Memory Manager.

Having the space-config.engine.memory_usage.explicit-gc enabled is recommended only in special cases where there is high load on the system with large amount of concurrent users accessing the local cache where the amount of CPUs/Cores is relatively small.

Local Cache Memory Handling

There might be cases when the local cache would not be able to evict its data fast enough. This will result an Exception to be thrown at 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 to release the evicted memory and retry the operation. See below example:

GigaSpace gigaspace;
while(true)
{
	try
	{
		Object obj = gigaspace.read(template);
		break;
	}
	catch (Exception re) {
		if (re.getCause() instanceof MemoryShortageException)
		Thread.sleep(1000);
	}			
}

Object Reference Storage Mode

Starting with XAP 7.0, the Space API local cache and local view have been modified to return a reference to the space object rather than returning a shallow copy (An object with a copy of the primitive fields and reference to the non-primitive fields) as performed with older versions. An identical object reference will be returned when conducting sub-subsequent read operation for the same object.

When using a local cache/view, a new object reference will be returned when:

• The object has been evicted and reloaded from the master space (relevant only for local cache).
• The object has been modified and an updated version has been sent from the master space via notification.

This improvement means the read operations using the GigaSpace.readByID , GigaSpace.read, GigaSpace.readMultiple (using a limited max objects where all the objects cached), GSIterator - having a local cache/view running at the client side, will be very fast and would not involve any new object generation.

This behavior lowers the JVM garbage collection impact on the application. In addition, all read based operations have been improved to be non-lock calls. This lowers the contention on the system when having large amount of concurrent threads reading data from the local cache/view (ideal for a web applications).

Tests of the local cache with XAP 7.0 having 10 client threads using a local cache resulted 20M read/per sec on 8 cores box.