[Java programming language only]

Configuring the near cache

Clients can optionally have a local, in-line cache when eXtreme Scale is used in a distributed topology. This optional cache is called a near cache, an independent data grid on each client, serving as a cache for the remote, server-side cache. The near cache is enabled by default when locking is disabled, or is configured as optimistic, and cannot be used when configured as pessimistic.

About this task

A near cache is fast because it provides local in-memory access to a subset of the entire cached data set that is stored remotely.

To configure the near cache, you can edit the necessary settings in the ObjectGrid XML file for your container server. The settings in this file apply to all clients, unless you override the settings. You can override the nearCacheEnabled setting for the near cache with either XML or programmatic configuration.

Procedure

  1. Near cache is enabled if you are using default settings. To enable the near cache, you must set the lockStrategy attribute in the ObjectGrid descriptor XML file for the container servers to NONE or OPTIMISTIC. The default value is OPTIMISTIC. For more information about the lockStrategy attribute, see ObjectGrid descriptor XML file. Clients do not maintain a near cache when the locking setting is configured as PESSIMISTIC.
  2. [Version 8.6 and later] To enable or disable the near cache, set the nearCacheEnabled attribute in the ObjectGrid descriptor XML file.
    [Version 8.6 and later] nearCacheEnabled
    Set the value to true to enable the client local cache. To use a near cache, the lockStrategy attribute must be set to NONE or OPTIMISTIC.

    Default: true (Optional)

    Important: In previous releases, you enabled and disabled the near cache with the numberOfBuckets attribute in the ObjectGrid descriptor XML file. If this value is set to 0, the near cache is disabled. This setting overrides the nearCacheEnabled attribute. If you do not set the numberOfBuckets or set it to a non-zero value, then the nearCacheEnabled attribute determines whether the near cache is enabled.
  3. Restart the container servers and clients. For more information, see Starting and stopping stand-alone servers and Configuring container servers in WebSphere Application Server.

Results

To check whether a near cache is enabled, run the BackingMap.isNearCacheEnabled() method in your client. You can also look for the CWOBJ1128I message in the log files on the client to see if the near cache is enabled.
[Version 8.6 and later]

Example

The following example ObjectGrid descriptor XML file configures an optimistic locking strategy and enables the near cache:
<?xml version="1.0" encoding="UTF-8"?> 
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
	xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd" 
	xmlns="http://ibm.com/ws/objectgrid/config">     
	<objectGrids>         
		<objectGrid name="Grid">
			<backingMap name="TestMap1" nearCacheEnabled="true" lockStrategy="OPTIMISTIC" copyMode="COPY_TO_BYTES"/>
		</objectGrid>
	</objectGrids>
</objectGridConfig>

What to do next

By default, the client-side near cache does not have a maximum size and out of memory errors in the client can occur. To control the size of the near cache, configure a client-side override that enables a time-to live (TTL) or least recently used (LRU) evictor on the client. For more information about configuring an evictor for the near cache, see Configuring an evictor for the near cache.