Configuring the embedded global cache to read data from replica shards of a cache map

You can configure your embedded global cache to read data from replica shards of a cache map instead of the primary cache map.

Before you begin

Complete the following steps:

Read the information about reading data from replica shards and the applications for which it is appropriate, see Optimizing the embedded global cache for use with different types of cache data.
Create the objectgrid.xml and deployment.xml files and configure the cache map names, see Optimizing the embedded global cache for use with different types of cache data.

About this task

If more than one container server exists, the default cache policy ensures that all data is replicated at least one time, so that each container server can host primary and replica shards of the cache data. By default, data is read only from the primary shard but you can configure the embedded global cache to support read access to replica shards.

You define that your embedded global cache can read data from replica shards of a cache map by configuring the deployment.xml file. You then configure the embedded global cache by using one of the following methods:

Place the deployment.xml file in a directory of the IBM® Integration Bus work path.
Use the mqsichangeproperty command to set a property on the integration node cache manager to point to the deployment.xml file.
Use the mqsichangeproperty command to set a property on the integration server cache manager to point to the deployment.xml file.

The embedded global cache can use only one deployment.xml file. Any property settings, if set, are used in the following order of precedence:

Integration server (if no policy is set on the integration node)
Note: If a policy is set on the integration node, the integration server inherits the properties of the integration node, and any properties set directly on the integration server are overwritten.
Integration node
IBM Integration Bus work path

Note: If you choose to configure the property on more than one integration server (or integration node) in the same IBM Integration Bus installation, the properties must result in the same map configuration to ensure consistency.

Procedure

Open the deployment.xml file, and set the replicaReadEnabled parameter to true on the mapSet element.

For example:

<?xml version="1.0" encoding="UTF-8"?>
<deploymentPolicy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://ibm.com/ws/objectgrid/deploymentPolicy ../deploymentPolicy.xsd" 
   xmlns="http://ibm.com/ws/objectgrid/deploymentPolicy">
   <objectgridDeployment objectgridName="WMB">
      <mapSet name="mapSet" numberOfPartitions="13" minSyncReplicas="0" maxSyncReplicas="1" replicaReadEnabled="true">
         <map ref="USER.OPTIMISTIC.*"/>  
         <map ref="USER.PESSIMISTIC.*"/>
         <map ref="USER.NONE.*"/> 
         <map ref="SYSTEM.BROKER.*"/> 
         <zoneMetadata>
            <shardMapping shard="P" zoneRuleRef="wmbRule"/>   
            <shardMapping shard="S" zoneRuleRef="wmbRule"/>
            <zoneRule name="wmbRule" exclusivePlacement="false">  
               <zone name="WMBZone"/>   
            </zoneRule>
         </zoneMetadata> 
      </mapSet>
   </objectgridDeployment>
</deploymentPolicy>

Note: If you add any additional map entries, you must add the equivalent entries in the objectgrid.xml; see Optimizing the embedded global cache for use with different types of cache data. You cannot configure any other options in this file.

Save the deployment.xml file and complete one of the following steps to configure the embedded global cache to use the properties from the file:
- Copy deployment.xml to the workpath/common/wxs directory, where workpath is the IBM Integration Bus work path, and then restart your integration node.
  Note: To verify the work path for your IBM Integration Bus installation, run the command mqsireportbroker integrationNode.
- Configure the location of the deployment.xml file in the integration node by running the following command:
```
mqsichangeproperties integrationNode -b cachemanager -o CacheManager -n deploymentPolicyCustomFile -v pathName/deployment.xml
```
  where pathName is the directory where you saved your deployment.xml file.
- Configure the location of the deployment.xml file in the integration server by running the following command:
```
mqsichangeproperties integrationNode -e integrationServer -o ComIbmCacheManager -n deploymentPolicyCustomFile -v pathName/deployment.xml
```
  where pathName is the directory where you saved your deployment.xml file.
  Note: You can change properties on an integration server only if a policy is not set on the integration node.
Note: If you made changes to the objectgrid.xml file to keep the file consistent with the deployment.xml, you must also complete this step for your copy of the objectgrid.xml file. For information about the equivalent commands, see Configuring locking strategies for the embedded global cache.

Results

You have configured read access to replica shards of one or more cache maps in the IBM Integration Bus embedded global cache.