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.

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. To enable or disable the near cache, set the nearCacheEnabled attribute in the ObjectGrid descriptor XML file.

   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. If the lockStrategy attribute must is set to NONE or OPTIMISTIC, the nearCacheEnabled property is set to true.

   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. Set the nearCacheCopyMode copy mode in the ObjectGrid descriptor XML file, or set the copy mode programmatically using the BackingMapConfiguration.setNearCacheCopyMode method.
   You can set the copy mode to nearCacheCopyMode only if the server is COPY_TO_BYTES or COPY_TO_BYTES_RAW.

   When you use this copy mode, you override existing CopyMode and readOnly properties to allow clients to store their objects as POJO (in their native form) on the client and bytes on the server. Data in its native POJO form is only stored and retrieved from the near cache. If COPY_TO_BYTES were the copy mode, then the object would have to be serialized and deserialized every time from the near-cache because data is stored in the near-cache as bytes. Therefore, using nearCacheCopyMode increases performance.

   The copy mode is disabled by default; for example:

   XML file example

   backingMap name="default" nearCacheCopyMode="NO_COPY" readOnly="true" /

   Programmatic example

   ObjectGridConfiguration copyModeConfig = ObjectGridConfigFactory.createObjectGridConfiguration("copyModeGrid");
   BackingMapConfiguration defaultMapConfig = ObjectGridConfigFactory.createBackingMapConfiguration("default");
   	        defaultMapConfig.setNearCacheCopyMode(CopyMode.NO_COPY);
   	        defaultMapConfig.setReadOnly(true);
   	        copyModeConfig.addBackingMapConfiguration(defaultMapConfig);

4. Restart the container servers and clients.
   For more information, see Starting and stopping stand-alone servers and Configuring container servers in WebSphere Application Server.

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>