Configure clients with WebSphere eXtreme Scale

Program guide > Access data with client applications

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:

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

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

Track map updates by an application
When an application is making changes to a Map during a transaction, a LogSequence object tracks those changes. If the application changes an entry in the map, a corresponding LogElement object provides the details of the change.

Enable client-side map replication
You can also enable replication of maps on the client side to make data available faster.

Parent topic:
Access data with client applications

Related concepts

ObjectGrid interface
BackMap interface
Interacting with an ObjectGrid using ObjectGridManager
Data access with indexes (Index API)
Access data in WebSphere eXtreme Scale
Use Sessions to access data in the grid
Cache objects with no relationships involved (ObjectMap API)
Cache objects and their relationships (EntityManager API)
Retrive entities and objects (Query API)
Clients

Related tasks

Program for transactions
Configure clients

Related reference

Connect to a distributed ObjectGrid

+
Search Tips | Advanced Search