Administration guide > Configure the deployment environment > Configuring clients



Configure clients with WebSphere eXtreme Scale

You can configure a WebSphere eXtreme Scale client based on your requirements such as the need to override settings.


Override plug-ins

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


Configure the client with XML

An ObjectGrid XML file can be used to alter settings on the client side.

To change the settings on a WebSphere eXtreme Scale client, create an ObjectGrid XML file that is similar in structure to the file that was used for the WebSphere eXtreme Scale server.

Assume that the following XML file was paired with a deployment policy XML file, and these files were used to start a WebSphere 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 a WebSphere 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,...

  1. Create a client-specific ObjectGrid instance.

  2. Copy the ObjectGrid XML file that was used to open the server.

  3. 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.

  4. 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>

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.

Create 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 ogManager instance of the ObjectGridManager interface 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 the Spring framework integration overview for more information on creating an XML descriptor file.


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, set the numberOfBuckets attribute to 0 in the client override ObjectGrid descriptor file. Read about Map entry locking for more information.


Parent topic:

Configure clients


Related concepts

Enable the client invalidation mechanism


Related tasks

Configure request retry timeout values

Related reference

Client properties file