WebSphere eXtreme Scale client configuration

WebSphere eXtreme Scale Administration Guide > Configure WebSphere eXtreme Scale

WebSphere eXtreme Scale client configuration

You can configure an eXtreme Scale client based on the requirements such as the need to override settings.
You can configure an eXtreme Scale client in the following ways:

XML configuration
Programmatic configuration
Spring Framework configuration
Disable the near cache

You can override the following plug-ins on a client:

ObjectGrid plug-ins

TransactionCallback plug-in
ObjectGridEventListener plug-in

BackMap plug-ins

Evictor plug-in
MapEventListener plug-in
numberOfBuckets attribute
ttlEvictorType attribute
timeToLive attribute

Configure the client with XML

An ObjectGrid XML file can be used to alter settings on the client side.
To change the settings on an eXtreme Scale client, create an ObjectGrid XML file that is similar in structure to the file that was used for the eXtreme Scale server.
Assume that the following XML file was paired with a deployment policy XML file, and these files were used to start an eXtreme Scale server.
companyGridServerSide.xml

<?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="CompanyGrid">
           
<bean id="TransactionCallback"
                className="com.company.MyTxCallback" />
           
<bean id="ObjectGridEventListener"
                className="com.company.MyOgEventListener" />
           
<backingMap name="Customer"
                pluginCollectionRef="customerPlugins" />
           
<backingMap name="Item" />
           
<backingMap name="OrderLine" numberOfBuckets="1049"
                timeToLive="1600" ttlEvictorType="LAST_ACCESS_TIME" />
           
<backingMap name="Order" lockStrategy="PESSIMISTIC"
                pluginCollectionRef="orderPlugins" />
       
</objectGrid>
   
</objectGrids>

   
<backingMapPluginCollections>
       
<backingMapPluginCollection id="customerPlugins">
           
<bean id="Evictor"
                className="com.ibm.websphere.objectGrid.plugins.builtins.LRUEvictor" />
           
<bean id="MapEventListener"
                className="com.company.MyMapEventListener" />
       
</backingMapPluginCollection>
       
<backingMapPluginCollection id="orderPlugins">
           
<bean id="MapIndexPlugin"
                className="com.company.MyMapIndexPlugin" />
       
</backingMapPluginCollection>
   
</backingMapPluginCollections>
</objectGridConfig>
On an eXtreme Scale server, the ObjectGrid instance named CompanyGrid behaves as defined by the companyGridServerSide.xml file. By default, the CompanyGrid client has the same settings as the CompanyGrid instance running on the server. However, some of the settings can be overridden on the client, as follows:

Create a client-specific ObjectGrid instance.
Copy the ObjectGrid XML file that was used to open the server.
Edit the new file to customize for the client side.

To set or update any of the attributes on the client, specify a new value or change the existing value.
To remove a plug-in from the client, use the empty string as the value for the className attribute.
To change an existing plug-in, specify a new value for the className attribute.
You can also add any plug-in supported for a client override: TRANSACTION_CALLBACK, OBJECTGRID_EVENT_LISTENER, EVICTOR, MAP_EVENT_LISTENER.

Create a client with the newly created client-override XML file.

The following ObjectGrid XML file can be used to specify some of the attributes and plug-ins on the CompanyGrid client.
companyGridClientSide.xml

<?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="CompanyGrid">
           
<bean id="TransactionCallback"
                className="com.company.MyClientTxCallback" />
           
<bean id="ObjectGridEventListener" className="" />
           
<backingMap name="Customer" numberOfBuckets="1429"
                pluginCollectionRef="customerPlugins" />
           
<backingMap name="Item" />
           
<backingMap name="OrderLine" numberOfBuckets="701"
                timeToLive="800" ttlEvictorType="LAST_ACCESS_TIME" />
           
<backingMap name="Order" lockStrategy="PESSIMISTIC"
                pluginCollectionRef="orderPlugins" />
       
</objectGrid>
   
</objectGrids>

   
<backingMapPluginCollections>
       
<backingMapPluginCollection id="customerPlugins">
           
<bean id="Evictor"
                className="com.ibm.websphere.objectGrid.plugins.builtins.LRUEvictor" />
           
<bean id="MapEventListener" className="" />
       
</backingMapPluginCollection>
       
<backingMapPluginCollection id="orderPlugins">
           
<bean id="MapIndexPlugin"
                className="com.company.MyMapIndexPlugin" />
       
</backingMapPluginCollection>
   
</backingMapPluginCollections>
</objectGridConfig>
The companyGridClientSide.xml file overrides several attributes and plug-ins on the CompanyGrid client as follows:

The TransactionCallback on the client is com.company.MyClientTxCallback instead of the server-side setting of com.company.MyTxCallback.
The client does not have an ObjectGridEventListener plug-in because the className value is the empty string.
The client sets the numberOfBuckets to 1429 for the Customer backingMap, retains its Evictor plug-in, and removes the MapEventListener plug-in.
The numberOfBuckets and timeToLive attributes of the OrderLine backingMap have changed
Although a different lockStrategy attribute is specified, there is no effect because the lockStrategy attribute is not supported for a client override.

To create the CompanyGrid client using the companyGridClientSide.xml file, pass the ObjectGrid XML file as a URL to one of the connect methods on the ObjectGridManager.
creating the client for XML

ObjectGridManager ogManager = 
    ObjectGridManagerFactory.ObjectGridManager();
ClientClusterContext clientClusterContext = 
    ogManager.connect("MyServer1.company.com:2809", null, new URL(
                "file:xml/companyGridClientSide.xml"));
Configure the client programmatically

You can also override client-side ObjectGrid settings programmatically. Create an ObjectGridConfiguration object that is similar in structure to the server-side ObjectGrid instance. The following code creates a client-side ObjectGrid instance that is functionally equivalent to the client override in the previous section which uses an XML file.
client-side override programmatically
ObjectGridConfiguration companyGridConfig = ObjectGridConfigFactory
    .createObjectGridConfiguration("CompanyGrid");
Plugin txCallbackPlugin = ObjectGridConfigFactory.createPlugin(
    PluginType.TRANSACTION_CALLBACK, "com.company.MyClientTxCallback");
companyGridConfig.addPlugin(txCallbackPlugin);

Plugin ogEventListenerPlugin = ObjectGridConfigFactory.createPlugin(
    PluginType.OBJECTGRID_EVENT_LISTENER, "");
companyGridConfig.addPlugin(ogEventListenerPlugin);

BackingMapConfiguration customerMapConfig = ObjectGridConfigFactory
    .createBackingMapConfiguration("Customer");
customerMapConfig.setNumberOfBuckets(1429);
Plugin evictorPlugin = ObjectGridConfigFactory.createPlugin(PluginType.EVICTOR,
    "com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor");
customerMapConfig.addPlugin(evictorPlugin);

companyGridConfig.addBackingMapConfiguration(customerMapConfig);

BackingMapConfiguration orderLineMapConfig = ObjectGridConfigFactory
    .createBackingMapConfiguration("OrderLine");
orderLineMapConfig.setNumberOfBuckets(701);
orderLineMapConfig.setTimeToLive(800);
orderLineMapConfig.setTtlEvictorType(TTLType.LAST_ACCESS_TIME);

companyGridConfig.addBackingMapConfiguration(orderLineMapConfig);

List ogConfigs = new ArrayList();
ogConfigs.add(companyGridConfig);

Map overrideMap = new HashMap();
overrideMap.put(CatalogServerProperties.DEFAULT_DOMAIN, ogConfigs);

ogManager.setOverrideObjectGridConfigurations(overrideMap);
ClientClusterContext client = ogManager.connect(catalogServerAddresses, null, null);
ObjectGrid companyGrid = ogManager.getObjectGrid(client, objectGridName);
The ObjectGridManager instance ogManager checks for overrides only in the ObjectGridConfiguration and BackingMapConfiguration objects that you include in the overrideMap Map. For instance, the previous code overrides the number of buckets on the OrderLine Map. However, the Order map remains unchanged on the client side because no configuration for that map is included.

Configure the client in the Spring Framework

Client-side ObjectGrid settings can also be overridden using the Spring Framework. The following example XML file shows how to build an ObjectGridConfiguration element, and use it to override some client side settings. This example calls the same APIs that are demonstrated in the programmatic configuration. The example is also functionally equivalent to the example in the ObjectGrid XML configuration.
client configuration with Spring

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN"
        "http://www.springframework.org/dtd/spring-beans.dtd">
<beans>
 
<bean id="companyGrid" factory-bean="manager" factory-method="getObjectGrid"
    singleton="true">
   
<constructor-arg type="com.ibm.websphere.objectgrid.ClientClusterContext">
     
<ref bean="client" />
   
</constructor-arg>
   
<constructor-arg type="java.lang.String" value="CompanyGrid" />
</bean>

 
<bean id="manager" class="com.ibm.websphere.objectgrid.ObjectGridManagerFactory"
    factory-method="getObjectGridManager" singleton="true">
   
<property name="overrideObjectGridConfigurations">
     
<map>
       
<entry key="DefaultDomain">
         
<list>
           
<ref bean="ogConfig" />
         
</list>
       
</entry>
     
</map>
   
</property>
 
</bean>

 
<bean id="ogConfig"
    class="com.ibm.websphere.objectgrid.config.ObjectGridConfigFactory"
    factory-method="createObjectGridConfiguration">
   
<constructor-arg type="java.lang.String">
     
<value>CompanyGrid</value>
   
</constructor-arg>
   
<property name="plugins">
     
<list>
     
<bean class="com.ibm.websphere.objectgrid.config.ObjectGridConfigFactory"
          factory-method="createPlugin">
         
<constructor-arg type="com.ibm.websphere.objectgrid.config.PluginType"
            value="TRANSACTION_CALLBACK" />
         
<constructor-arg type="java.lang.String"
            value="com.company.MyClientTxCallback" />
       
</bean>
       
<bean class="com.ibm.websphere.objectgrid.config.ObjectGridConfigFactory"
          factory-method="createPlugin">
         
<constructor-arg type="com.ibm.websphere.objectgrid.config.PluginType"
            value="OBJECTGRID_EVENT_LISTENER" />
         
<constructor-arg type="java.lang.String" value="" />
       
</bean>
     
</list>
    </property>
     
<property name="backingMapConfigurations">
       
<list>
       
<bean class="com.ibm.websphere.objectgrid.config.ObjectGridConfigFactory"
            factory-method="createBackingMapConfiguration">
           
<constructor-arg type="java.lang.String" value="Customer" />
             
<property name="plugins">
           
<bean class="com.ibm.websphere.objectgrid.config.ObjectGridConfigFactory"
                  factory-method="createPlugin">
                 
<constructor-arg type="com.ibm.websphere.objectgrid.config.PluginType"
              value="EVICTOR" />
            <constructor-arg type="java.lang.String"
                    value="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" />
               
</bean>
             
</property>
             
<property name="numberOfBuckets" value="1429" />
           
</bean>
           
<bean class="com.ibm.websphere.objectgrid.config.ObjectGridConfigFactory"
              factory-method="createBackingMapConfiguration">
               
<constructor-arg type="java.lang.String" value="OrderLine" />
                 
<property name="numberOfBuckets" value="701" />
            <property name="timeToLive" value="800" />
            <property name="ttlEvictorType">
                   
<value type="com.ibm.websphere.objectgrid.
                                            TTLType">LAST_ACCESS_TIME</value>
            </property>
           
</bean>
         
</list>
       
</property>
     
</bean>

     
<bean id="client" factory-bean="manager" factory-method="connect"
        singleton="true">
       
<constructor-arg type="java.lang.String">
       
<value>localhost:2809</value>
       
</constructor-arg>
     
<constructor-arg
          type="com.ibm.websphere.objectgrid.security.
                        config.ClientSecurityConfiguration">
         
<null />
       
</constructor-arg>
     
<constructor-arg type="java.net.URL">
       
<null />
       
</constructor-arg>
     
</bean>
</beans>
After creating the XML file, load the file and build the ObjectGrid with the following code snippet.
BeanFactory beanFactory = new XmlBeanFactory(new
  UrlResource("file:test/companyGridSpring.xml"));

ObjectGrid companyGrid = (ObjectGrid) beanFactory.getBean("companyGrid");
Read about integrating with the Spring framework for more information.

Disable the client near cache

The near cache is enabled by default when locking is configured as optimistic or none. Clients do not maintain a near cache when the locking setting is configured as pessimistic.
To disable the near cache, you must set the numberOfBuckets attribute to 0 in the client override ObjectGrid descriptor file.
Read about map entry locking for more information.

Enable the client invalidation mechanism
In a distributed WebSphere eXtreme Scale environment, the client side has a near cache by default when using the optimistic locking strategy or when locking is disabled. The near cache has its own local cached data. If an eXtreme Scale client commits an update, the update goes to the client near cache and server. However, other eXtreme Scale clients do not receive the update information and might have data that is out of date.
Configure the request retry timeout
With reliable maps, you can supply a retry timeout to WebSphere eXtreme Scale for transaction requests.

Parent topic
Configure WebSphere eXtreme Scale

Related tasks

Configure a locking strategy

+
Search Tips | Advanced Search