Configuring an eXtreme Scale client

You can configure an eXtreme Scale client based on your requirements such as overriding settings.

You can configure an eXtreme Scale client in the following ways:
You can override the following plug-ins on a client.

Configuring 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, you must 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 CompanyGrid behaves as defined by the companyGridServerSide.xml file. By default, the CompanyGrid client has the same settings as the CompanyGrid that is running on the server. However, some of the settings can be overridden on the client.

Create a client specific ObjectGrid to override some of these settings. Copy the ObjectGrid XML file that was used to open the server and edit the file to customize for the client side. 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. A plug-in can also be added to the file if it is one of the supported overriding plug-ins.

To set one of the attributes on the client, specify a new value.

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. On the client, the TransactionCallback is com.company.MyClientTxCallback as opposed to com.company.MyTxCallback, which runs on the server. The ObjectGridEventListener is removed on the client because the className value is the empty string.

The Customer backingMap has its numberOfBuckets set to 1429 on the client. The Customer backingMap retains its Evictor from the server configuration, but the MapEventListener is removed from the client.

The numberOfBuckets and timeToLive have been adjusted on the client side of the OrderLine backingMap.

The lockStrategy attribute in this file is ignored no matter what value is specified. This attribute is not supported for overriding on the client side.

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"));

Configuring 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. The following code will construct a client side ObjectGrid that is functionally equivalent to what would be created by using the companyGridClientSide.xml that was provided in the previous section.

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);

Only ObjectGridConfiguration and BackingMapConfiguration objects that are included in the overrideMap will be checked for overridden plugins and attributes. For instance, the code above will override the number of buckets on the OrderLine map. However, the Order map will remain unchanged on the client-side because there is no configuration for it included.

Configuring 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, 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");

See Integrating with Spring framework for more information.

Disabling the near cache

The near cache is enabled by default when locking is configured as optimistic or none and cannot be used when configured as pessimistic.

To disable the near cache, you must set the numberOfBuckets attribute to 0 in the client override ObjectGrid descriptor file.

See Map entry locking for more information.