Home

+

Search Tips   |   Advanced Search

Configure WebSphere eXtreme Scale v8.6

  1. Configuration methods
  2. Operational checklist
  3. Configure data grids
    1. Configure local deployments
    2. Configure data grids to use XDF
    3. Configure evictors with XML files
    4. Configure a locking strategy
    5. Configure peer-to-peer replication with JMS
  4. Configure deployment policies
    1. Configure distributed deployments
    2. Distributed topology
    3. Control shard placement with zones
  5. Configure catalog and container servers
    1. Configure catalog servers and catalog service domains
    2. Example: Configuring catalog service domains
    3. Configure WXS with WAS
    4. Configure the quorum mechanism
    5. Tuning the heartbeat interval setting for failover detection
    6. Configure container servers
    7. Configure WXS servers to run in the Liberty profile
    8. Configure an Enterprise Data Grid in a stand-alone environment for dynamic caching
    9. Configure multiple data center topologies
  6. Configure ports
    1. Configure ports in stand-alone mode
    2. Configure ports in a WAS environment
    3. Servers with multiple network cards
  7. Configure transports
    1. Displaying the transport type of the catalog service domain
    2. Configure IBM eXtremeIO (XIO)
    3. Configure Object Request Brokers
    4. Configure IBM eXtremeMemory
  8. 10. Configure Java clients
    1. Java client overrides
    2. Configure Java clients with XML configuration
    3. Configure Java clients programmatically
    4. Configure the near cache
    5. Configure near cache for dynamic cache
    6. Configure near-cache invalidation
    7. Configure JMS-based client synchronization
    8. Configure request retry timeout values
  9. Configure .NET clients
    1. Configure .NET clients programmatically
  10. Configure WXS connection factories
    1. Configure Eclipse environments to use WXS connection factories
  11. Configure cache integration
    1. Configure HTTP session managers
    2. Configure dynamic cache instances
    3. JPA level 2 (L2) cache plug-in
    4. Configure a Spring cache provider
  12. Configure database integration
    1. Configure JPA loaders
    2. Configure a JPA time-based data updater
  13. Configure REST data services
    1. Enable the REST data service
    2. Configure application servers for the REST data service
    3. Configure Web browsers to access REST data service ATOM feeds
    4. Use a Java client with REST data services
    5. Visual Studio 2008 WCF client with REST data service
    6. 16. Deploying the REST gateway
    7. 17. Configure OSGi-enabled plug-ins using the ObjectGrid descriptor XML file
  14. 18. Configure servers for OSGi
    1. Configure WXS plug-ins with OSGi Blueprint
    2. Configure servers with OSGi Blueprint
    3. Configure servers with OSGI config admin
  15. 20. Scenario: Configuring HTTP session failover in the Liberty profile
    1. Enable the WXS web feature in the Liberty profile
    2. Enable the WXS webGrid feature in the Liberty profile
    3. Enable the WXS webApp feature in the Liberty profile
    4. Configure a web server plug-in to forward requests to multiple servers in the Liberty profile
    5. Merge plug-in configuration files for deployment to the application server plug-in
  16. Configure an Enterprise Data Grid for dynamic caching using a Liberty profile
  17. Configure WXS REST clients in the Liberty profile



Configuration methods

We can configure most aspects of the product with XML files and property files. We can also use programmatic methods, including application and system programming interfaces, plug-ins, and managed beans.

Use the following files to create a basic configuration:

File Description
Server properties Settings for catalog and container servers, such as trace, logging, security, ports, and so on. To specify...

  • Use a system property
  • Place file in the classpath
  • Specify file in the server start script
Client properties Client properties, including ports and security settings. To specify...

  • Use a system property
  • Place file in the classpath
  • Use ClientClusterContext.getClientProperties
ObjectGrid descriptor Data grid and map configuration.

  • For stand-alone configurations, specify file in the server start script.
  • For WAS configurations, add file to the application module
Deployment policy descriptor Control shard and placement of data on the various container servers in the configuration.

  • For stand-alone configurations, specify file in the server start script.
  • For WAS configurations, add file to the application module



Operational checklist

For AIX...

TCP_KEEPINTVL Interval between packets that are sent to validate the connection. Socket keep-alive protocol. Enables detection of network outage. When using WebSphere eXtreme Scale, set the value to 10. In half seconds.

To check the current setting...

    # no -o tcp_keepintvl

To change the current setting...

    # no -o tcp_keepintvl=10
TCP_KEEPINIT Initial timeout value for TCP connection. Socket keep-alive protocol that enables detection of network outage. When using WXS, set the value to 40. In half seconds.

To check the current setting

    # no -o tcp_keepinit

To change the current setting...

    # no -o tcp_keepinit=40
ORB properties Update /java/jre/ib/orb.properties to modify the transport behavior of the grid.
Use parameters in the startOgServer or startXsServer script. In particular...

  • Set heap settings with the -jvmArgs parameter.
  • Set application class path and properties with the -jvmArgs parameter.
  • Set -jvmArgs parameters for configuring agent monitoring.

Port settings WXS has to open ports for communications for some transports. These ports are all dynamically defined. However, if a firewall is in use between containers then specify the ports.

Listener port -listenerPort Port used for communication between processes.
Core group port -haManagerPort Port used for failure detection. Same as peerPort. Note that core groups do not need to communicate across zones, so you might not need to set this port if the firewall is open to all the members of a single zone.
JMX service port -JMXServicePort Port that the JMX service should use.
SSL port -Dcom.ibm.CSI.SSLPort=1234 Used with -jvmArgs argument. Sets the SSL port to 1234. Secure port peer to the listener port.
Client port -catalogServiceEndPoints Used in the catalog service only. Format...

serverName:hostName:clientPort:peerPort

startOgServer script (ORB) startXsServer script (XIO)
Verify that security settings are configured correctly:

  • Transport (SSL)
  • Application (Authentication and Authorization)

To verify your security settings, we can try to use a malicious client to connect to the configuration. For example, when the SSL-Required setting is configured, a client that has a TCP_IP setting with or a client with the wrong trust store should not be able to connect to the server. When authentication is required, a client with no credential, such as a user ID and password, should not be able to connect to the sever. When authorization is enforced, a client with no access authorization should not be granted the access to the server resources.

Choose how we are going to monitor your environment.

  • xscmd tool:

    • The JMX ports of the catalog servers need to be visible to the xscmd tool. The container server ports also need to be accessible for some commands that gather information from the containers.

  • Monitoring console:

    With the monitoring console, we can chart current and historical statistics.

  • Vendor monitoring tools:



Configure data grids

Use an ObjectGrid descriptor XML file to configure data grids, backing maps, plug-ins, and so on.

For a distributed deployment, you need...


Configure local deployments

A local in-memory WXS configuration can be created by using an ObjectGrid descriptor XML file or APIs. To create a local deployment, you create an ObjectGrid descriptor XML file and then pass the file to the createObjectGrid methods in the ObjectGridManager interface. Alternatively, we can also create the entire deployment programmatically with the ObjectGridManager interface.

  1. Create an ObjectGrid descriptor XML file.

    The following companyGrid.xml file is an example of an ObjectGrid descriptor XML. The first few lines of the file include the required header for each ObjectGrid XML file. The file defines an ObjectGrid instance named "CompanyGrid" and several BackingMaps named "Customer," "Item," "OrderLine," and "Order." 

    <!-- companyGrid.xml file  -->

<?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">
   <backingMap name="Customer" />
   <backingMap name="Item" />
   <backingMap name="OrderLine" />
   <backingMap name="Order" />
  </objectGrid>
 </objectGrids>

</objectGridConfig>

  2. Pass the XML file to one of the createObjectGrid methods in the ObjectGridManager interface.

    The following code sample validates the companyGrid.xml file against the XML schema, and creates the ObjectGrid instance named "CompanyGrid." The newly created ObjectGrid instance is not cached. 

    ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", new URL("file:etc/test/companyGrid.xml"), true, false);


Configure data grids to use XDF

If we are using an enterprise data grid, enable XDF so that both Java and .NET can access the same data grid objects. Use XDF to serialize and store keys and values in the data grid in a language-independent format. XDF is now the default serialization technology used when we are running XIO, and have a copy mode set to COPY_TO_BYTES. When enabled, Java and C# objects can share data in the same data grid.

XDF benefits:

To enable XDF, in the ObjectGrid descriptor XML file, set the CopyMode attribute to XDF in the backingMap element of the ObjectGrid descriptor XML file.

Also enable IBM eXtremeIO (XIO) in the environment (-enableXIO).


Configure evictors with XML files

In addition to programmatically setting a time-to-live (TTL) evictor with the BackingMap interface, we can use an XML file to configure an evictor on each BackingMap instance.

Evictor types include...

Set the evictor settings before you start your container servers.


Configure the near cache to update the LAST_ACCESS_TIME value for the TTL evictor in the data grid

We can configure the near cache configured on the client to propagate TTL read operations to the remote data grid. Configuring this propagation prevents cache entries from getting prematurely evicted from the remote data grid.

To enable the near cache to update TTL metadata on the remote data grid

  1. Set nearCacheLastAccessTTLSyncEnabled in the ObjectGrid descriptor XML file.

    Set this attribute on the same backingMap element on which you have the TTL evictor enabled.

    nearCacheLastAccessTTLSyncEnabled

    Set to true to enable TTL information to be synchronized with the remote data grid. The LAST_ACCESS_TIME TTL evictor type must be enabled when you enable this property.

    In the following example, both maps in the Grid ObjectGrid element have a TTL evictor configured. The Map1 backingMap element also has synchronization with the remote data grid enabled. 

    <?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="Grid">         
             <backingMap name="Map1" 
                         lockStrategy="OPTIMISTIC" 
                         nearCacheLastAccessTTLSyncEnabled="true"  
                         ttlEvictorType="LAST_ACCESS_TIME" 
                         timeToLive="60"  
                         copyMode="COPY_TO_BYTES"/>

             <backingMap name="Map2" 
                         lockStrategy="OPTIMISTIC" 
                         nearCacheLastAccessTTLSyncEnabled="false" 
                         ttlEvictorType="LAST_ACCESS_TIME" 
                         timeToLive="60" 
                         copyMode="COPY_TO_BYTES"/>

        </objectGrid>
    </objectGrids>
...
...
</objectGridConfig>

  2. Restart the container servers and clients.


Results

When cache entries are added to the remote data grid, the same keys and values are inserted into the near cache on the client. When the client gets or fetches keys from the cache, the values are returned from the near cache. The TTL metadata is also sent to the remote data grid, so that the remote data grid has the most recent TTL information.


Configure a locking strategy

We can define an optimistic, a pessimistic, or no locking strategy on each BackingMap in the WXS configuration.

Each BackingMap instance can be configured to use one of the following locking strategies:

  1. Optimistic locking mode
  2. Pessimistic locking mode
  3. None

The default lock strategy is OPTIMISTIC. Use optimistic locking when data is changed infrequently. Locks are only held for a short duration while data is being read from the cache and copied to the transaction. When the transaction cache is synchronized with the main cache, any cache objects that have been updated are checked against the original version. If the check fails, then the transaction is rolled back and an OptimisticCollisionException exception results.

The PESSIMISTIC lock strategy acquires locks for cache entries and should be used when data is changed frequently. Any time a cache entry is read, a lock is acquired and conditionally held until the transaction completes. The duration of some locks can be tuned using transaction isolation levels for the session.

If locking is not required because the data is never updated or is only updated during quiet periods, we can disable locking using the NONE lock strategy. This strategy is very fast because a lock manager is not required. The NONE lock strategy is ideal for look-up tables or read-only maps.

To avoid a java.lang.IllegalStateException exception, you must call the setLockStrategy method before calling the initialize or getSession methods on the ObjectGrid instance.


Configure peer-to-peer replication with JMS

The Java Message Service (JMS) based peer-to-peer replication mechanism is used in both the distributed and local WXS environment. JMS is a core-to-core replication process and allows data updates to flow among local ObjectGrids and distributed ObjectGrids. For example, with this mechanism we can move data updates from a distributed WXS data grid to a local WXS grid, or from a grid to another grid in a different system domain.

The JMS-based peer-to-peer replication mechanism is based on the built-in JMS-based ObjectGridEventListener, com.ibm.websphere.objectgrid.plugins.builtins.JMSObjectGridEventListener.

The following is an XML configuration example to enable a peer-to-peer replication mechanism on a WXS configuration:

Peer-to-peer replication configuration - XML example 

<bean id="ObjectGridEventListener" 
      className="com.ibm.websphere.objectgrid.plugins.JMSObjectGridEventListener">

 <property name="replicationRole" 
           type="java.lang.String" 
           value="DUAL_ROLES" 
           description="" />

  <property name="replicationStrategy" type="java.lang.String" value="PUSH" description="" />

  <property name="jms_topicConnectionFactoryJndiName" 
            type="java.lang.String" 
            value="defaultTCF" 
            description="" />

  <property name="jms_topicJndiName" 
               type="java.lang.String" 
               value="defaultTopic" 
               description="" />

  <property name="jms_topicName" 
               type="java.lang.String" 
               value="defaultTopic" 
               description="" />

  <property name="jms_userid" 
               type="java.lang.String" 
               value="" 
               description="" />

  <property name="jms_password" 
               type="java.lang.String" 
               value="" 
               description="" />

  <property name="jndi_properties" 
            type="java.lang.String" 
            value="java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory; 
            java.naming.provider.url=tcp://localhost:61616;connectionFactoryNames=defaultTCF; 
            topic.defaultTopic=defaultTopic"
            description="jndi properties" />

</bean>


Distribute changes between peer JVMs

The LogSequence and LogElement objects distribute changes between peer JVMs and communicate the changes that have occurred in a WXS transaction with an ObjectGridEventListener plug-in.

A prerequisite is that the ObjectGrid instance must be cached by the ObjectGridManager. See createObjectGrid methods for more information. The cacheInstance boolean value must be set to true.

It is not necessary for you to implement this mechanism. There is a built-in peer-to-peer replication mechanism for you to use this function.

The objects provide a means for an application to publish changes that have occurred in an ObjectGrid using a message transport to peer ObjectGrids in remote JVMs and then apply those changes on that JVM. The LogSequenceTransformer class is critical to enabling this support. This article examines how to write a listener using a Java Message Service (JMS) messaging system for propagating the messages. To that end, WXS supports transmitting LogSequences that result from a WXS transaction commit across WAS cluster members with an IBM-provided plug-in. This function is not enabled by default, but can be configured to be operational. However, when either the consumer or producer is not a WAS, using an external JMS messaging system might be required.


Implementing the mechanism

The LogSequenceTransformer class, and the ObjectGridEventListener, LogSequence and LogElement APIs allow any reliable publish-and-subscribe to be used to distribute the changes and filter the maps we want to distribute. The snippets in this topic show how to use these APIs with JMS to build a peer-to-peer ObjectGrid shared by applications hosted on a diverse set of platforms sharing a common message transport.

Initialize the plug-in

The ObjectGrid calls the initialize method of the plug-in, part of the ObjectGridEventListener interface contract, when the ObjectGrid starts. The initialize method must obtain its JMS resources, including connections, sessions, and publishers, and start the thread that is the JMS listener.

The following examples show the initialize method: 

initialize method example
public void initialize(Session session) {
        mySession = session;
        myGrid = session.getObjectGrid();
        try {
            if (mode == null) {
                throw new ObjectGridRuntimeException("No mode specified");
            }
            if (userid != null) {
                connection = topicConnectionFactory.createTopicConnection(userid, password);
            } else connection = topicConnectionFactory.createTopicConnection();

            // need to start the connection to receive messages.
            connection.start();

            // the jms session is not transactional (false).
            jmsSession = connection.createTopicSession(false, javax.jms.Session.AUTO_ACKNOWLEDGE);
            if (topic == null)
                if (topicName == null) {
                    throw new ObjectGridRuntimeException("Topic not specified");
                } else {
                    topic = jmsSession.createTopic(topicName);
                }
            publisher = jmsSession.createPublisher(topic);
            // start the listener thread.
            listenerRunning = true;
            listenerThread = new Thread(this);
            listenerThread.start();
        } catch (Throwable e) {
            throw new ObjectGridRuntimeException("Cannot initialize", e);
        }
    }

The code to start the thread uses a Java SE thread. If we are running a WAS v6.x or a WAS Version 5.x Enterprise server, use the asynchronous bean application programming interface (API) to start this daemon thread. We can also use the common APIs. Following is an example replacement snippet showing the same action using a work manager: 

// start the listener thread.
listenerRunning = true;
workManager.startWork(this, true);

The plug-in must also implement the Work interface instead of the Runnable interface. You also need to add a release method to set the listenerRunning variable to false. The plug-in must be provided with a WorkManager instance in its constructor or by injection if using an Inversion of Control (IoC) container.

Transmit the changes

The following is a sample transactionEnd method for publishing the local changes that are made to an ObjectGrid. This sample uses JMS, although we can use any message transport that is capable of reliable publish-and subscribe-messaging. 

transactionEnd method example

    // This method is synchronized to make sure the     
    // messages are published in the order the transaction
    // were committed. If we started publishing the messages
    // in parallel then the receivers could corrupt the Map
    // as deletes may arrive before inserts etc.
    public synchronized void transactionEnd(String txid, boolean isWriteThroughEnabled,
    boolean committed,
            Collection changes) {
        try {
            // must be write through and commited.
            if (isWriteThroughEnabled && committed) {
                // write the sequences to a byte []
                ByteArrayOutputStream bos = new ByteArrayOutputStream();
                ObjectOutputStream oos = new ObjectOutputStream(bos);
                if (publishMaps.isEmpty()) {
                    // serialize the whole collection
                    LogSequenceTransformer.serialize(changes, oos, this, mode);
                } else {
                    // filter LogSequences based on publishMaps contents
                    Collection publishChanges = new ArrayList();
                    Iterator iter = changes.iterator();
                    while (iter.hasNext()) {
                        LogSequence ls = (LogSequence) iter.next();
                        if (publishMaps.contains(ls.getMapName())) {
                            publishChanges.add(ls);
                        }
                    }
                    LogSequenceTransformer.serialize(publishChanges, oos, this, mode);
                }
                // make an object message for the changes
                oos.flush();
                ObjectMessage om = jmsSession.createObjectMessage(bos.toByteArray());
                // set properties
                om.setStringProperty(PROP_TX, txid);
                om.setStringProperty(PROP_GRIDNAME, myGrid.getName());
                // transmit it.
                publisher.publish(om);
            }
        } catch (Throwable e) {
            throw new ObjectGridRuntimeException("Cannot push changes", e);
        }
    }

This method uses several instance variables:

Receive and apply update messages

Following is the run method. This method runs in a loop until the application stops the loop. Each loop iteration attempts to receive a JMS message and apply it to the ObjectGrid. 

JMS message run method example
private synchronized boolean isListenerRunning() {
        return listenerRunning;
    }

    public void run() {
        try {
            System.out.println("Listener starting");
            // get a jms session for receiving the messages.
            // Non transactional.
            TopicSession myTopicSession;
            myTopicSession = connection.createTopicSession(false, javax.jms.Session.AUTO_ACKNOWLEDGE);

            // get a subscriber for the topic, true indicates don't receive            
            // messages transmitted using publishers
            // on this connection. Otherwise, we'd receive our own updates.
            TopicSubscriber subscriber = myTopicSession.createSubscriber(topic,
       null, true);
            System.out.println("Listener started");
            while (isListenerRunning()) {
                ObjectMessage om = (ObjectMessage) subscriber.receive(2000);
                if (om != null) {
                    // Use Session that was passed in on the initialize...
                    // very important to use no write through here
                    mySession.beginNoWriteThrough();
                    byte[] raw = (byte[]) om.getObject();
                    ByteArrayInputStream bis = new ByteArrayInputStream(raw);
                    ObjectInputStream ois = new ObjectInputStream(bis);
                    // inflate the LogSequences
                    Collection collection = LogSequenceTransformer.inflate(ois, myGrid);
                    Iterator iter = collection.iterator();
                    while (iter.hasNext()) {
                        // process each Maps changes according to the mode when
                        // the LogSequence was serialized
                        LogSequence seq = (LogSequence) iter.next();
                        mySession.processLogSequence(seq);
                    }
                    mySession.commit();
                } // if there was a message
            } // while loop
            // stop the connection             connection.close();
        } catch (IOException e) {
            System.out.println("IO Exception: " + e);
        } catch (JMSException e) {
            System.out.println("JMS Exception: " + e);
        } catch (ObjectGridException e) {
            System.out.println("ObjectGrid exception: " + e);
            System.out.println("Caused by: " + e.getCause());
        } catch (Throwable e) {
            System.out.println("Exception : " + e);
        }
        System.out.println("Listener stopped");
    }


JMS event listener

The JMSObjectGridEventListener is designed to support client-side near cache invalidation and a peer-to-peer replication mechanism. It is a Java Message Service (JMS) implementation of the ObjectGridEventListener interface.

The client invalidation mechanism can be used in a distributed WXS environment to ensure client near cache data to be synchronized with servers or other clients. Without this function, the client near cache could hold stale data. However, even with this JMS-based client invalidation mechanism, you have to take into consideration the timing window for updating a client near cache because of the delay for the run time in publishing updates.

The peer-to-peer replication mechanism can be used in both distributed and local WXS environments. It is an ObjectGrid core-to-core replication process and allows data updates to flow among local ObjectGrids and distributed ObjectGrids. For example, with this mechanism we can move data updates from a distributed grid to a local ObjectGrid, or from any grid to another grid in a different system domain.

The JMSObjectGridEventListener requires the user to configure JMS and JNDI information to obtain required JMS resources. Additionally, replication-related properties must be set correctly. In a JEE environment, the JNDI should be available in both Web and Enterprise JavaBean (EJB) containers. In this case, the JNDI property is optional unless we want to obtained external JMS resources.

This event listener has properties we can configure with XML or programmatic approaches, which can be used for only client invalidation, only peer-to-peer replication, or both. Most properties are optional for customizing the behavior to achieve your required functionality.

For more information see the JMSObjectGridEventListener API.


Extending the JMSObjectGridEventListener plug-in

The JMSObjectGridEventListener plug-in allows peer ObjectGrid instances to receive updates when data in the grid has been changed or evicted. It also allows clients to be notified when entries are updated or evicted from a WXS grid. This topic describes how to extend the JMSObjectGridEventListener plug-in to allow applications to be notified when a JMS message is received. This is most useful when using the CLIENT_SERVER_MODEL setting for client invalidation.

When running in the receiver role, the overridden JMSObjectGridEventListener.onMessage method is automatically called by the WXS runtime when the JMSObjectGridEventListener instance receives JMS message updates from the grid. These messages wrap a collection of LogSequence. Objects. The LogSequence objects are passed to the onMessage method and the application uses the LogSequence to identify which cache entries have been inserted, deleted, updated or invalidated.

To use the onMessage extension point applications...

  1. Create a new class, extending the JMSObjectGridEventListener class, overriding the onMessage method.

  2. Configure the extended JMSObjectGridEventListener the same way as the ObjectGridEventListener for ObjectGrid.

The extended JMSObjectGridEventListener class is a child class of the JMSObjectGridEventListener class and can only override two methods: the initialize (optional) and onMessage methods. If a child class of the JMSObjectGridEventListener class needs to use any ObjectGrid artifacts such as ObjectGrid or Session in the onMessage method, it can get these artifacts in the initialize method and cache them as instance variables. Also, in the onMessage method, cached ObjectGrid artifacts can be used to process a passed collection of LogSequences.

The overridden initialize method has to invoke super.initialize method to initialize parent JMSObjectGridEventListener appropriately.

The following is a sample for an extended JMSObjectGridEventListener class. 

package com.ibm.websphere.samples.objectgrid.jms.price;

import java.util.*;
import com.ibm.websphere.objectgrid.*;
import com.ibm.websphere.objectgrid.plugins.LogElement;
import com.ibm.websphere.objectgrid.plugins.LogSequence;
import com.ibm.websphere.objectgrid.plugins.builtins.JMSObjectGridEventListener;

public class ExtendedJMSObjectGridEventListener extends JMSObjectGridEventListener{
 protected static boolean debug = true;
 
    /**
     * This is the grid associated with this listener.
     */
    ObjectGrid grid;

    /**
     * This is the session associated with this listener.
     */
    Session session;
    
    String objectGridType;
    
    public List receivedLogSequenceList = new ArrayList();

 
 /* (non-Javadoc)
  * @see com.ibm.websphere.objectgrid.plugins.builtins.JMSObjectGridEventListener
    #initialize(com.ibm.websphere.objectgrid.Session)
  */
 public void initialize(Session session) {
  // Note: if need to use any ObjectGrid artifact, this class need to get ObjectGrid   
  //  from the passed Session instance and get ObjectMap from session instance   
  // for any transactional ObjectGrid map operation.
  
  super.initialize(session);
  // must invoke super's initialize method.
  this.session = session;
  // cache the session instance, in case need to   
  //   use it to perform map operation.
  this.grid = session.getObjectGrid();
  // get ObjectGrid, in case need
  //   to get ObjectGrid information.
  
  if (grid.getObjectGridType() == ObjectGrid.CLIENT)
   objectGridType = "CLIENT";
  else if (grid.getObjectGridType() == ObjectGrid.SERVER)
   objectGridType = "Server";

  if (debug)
   System.out.println("ExtendedJMSObjectGridEventListener[" +
     objectGridType + "].initialize() : grid = " + this.grid);
 }
 
 /* (non-Javadoc)
  * @see com.ibm.websphere.objectgrid.plugins.builtins.JMSObjectGridEventListener
    #onMessage(java.util.Collection)
  */
 protected void onMessage(Collection logSequences) {
  System.out.println("ExtendedJMSObjectGridEventListener[" +
    objectGridType + "].onMessage(): ");
  
  Iterator iter = logSequences.iterator();
  
  while (iter.hasNext()) {
            LogSequence seq = (LogSequence) iter.next();
            
      StringBuffer buffer = new StringBuffer();
      String mapName = seq.getMapName();
      int size = seq.size();
      buffer.append("\nLogSequence[mapName=" + mapName + ", size=" + size + ",
     objectGridType=" + objectGridType
        + "]: ");

      Iterator logElementIter = seq.getAllChanges();
      for (int i = seq.size() - 1; i >= 0; --i) {
       LogElement le = (LogElement) logElementIter.next();
       buffer.append(le.getType() + " -> key=" + le.getCacheEntry().getKey() + ", ");
      }
      buffer.append("\n");

      receivedLogSequenceList.add(buffer.toString());

      if (debug) {
       System.out.println("ExtendedJMSObjectGridEventListener["
      + objectGridType + "].onMessage(): " + buffer.toString());
      }
  }    
 }
 
 public String dumpReceivedLogSequenceList() {
  String result = "";
  int size = receivedLogSequenceList.size();
  result = result + "\nExtendedJMSObjectGridEventListener[" + objectGridType
    + "]: receivedLogSequenceList size = " + size + "\n";
  for (int i = 0; i < size; i++) {
   result = result + receivedLogSequenceList.get(i) + "\n";
  }
  return result;
 }

 public String toString() {
  return "ExtendedJMSObjectGridEventListener["
    + objectGridType + " - " + this.grid + "]";
 }}


Configuration

The extended JMSObjectGridEventListener class must be configured the same way for both client invalidation and peer-to-peer replication mechanism. The following is the XML configuration example. 

<objectGrid name="PRICEGRID">
   <bean id="ObjectGridEventListener"
    className="com.ibm.websphere.samples.objectgrid.jms.
      price.ExtendedJMSObjectGridEventListener">
    <property name="invalidationModel" type="java.lang.String"
     value="CLIENT_SERVER_MODEL" description="" />
    <property name="invalidationStrategy" type="java.lang.String"
     value="INVALIDATE" description="" />
    <property name="jms_topicConnectionFactoryJndiName" type="java.lang.String"
     value="jms/TCF" description="" />
    <property name="jms_topicJndiName" type="java.lang.String"
     value="GRID.PRICEGRID" description="" />
    <property name="jms_topicName" type="java.lang.String"
     value="GRID.PRICEGRID" description="" />
    <property name="jms_userid" type="java.lang.String" value=""
     description="" />
    <property name="jms_password" type="java.lang.String" value=""
     description="" />     
   </bean>
   <backingMap name="PRICE" pluginCollectionRef="PRICE"></backingMap>
      </objectGrid>
The className of ObjectGridEventListener bean is configured with the extended JMSObjectGridEventListener class with the same properties as the generic JMSObjectGridEventListener.


Configure deployment policies

Use the deployment policy descriptor XML file and the objectgrid descriptor XML file to manage a distributed deployment. The deployment policy is encoded as an XML file that is provided to the container server. The deployment policy provides information about maps, map sets, partitions, replicas, and so on. It also controls shard placement behaviors.


Configure distributed deployments

Use the deployment policy descriptor XML file and the ObjectGrid descriptor XML file to manage your topology.

The deployment policy is encoded as an XML file that is provided to the WXS container server. The XML file specifies the following information:

The deployment policy also controls the following placement behaviors.

Endpoint information is not pre-configured in the dynamic environment. There are no server names or physical topology information found in the deployment policy. All shards in a data grid are automatically placed into container servers by the catalog service. The catalog service uses the constraints that are defined by the deployment policy to automatically manage shard placement. This automatic shard placement leads to easy configuration for large data grids. We can also add servers to your environment as needed.

Restriction: In a WAS environment, a core group size of more than 50 members is not supported.

A deployment policy XML file is passed to a container server during startup. A deployment policy must be used along with an ObjectGrid XML file. The deployment policy is not required to start a container server, but is recommended. The deployment policy must be compatible with the ObjectGrid XML file used with it. For each objectgridDeployment element in the deployment policy, you must include a corresponding objectGrid element in your ObjectGrid XML file. The maps in the objectgridDeployment must be consistent with the backingMap elements found in the ObjectGrid XML. Every backingMap must be referenced within only one mapSet element.

In the following example, the companyGridDpReplication.xml file is intended to be paired with the corresponding companyGrid.xml file.

companyGridDpReplication.xml...

companyGrid.xml...

The companyGridDpReplication.xml file has one mapSet element that is divided into 11 partitions. Each partition must have exactly one synchronous replica. The number of synchronous replicas is specified by the minSyncReplicas and maxSyncReplicas attributes. Because the minSyncReplicas attribute is set to 1, each partition in the mapSet element must have at least one synchronous replica available to process write transactions. Because the maxSyncReplicas attribute is set to 1, each partition cannot exceed one synchronous replica. The partitions in this mapSet element have no asynchronous replicas.

The numInitialContainers attribute instructs the catalog service to defer placement until four container servers are available to support this ObjectGrid instance. The numInitialContainers attribute is ignored after the specified number of container servers has been reached.

We can also use the placementDeferralInterval property and...

...to delay the placement of shards on the container servers.

Although the companyGridDpReplication.xml file is a basic example, a deployment policy can offer you full control over your environment.


Distributed topology

Distributed coherent caches offer increased performance, availability, and scalability, which we can configure.

WXS automatically balances servers. We can include additional servers without restarting WebSphere WXS. Adding additional servers without having to restart WXS allows us to have simple deployments and also large, terabyte-sized deployments in which thousands of servers are needed.

This deployment topology is flexible. Using the catalog service, we can add and remove servers to better use resources without removing the entire cache. Use the startOgServer and stopOgServer or startXsServer and stopXsServer commands to start and stop container servers. Both of these commands require you to specify the -catalogServiceEndPoints option. All distributed deployment clients communicate to the catalog service through the Internet Interoperability Object Protocol (IIOP). All clients use the ObjectGrid interface to communicate with servers.

The dynamic configuration capability of WXS makes it easy to add resources to the system. Containers host the data and the catalog service allows clients to communicate with the grid of container servers. The catalog service forwards requests, allocates space in host container servers, and manages the health and availability of the overall system. Clients connect to a catalog service, retrieve a description of the container server topology, and then communicate directly to each server as needed. When the server topology changes due to the addition of new servers, or due to the failure of others, the catalog service automatically routes client requests to the appropriate server that hosts the data.

A catalog service typically exists in its own grid of Java virtual machines. A single catalog server can manage multiple servers. We can start a container server in a JVM by itself or load the container server into an arbitrary JVM with other container servers for different servers. A client can exist in any JVM and communicate with one or more servers. A client can also exist in the same JVM as a container server.

We can also create a deployment policy programmatically when we are embedding a container server in an existing Java process or application.



Control shard placement with zones

Use the deployment policy to define zones. Zones give you control over shard placement in WXS. Zones are a logical, user-defined concept used to represent logical groupings of physical servers.


Configure zones for replica placement across data centers

Zone support allows configurations for replica placement across data centers. Grids of thousands of partitions can be managed using a handful of optional placement rules. A data center can be different floors of a building, different buildings, or even different cities or other distinctions as configured with zone rules.

Java virtual machines that host a WXS server can be tagged with a zone identifier. The deployment file can now include one or more zone rules and these zone rules are associated with a shard type. A JVM can have multiple containers but only 1 server. A container can host multiple shards from a single ObjectGrid.

This capability is useful to make sure that replicas and primaries are placed in different locations or zones for better high availability. Normally, WXS does not place a primary and replica shard on JVMs with the same IP address. This simple rule normally prevents two WXS servers from being placed on the same physical computer. However, you might require a more flexible mechanism. For example, you might be using two blade chassis and want the primaries to be striped across both chassis and the replica for each primary be placed on the other chassis from the primary.

Striped primaries means that primaries are placed into each zone, and the replica for each primary is located in the opposite zone. For example primary 0 would be in zoneA, and sync replica 0 would be in zoneB. Primary 1 would be in zoneB, and sync replica 1 would be in zoneA.

The chassis name would be the zone name in this case. Alternatively, you might name zones after floors in a building and use zones to make sure that primaries and replicas for the same data are on different floors. Buildings and data centers are also possible. Testing has been done across data centers using zones as a mechanism to ensure the data is adequately replicated between the data centers. If we are using the HTTP Session Manager for WXS, we can also use zones. With this feature, we can deploy a single Web application across three data centers and ensure that HTTP sessions for users are replicated across data centers so that the sessions can be recovered even if an entire data center fails.

If required, WXS can make sure that backups and primaries for the same partition are located in different data centers. It can put all primaries in data center 1 and all replicas in data center 2 or it can round robin primaries and replicas between both data centers. The rules are flexible so that many scenarios are possible. WXS can also manage thousands of servers, which together with completely automatic placement with data center awareness makes such large grids affordable from an administrative point of view. Administrators can specify what they want to do simply and efficiently.

We can split the primaries and replicas into separate zones when a hot standby is required.

To specify the zone to use for all containers within the server use the -zone parameter with the server start script

We can also specify a zone programmatically using a zone name for a container as as described in the Embedded server API .


Associate WebSphere Extended Deployment nodes with zones

If we are using WXS with WebSphere Extended Deployment Java EE applications, we can use WebSphere Extended Deployment node groups to place servers in specific zones.

In WXS, a JVM is only allowed to be a member of a single zone. However, WebSphere allows a node to be a part of multiple node groups. Use this functionality of WXS zones if you ensure that each of your nodes is in only one zone node group.

Use the following syntax to name your node group to declare it a zone: ReplicationZone<UniqueSuffix>. Servers running on a node that is part of such a node group are included in the zone specified by the node group name. The following is a description of an example topology.

First, you configure 4 nodes: node1, node2, node3, and node4, each node having 2 servers. Then you create a node group named ReplicationZoneA and a node group named ReplicationZoneB. Next, you add node1 and node2 to ReplicationZoneA and add node3 and node4 to ReplicationZoneB.

When the servers on node1 and node2 are started, they will become part of ReplicationZoneA, and likewise the servers on node3 and node4 will become part of ReplicationZoneB.

A grid-member JVM checks for zone membership at startup only. Adding a new node group or changing the membership only has an impact on newly started or restarted JVMs.


Zone rules

An WXS partition has one primary shard and zero or more replica shards. For this example, P is the primary shard, S is a synchronous replica and A is an asynchronous replica. A zone rule has three components:

The zone name for a container can be specified as described in the documentation for Embedded server API . A zone rule specifies the possible set of zones in which a shard can be placed. The inclusive flag indicates that after a shard is placed in a zone from the list, then all other shards are also placed in that zone. An exclusive setting indicates that each shard for a partition is placed in a different zone in the zone list. For example, using an exclusive setting means that if there are three shards (primary, and two synchronous replicas), then the zone list must have three zones.

Each shard can be associated with one zone rule. A zone rule can be shared between two shards. When a rule is shared then the inclusive or exclusive flag extends across shards of all types sharing a single rule.


Stripe primaries and replicas across zones

You have three blade chassis, and want primaries distributed across all three, with a single synchronous replica placed in a different chassis than the primary. Define each chassis as a zone with chassis names ALPHA, BETA, and GAMMA. An example deployment XML follows: 

<?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="library">

   <mapSet name="ms1" 
         numberOfPartitions="37" 
         minSyncReplicas="1"
         maxSyncReplicas="1" 
         maxAsyncReplicas="0">

   <map ref="book" />

   <zoneMetadata>

    <shardMapping shard="P" zoneRuleRef="stripeZone"/>
    <shardMapping shard="S" zoneRuleRef="stripeZone"/>

    <zoneRule name ="stripeZone" exclusivePlacement="true" >
     <zone name="ALPHA" />
     <zone name="BETA" />
     <zone name="GAMMA" />
    </zoneRule>

   </zoneMetadata>
  </mapSet>
 </objectgridDeployment>

</deploymentPolicy>

This deployment XML contains a grid called library with a single Map called book. It uses four partitions with a single synchronous replica. The zone metadata clause shows the definition of a single zone rule and the association of zone rules with shards. The primary and synchronous shards are both associated with the zone rule "stripeZone". The zone rule has all three zones in it and it uses exclusive placement. This rule means that if the primary for partition 0 is placed in ALPHA then the replica for partition 0 will be placed in either BETA or GAMMA. Similarly, primaries for other partitions are placed in other zones and the replicas will be placed.

Asynchronous replica in a different zone than primary and synchronous replica

In this example, two buildings exist with a high latency connection between them. You want no data loss high availability for all scenarios. However, the performance impact of synchronous replication between buildings leads you to a trade off. You want a primary with synchronous replica in one building and an asynchronous replica in the other building. Normally, the failures are JVM crashes or computer failures rather than large scale issues. With this topology, we can survive normal failures with no data loss. The loss of a building is rare enough that some data loss is acceptable in that case. We can make two zones, one for each building. The deployment XML file follows: 

<?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="library">
  <mapSet name="ms1" numberOfPartitions="13" minSyncReplicas="1"
   maxSyncReplicas="1" maxAsyncReplicas="1">
   <map ref="book" />
   <zoneMetadata>
    <shardMapping shard="P" zoneRuleRef="primarySync"/>
    <shardMapping shard="S" zoneRuleRef="primarySync"/>
    <shardMapping shard="A" zoneRuleRef="aysnc"/>
    <zoneRule name ="primarySync" exclusivePlacement="false" >
      <zone name="BldA" />
      <zone name="BldB" />
    </zoneRule>
    <zoneRule name="aysnc" exclusivePlacement="true">
      <zone name="BldA" />
      <zone name="BldB" />
    </zoneRule>
   </zoneMetadata>
  </mapSet>
 </objectgridDeployment>
</deploymentPolicy>

The primary and synchronous replica share a primaySync zone rule with an exclusive flag setting of false. So, after the primary or sync gets placed in a zone, then the other is also placed in the same zone. The asynchronous replica uses a second zone rule with the same zones as the primarySync zone rule but it uses the exclusivePlacement attribute set to true. This attribute indicates that means a shard cannot be placed in a zone with another shard from the same partition. As a result, the asynchronous replica does not get placed in the same zone as the primary or synchronous replicas.

Placing all primaries in one zone and all replicas in another zone

Here, all primaries are in one specific zone and all replicas in a different zone. We will have a primary and a single asynchronous replica. All replicas will be in zone A and primaries in B. 

 <?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="library">
   <mapSet name="ms1" numberOfPartitions="13" minSyncReplicas="0"
    maxSyncReplicas="0" maxAsyncReplicas="1">
    <map ref="book" />
    <zoneMetadata>
     <shardMapping shard="P" zoneRuleRef="primaryRule"/>
     <shardMapping shard="A" zoneRuleRef="replicaRule"/>
     <zoneRule name ="primaryRule">
      <zone name="A" />
     </zoneRule>
     <zoneRule name="replicaRule">
      <zone name="B" />
       </zoneRule>
      </zoneMetadata>
     </mapSet>
   </objectgridDeployment>
 </deploymentPolicy>

Here, we can see two rules, one for the primaries (P) and another for the replica (A).


Zones over wide area networks (WAN)

You might want to deploy a single WXS over multiple buildings or data centers with slower network interconnections. Slower network connections lead to lower bandwidth and higher latency connections. The possibility of network partitions also increases in this mode due to network congestion and other factors. WXS approaches this harsh environment in the following ways.

Limited heart beating between zones

Java virtual machines grouped together into core groups do heart beat each other. When the catalog service organizes Java virtual machines in to groups, those groups do not span zones. A leader within that group pushes membership information to the catalog service. The catalog service verifies any reported failures before taking action. It does this by attempting to connect to the suspect Java virtual machines. If the catalog service sees a false failure detection then it takes no action as the core group partition will heal in a short period of time.

The catalog service will also heart beat core group leaders periodically at a slow rate to handle the case of core group isolation.


Zone-preferred routing

With zone-preferred routing, we can define how WXS directs transactions to zones.

You have control over where the shards of a data grid are placed.

Zone-preferred routing gives WXS clients the capability to specify a preference for a particular zone or set of zones. As a result, client transactions are routed to preferred zones before attempting to route to any other zone.


Requirements for zone-preferred routing

Before attempting zone-preferred routing, ensure that the application is able to satisfy the requirements of your scenario.

Per-container partition placement is necessary to use zone-preferred routing. This placement strategy is a good fit for applications that are storing session data in the ObjectGrid. The default partition placement strategy for WXS is fixed-partition. Keys are hashed at transaction commit time to determine which partition houses the key-value pair of the map when using fixed-partition placement.

Per-container placement assigns your data to a random partition when the transaction commits time through the SessionHandle object. You must be able to reconstruct the SessionHandle object to retrieve your data from the data grid.

Use zones to have more control over where primary shards and replica shards are placed in your domain. Using multiple zones in the deployment is advantageous when your data is in multiple physical locations. Geographically separating primaries and replicas is a way to ensure that catastrophic loss of one data center does not affect the availability of the data.

When data is spread across multiple zones, it is likely that clients are also spread across the topology. Routing clients to their local zone or data center has the obvious performance benefit of reduced network latency. Route clients to local zones or data centers when possible.


Configure your topology for zone-preferred routing

Consider the following scenario. You have two data centers: Chicago and London. To minimize response time of clients, we want clients to read and write data to their local data center.

Primary shards must be placed in each data center so that transactions can be written locally from each location. Clients must be aware of zones to route to the local zone.

Per-container placement locates new primary shards on each container that is started. Replicas are placed according to zone and placement rules specified by the deployment policy. By default, a replica is placed in a different zone than its primary shard. Consider the following deployment policy for this scenario. 

<?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="universe">
  <mapSet name="mapSet1" placementStrategy="PER_CONTAINER"
   numberOfPartitions="3" maxAsyncReplicas="1">
   <map ref="planet" />
  </mapSet>
 </objectgridDeployment>
</deploymentPolicy>

Each container that starts with the deployment policy receives three new primaries. Each primary has one asynchronous replica. Start each container with the appropriate zone name. Use the -zone parameter if we are starting your containers with the startOgServer or startXsServer script.

For a Chicago container server: 

startOgServer.sh s1 
    -objectGridFile ../xml/universeGrid.xml 
    -deploymentPolicyFile ../xml/universeDp.xml 
    -catalogServiceEndPoints MyServer1.company.com:2809 
    -zone Chicago

startXsServer.sh s1 
    -objectGridFile ../xml/universeGrid.xml 
    -deploymentPolicyFile ../xml/universeDp.xml 
    -catalogServiceEndPoints MyServer1.company.com:2809 
    -zone Chicago

If containers are running in WAS, you must create a node group and name it with the prefix ReplicationZone. Servers running on the nodes in these node groups are placed in the appropriate zone. For example, servers running on a Chicago node might be in a node group named ReplicationZoneChicago.

Primary shards for the Chicago zone have replicas in the London zone. Primary shards for the London zone have replicas in the Chicago zone.

Set the preferred zones for the clients. Provide a client properties file to your client JVM. Create a file named objectGridClient.properties and ensure that this file is in your classpath.

Include the preferZones property in the file. Set the property value to the appropriate zone. Clients in Chicago must have the following value in the objectGridClient.properties file:

The property file for London clients must contain the following value:

This property instructs each client to route transactions to its local zone if possible. The topology asynchronously replicates data that is inserted into a primary shard in the local zone into the foreign zone.


Use the SessionHandle interface to route to the local zone

The per-container placement strategy does not use a hash-based algorithm to determine the location of your key-value pairs in the data grid. You must use SessionHandle objects to ensure that transactions are routed to the correct location when we are using this placement strategy. When a transaction is committed, a SessionHandle object is bound to the session if one has not already been set. The SessionHandle object can also be bound to the Session by calling the Session.getSessionHandle method before committing the transaction. The following code snippet shows a SessionHandle being bound before committing the transaction. 

Session ogSession = objectGrid.getSession();

// binding the SessionHandle
SessionHandle sessionHandle = ogSession.getSessionHandle();

ogSession.begin();
ObjectMap map = ogSession.getMap("planet");
map.insert("planet1", "mercury");

// tran is routed to partition specified by SessionHandle
ogSession.commit();

Assume that the prior code was running on a client in your Chicago data center. The preferZones attribute is set to Chicago for this client. As a result, the deployment would route transactions to one of the primary partitions in the Chicago zone: partition 0, 1, 2, 6, 7, or 8.

The SessionHandle object provides a path back to the partition that is storing this committed data. The SessionHandle object must be reused or reconstructed and set on the Session to get back to the partition containing the committed data. 

ogSession.setSessionHandle(sessionHandle);
ogSession.begin();

// value returned will be "mercury"
String value = map.get("planet1");
ogSession.commit();

The transaction in this code reuses the SessionHandle object that was created during the insert transaction. The get transaction then routes to the partition that holds the inserted data. Without the SessionHandle object, the transaction cannot retrieve the inserted data.


How container and zone failures affect zone-based routing

Generally, a client with the preferZones property set routes all transactions to the specified zone or zones. However, the loss of a container results in the promotion of a replica shard to a primary shard . A client that was previously routing to partitions in the local zone must retrieve previously inserted data from the remote zone.

Consider the following scenario. A container in the Chicago zone is lost. It previously contained primaries for partitions 0, 1, and 2. The new primary shards for these partitions are then placed in the London zone because the London zone hosted the replicas for these partitions.

Any Chicago client that is using a SessionHandle object that points to one of the failed-over partitions now reroutes to London. Chicago clients that are using new SessionHandle objects route to Chicago-based primaries.

Similarly, if the entire Chicago zone is lost, all replicas in the London zone are promoted to primaries. In this scenario, all Chicago clients route their transactions to London.


Define zones for container servers

Zones are collections of container servers. A container server can belong only one zone. A container server is assigned to a zone when it starts.

You must plan your zones before you start your container servers because container servers define their zone membership at startup. To change the zone membership of a container server, restart the server with the new zone information.


Example: Zone definitions in the deployment policy descriptor XML file

We can specify zones and zone rules with the deployment policy descriptor XML file.


Example: Primary and replica shards in different zones

This example places primary shards in one zone, and replica shards in a different zone, with a single asynchronous replica. All primary shards start in the DC1 zone. Replica shards start in zone DC2. 

<?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="library">
 <mapSet name="ms1" numberOfPartitions="13" minSyncReplicas="0"
  maxSyncReplicas="0" maxAsyncReplicas="1">
  <map ref="book" />
  <zoneMetadata>
    <shardMapping shard="P" zoneRuleRef="primaryRule"/>
    <shardMapping shard="A" zoneRuleRef="replicaRule"/>
    <zoneRule name="primaryRule">
     <zone name="DC1" />
    </zoneRule>
    <zoneRule name="replicaRule">
    </zoneRule>
  </zoneMetadata>
  </mapSet>
  </objectgridDeployment>
 </deploymentPolicy>

One asynchronous replica is defined in the ms1 mapSet element. Therefore, two shards exist for each partition: a primary and one asynchronous replica. In the zoneMetadata element, a shardMapping element is defined for each shard: P for the primary, and DC1 for the asynchronous replica. The primaryRule attribute defines the zone set for the primary shards, which is just zone DC1, and this rule is to be used for primary shard placement. Asynchronous replicas are placed in the DC2 zone.

However, if the DC2 zone is lost, the replica shards become unavailable. The loss or failure of a container server in the DC1 zone can result in data loss, even though a replica has been specified.

To address this possibility, we can either add a zone or add a replica, as described in the following sections.


Example: Add a zone, striping shards

The following code configures a new zone: 

<?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="library">
  <mapSet name="ms1" numberOfPartitions="13" minSyncReplicas="0"
   maxSyncReplicas="0" maxAsyncReplicas="1">
     <map ref="book" />
     <zoneMetadata>
      <shardMapping shard="P" zoneRuleRef="stripeRule"/>
      <shardMapping shard="A" zoneRuleRef="stripeRule"/>
      <zoneRule name="stripeRule" exclusivePlacement="true">
       <zone name="A" />
       <zone name="B" />
      <zone name="C" />
      </zoneRule>
    </zoneMetadata>
   </mapSet>
 </objectgridDeployment>
</deploymentPolicy>

Three total zones have been defined in this code: A, B, and C. Instead of separate primary and replica zone rules, a shared zone rule named stripeRule is defined. This rule includes all of the zones, with the exclusivePlacement attribute set to true. The WXS placement policy ensures that primary and replica shards are in separate zones. This striping of placement causes primary and replica shards to spread across both zones to conform to this policy. Adding a third zone C ensures that losing any one zone does not result in data loss, and still leaves primary and replica shards for each partition. A zone failure results in the loss of either the primary shard, the replica shard, or neither. Any lost shard is replaced from the surviving shard in a surviving zone, placing it in the other surviving zone.


Example: Add a replica and define multiple data centers

The classic two data-center scenario has high speed, low latency networks in each data center, but high latency between the data centers. Synchronous replicas are used in each data center where the low latency minimizes the impact of replication on response times. Asynchronous replication is used between data centers, so the high latency network has no impact on response time. 

<?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="library">
   <mapSet name="ms1" numberOfPartitions="13" minSyncReplicas="1"
   maxSyncReplicas="1" maxAsyncReplicas="1">
    <map ref="book" />
    <zoneMetadata>
     <shardMapping shard="P" zoneRuleRef="primarySync"/>
     <shardMapping shard="S" zoneRuleRef="primarySync"/>
     <shardMapping shard="A" zoneRuleRef="async"/>
    <zoneRule name="primarySync" exclusivePlacement="false">
      <zone name="DC1" />
      <zone name="DC2" />
     </zoneRule>
     <zoneRule name="async" exclusivePlacement="true">
     <zone name="DC1" />
      <zone name="DC2" />
     </zoneRule>
   </zoneMetadata>
  </mapSet>
  </objectgridDeployment>
 </deploymentPolicy>

The primary and synchronous replica share the primarySync rule with an exclusivePlacement attribute setting of false. The exclusivePlacement attribute set to false creates a configuration with the primary and synchronous replica shards of each partition placed in the same zone. The asynchronous replica shard uses a second zone rule with mostly the same zones as the primarySync zone rule. However the asynchronous replica uses the exclusivePlacement attribute set to true. The exclusivePlacement attribute, when set to true, means that a shard cannot be placed in a zone with another shard from the same partition. As a result, the asynchronous replica shard does not get placed in the same zone as the primary or synchronous replica shard. There are three shards per partition in this mapSet: a primary, and both a synchronous and asynchronous replica, so there are three shardMapping elements, one for each shard.

If a zone is lost, any asynchronous replicas are lost, and not regenerated, because they have no separate zone. If the primary and replica shards are lost, then the surviving asynchronous replica is promoted to primary, and a new synchronous replica is created in the zone. The primaries and replicas are striped across each zone.

With exclusive placement, each shard has its own zone: You must have enough zones for all the shards we want to place in their own zones. If a rule has one zone, only one shard can be placed in the zone. With two zones, we can have up to two shards in the zone.


Example: Zones in a WAS environment

The following code configures a new zone: 

<?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="library">
  <mapSet name="ms1" numberOfPartitions="13" minSyncReplicas="0"
   maxSyncReplicas="0" maxAsyncReplicas="1">
     <map ref="book" />
     <zoneMetadata>
      <shardMapping shard="P" zoneRuleRef="stripeRule"/>
      <shardMapping shard="A" zoneRuleRef="stripeRule"/>
      <zoneRule name="stripeRule" exclusivePlacement="true">
      <zone name="ReplicationZoneA" />
       <zone name="ReplicationZoneB" />
      <zone name="ReplicationZoneC" />
      </zoneRule>
    </zoneMetadata>
   </mapSet>
 </objectgridDeployment>
</deploymentPolicy>
For this example, three node groups are defined in the WAS environment: ReplicationZoneA, ReplicationZoneB, and ReplicationZoneC. The node group name and the zone name in the deployment policy descriptor XML file must be identical, and must contain the text ReplicationZone<identifier>. This file defines a similar configuration to the striping shards example, but shows the required naming for a WAS configuration.


View zone information with the xscmd utility

Use the xscmd utility to view information about your current zone deployment, including shard placement data.

We can determine information about the configuration related to zone settings using the xscmd utility that ships with the product.

To determine information about the shards of data...


Example

We can also run a simpler scenario using the getting started sample: /path/to/ObjectGrid/gettingstarted.

  1. Start a catalog server:
      runcat.bat

  2. Determine required number of replicas, zone rules, containers, and other settings...
      startOgServer.sh serverA0 -objectgridFile xml\objectgrid.xml -deploymentPolicyFile xml\deployment.xml -zone zoneA
      startXsServer.sh serverA0 -objectgridFile xml\objectgrid.xml -deploymentPolicyFile xml\deployment.xml -zone zoneA

  3. We can stop container processes to simulate failure in the data grid:
      stopOgServer.bat serverA0,serverA1,serverB0 -catalogServiceEndPoints localhost:2809
      stopXsServer.bat serverA0,serverA1,serverB0 -catalogServiceEndPoints localhost:2809
    .

    If the server that contains the last shard of a partition is stopped, WXS allocates a new primary shard . We can check for data loss:

    • The runclient script inserts and reads item in the data grid.

    • The xscmd -c showMapSizes command shows the number of items in the data grid.

  4. Show active container servers with the following command:
      xscmd -c showPlacement -z zone_name



Configure catalog and container servers

WXS has two types of servers:


Configure catalog servers and catalog service domains

The catalog service hosts logic that is typically idle during steady states. As a result, the catalog service minimally influences scalability. The service is built to service hundreds of container servers that become available simultaneously. For high availability, configure the catalog service into a catalog service domain.

After a catalog service domain is started, the members of the data grid bind together.

Best practice is to start a minimum of three catalog servers on three different nodes.

If we are using only two nodes, configure two catalog servers on each of the two nodes for a total of four catalog server processes. Creating this configuration ensures that when only one of the nodes is started, the required two catalog servers are running. Start at least two catalog servers at the same time. When catalog servers start, they look for other catalog servers in the configuration, and do not start successfully until at least one other catalog server is found.

You configure stand-alone catalog server and catalog service domains with parameters and property files that you pass to the start server command or to the embedded server API.

We can configure catalog servers that run in WAS with the WAS admin console, administrative tasks, and the server properties file. The server life cycle is controlled by the process life cycle within WAS. When processes start or stop in WAS, the catalog servers running on these processes also start or stop.


Example: Configuring catalog service domains

When using the catalog service, a minimum of two catalog servers are required to avoid a single point of failure. Depending on the number of nodes in your environment, we can create different configurations to ensure that at least two catalog servers are always running.


Example: Starting four catalog servers on two nodes in a stand-alone environment

The following script starts catalog servers cs0 and cs1 on the host1 node, and starts catalog servers cs2 and cs3 on the host2 node.

Deprecated: The startOgServer and stopOgServer commands start servers that use the ORB transport mechanism. The ORB is deprecated, but we can continue using these scripts if you were using the ORB in a previous release. The IBM eXtremeIO (XIO) transport mechanism replaces the ORB. Use the startXsServer and stopXsServer scripts to start and stop servers that use the XIO transport.

Remember: You must use the -listenerPort option because the catalog servers running on a node each require a unique port number.


Example: Starting multiple catalog servers in a WAS environment

Catalog servers start automatically in a WAS environment. We can define multiple catalog servers to start by creating a catalog service domain. After you specify multiple endpoints in the catalog service domain, restart the included application servers so that the catalog servers start in parallel.


Configure WXS with WAS

We can run catalog service and container server processes in WAS. The process to configure these servers is different than a stand-alone configuration. The catalog service can automatically start in WAS servers or dmgrs. Container process start when a WXS application is deployed and started in the WAS environment.

Do not collocate your container servers with catalog servers in a production environment. Include the catalog service in multiple node agent processes or in an application server that is not hosting a WXS application.

See also...

  1. Configure WebSphere Commerce to use WXS for dynamic cache to improve performance and scale
  2. WebSphere Business Process Management and Connectivity integration


Configure the catalog service in WAS

Catalog service processes can run in WAS. The server life cycle in WAS determines when the catalog service starts and stops.


Create catalog service domains in WAS

Catalog service domains define a group of catalog servers that manage the placement of shards and monitor the health of container servers in the data grid.

By creating a catalog service domain, we are defining a highly available collection of catalog servers.

These catalog servers can run in WebSphere Application Server within a single cell and core group. The catalog service domain can also define a remote group of servers that run in different Java SE processes or other WebSphere Application Server cells.

For catalog servers that run on existing application servers within the cell: When you define a catalog service domain that places catalog servers on the application servers within the cell, the core group mechanisms of WAS are used. The catalog service automatically starts on the application servers in the cell. As a result, the members of a single catalog service domain cannot span the boundaries of a core group, and a catalog service domain therefore cannot span cells. However, WXS container servers and clients can span cells by connecting to a catalog server across cell boundaries, such as a stand-alone catalog service domain or a catalog service domain embedded in another cell.

For remote catalog servers: We can connect WXS containers and clients to a catalog service domain running in another WAS cell or running as stand-alone processes. Because remotely configured catalog servers do not automatically start in the cell, manually start any remotely configured catalog servers. When you configure a remote catalog service domain, the domain name should match the domain name specified when you start the remote catalog servers. The default catalog service domain name for stand-alone catalog servers is false Domain. Specify a catalog service domain name with the startOgServer or startXsServer command -domain parameter, a server properties file, or with the embedded server API. Start each remote catalog server process in the remote domain with the same domain name.

Do not collocate the catalog services with WXS container servers in a production environment. Include the catalog service in multiple node agent processes or in an application server that is not hosting a WebSphere WXS application.

  1. Create the catalog service domain.

    1. In the WAS admin console, click...

        System administration > WXS > Catalog service domains > New

    2. Define a name, default value, and JMX authentication credentials for the catalog service domain. If we are configuring remote endpoints for the catalog service domain, the name of the catalog service domain should match the name of the catalog service domain that you specify when you start the catalog servers.

    3. Add catalog server endpoints. We can either select existing application servers or add remote servers running a catalog service.

  2. Test the connection to the catalog servers within the catalog service domain. For existing application servers, catalog servers start when the associated application server is started. For remote application servers, start the servers manually using the startOgServer or startXsServer command or embedded server API.

    1. In the WAS admin console, click...

        System administration > WXS > Catalog service domains

    2. Select the catalog service domain to test and click...

        Test connection

      When you click this button, all of the defined catalog service domain end points are queried one by one, if any one end point is available, returns a message that indicates that the connection to the catalog service domain was successful.


Catalog service domain administrative tasks

Use the Jacl or Jython scripting languages to manage catalog service domains in your WAS configuration.


Requirements

You must have the WXS client installed in your WAS environment.


List all administrative tasks

To get a list of all of the administrative tasks that are associated with catalog service domains, run the following command with wsadmin: 

wsadmin>$AdminTask help XSDomainManagement


Commands


createXSDomain

Register a new catalog service domain.

Argument Description
-name Required. Name of the catalog service domain to create.
-default Specifies whether the catalog service domain is the default for the cell. Default is true. (Boolean: set to true or false)
-properties Custom properties for the catalog service domain.
-enableXIO Specifies whether IBM eXtreme IO (XIO) or the ORB is used for transport communication in this catalog service domain.

true Specifies that XIO is used.
false Specifies that the ORB is used. If you do not specify a value, the default is true (XIO enabled). If you have remote servers in the catalog service domain, the -enableXIO parameter does not configure XIO or ORB on the remote servers. To configure transports on remote servers, specify the transport type when you start the remote servers.

Argument Description
name_of_endpoint Name of the catalog service endpoint.

  • For existing application servers: The name of the endpoint must be in the following format:

      cell_name\node_name\server_name

  • For remote servers: Host name of the remote server. We can have the same name for multiple endpoints, but the client port values must be unique for each endpoint.

custom_properties Custom properties for the catalog service domain endpoint. If you do not have any custom properties, use a set of double quotation marks (

"") for this argument.

endpoint_ports Port numbers for the catalog service domain endpoint. The ports must be specified in the following order:

    <client_port>,<listener_port>

Client Port Port used for communication between the catalog servers in the catalog service domain. Required for catalog servers running in WAS processes only and can be set to any port that is not being used elsewhere.
Listener Port Port used for communication with clients. Required for remote endpoints and must match the value used when the catalog service was started. The listener port is used by clients and containers to communicate with the catalog service.

For WXS remote endpoints: Defines the ORB listener port for containers and clients to communicate with the catalog service through the ORB. For WAS endpoints, the listener port value is optional because the value is inherited from the BOOTSTRAP_ADDRESS port configuration.

Argument Description
-securityEnabled Specifies that client security is enabled for the catalog server. The server properties file that is associated with the selected catalog server must have a matching securityEnabled setting in the server properties file. If these settings do not match, an exception results. (Boolean: set to true or false)
-credentialAuthentication Optional. Indicates if credential authentication is enforced or supported.

Never No client certificate authentication is enforced.
Required Credential authentication is always enforced. If the server does not support credential authentication, the client cannot to connect to the server.
Supported (false ) Credential authentication is enforced only if both the client and server support credential authentication.
-authenticationRetryCount Optional. Number of times that authentication gets tried again if the credential is expired.

If you do not want to try authentication again, set the value to 0. The default value is 0.

-credentialGeneratorClass Indicates the com.ibm.websphere.objectgrid.security.plugins.builtins. WSTokenCredentialGenerator implementation class, so the client retrieves the security tokens from the thread.
-credentialGeneratorProps Properties for the CredentialGenerator implementation class. The properties are sent to the object with the setProperties(String) method. The credential generator properties value is used only when a value is specified for the Credential generator class field.

Return value:

Batch mode example usage

Batch mode requires correct formatting of the command entry. Consider using interactive mode to ensure the values that you enter are processed correctly. When you use batch mode, you must define the -defineDomainServers step arguments using a specific array of properties. This array of properties is in the format...

The endpoint_ports value is a list of ports that must be specified in the following order:

Interactive mode example usage


deleteXSDomain

Delete a catalog service domain.

Required parameters:

-name

Name of the catalog service domain to delete.

Return value:

Batch mode example usage

Interactive mode example usage


getdefault XSDomain

Return the default catalog service domain for the cell.

Required parameters: None

Return value: The name of the default catalog service domain.

Batch mode example usage

Interactive mode example usage


listXSDomains

Return a list of the existing catalog service domains.

Required parameters: None

Return value: A list of all of the catalog service domains in the cell.

Batch mode example usage

Interactive mode example usage


modifyXSDomain

Modify an existing catalog service domain.

Batch mode requires correct formatting of the command entry. Consider using interactive mode to ensure the values that you enter are processed correctly. When you use batch mode, you must define the -modifyEndpoints, -addEndpoints and -removeEndpoints step arguments using a specific array of properties. This array of properties is in the format...

The endpoint_ports value is a list of ports that must be specified in the following order:

Argument Description
-name Required. Name of the catalog service domain to edit.
-default If set to true, specifies that the selected catalog service domain is the default for the cell. (Boolean)
-properties Custom properties for the catalog service domain.
-enableXIO Specifies whether IBM eXtreme IO (XIO) or the ORB is used for transport communication in this catalog service domain.

true Specifies that XIO is used.
false Specifies that the ORB is used.
If you do not specify a value, the default is true (XIO enabled). If you have remote servers in the catalog service domain, we cannot configure XIO on the remote servers.

Argument Description
name_of_endpoint Name of the catalog service endpoint.

  • For existing application servers: The name of the endpoint must be in the following format:

      cell_name\node_name\server_name

  • For remote servers: Host name of the remote server. We can have the same name for multiple endpoints, but the listener port values must be unique for each endpoint.

endpoint_ports Port numbers for the catalog service domain endpoint. The endpoints must be specified in the following order:

    <client_port>,<listener_port>

Client Port Port used for communication between the catalog servers in the catalog service domain. Required for catalog servers running in WAS processes only and can be set to any port that is not being used elsewhere.
Listener Port Port used for communication with clients. Required for remote endpoints and must match the value used when the catalog service was started. The listener port is used by clients and containers to communicate with the catalog service.

For WXS remote endpoints. Defines the ORB listener port for containers and clients to communicate with the catalog service. For WAS endpoints, specifying the listener port value is optional. The value depends on transport type we are using. If we are using the ORB, the value is inherited from the BOOTSTRAP_ADDRESS port configuration. If we are using IBM extremeIO, the value is inherited from the XIO_ADDRESS port configuration.

Argument Description
name_of_endpoint Name of the catalog service endpoint.

  • For existing application servers: The name of the endpoint must be in the following format:

      cell_name\node_name\server_name

  • For remote servers: Host name of the remote server.

    We can have the same name for multiple endpoints, but the listener port values must be unique for each endpoint.

custom_properties Custom properties for the catalog service domain endpoint. If you do not have any custom properties, use a set of double quotation marks (

"") for this argument.

endpoint_ports Port numbers for the catalog service domain endpoint. The endpoints must be specified in the following order:

    <client_port>,<listener_port>

Client Port Port used for communication between the catalog servers in the catalog service domain. Required for catalog servers running in WAS processes only and can be set to any port that is not being used elsewhere.
Listener Port Port used for communication with clients. Required for remote endpoints and must match the value used when the catalog service was started. The listener port is used by clients and containers to communicate with the catalog service.

For WXS remote endpoints: Defines the ORB listener port for containers and clients to communicate with the catalog service through the ORB. For WAS endpoints, specifying the listener port value is optional because the value is inherited from the BOOTSTRAP_ADDRESS port configuration.

Argument Description
name_of_endpoint Name of the catalog service endpoint to delete.

Argument Description
-securityEnabled Specifies that client security is enabled for the catalog server. The server properties file that is associated with the selected catalog server must have a matching securityEnabled setting in the server properties file. If these settings do not match, an exception results. (Boolean: set to true or false)
-credentialAuthentication Optional. Indicates whether credential authentication is enforced or supported.

Never

No client certificate authentication is enforced.

Required Credential authentication is always enforced. If the server does not support credential authentication, the client cannot to connect to the server.
Supported (false ) Credential authentication is enforced only if both the client and server support credential authentication.
-authenticationRetryCount (optional) Number of times that authentication gets tried again if the credential is expired.

If you do not want to try authentication again, set the value to 0. The default value is 0. -credentialGeneratorClass Indicates the com.ibm.websphere.objectgrid.security.plugins.builtins. WSTokenCredentialGenerator implementation class, so the client retrieves the security tokens from the thread. -credentialGeneratorProps Properties for the CredentialGenerator implementation class. The properties are sent to the object with the setProperties(String) method. The credential generator properties value is used only when a value is specified for the Credential generator class field.

Return value:

Batch mode example usage

Interactive mode example usage

getTransport

Display the transport type for the catalog service domain: IBM eXtremeIO (XIO) or ORB.

If we run this command on a catalog service domain that contains remote servers, or if the catalogServerName is a remote server, an error results. You must use the xscmd -c showTransport command for remote servers.

Required parameters:

-domainName

Name of the catalog service domain for which to display the transport type.

-catalogServerName

Name of the catalog server for which to display the transport type.

Return value: ORB or XIO

Display the transport for a catalog service domain

Display the transport for a catalog server

Interactive mode example usage


testXSDomainConnection

Test the connection to a catalog service domain.

Required parameters:

-name

Name of the catalog service domain to which to test the connection.

Optional parameters

-timeout

Maximum amount of time to wait for the connection, in seconds.

Return value: If a connection can be made, returns true, otherwise, connection error information is returned.

Batch mode example usage

Interactive mode example usage


testXSServerConnection

Test the connection to a catalog server. Works for both stand-alone servers and servers that are a part of a catalog service domain.

Required parameters:

host

Host on which the catalog server resides.

listenerPort

Listener port for the catalog server.

Optional parameters

timeout

Maximum amount of time to wait for a connection to the catalog server, in seconds.

domain

Name of a catalog service domain. If you define a value for this parameter, the client security properties for the specified catalog service domain are used to test the connection. Otherwise, a search occurs to find the catalog service domain for the specified host and listener port. If a catalog service domain is found, the client security properties that are defined for the catalog service domain are used to test the server. Otherwise, no client security properties are used during the test.

Return value:

Batch mode example usage

Interactive mode example usage


Catalog service domain collection

Use this page to manage catalog service domains. Catalog service domains define a group of catalog servers that manage the placement of shards and monitors the health of container servers in the data grid.

To view this administrative console page, click...

To create a new catalog service domain, click New. To delete a catalog service domain, select the catalog service domain we want to remove and click Delete.

Test Connection

When you click the Test connection button, all of the defined catalog service domain end points are queried one by one, if any one end point is available, returns a message that indicates that the connection to the catalog service domain was successful. Use this button to test configured the connection and security information correctly.

Set false

Defines the catalog service domain used as the default. Select one catalog service domain as the default and click Set default. Only one catalog service domain can be selected as the default.

Name

Name for the catalog service domain.

false

Specifies which catalog service domain in the list is the default. The default catalog service domain is indicated with the following icon: .


Catalog service domain settings

Use this page to manage the settings for a specific catalog service domain. Catalog service domains define a group of catalog servers that manage the placement of shards and monitors the health of container servers in the data grid. We can define a catalog service domain that is in the same cell as the dmgr. We can also define remote catalog service domains if your WXS configuration is in a different cell or the data grid is made up of Java SE processes.

To view this administrative console page, click...

Test connection

When you click the Test connection button, all of the defined catalog service domain end points are queried one by one, if any one end point is available, returns a message that indicates that the connection to the catalog service domain was successful. Use this button to test configured the connection and security information correctly.

Name

Name of the catalog service domain.

Enable this catalog service domain as the default unless another catalog service domain is explicitly specified

If you select this check box, the selected catalog service domain becomes the default catalog service domain for the cell. Each server profile in the cell that is augmented with the WXS profile belongs to the selected catalog service domain.

For WXS, all WXS containers that are embedded in Java EE application modules connect to the default domain. Clients can connect to the default domain using the ServerFactory.getServerProperties().getCatalogServiceBootstrap() API to retrieve the catalog service endpoints to use when calling the ObjectGridManager.connect() API.

If you change the default domain to point to a different set of catalog servers, then all containers and clients refer to the new domain after they are restarted.

Enable IBM eXtremeIO (XIO) communication

Specifies if the catalog service domain uses XIO communication. If this option is not selected, the ORB is used.

Note: We cannot enable XIO communication on remote servers from the WAS admin console. Enable XIO on remote servers when you start the servers with the startXsServer script.

Catalog servers

Specifies a list of catalog servers that belong to this catalog service domain.

Click New to add a catalog server to the list. This catalog server must already exist in the WXS configuration. We can also edit or delete a server from the list by selecting the endpoint and then clicking Edit or Delete.  Define the following properties for each catalog server endpoint:

Catalog server endpoint

Name of the existing application server or remote server on which the catalog service is running. A catalog service domain cannot contain a mix of existing application servers and remote server endpoints.

  • Existing application server: Path of an application server, node agent, or dmgr in the cell. A catalog service starts automatically in the selected server. Select from the list of the existing application servers. All of the application servers that you define within the catalog service domain must be in the same core group.

  • Remote server: Host name of the remote catalog server.

    For WXS remote endpoints: Host name of the remote catalog server process. Start the remote servers with the startOgServer or startXsServer script or the embedded server API.

    Note: We cannot enable XIO communication on remote servers from the WAS admin console. Enable XIO on remote servers when you start the servers with the startXsServer script.

Client Port

Port used for communication between the catalog servers in the catalog service domain. Required for catalog servers running in WAS processes. We can set the value to any port that is not being used by another process.

Listener Port

Port used for communication with clients. Required for remote endpoints and must match the value used when the catalog service was started. The listener port is used by clients and containers to communicate with the catalog service.

For WXS remote endpoints:

  • If we are using the ORB transport, the BOOTSTRAP_ADDRESS value for each WAS application server is used.

  • If we are using the IBM eXtremeIO transport, the XIO_ADDRESS value is used.

Status

Icon Definition
Unknown
Started
Stopped


Client security properties

Use this page to configure client security for a catalog service domain. These settings apply to all the servers in the catalog service domain. These properties can be overridden by specifying a splicer.properties file with the com.ibm.websphere.xs.sessionFilterProps custom property or by splicing the application EAR file.

To view this administrative console page, click...

Enable client security

Specifies that client security is enabled for the catalog server. The server properties file that is associated with the selected catalog server must have a matching securityEnabled setting in the server properties file. If these settings do not match, an exception results.

Credential authentication

Indicates if credential authentication is enforced or supported.

Never

No client credential authentication is enforced.

Required

Credential authentication is always enforced. If the server does not support credential authentication, the client cannot to connect to the server.

Supported

Credential authentication is enforced only if both the client and server support credential authentication.

Authentication retry count

Number of times that authentication gets tried again if the credential is expired.

If you do not want to try authentication again, set the value to 0.

Credential generator class

Indicates the com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator implementation class, so the client retrieves the credential from the CredentialGenerator object.

We can choose from two predefined credential generator classes, or we can specify a custom credential generator. If you choose a custom credential generator, you must indicate the name of the credential generator class.

Subject type

Specifies if we are using the J2EE caller or the J2EE runAs subject type. Specify this value when you choose the WSTokenCredentialGenerator credential generator.

User ID

Specify a user ID when we are using the UserPasswordCredentialGenerator credential generator implementation.

Password

Specify a password when we are using the UserPasswordCredentialGenerator credential generator implementation.

Credential generator properties

Properties for a custom CredentialGenerator implementation class. The properties are set in the object with the setProperties(String) method. The credential generator properties value is used only when a value is specified for the Credential generator class field.


Catalog service domain custom properties

We can further edit the configuration of the catalog service domain by defining custom properties.

To view this administrative console page, click...

To create a new custom property, click New.

Name

Name of the custom property for the catalog service domain.

Value

Specifies a value for the custom property for the catalog service domain.


Configure the quorum mechanism

The quorum mechanism is configured for each catalog service. Enable the quorum mechanism on all of the catalog servers in the catalog service domain.

Before you enable the quorum mechanism, configure a topology that supports this type of configuration. The configuration must support the following requirements:

Flat IP address space Any addressable element on the network must be able to connect to any other addressable element on the network unimpeded. You must use a flat IP address naming space. All the firewalls in the configuration must allow all traffic to flow between the IP addresses and ports that are being used to host catalog servers and container servers.
Number of catalog servers Start at least one catalog server for each data center in the configuration.
Heartbeat interval setting If you do not define the heartbeat interval, the default value is 30 seconds. WXS checks on the JVMs in a single zone at the defined interval. For example, if a heartbeat on a container server is missed, and quorum is established, a failover event occurs to place a new container server.
Transport security Because data centers are normally deployed in different geographical locations, you might want to enable transport security between the data centers for security reasons.

The quorum mechanism is disabled by default. Enable the quorum mechanism in the following scenarios:

We can leave the quorum mechanism disabled if the catalog service domain is contained within a single data center, or is on a local area network (LAN). In this type of configuration, default heart beating is used and brownouts are assumed to be shorter than 10 seconds. Because the detection period is approximately 30 seconds, any short brownouts that occur do not cause placement changes to occur in the data grid.

If you enable quorum, all the catalog servers must be available and communicating with the data grid to conduct placement operations. If a network brownout occurs, placement is paused until all the catalog servers are available. If a data center failure occurs, manual administrator actions are required to remove the failed catalog server from the quorum.

  1. Enable quorum on the catalog servers.

    In WAS, configure quorum with the server properties file. In a stand-alone environment we can either use the properties method or enable quorum when you start the server:

    • Set the enableQuorum=true property in the server properties file.

      Use this configuration in a WAS or stand-alone environment. 

      catalogClusterEndPoints=cat0:cat0.domain.com:6600:6601,
cat1:cat1.domain.com:6600:6601
catalogServiceEndPoints= cat0.domain.com:2809, cat1.domain.com:2809
enableQuorum=true

    • Pass the -quorum enabled flag on the startOgServer or startXsServer command.

      Use this configuration method when you start stand-alone servers only. 

      # bin/startOgServer cat0 .serverProps objectGridServer.properties -quorum true
      # bin/startXsServer cat0 .serverProps objectGridServer.properties -quorum true

  2. Start container servers in the same zone.

    When we are running a data grid across data centers, the servers must use the zone information to identify the data center in which they reside. Setting the zone on the container servers allows WXS to monitor health of the container servers that are scoped to the data center, minimizing cross-data-center traffic. The container server JVMs in a core group must never span multiple LANs that are connected with links, like in a wide area network.

    Container server JVMs are tagged with a zone identifier. The data grid of container JVMs is automatically broken in to small core groups of JVMs. A core group only includes JVMs from the same zone. JVMs from different zones are never in the same core group.

    A core group aggressively tries to detect the failure of its member JVMs.


Results

By setting the quorum mechanism to be enabled on the catalog servers within a catalog service domain, all the catalog servers must be available for data grid placement operations to occur. In the event of a short network brownout, placement operations are temporarily stopped until all the catalog servers in the quorum are available.

We can add additional catalog servers to the quorum by repeating these steps.

We can remove a catalog server from the quorum by stopping the catalog server with the administrative method that is required by the configuration. When a catalog server is stopped through administrative actions, quorum is automatically reestablished among the remaining catalog servers, and placement can continue. If you restart the catalog server with the steps described in this topic, the catalog server can rejoin the quorum.

If a long-term or permanent failure of a catalog server that is in the currently defined quorum occurs, you must override the quorum mechanism so that placement can continue.


Tune the heartbeat interval setting for failover detection

We can configure the amount of time between system checks for failed servers with the heartbeat interval setting. This setting applies to catalog servers only.

Configure failover varies depending on the type of environment we are using. If we are using a stand-alone environment, we can configure failover with the command line. If we are using a WAS Network Deployment environment, configure failover in the WAS Network Deployment administrative console.


What to do next

When these settings are modified to provide short failover times, there are some system-tuning issues to be aware of. First, Java is not a real-time environment. It is possible for threads to be delayed if the JVM is experiencing long garbage collection times. Threads might also be delayed if the machine hosting the JVM is heavily loaded (due to the JVM itself or other processes running on the machine). If threads are delayed, heartbeats might not be sent on time. In the worst case, they might be delayed by the required failover time. If threads are delayed, false failure detections occur. The system must be tuned and sized to ensure that false failure detections do not happen in production. Adequate load testing is the best way to ensure this. The current version of WXS supports WebSphere Real Time.


Configure container servers

The container server stores application data for the data grid. This data is generally broken into parts, which are called partitions, which are hosted across multiple container servers. Each container server in turn hosts a subset of the complete data.


Container server reconnect properties

Use Java virtual machine (JVM) properties to configure how your container server reconnects to the data grid if the container server becomes disconnected.


JVM system properties

If a container server becomes disconnected from the data grid, WXS attempts to reconnect those container servers. By setting system properties, we can control how the container reconnect functionality performs. We can set these properties when you start a container server. Some of the properties are applicable to WXS in a stand-alone environment, while others are only applicable when starting a container server for WXS for WAS. For example, when starting a container server for WebSphere WXS in a stand-alone environment, we can set these properties as an option from the command line:

startOgServer.sh server01 -objectgridFile objectgrid.xml -deploymentPolicyFile deployment.xml -Dcom.ibm.websphere.objectgrid.container.reconnect.restart=false

startXsServer.sh server01 -objectgridFile objectgrid.xml -deploymentPolicyFile deployment.xml -Dcom.ibm.websphere.objectgrid.container.reconnect.restart=false

To set the appropriate property for WXS for WAS, we can use the WebSphere Integrated Solutions Console tool. This tool is a graphical user interface that resides on the WAS environment, and is installed as an extension to the WebSphere ISC.

com.ibm.websphere.objectgrid.container.reconnect.block.reconnect.time

Defines the amount of time (in milliseconds) to block another container reconnect call. Only valid when a container server is started for the product offering: WXS for WAS.

Default: 30000 milliseconds

com.ibm.websphere.objectgrid.container.reconnect.min.successful.heartbeats

Defines the minimum number of successful heartbeats before a container can be stopped. Only valid when a container server is started for the product offering: WXS for WAS.

Default: 10

com.ibm.websphere.objectgrid.container.reconnect.restart

Defines whether container reconnect can restart the JVM. Only valid when a container server is started for WXS in a stand-alone environment.

Default: true

com.ibm.websphere.objectgrid.container.reconnect.restart.delay

Defines the time (in milliseconds) to delay after parent death before proceeding with startup on the newly created child container when restarting the JVM. Only valid when a container server is started for the product offering: WXS in a stand-alone environment.

Default: 2000 milliseconds

com.ibm.websphere.objectgrid.container.reconnect.restart.parent.timeout

Defines the time (in milliseconds) for the newly created child container to wait for parent death before timing out when restarting the JVM. Only valid when a container server is started for the product offering: WXS in a stand-alone environment.

Default: 180000 milliseconds

com.ibm.websphere.objectgrid.container.reconnect.retry.forever

Defines whether the container retries container reconnect forever. Only valid when a container server is started for the product offering: WXS for WAS.

Default: false


Configure container servers in WAS

Configure container servers in WAS by using a server properties file and deployment policy XML file that is embedded into a Java EE application module. Container servers stop and start when the application is stopped and started.

Configure a catalog service domain.

To create container servers in WAS, you must embed the WXS configuration XML files to create the container servers within the application module.

  1. Identify the application servers on which we want to deploy the Java EE application that contains the WXS container server definitions. Verify that the target application server profiles have been augmented with the WebSphere WXS profile. In a production environment, do not collocate the servers that you use for container servers with the catalog servers.

  2. Configure a server properties file and add the server properties file to the class path for each target application server node.

  3. Add the ObjectGrid descriptor XML file and deployment policy XML file to the application module.


Configure WAS applications to automatically start container servers

Container servers in a WAS environment start automatically when a module starts that has the WXS XML files included.

WAS and WXS must be installed, and you must be able to access the WAS admin console.

Java Platform, Enterprise Edition applications have complex class loader rules that greatly complicate loading classes when using a shared data grid within a Java EE server. A Java EE application is typically a single Enterprise Archive (EAR) file. The EAR file contains one or more deployed Enterprise JavaBeans (EJB) or web archive (WAR) modules.

WXS watches for each module start and looks for WXS XML files. If the catalog service detects that a module starts with the XML files, the application server is registered as a container server JVM. By registering the container servers with the catalog service, the same application can be deployed in different data grids, but used as a single data grid by the catalog service. The catalog service is not concerned with cells, grids, or dynamic grids. A single data grid can span multiple cells if required.

  1. Package your EAR file to have modules that include the WXS XML files in the META-INF folder. WXS detects the presence of the objectGrid.xml and objectGridDeployment.xml files in the META-INF folder of EJB and WEB modules when they start. If only an objectGrid.xml file is found, then the JVM is assumed to be client. Otherwise, it is assumed this JVM acts as a container for the data grid that is defined in the objectGridDeployment.xml file.

    You must use the correct names for these XML files. The file names are case-sensitive. If the files are not present, then the container does not start. We can check the systemout.log file for messages that indicate that shards are being placed. An EJB module or WAR module using WXS must have WXS XML files in its META-INF directory.

    The WXS XML files include:

    • An ObjectGrid descriptor XML file, named objectGrid.xml.

    • A deployment descriptor XML file named objectGridDeployment.xml.

    • (Optional) An entity metadata descriptor XML file, if entities are used. The entity.xml file name must match the name specified in the objectGrid.xml file.

    The run time detects these files, then contacts the catalog service to inform it that another container is available to host shards for that WXS.

    If the application has entities and we are planning to use one container server, set the minSyncReplicas value to 0 in the deployment descriptor XML file. Otherwise, you might see one of the following messages in the SystemOut.log file because placement cannot occur until another server starts to meet the minSyncReplica policy:

      CWPRJ1005E: Error resolving entity association. Entity=entity_name, association=association_name. CWOBJ3013E: The EntityMetadata repository is not available. Timeout threshold reached when trying to register the entity: entity_name.

  2. Deploy and start the application.

    The container starts automatically when the module is started. The catalog service starts to place partition primaries and replicas (shards) as soon as possible. This placement occurs immediately unless you configure the environment to delay placement.


What to do next

Applications within the same cell as the containers can connect to these data grids by using a ObjectGridManager.connect(null, null) method and then call the getObjectGrid(ccc, "object grid name") method. The connect or getObjectGrid methods might be blocked until the containers have placed the shards, but this blocking is only an issue when the data grid is starting.

ClassLoaders

Any plug-ins or objects stored in a WXS are loaded on a certain class loader. Two EJB modules in the same EAR can include these objects. The objects are the same but are loaded with different ClassLoaders. If application A stores a Person object in a map that is local to the server, application B receives a ClassCastException if it tries to read that object. This exception occurs because application B loaded the Person object on a different class loader.

One approach to resolve this problem is to have a root module contain the necessary plug-ins and objects that are stored in the WXS. Each module that uses WXS must reference that module for its classes. Another resolution is to place these shared objects in a utility JAR file that is on a common class loader shared by both modules and applications. The objects can also be placed in the WebSphere classes or lib/ext directory, however this placement complicates the deployment.

EJB modules in an EAR file typically share the same ClassLoader and are not affected by this problem. Each WAR module has its own ClassLoader and is affected by this problem.

Connecting to a data grid client-only

If the catalog.services.cluster property is defined in the cell, node or server custom properties, any module in the EAR file can call the ObjectGridManager.connect (ServerFactory.getServerProperties().getCatalogServiceBootstrap(), null, null) method to get a ClientClusterContext. The module can also call the ObjectGridManager.getObjectGrid(ccc, "grid name") method to gain a reference to the data grid. If any application objects are stored in Maps, verify that those objects are present in a common ClassLoader.

Java clients or clients outside the cell can connect with the bootstrap IIOP port of the catalog service. In WAS, the dmgr hosts the catalog service by default. The client can then obtain a ClientClusterContext and the named data grid.

Entity manager

With the entity manager, the tuples are stored in the maps instead of application objects, resulting in fewer class loader problems. Plug-ins can be a problem, however. Also note that a client override ObjectGrid descriptor XML file is always required when connecting to a data grid that has entities defined: ObjectGridManager.connect("host:port[,host:port], null, objectGridOverride) or ObjectGridManager.connect(null, objectGridOverride).


Configure WXS servers to run in the Liberty profile

Create server and catalog service definitions to run WXS in the Liberty profile.

Install the WAS Liberty profile and WXS.

  1. Create a server definition; for example: 
    <wlp install_root>/bin/server create <your server name>

  2. Find server.xml under your server definition and open it in an editor. A commented feature manager stanza already exists. We can find the server definition in the following directory: 
    <wlp install_root>/usr/servers/<your server name>

  3. Create a catalog service definition. To define a catalog service in a server, you need the WXS server feature and the server configuration file.

    1. Add the server feature to the server definition: 
      <featureManager> 
     <feature>eXtremeScale_server-1.1</feature> 
</featureManager>

    2. Add the configuration to tell the server feature that this server is a catalog service; for example: 
      <com.ibm.ws.xs.server.config isCatalog="true"/>


What to do next

After you configure WXS servers, we can start yours servers in the Liberty profile.


Configure an Enterprise Data Grid in a stand-alone environment for dynamic caching

Copy and modify these deployment and objectGrid descriptor files to configure an enterprise grid for dynamic caching. These files are used to start an enterprise data grid.

When WXS is specified as the provider for a WAS dynamic cache instance, the WXS servers are started in either a stand-alone environment or within a WAS environment. This process requires the use of deployment and objectGrid descriptor files used to configure the enterprise data grid. Dynamic caching requires a specific configuration. Therefore, several XML files are delivered with WebSphere WXS that are intended to be copied, altered (as needed), and used to start the enterprise data grid. These files can be used as-is, but are subject to change and therefore should be copied to a separate location before they are altered or used. Depending on how you have installed WXS, these files are located in either the was_root/optionalLibraries/ObjectGrid/dynacache/etc directory for installations with WAS; or for an installation in a stand-alone environment, these files are located in wxs_install_root/ObjectGrid/dynacache/etc directory.

It is highly recommended that these files be copied to some other location before they are edited or used.

Dynamic cache descriptor file (dynacache-remote-deployment.xml)

This file is the deployment descriptor file for starting a container server for dynamic caching. Although this file can be used as-is, the following following elements or attributes are occasionally changed or have significant importance:

  • mapSet name and map ref

    The name attribute in mapSet, and the defined value for map ref do not directly correspond to the dynamic cache instance name configured for WAS and are typically not changed. If, however, these values are changed, then corresponding custom properties must be added to the configuration of the dynamic cache instance.

  • numberOfPartitions

    This attribute may be changed to represent the appropriate number of partitions for the configuration.

  • maxAsyncReplicas

    This attribute may be changed. A dynamic cache typically is used in a side-cache model with a database or some other source as the system of record for the data. As a result, setting this to OPTIMISTIC or NONE will trigger near cache processing, when the eXtreme I/O (XIO) transport type is used, and the space and performance trade-offs required to make the data highly available discourage the use of replication. However, in some cases high availability is important.

  • numInitialContainers

    This attribute should be set to the number of containers that will be included in the initial startup of the enterprise data grid. Having this set correctly will aid in the placement and distribution of partitions throughout the data grid.

Dynamic cache ObjectGrid descriptor XML file (dynacache-remote-objectgrid.xml)

This file is the recommended ObjectGrid descriptor file for starting a container server for dynamic caching. It is configured to run with the eXtreme I/O transport type (XIO) using eXtreme Data Formatting (XDF). In addition, the Dependency ID and Template ID indexes are configured to use a Global Index, which improves invalidation performance. Although this file can be used as-is, the following following elements or attributes are occasionally changed or have significant importance.

  • objectGrid name and backingMap name

    The name attributes in the objectGrid and backingMap elements do not directly correspond to the dynamic cache instance name configured for WAS cache instance and typically do not need to be changed. If, however, these attributes are changed, then the corresponding custom properties must be added to the configuration of the dynamic cache instance.

  • copyMode

    Set this attribute to COPY_TO_BYTES. This value enables XDF when the eXtreme I/O (XIO) transport type is used. Changing to some other copyMode will disable XDF and will require that you uncomment the ObjectTransformer plugin bean.

  • lockStrategy

    Set this attribute to PESSIMISTIC. Setting this to OPTIMISTIC or NONE will trigger near cache processing and must be accompanied with properties from the dynamic-nearcache-objectgrid.xml.

  • backingMapPluginCollections

    This element is required. The child elements Evictor plug-in and MapIndex plug-in are both required for dynamic caching and must not be removed.

  • GlobalIndexEnabled

    Both the DEPENDENCY_ID_INDEX and TEMPLATE_INDEX contain a GlobalIndexEnabled property set to true. Setting this value to false will disable the global index feature for these indexes. It is recommended to leave these global indexes enabled unless we are running with a small number of total partitions, for example, less than 40.

  • objectTransformer

    Since this objectGrid descriptor file is intended to run in XDF, it has been commented out. To disable XDF (by changing the copyMode value) then uncomment this plug-in.

Dynamic near cache ObjectGrid descriptor file (dynacache-nearCache-ObjectGrid.xml)

This file is the recommended ObjectGrid descriptor file for starting grid container servers for dynamic caching when a near-cache is desired. It is configured to run with the eXtreme I/O transport type (XIO) using eXtreme Data Formatting (XDF). In addition, the Dependency ID and Template indexes are configured to use a Global Index, which improves invalidation performance. The dynamic caching near cache capability requires the use of the eXtreme I/O (XIO) transport type.

Although this file can be used as-is, the following elements or attributes are occasionally changed or have significant importance:

  • objectGrid name and backingMap name

    These values in this file do not directly correspond to the dynamic cache instance name configured for the WAS's cache instance and typically do not need to be changed. If, however, these values are changed, then corresponding custom properties must be added to the configuration of the dynamic cache instance.

  • lockStrategy

    This property must be set to OPTIMISTIC or NONE to enable a near cache. No other lockingStrategy supports a near cache.

  • nearCacheInvalidationEnabled

    This property must be set to true to enable a dynamic caching near cache. This feature uses pub-sub to flow invalidations from the far cache to the near cache instances, keeping them in-sync.

  • nearCacheLastAccessTTLSyncEnabled

    This property must be set to true to enable a dynamic caching near cache. This feature uses pub-sub to flow TTL evictions from the far cache to the near cache instances, keeping them in -sync.

  • copyMode

    This backingMap property is set to COPY_TO_BYTES. This value enables XDF when the eXtreme I/O (XIO) transport type is used. Changing to some other copyMode will disable XDF and will require that the ObjectTransformer plugin bean be uncommented.

  • backingMapPluginCollections

    The MapIndexPlugins and Evictor are mandatory items for dynamic caching and must not be removed.

  • GlobalIndexEnabled

    Both the DEPENDENCY_ID_INDEX and TEMPLATE_INDEX contain a GlobalIndexEnabled property set to true. Setting this value to false will disable the global indexfeature for these indexes. It is recommended to leave these global indexes enabled unless we are running with a small number of total partitions (< 40).

  • ObjectTransformer

    Since this file is intended to run in XDF this plugin as been commented out. If XDF is to be disabled (via changing the copyMode) then this plugin must be uncommented.

Dynamic legacy ObjectGrid descriptor file (dynacache-legacy85-ObjectGrid.xml)

This file is the recommended ObjectGrid descriptor file for starting a container server for dynamic caching when you have chosen a near-cache. Although this file can be used as-is, the following elements or attributes are occasionally changed or have significant importance:

  • objectGrid name and backingMap name

    These values in this file do not directly correspond to the dynamic cache instance name configured for the WAS's cache instance and typically do not need to be changed. If, however, these values are changed, then corresponding custom properties must be added to the configuration of the dynamic cache instance.

  • copyMode

    This backingMap property is set to COPY_ON_READ_AND_COMMIT. This value should not be changed.

  • lockStrategy

    This backingMap property is set to PESSIMISTIC. This value should not be changed.

  • backingMapPluginCollections

    The MapIndexPlugins, Evictor, and Object Transformer are mandatory items for dynamic caching and must not be removed.



Configure multiple data center topologies

With the multi-master asynchronous replication, you link a set of catalog service domains. The connected catalog service domains are then synchronized using replication over the links. We can define the links using properties files, at run time with JMX programs, or with command-line utilities. The set of current links for a domain is stored in the catalog service. We can add and remove links without restarting the catalog service domain that hosts the data grid.


Examples

Suppose to configure a two-domain setup involving catalog service domains A and B.

Here is the server properties file for the catalog server in domain A: 

domainName=A
foreignDomains=B
B.endPoints=hostB1:2809, hostB2:2809

Here is the server properties file for the catalog server in domain B. Notice the similarity between the two property files. 

domainName=B
foreignDomains=A
A.endPoints=hostA1:2809,hostA2:2809

After the two domains are started, then any data grids with the following characteristics are replicated between the domains.

The replication policy of a catalog service domain is ignored.

The preceding example shows how to configure each domain to have a link to the other domain, but it is necessary only to define a link in one direction. This fact is especially useful in hub and spoke topologies, allowing a much simpler configuration. The hub property file does not require updates as spokes are added, and each spoke file needs only to include hub information. Similarly, a ring topology requires each domain to have only a link to the previous and next domain in the ring.

The hub and four spokes (domains A, B, C, and D) has server property files like the following examples. 

domainName=Hub

Spoke A has the following server properties: 

domainName=A
foreignDomains=Hub Hub.endPoints=hostH1:2809, hostH2:2809

Spoke B has the following server properties: 

domainName=B
foreignDomains=Hub Hub.endPoints=hostH1:2809, hostH2:2809

Spoke C has the following server properties: 

domainName=C
foreignDomains=Hub Hub.endPoints=hostH1:2809, hostH2:2809

Spoke D has the following properties: 

domainName=D
foreignDomains=Hub Hub.endPoints=hostH1:2809, hostH2:2809


What to do next

Improve response time and data availability with WXS multi-master capability



Configure ports

You must open ports to communicate among servers and with remote servers.


Configure ports in stand-alone mode

We can configure the necessary ports for servers and clients in an eXtreme scale deployment by using command-line parameters, property files or programmatically. Most examples included in the following sections describe command-line parameters to the startOgServer or startXsServer script. Equivalent configuration options can also be set in properties files, using the embedded server API or the client API.

  1. Start catalog service endpoints.

    WXS uses IIOP to communicate between JVMs. The catalog service JVMs are the only processes that require the explicit configuration of ports for the IIOP services and group services ports. Other processes dynamically allocate ports.

    1. Specify client and peer ports. The client port and peer port are used for communication between catalog services in a catalog service domain. To specify the client port and peer port...

      -catalogServiceEndPoints <serverName:hostName:clientPort:peerPort>

      Specifies a list of catalog servers to link together into a catalog service domain. Each attribute is defined as follows:

      serverName

      Name of the catalog server.

      hostName

      Host name for the computer where the server is launched.

      clientPort

      Port used for peer catalog service communication.

      peerPort

      This value is the same as the haManagerPort. Port used for peer catalog service communication.
      The following example starts the cs1 catalog server, which is in the same catalog service domain as the cs2 and cs3 servers: 
      startOgServer.bat|sh cs1 -catalogServiceEndPoints 
cs1:MyServer1.company.com:6601:6602,cs2:MyServer2.company.com:6601:6602,cs3:MyServer3.company.com:6601:6602
      If you start additional catalog servers, they must include the same servers in the -catalogServiceEndPoints argument. The order of the list can be different, but the servers contained in the list must be the same for each catalog server. Do not put any spaces in the list.
      We can also set the catalog service end points with the catalogClusterEndPoints server property .

    2. Set the listener host and port. The listener port is used for communication between catalog services in a catalog service domain, and for communication between catalog services and container servers and clients. To specify the listener port and listener host...

      -listenerHost <host name>

      Host name to which the ORB or eXtremeIO (XIO) transport binds for communication. The value must be a fully-qualified domain name or IP address. If the configuration involves multiple network cards, set the listener host and port to let the transport mechanism in the JVM know the IP address for which to bind. If you do not specify which IP address to use, symptoms such as connection timeouts, unusual API failures, and clients that seem to hang can occur. Default: localhost

      -listenerPort <port>

      Port number to which the ORB or eXtremeIO (XIO) transport binds. This setting configures containers and clients to communicate with the catalog service. In WAS, the listenerPort is inherited by the BOOTSTRAP_ADDRESS port (when we are using the ORB transport) or the XIO_address port (when we are using XIO transport) port configuration. This property applies to both the container server and the catalog service. Default: 2809

      We can also set the listener port and listener host with the listenerHost and listenerPort server properties .

    3. Optional: Set the JMX service port.

      The JMX service port is used for communication from JMX clients. To specify the JMX service port...

      -JMXServicePort <port>

      Port number on which the MBean server listens communication with Java Management Extensions (JMX). The JMXServicePort property specifies the non-SSL port for JMX. You must use a different port number for each JVM in the configuration. To use JMX/RMI, explicitly specify the JMXServicePort and port number, even to use the default port value. This property applies to both the container server and the catalog service. (Required for stand-alone environments only.)

      Default: 1099 for catalog servers

      We can also set the JMX service port with the JMXServicePort server property .

    4. Optional: Set the JMX connector port.

      The JMX connector port is used for communication from JMX clients. To specify the JMX connector port...

      -JMXConnectorPort <port>

      Defines the SSL port to which the JMX service binds.

      We can also set the JMX connector port with the JMXConnectorPort server property .

    5. Set the Secure Socket Layer (SSL) port.

      When security is enabled, an SSL port is also required. To specify the SSL port... 

      -jvmArgs -Dcom.ibm.CSI.SSLPort=<sslPort>

    Example using the command line. Start the first catalog server on hostA. An example of the command follows: 

    ./startOgServer.sh cs1 -listenerHost hostA -listenerPort 2809
-catalogServiceEndPoints cs1:hostA:6601:6611,cs2:hostB:6601:6611
    ./startXsServer.sh cs1 -listenerHost hostA -listenerPort 2809
-catalogServiceEndPoints cs1:hostA:6601:6611,cs2:hostB:6601:6611

    Start the second catalog server on hostB. An example of the command follows: 

    ./startOgServer.sh cs2 -listenerHost hostB -listenerPort 2809
-catalogServiceEndPoints cs1:hostA:6601:6611,cs2:hostB:6601:6611
    ./startXsServer.sh cs2 -listenerHost hostB -listenerPort 2809
-catalogServiceEndPoints cs1:hostA:6601:6611,cs2:hostB:6601:6611

  2. Start container server endpoints.

    The following command starts a container JVM to use with the example catalog service: 

    ./startOgServer.sh c0 -catalogServiceEndPoints hostA:2809,hostB:2809 
    ./startXsServer.sh c0 -catalogServiceEndPoints hostA:2809,hostB:2809

    The container server JVMs use two ports. The HA manager port is used for internal communication between peer container servers and catalog servers. The listener port is used for IIOP communication between peer container servers, catalog servers, and clients. The listener host is used to bind the ORB to a specific network adapter. If you do not specify, both ports are dynamically selected. However, if we want to explicitly configure ports, such as in a firewall environment, we can use a command-line options to specify the ORB port.

    1. Specify the listener host and port. To specify the listener port and listener host...

      -listenerHost <host name>

      Host name to which the ORB or eXtremeIO (XIO) transport binds for communication. The value must be a fully-qualified domain name or IP address. If the configuration involves multiple network cards, set the listener host and port to let the transport mechanism in the JVM know the IP address for which to bind. If you do not specify which IP address to use, symptoms such as connection timeouts, unusual API failures, and clients that seem to hang can occur. Default: localhost

      -listenerPort <port>

      Port number to which the ORB or eXtremeIO (XIO) transport binds. This setting configures containers and clients to communicate with the catalog service. In WAS, the listenerPort is inherited by the BOOTSTRAP_ADDRESS port (when we are using the ORB transport) or the XIO_address port (when we are using XIO transport) port configuration. This property applies to both the container server and the catalog service. Default: 2809

      We can also set listener port and listener host with the listenerHost and listenerPort server properties .

    2. Specify the HA manager port. To specify the HA manager port...

      -haManagerPort <port>

      Port number the high availability manager uses. If this property is not set, a free port is chosen. This property is ignored in WAS environments.

      We can also set the HA manager port with the HAManagerPort server property .

    3. Optional: Specify the SSL port.

      When security is enabled, a Secure Socket Layer (SSL) port is also required. To specify the SSL port... 

      -jvmArgs -Dcom.ibm.CSI.SSLPort=<sslPort>

    4. Optional: Specify the JMX service port.

      -JMXServicePort <port>

      Port number on which the MBean server listens communication with JMX. The JMXServicePort property specifies the non-SSL port for JMX. You must use a different port number for each JVM in the configuration. To use JMX/RMI, explicitly specify the JMXServicePort and port number, even to use the default port value. This property applies to both the container server and the catalog service. (Required for stand-alone environments only.)

      Default: 1099 for catalog servers

      We can also set the JMX service port with the JMXServicePort server property .

    5. Optional: Set the JMX connector port.

      The JMX connector port is used for communication from JMX clients. To specify the JMX connector port:

      -JMXConnectorPort <port>

      Defines the SSL port to which the JMX service binds.

      We can also set the JMX connector port with the JMXConnectorPort server property .

  3. Start client endpoints.

    Clients must know the catalog service listener end points only. Clients retrieve end points for container server JVMs, which are the JVMs that hold the data, automatically from the catalog service. To connect to the catalog service in the previous example, the client must pass the following list of host:port pairs to the connect API: 

    hostA:2809,hostB:2809

    The client can also receive callbacks from container servers when using the DataGrid API. These callbacks communicate using IIOP with the ORB listener port. To specify the port and network adapter to receive callbacks, set the listenerHost and listenerPort properties in the client properties file.

    When security is enabled, a Secure Socket Layer (SSL) port is also required. To specify the SSL port, use the following system property when starting the client process: 

    -jvmArgs -Dcom.ibm.CSI.SSLPort=<sslPort>


Configure ports in a WAS environment

WXS catalog services, container servers and clients, when running in WAS processes, utilize ports and services already defined for the process.

The following sections explain details relating to using ports in the deployment.

  1. Catalog service endpoints

    WXS catalog services run in any WAS process and are configured using the administrative console or using administrative tasks. All ports are inherited by the process except for the client port, which is explicitly configured.

  2. Container server endpoints

    WXS container servers are hosted within Java EE modules. The container servers use the ports defined for the application server process. For details on which ports are used by the container service.

  3. Client endpoints

    WXS clients are hosted within Java EE web or EJB modules.

    Clients programmatically connect to the catalog service domain using the ObjectGridManager.connect() API. When connecting to a catalog service domain hosted within the same cell, the client connection will automatically find the default catalog service domain using the following API call on the ObjectGridManager: 

    connect(securityProps, overRideObjectGridXML)

    If the default catalog service domain is hosted remotely (external to the cell), the catalog service endpoints must be specified using the following method on the ObjectGridManager API: 

    connect(catalogServerEndpoints, securityProps, overRideObjectGridXml)

    If the default catalog service domain is defined in the cell, then the CatalogServerProperties API can be used to retrieve the catalog server addresses. The XSDomainManagement administrative task can also be used to retrieve any configured catalog service domain endpoints.


Servers with multiple network cards

We can run WXS processes on a server that has more than one network card.

If a server or client is running on a server that contains more than one network card, then specify the network port and host name in your WXS configuration to bind to a specified card. If this configuration is not specified, then the WXS runtime automatically chooses a network post and host name, which may result in connection failures or slower performance.

When we are setting the host name for WXS processes that are embedded in WAS, you might need to consider the WAS or other stack products in the configuration. For an example, see Technote: Configuring the node agent on one NIC and its application server on another NIC, which is on a different subnet, can lead to ORB errors .

For catalog or container servers, set the listener host and listener port in one of the following ways:

For clients, we cannot use the command line, and must use client properties .

Configuring ports

Configuring ports in stand-alone mode

Configuring ports in a WAS environment



Configure transports

Transports enable the exchange of objects and data between different server processes in the configuration.

Two options exist for transports within WXS: the ORB or IBM eXtremeIO (XIO).

ORB

When you use the ORB, cache entries are stored on the Java heap. Generally, the relative response time is slower than XIO due to the periodic garbage collection that occurs in this environment.

Deprecated: The ORB is deprecated. If you were not using the ORB in a previous release, use IBM eXtremeIO (XIO) for your transport mechanism. If we are using the ORB, consider migrating the configuration to use XIO.

XIO

When you use XIO, cache entries are stored in native memory, or IBM eXtremeMemory. Because cache entries are stored in native memory, relative response time is faster than the ORB.


Displaying the transport type of the catalog service domain

We can display the transport type that is currently being used for the catalog service domain.

We can display the transport types that are being used in a stand-alone catalog service domain or a catalog service domain running in WAS.


Configure IBM eXtremeIO (XIO)

IBM eXtremeIO (XIO) is a transport mechanism that replaces the ORB.

We can configure XIO for all the container servers in the catalog service domain by enabling XIO in the catalog servers. The container servers discover the transport type of the catalog server and use that transport type.

How you enable XIO depends on the type of servers we are using:

Use command-line arguments and server properties to configure XIO behavior:


Results

The servers that you configured use the XIO transport.


What to do next

We can also use IBM eXtremeMemory to help you avoid garbage collection pauses, leading to more constant performance and predicable response times.


Configure Object Request Brokers

(Deprecated) The ORB is used by WXS to communicate over a TCP stack. Use the orb.properties file to pass the properties used by the ORB to modify the transport behavior of the data grid. No action is required to use the ORB provided by WebSphere WXS or WAS for your WebSphere WXS servers.

Deprecated: The ORB is deprecated. If you were not using the ORB in a previous release, use IBM eXtremeIO (XIO) for your transport mechanism. If we are using the ORB, consider migrating the configuration to use XIO.


Configure the Object Request Broker in a WAS environment

(Deprecated) Use WXS with applications that use the ORB directly in WAS or WAS Network Deployment environments.

Deprecated: The ORB is deprecated. If you were not using the ORB in a previous release, use IBM eXtremeIO (XIO) for your transport mechanism. If we are using the ORB, consider migrating the configuration to use XIO.

  1. Name the application servers appropriately.

    We cannot have servers in a WAS environment with the same name when the servers are using the ORB to communicate with each other. We can resolve this restriction by specifying the system property -Dcom.ibm.websphere.orb.uniqueServerName=true for the processes that have the same name. For example, when servers with the name

    server1 on each node are used as a catalog service domain, or where multiple node agents are used to form a catalog service domain.

  2. Tune the ORB properties within the WAS configuration.

    Depending on the property, you might change a setting in the administrative console or in the was_rootproperties/orb.properties file.

  3. If we are using multiple network interface cards, set the ORB_LISTENER_ADDRESS value in the ports panel in the WAS admin console. Repeat this step for each application server in the configuration.

    1. For an application server, click...

        Servers > Application servers > server_name

      Under Communications, click Ports. The Ports panel is displayed for the specified server.

    2. Click Details and edit the ORB_LISTENER_ADDRESS value.

    3. Enter the IP address in the Host field. This value must be a private address for a multiple network interface environment. DNS host names are not supported for the ORB_LISTENER_ADDRESS value.

    4. Enter the port number in the Port field. The port number specifies the port for which the service is configured to accept client requests. The port value is used with the host name.


What to do next

Use the wxsLogAnalyzer tool to verify the ORB settings across your environment.


Configure the Object Request Broker with stand-alone WXS processes

(Deprecated) Use WXS with applications that use the ORB directly in environments that do not contain WAS or WAS Network Deployment.

Deprecated: The ORB is deprecated. If you were not using the ORB in a previous release, use IBM eXtremeIO (XIO) for your transport mechanism. If we are using the ORB, consider migrating the configuration to use XIO. If you use the ORB within the same process as WXS when we are running applications, or other components and frameworks, that are not included with WXS, you might need to complete additional tasks to ensure that WXS runs correctly in your environment.

Add the ObjectGridInitializer property to the orb.properties file to initialize the use of the ORB in your environment. Use the ORB to enable communication between WXS processes and other processes that are in your environment.

  1. The stand-alone installation does not include an orb.properties file. You must put an orb.properties file is in the java/jre/lib directory.

  2. In the orb.properties file, type the following line, and save your changes: 
    org.omg.PortableInterceptor.ORBInitializerClass.com.ibm.ws.objectgrid.corba.ObjectGridInitializer


Results

WXS correctly initializes the ORB and coexists with other applications for which the ORB is enabled.


What to do next

Use the xsLogAnalyzer tool to verify the ORB settings across your environment.


Configure a custom Object Request Broker

(Deprecated) WXS uses the ORB to enable communication among processes. No action is required to use the ORB provided by WebSphere WXS or WAS for your WebSphere WXS servers. Little effort is required to use the same ORBs for your WebSphere WXS clients. If instead use a custom ORB, the ORB supplied with the IBM SDK is a good choice, although configure the ORB. ORBs from other vendors can be used, also with configuration.

Deprecated: The ORB is deprecated. If you were not using the ORB in a previous release, use IBM eXtremeIO (XIO) for your transport mechanism. If we are using the ORB, consider migrating the configuration to use XIO.

Determine if we are using the ORB provided with WXS or WAS, the ORB provided with the IBM SDK, or an external vendor ORB.

We can make separate decisions for the WXS server processes and WebSphere WXS client processes. While WXS supports developer kits from most vendors, it is recommended you use the ORB that is supplied with WXS for both your server and client processes. WXS does not support the ORB that is supplied with the Oracle Java Development Kit (JDK).

Become familiar with the configuration that is required to use the ORB of your choice.

Case 1: Default ORB

  • For your WXS server processes, no configuration is required to use the ORB provided with WebSphere WXS or WAS.

  • For your WXS client processes, minimal classpath configuration is required to use the ORB provided with WebSphere WXS or WAS.

Case 2: Custom ORB (IBM)

To configure your WXS client processes to use the ORB provided with the IBM SDK, see the instructions later in this topic. Use the IBM ORB whether we are using the IBM SDK or another development kit. Use IBM SDK v6 or later.

Case 3: Custom ORB (supplied by an external vendor)

Use a vendor ORB for your WXS client processes is the least tested option. Any problems that you encounter when you use ORBs from independent software vendors must be reproducible with the IBM ORB and compatible JRE before you contact support.

The ORB supplied with the Oracle Java Development Kit (JDK) is not supported.



Configure IBM eXtremeMemory

By configuring eXtremeMemory, we can store objects in native memory instead of on the Java heap. Configuring eXtremeMemory enables the IBM eXtremeIO transport mechanism.

When we are using eXtremeMemory, eXtremeIO is used for communication between container servers. Objects are serialized into bytes on the container server. To enable eXtremeMemory, you set the required server properties on all of the container servers in the data grid and restart the servers.

eXtremeMemory is not used on catalog servers. If you have a catalog server and a container server that are collocated, the container servers use eXtremeMemory, but the catalog server does not.

  1. Configure the native libraries by setting the appropriate environment variables. Add the /path/to/ObjectGrid/native directory to the native library path.

    We can set the environment variable with one of the following ways:

    • Set the LD_LIBRARY_PATH environment variable before calling the Java program: 
      LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/path/to/ObjectGrid/native export LD_LIBRARY_PATH

    • Set the java.library.path Java system property to the location where the native libraries are located: 
       java -Djava.library.path=/path/to/ObjectGrid/native <other args>

  2. Update the server properties file for each container server in the configuration to enable eXtremeMemory. To enable eXtremeMemory, set the enableXM property. If you do not want the default value of 25% of the entire system to be used for eXtremeMemory, also set the maxXMSize property. After you decide on the properties to set, we can set the values in the server properties file or programmatically with the ServerProperties interface.

    Required properties

    enableXM

    When set to true, enables IBM eXtremeMemory on the server and configures the server to use IBM eXtremeIO for synchronous and asynchronous replication. Cache entries are stored in native memory instead of on the Java heap.

    All container servers in the data grid must use the same value for the enableXM property.

    Default: false

    Suggested properties

    maxXMSize

    Set the maximum amount of memory, in megabytes, used by the server for eXtremeMemory storage.

    Default: 25% of the total memory on the system

  3. Optional: Tune the JVMs for eXtremeMemory.

  4. Enable the container servers to start using eXtremeMemory. Use one of the following methods to pick up the new property values:

    • Place a well-named objectGridServer.properties file in the class path.

    • Set the properties from the application with the ServerProperties interface.

    • Start an OSGi server bundle.

    • Restart the container servers.


What to do next

We can also set properties to configure eXtremeIO.



Configure Java clients

We can configure WXS to run in a stand-alone environment, or in an environment with WAS. For a WebSphere WXS deployment to pick up configuration changes on the server grid side, restart processes to make these changes take effect rather than being applied dynamically. However, on the client side, although we cannot alter the configuration settings for an existing client instance, we can create a new client instance with the settings you require by using an XML file or doing so programmatically. When creating a client, we can override the default settings that come from the current server configuration.

We can configure a WXS client (Java client only) in the following ways, each of which can be done with a client override XML file or programmatically:


Java client overrides

We can configure a WXS client based on your requirements by overriding the server settings. We can override several plug-ins and attributes.

To override settings on a client, we can use either XML or programmatic configuration.

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


Configure Java clients with XML configuration

Use an ObjectGrid configuration XML file to override settings on the client side.

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

  1. Create an ObjectGrid configuration XML file for the client that is similar in structure to the file for the container server.

    Assume that the following XML file was paired with a deployment policy XML file, and these files were used to start a container 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" nearCacheEnabled="true"
                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>
            <bean id="MapIndexPlugin"
                className="com.company.MyMapIndexPlugin" />
        </backingMapPluginCollection>
    </backingMapPluginCollections>
</objectGridConfig>

    On a container 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.

    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" nearCacheEnabled="true"
                pluginCollectionRef="customerPlugins" />
            <backingMap name="Item" />
            <backingMap name="OrderLine" nearCacheEnabled="true"
                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>
            <bean id="MapIndexPlugin"
                className="com.company.MyMapIndexPlugin" />
        </backingMapPluginCollection>
    </backingMapPluginCollections>
</objectGridConfig>

    The XML file defines the following overrides:

    • The TransactionCallback bean 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 enables a near cache for the Customer backingMap, retains its Evictor plug-in, and removes the MapEventListener plug-in.

    • The timeToLive attribute of the OrderLine backingMap changed.

    • Although a different lockStrategy attribute is specified, there is no effect because the lockStrategy attribute is not supported for a client override.

  2. Create the client with the XML file.

    To create the CompanyGrid client with the companyGridClientSide.xml file, pass the ObjectGrid XML file as a URL to one of the connect methods on the ObjectGridManager interface: 

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


Configure Java clients programmatically

We can override client-side settings programmatically. Create an ObjectGridConfiguration object that is similar in structure to the server-side ObjectGrid instance.

The following code example creates the same overrides that are described in Configuring Java clients with XML configuration .

The following code creates a client-side ObjectGrid instance. 

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(catalogServerEndpoints, 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 near cache

Clients can optionally have a local, in-line cache when WXS is used in a distributed topology. This optional cache is called a near cache, an independent ObjectGrid on each client, serving as a cache for the remote, server-side cache. The near cache is enabled by default when locking is disabled, or is configured as optimistic, and cannot be used when configured as pessimistic.

A near cache is fast because it provides local in-memory access to a subset of the entire cached data set that is stored remotely.

We can edit the necessary settings in the ObjectGrid XML file for your container server. The settings in this file apply to all clients, unless you override the settings. We can override the nearCacheEnabled setting for the near cache with either XML or programmatic configuration.

  1. Near cache is enabled if we are using default settings.

    To enable the near cache, set the lockStrategy attribute in the ObjectGrid descriptor XML file for the container servers to NONE or OPTIMISTIC. The default value is OPTIMISTIC. Clients do not maintain a near cache when the locking setting is configured as

    PESSIMISTIC.

  2. To enable or disable the near cache, set the nearCacheEnabled attribute in the ObjectGrid descriptor XML file.

    nearCacheEnabled

    Set true to enable the client local cache. To use a near cache, the lockStrategy attribute must be set to NONE or OPTIMISTIC.

    Default: true (Optional)

    In previous releases, you enabled and disabled the near cache with the numberOfBuckets attribute in the ObjectGrid descriptor XML file. If this value is set to 0, the near cache is disabled. This setting overrides the nearCacheEnabled attribute. If you do not set the numberOfBuckets or set it to a non-zero value, then the nearCacheEnabled attribute determines whether the near cache is enabled.

  3. Restart the container servers and clients.


Results

To check whether a near cache is enabled, run the BackingMap.isNearCacheEnabled() method in your client. We can also look for the CWOBJ1128I message in the log files on the client to see if the near cache is enabled.


Example

The following example ObjectGrid descriptor XML file configures an optimistic locking strategy and enables the near cache: 

<?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="Grid">
   <backingMap name="TestMap1" nearCacheEnabled="true" lockStrategy="OPTIMISTIC" copyMode="COPY_TO_BYTES"/>
  </objectGrid>
 </objectGrids>
</objectGridConfig>


Configure near cache for dynamic cache

We can enable near cache in your dynamic cache provider so that an independent ObjectGrid exists on your dynamic cache provider, serving as a fast cache for the remote, server-side cache.

Modify the backingMap of the objectgrid.xml file to enable near cache in dynamic cache.

  1. Add the following properties to the backingMap of the objectgrid.xml to enable near cache on your dynamic cache provider: A near cache for a dynamic cache must have the nearCacheEnabled, nearCacheInvalidationEnabled, and nearCacheLastAccessTTLSyncEnabled properties that are set to true; for example: 
    <backingMap name="IBM_DC_PARTITIONED_.*" template="true" readOnly="false.  
< pluginCollectionRef=.all. preloadMode=.false. nearCacheEnabled=.true. 
nearCacheInvalidationEnabled="true" nearCacheLastAccessTTLSyncEnabled= .true. 
lockStrategy=.OPTIMISTIC" 
copyMode="COPY_ON_READ_AND_COMMIT" ttlEvictorType="NONE" nullValuesSupported="false" />
    Each of the attributes on the backingMap element have the following definitions:

    nearCacheEnabled

    Set true to enable the client local cache. To use a near cache, the lockStrategy attribute must be set to NONE or OPTIMISTIC.

    Default: true (Optional)

    nearCacheInvalidationEnabled

    Set true to enable the removal of stale data from the near cache as quickly as possible. Any update, deletion, or invalidation operation against the data grid triggers an asynchronous invalidation in the near cache. Because the invalidation is asynchronous, client applications might access stale data for a short time period after an update has occurred before the stale value is removed from the near cache. To use near cache invalidation, the lockStrategy attribute must be set to NONE or OPTIMISTIC.

    Default: false (Optional)

    nearCacheLastAccessTTLSyncEnabled

    Set true to enable TTL information to be synchronized with the remote data grid. The LAST_ACCESS_TIME TTL evictor type must be enabled when you enable this property.

    Default: false (Optional)

  2. Optional: Configure the optimistic locking strategy for maps that support applications, which use dynamic cache.

    The default lock strategy is OPTIMISTIC. Use optimistic locking when data is changed infrequently. Locks are only held for a short duration while data is being read from the cache and copied to the transaction. When the transaction cache is synchronized with the main cache, any cache objects that have been updated are checked against the original version. If the check fails, then the transaction is rolled back and an OptimisticCollisionException exception results.

    • Programmatically using the setLockStrategy method: 
      import com.ibm.websphere.objectgrid.BackingMap;
import com.ibm.websphere.objectgrid.LockStrategy;
import com.ibm.websphere.objectgrid.ObjectGrid;
import com.ibm.websphere.objectgrid.ObjectGridManagerFactory;
...
ObjectGrid og = 
 ObjectGridManagerFactory.getObjectGridManager().createObjectGrid("test");
BackingMap bm = og.defineMap("optimisticMap");
bm.setLockStrategy( LockStrategy.OPTIMISTIC );

    • Use the lockStrategy attribute in the ObjectGrid descriptor XML file .: 
      <?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="test">
            <backingMap name="optimisticMap"
                lockStrategy="OPTIMISTIC"/>
        </objectGrid>
    </objectGrids>
</objectGridConfig>


Configure near-cache invalidation

We can configure near-cache invalidation to remove stale data from the near cache as quickly as possible. When an update, deletion, or invalidation operation is run against the remote data grid, an asynchronous invalidation operation gets triggered in the near cache. This mechanism works more quickly than the other option of using TTL eviction in the near cache.

Enable near-cache invalidation provides a more accurate set of data from the remote data grid because the near cache is updated when the remote data changes.

We can edit the necessary settings in the ObjectGrid XML file for your container server. The settings in this file apply to all clients, unless you override the settings. If you enable near-cache invalidation on the server, we can disable the near-cache invalidation on the client by overriding the nearCacheInvalidationEnabled attribute for the near cache with either XML or programmatic configuration. However, we cannot override the attribute to enable the near-cache invalidation when near-cache invalidation is disabled on the server.

  1. Set the nearCacheInvalidationEnabled attribute in the ObjectGrid descriptor XML file. Set this attribute on the backingMap element.

    nearCacheInvalidationEnabled

    Set true to enable the removal of stale data from the near cache as quickly as possible. Any update, deletion, or invalidation operation against the data grid triggers an asynchronous invalidation in the near cache. Because the invalidation is asynchronous, client applications might access stale data for a short time period after an update has occurred before the stale value is removed from the near cache. To use near cache invalidation, the lockStrategy attribute must be set to NONE or OPTIMISTIC.

    Default: false (Optional)

  2. Restart the container servers and clients.


Configure JMS-based client synchronization

Use JMS-based client synchronization to keep data from the client near cache synchronized with other severs and clients.


Near cache

Use the built-in Java Message Service (JMS)-based com.ibm.websphere.objectgrid.plugins.builtins.JMSObjectGridEventListener class to enable the client invalidation mechanism within a distributed WXS environment.

The client invalidation mechanism is the solution for the issue of stale data in client near cache in distributed WXS environment. This mechanism ensures that the client near cache is synchronized with servers or other clients. However, even with this JMS-based client invalidation mechanism, the client near cache does not immediately update. A delay occurs when the run time publishes updates.

Two models are available for the client invalidation mechanism in a distributed WXS environment:

If you do not want to use JMS to synchronize your near cache, we can also use near cache invalidation.


Client-server model

In a client-server model, the servers are in a JMS publisher role and the client is in JMS receiver role. 

client-server model XML example
<?xml version="1.0" encoding="UTF-8"?>
<?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="AgentObjectGrid">
      <bean id="ObjectGridEventListener"
        className="com.ibm.websphere.objectgrid.plugins.builtins.JMSObjectGridEventListener">
        <property name="invalidationModel" type="java.lang.String" value="CLIENT_SERVER_MODEL" description="" />
        <property name="invalidationStrategy" type="java.lang.String" value="PUSH" description="" />
        <property name="mapsToPublish" type="java.lang.String" value="agent;profile;pessimisticMap" description="" />
        <property name="jms_topicConnectionFactoryJndiName" type="java.lang.String" value="defaultTCF" description="" />
        <property name="jms_topicJndiName" type="java.lang.String" value="defaultTopic" description="" />
        <property name="jms_topicName" type="java.lang.String" value="defaultTopic" description="" />
        <property name="jms_userid" type="java.lang.String" value="" description="" />
        <property name="jms_password" type="java.lang.String" value="" description="" />
        <property name="jndi_properties" type="java.lang.String"
          value="java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory;
     java.naming.provider.url= 
    tcp://localhost:61616;connectionFactoryNames=defaultTCF;topic.defaultTopic=defaultTopic"
          description="jndi properties" />
      </bean>

      <backingMap name="agent" readOnly="false" pluginCollectionRef="agent" preloadMode="false"
        lockStrategy="OPTIMISTIC" copyMode="COPY_ON_READ_AND_COMMIT" ttlEvictorType="LAST_ACCESS_TIME"
        timeToLive="28800" />
      <backingMap name="profile" readOnly="false" pluginCollectionRef="profile" preloadMode="false"
        lockStrategy="OPTIMISTIC" copyMode="COPY_ON_READ_AND_COMMIT" ttlEvictorType="LAST_ACCESS_TIME"
        timeToLive="2700" />
      <backingMap name="pessimisticMap" readOnly="false" pluginCollectionRef="pessimisticMap" preloadMode="false"
        lockStrategy="PESSIMISTIC" copyMode="COPY_ON_READ_AND_COMMIT" ttlEvictorType="LAST_ACCESS_TIME"
        timeToLive="2700" />
      <backingMap name="excludedMap1" readOnly="false" pluginCollectionRef="excludedMap1" preloadMode="false"
        lockStrategy="OPTIMISTIC" copyMode="COPY_ON_READ_AND_COMMIT" ttlEvictorType="LAST_ACCESS_TIME"
        timeToLive="2700" />
      <backingMap name="excludedMap2" readOnly="false" pluginCollectionRef="excludedMap2" preloadMode="false"
        lockStrategy="OPTIMISTIC" copyMode="COPY_ON_READ_AND_COMMIT" ttlEvictorType="LAST_ACCESS_TIME"
        timeToLive="2700" />
    </objectGrid>
  </objectGrids>

  <backingMapPluginCollections>
    <backingMapPluginCollection id="agent">
      <bean id="ObjectTransformer" className="com.ibm.ws.objectgrid.test.scenario.AgentObjectTransformer" />
    </backingMapPluginCollection>
    <backingMapPluginCollection id="profile">
      <bean id="ObjectTransformer" className="com.ibm.ws.objectgrid.test.scenario.ProfileObjectTransformer" />
      <bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor">
        <property name="maxSize" type="int" value="2000" description="set max size for LRU evictor" />
        <property name="sleepTime" type="int" value="15" description="evictor thread sleep time" />
        <property name="numberOfLRUQueues" type="int" value="50" description="set number of LRU queues" />
      </bean>
    </backingMapPluginCollection>

    <backingMapPluginCollection id="pessimisticMap" />
    <backingMapPluginCollection />
    <backingMapPluginCollection />
  </backingMapPluginCollections>

</objectGridConfig>


Client as dual roles model

In client as dual roles model, each client has both JMS publisher and receiver roles. The client publishes every committed transactional change to a designated JMS destination and receives all the committed transactional changes from other clients. The server has nothing to do with JMS in this model. 

dual-roles model XML example
<?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="AgentObjectGrid">
      <bean id="ObjectGridEventListener"
        className="com.ibm.websphere.objectgrid.plugins.builtins.JMSObjectGridEventListener">
        <property name="invalidationModel" type="java.lang.String" value="CLIENT_AS_DUAL_ROLES_MODEL" description="" />
        <property name="invalidationStrategy" type="java.lang.String" value="PUSH" description="" />
        <property name="mapsToPublish" type="java.lang.String" value="agent;profile;pessimisticMap" description="" />
        <property name="jms_topicConnectionFactoryJndiName" type="java.lang.String" value="defaultTCF" description="" />
        <property name="jms_topicJndiName" type="java.lang.String" value="defaultTopic" description="" />
        <property name="jms_topicName" type="java.lang.String" value="defaultTopic" description="" />
        <property name="jms_userid" type="java.lang.String" value="" description="" />
        <property name="jms_password" type="java.lang.String" value="" description="" />
        <property name="jndi_properties" type="java.lang.String"
          value="java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory;java.naming.provider.url=
     tcp://localhost:61616;connectionFactoryNames=defaultTCF;topic.defaultTopic=defaultTopic"
          description="jndi properties" />
      </bean>

      <backingMap name="agent" readOnly="false" pluginCollectionRef="agent" preloadMode="false"
        lockStrategy="OPTIMISTIC" copyMode="COPY_ON_READ_AND_COMMIT" ttlEvictorType="LAST_ACCESS_TIME"
        timeToLive="28800" />
      <backingMap name="profile" readOnly="false" pluginCollectionRef="profile" preloadMode="false"
        lockStrategy="OPTIMISTIC" copyMode="COPY_ON_READ_AND_COMMIT" ttlEvictorType="LAST_ACCESS_TIME"
        timeToLive="2700" />
      <backingMap name="pessimisticMap" readOnly="false" pluginCollectionRef="pessimisticMap" preloadMode="false"
        lockStrategy="PESSIMISTIC" copyMode="COPY_ON_READ_AND_COMMIT" ttlEvictorType="LAST_ACCESS_TIME"
        timeToLive="2700" />
      <backingMap name="excludedMap1" readOnly="false" pluginCollectionRef="excludedMap1" preloadMode="false"
        lockStrategy="OPTIMISTIC" copyMode="COPY_ON_READ_AND_COMMIT" ttlEvictorType="LAST_ACCESS_TIME"
        timeToLive="2700" />
      <backingMap name="excludedMap2" readOnly="false" pluginCollectionRef="excludedMap2" preloadMode="false"
        lockStrategy="OPTIMISTIC" copyMode="COPY_ON_READ_AND_COMMIT" ttlEvictorType="LAST_ACCESS_TIME"
        timeToLive="2700" />
    </objectGrid>
  </objectGrids>

  <backingMapPluginCollections>
    <backingMapPluginCollection id="agent">
      <bean id="ObjectTransformer" className="com.ibm.ws.objectgrid.test.scenario.AgentObjectTransformer" />
    </backingMapPluginCollection>
    <backingMapPluginCollection id="profile">
      <bean id="ObjectTransformer" className="com.ibm.ws.objectgrid.test.scenario.ProfileObjectTransformer" />
      <bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor">
        <property name="maxSize" type="int" value="2000" description="set max size for LRU evictor" />
        <property name="sleepTime" type="int" value="15" description="evictor thread sleep time" />
        <property name="numberOfLRUQueues" type="int" value="50" description="set number of LRU queues" />
      </bean>
    </backingMapPluginCollection>

    <backingMapPluginCollection id="pessimisticMap" />
    <backingMapPluginCollection />
    <backingMapPluginCollection />
  </backingMapPluginCollections>

</objectGridConfig>


Configure request retry timeout values

With reliable maps, we can supply a retry timeout value in milliseconds to WXS for transaction requests.

We can configure the timeout value on the client properties file or in a session. The session value overrides the client properties setting. If the value is set to greater than zero, the request is tried until either the timeout condition is met or a permanent failure occurs. A permanent failure might be a DuplicateKeyException exception. A value of zero indicates the fail-fast mode setting and WXS does not attempt to try the transaction again after any type of transaction.

During run time, the transaction timeout value is used with the retry timeout value, ensuring that the retry timeout does not exceed the transaction timeout.

Two types of transactions exist: Autocommit transactions, and transactions that use explicit begin and commit methods. The valid exceptions for retry differ between these two types of transactions:

Application or other permanent failures return immediately and the client does not try the transaction again. These permanent failures include the DuplicateKeyException and KeyNotFoundException exceptions. Use the fail-fast setting to return all exceptions without trying transactions again after any exceptions.

Exceptions where the client tries the transaction again:

Permanent exceptions, where the transaction is not tried again:


Configure .NET clients

We can configure the WXS .NET client using the client properties file, server-side XML configuration, or programmatically overriding select server properties configuration properties through the .NET client.

Configuration through client properties file occurs during .NET client's Connect() call to the grid. However, when the client properties file is not specified during Connect() call, the client properties are initialized with the values defined in the installed Client.Net.properties file. After the client call the Connect() method, any changes to the Client properties file can take effect only by restarting the client's connection to the grid. Any failure with .NET client properties configuration including bad property values, bad client properties location, etc. results in an exception being thrown from the Connect() method. The .NET client also receives several server side XML configuration property values that can be overidden programmatically using the .NET client API.

.NET client overrides

WXS client for .NET can be configured based on requirements by overriding server properties. These server properties are set through objectgrid.xml configuration file while starting up the servers.

To override settings on a client, we can use a programmatic configuration on the .NET client.

We can override the following attributes on a client:


Configure .NET clients programmatically

We can override client-side settings programmatically. Create an ObjectGridConfiguration object that is similar in structure to the server-side ObjectGrid instance.

The following code example creates the same overrides that are described in .NET client overrides .

The following code creates a client-side ObjectGrid instance. 

IGridManager gm = GridManagerFactory.GetGridManager();
ICatalogDomainInfo cdi = gm.CatalogDomainManager.CreateCatalogDomainInfo("localhost:2809");
ctx = gm.Connect(cdi, "Sample.Client.Net.properties");
IGrid grid = gm.GetGrid( ctx, "Grid");

//Overriding grid.s txTimeout value grid.TransactionTimeout = new TimeSpan(0, 0, 30);

IGridMapPessimisticTxObject, Object gridMap;
gridMap = grid.GetGridMapPessimisticTx<Object, Object>("Map1");

//Overriding timeToLive value gridMap.TimeToLive = new TimeSpan(0, 0, 50);

//Overriding lockTimeout value gridMap.LockTimeout = new TimeSpan(0, 0, 20);

//Overriding txTimeout value
gridMap.Transaction.TransactionTimeout = new TimeSpan(0, 0, 40);

//Overriding txIsolation value
gridMap.Transaction.TransactionIsolationLevel = TxnIsolationLevel.ReadUncommitted;

//Calling ResetTofalse s(), resets the value of timeToLive, lockTimeout,
//txTimeout, txIsolation back to values when .NET client initialized the grid.

gridMap.ResetTofalse s();

Before overriding timeToLive programmatically, set ttlEvictorType to LAST_ACCESS_TIME or LAST_UPDATE_TIME in the objectgrid.xml file. If the .NET client tries to programmatically override timeToLive without setting the ttlEvictorType value, an exception will be thrown. txTimeout value set to TimeSpan.Zero indicates an unlimited timeout.


Configure WXS connection factories

An WXS connection factory allows Java EE applications to connect to a remote WXS data grid. Use custom properties to configure resource adapters.

Before you create the connection factories, install the resource adapter.

After you install the resource adapter, we can create one or more resource adapter connection factories that represent WXS client connections to remote data grids. Complete the following steps to configure a resource adapter connection factory and use it within an application.

We can create a WXS connection factory at the node scope for stand-alone resource adapters or within the application for embedded resource adapters.

  1. Use the WAS admin console to create a WXS connection factory that represents a WXS client connection. See Configuring Java EE Connector connection factories in the administrative console. After you specify properties for the connection factory in the General Properties panel, you must click Apply for the Custom properties link to become active.

  2. Click Custom properties in the administrative console. Set the following custom properties to configure the client connection to the remote data grid.

    Property Name Type Description
    ConnectionName String (Optional) The name of the WXS client connection.

    The ConnectionName helps identify the connection when exposed as a managed bean. This property is optional. If not specified, the ConnectionName is undefined.

    CatalogServiceEndpoints String (Optional) The catalog service domain end points in the format: <host>:<port>[,<host><port>].

    This property is required if the catalog service domain is not set.

    CatalogServiceDomain String (Optional) The catalog service domain name that is defined in WAS.

    This property is required if the CatalogServiceEndpoints property is not set.

    ObjectGridName String (Optional) The name of the data grid that this connection factory connects to. If not specified, then the application must supply the name when obtaining the connection from the connection factory.
    ObjectGridURL String (Optional) The URL of the client data grid, override XML file. This property is not valid if the ObjectGridResource is also specified.
    ObjectGridResource String The resource path of the client data grid, override XML file. This property is optional and invalid if ObjectGridURL is also specified.
    ClientPropertiesURL String (Optional) The URL of the client properties file. This property is not valid if the ClientPropertiesResource is also specified.
    ClientPropertiesResource String (Optional) The resource path of the client properties file. This property is not valid if the ClientPropertiesURL is also specified.

    WAS also allows other configuration options for adjusting connection pools and managing security.


What to do next

Create a WXS connection factory reference in the application.

Catalog service domain settings

Configuring connection factories for resource adapters within applications

Configuring Java EE Connector connection factories in the administrative console

Configuring new J2C connection factories using wsadmin scripting

J2C connection factories collection

Connection factory JNDI name practices


Configure Eclipse environments to use WXS connection factories

The WXS resource adapter includes custom connection factories. To use these interfaces in your WXS Java Platform, Enterprise Edition (Java EE) applications, you must import the wxsra.rar file into your workspace and link it to the application project.

  1. Import the wxsra.rar file into your project by selecting File > Import. The Import window is displayed.

  2. Select Java EE > RAR file. The Connector Import window is displayed.

  3. To specify the connector file, click Browse to locate the wxsra.rar file. The wxsra.rar file is installed when you install a resource adapter. We can find the resource adapter archive (RAR) file in the following location:

    • For WAS installations: wxs_install_root/optionalLibraries/ObjectGrid
    • For stand-alone installations: wxs_install_root/ObjectGrid/lib directory

  4. Create a name for the new connector project in the Connector project field. Use

    wxsra, which is the default name.

  5. Choose a Target runtime, which references a Java EE server runtime environment.

  6. Optionally select Add project to EAR to embed the RAR into an existing EAR project.


Results

The RAR file is now imported into your Eclipse workspace.


What to do next

We can reference the RAR project from your other Java EE projects...

  1. Right click on the project and click Properties.

  2. Select Java Build Path.

  3. Select the Projects tab.

  4. Click Add.

  5. Select the wxsra connector project, and click OK.

  6. Click OK again to close the Properties window.

The WXS resource adapter classes are now in the classpath. To install product runtime JAR files using the Eclipse console.



Configure cache integration

WXS can integrate with other caching-related products. We can also use the WebSphere WXS dynamic cache provider to plug WebSphere WXS into the dynamic cache component in WAS. Another extension to WAS is the WXS HTTP session manager, which can help to cache HTTP sessions.

Troubleshooting loaders

Configuring JPA loaders


Configure HTTP session managers

The HTTP session manager provides session replication capabilities for an associated application. The session manager works with the Web container to create and manage the life cycles of HTTP sessions that are associated with the application.


13.1.1. Configure the HTTP session manager with WAS

While WAS provides session management function, the performance degrades as the number of requests increases. WXS comes bundled with a session management implementation that provides session replication, high availability, better scalability and more robust configuration options.

WXS must be installed on your WAS or WAS Network Deployment cell to use the WXS session manager.

When using WXS for HTTP session replication on WAS, the Allow overflow session management setting must be checked for every applicable web application and application server hosting that web application. For more information, see Session management settings .

Global security must be enabled in the WAS admin console, if the catalog servers within the catalog service domain have SSL enabled or we want to use SSL for a catalog service domain with SSL supported. You require SSL for a catalog server by setting the transportType attribute to SSL-Required in the Server properties file . For more information about configuring global security, see Global security settings .

The WXS HTTP session manager supports both embedded and remote servers for caching.

In the embedded scenario, the WXS servers are collocated in the same processes where the servlets run. The session manager can communicate directly with the local ObjectGrid instance, avoiding costly network delays.

If we are using WAS, place the supplied wxs_home /session/samples/objectGrid.xml and wxs_home /session/samples/objectGridDeployment.xml files into the META-INF directories of your Web archive (WAR) files. WXS automatically detects these files when the application starts and automatically starts the WXS containers in the same process as the session manager.

We can modify the objectGridDeployment.xml file depending on to use synchronous or asynchronous replication and how many replicas we want configured.

In the remote servers scenario, the container servers run in different processes than the servlets. The session manager communicates with a remote container server. To use a remote, network-attached container server, the session manager must be configured with the host names and port numbers of the catalog service domain. The session manager then uses a WXS client connection to communicate with the catalog server and the container servers.

If the container servers are starting in independent, stand-alone processes, start the WXS containers with the objectGridStandAlone.xml and objectGridDeploymentStandAlone.xml files that are supplied in the session manager samples directory.

  1. Splice the application so that it can use the session manager. To use the session manager, add the appropriate filter declarations to the Web deployment descriptors for the application. In addition, session manager configuration parameters are passed in to the session manager in the form of servlet context initialization parameters in the deployment descriptors. There are multiple ways in which we can introduce this information into the application:

    • Auto-splice with WAS

      We can configure the application to use the WXS HTTP session manager when you install the application. We can also edit the application or server configuration to use the WebSphere WXS HTTP session manager.

    • Auto-splice the application with custom properties

      You do not need to manually splice the applications when the application is running in WAS or WAS Network Deployment.

      Add a custom property to either a cell or a server to set the splicer.properties file for all of the Web applications at that scope...

      1. In the WAS admin console, navigate to the correct path for where we want to set the custom property to indicate the location of the splicer.properties file.

        • To set the custom property for all applications or a specific application, click...

            System administration > Cell > Custom properties

        • To set the custom property to apply to all the applications on a specific application server, click...

            Application server > <server_name> > Administration > Custom properties

          The property name is com.ibm.websphere.xs.sessionFilterProps, and its value is the location of the splicer.properties file the applications require. An example path for the location of a file follows: /opt/splicer.properties.

      2. Add the com.ibm.websphere.xs.sessionFilterProps custom property. This custom property value gives the location of the splicer.properties file to edit. The file exists on the dmgr. To indicate the splicer.properties file for a specific application with a cell-level custom property, enter the name of the custom property as:

        <application_name>,com.ibm.websphere.xs.sessionFilterProps, where application_name indicates the name of the application for which we want to apply the custom property.

      Ensure that the updated splicer.properties file is on the same path on all nodes containing an application server hosting the application or applications that are being spliced for session replication.

      The cell, server, and application scope are available scopes and are only available when running in a dmgr. If you require a different scope, manually splice your Web applications.

      Remember: Also, note that the auto-splice option works only if all of the nodes running the application contain the splicer.properties file at the same path. For mixed environments containing Windows and UNIX nodes, this option is not possible, so manually splice the application.

    • Splice the application with the addObjectGridFilter script

      Use a command-line script provided along with WXS to splice an application with filter declarations and configuration in the form of servlet context initialization parameters. For a WAS deployment, this script is located in <was_home>/optionalLibraries/ObjectGrid/session/bin/addObjectGridFilter.bat/sh . For a stand-alone deployment, the script is at WXS_HOME/ObjectGrid/session/bin/addObjectGridFilter.sh/bat. The oddObjectGridFilter script takes two parameters:

      • Application - absolute path to the enterprise archive file to be spliced
      • Absolute path to the splicer properties file that contains various configuration properties.

      The usage format of this script follows:

      Windows: 

      addObjectGridFilter.bat [ear_file] [splicer_properties_file]
      addObjectGridFilter.sh [ear_file] [splicer_properties_file]

      Example using WXS installed on WAS on UNIX:

      1. cd wxs_home /optionalLibraries/ObjectGrid/session/bin

      2. addObjectGridFilter.sh /tmp/mySessionTest.ear was_root/optionalLibraries/ObjectGrid/session/samples/splicer.properties

      Example using WXS installed in a stand-alone directory on UNIX:

      1. cd was_root/session/bin

      2. addObjectGridFilter.sh /tmp/mySessionTest.ear was_root/session/samples/splicer.properties

      The servlet filter that is spliced maintains defaults for configuration values. We can override these default values with configuration options that you specify in the properties file in the second argument.

      We can modify and use the sample splicer.properties file that is provided withWXS installation. We can also use the addObjectGridServlets script, which inserts the session manager by extending each servlet. However, the recommended script is the addObjectGridFilter script.

    • Manually splice the application with the Ant build script

      WXS ships with a build.xml file that can be used by Apache Ant, which is included in the was_root/bin folder of a WAS installation. We can modify the build.xml file to change the session manager configuration properties. The configuration properties are identical to the property names in the splicer.properties file. You modify the build.xml file, invoke the Ant process by running the following command:

      • ant.sh, ws_ant.sh
      • Windows: ant.bat, ws_ant.bat

      (UNIX) or (Windows).

    • Manually update the Web descriptor

      Edit the web.xml file that is packaged with the Web application to incorporate the filter declaration, its servlet mapping, and servlet context initialization parameters. Do not use this method because it is prone to errors.

  2. Deploy the application. Deploy the application with your normal set of steps for a server or cluster. After we deploy the application, we can start the application.

  3. Access the application. We can now access the application, which interacts with the session manager and WXS.


What to do next

We can change a majority of the configuration attributes for the session manager when you instrument the application to use the session manager. These attributes include: synchronous or asynchronous replication, in-memory session table size, and so on. Apart from the attributes that can be changed at application instrumentation time, the only other configuration attributes that we can change after the application deployment are the attributes that are related to the WXS server cluster topology and the way that their clients (session managers) connect to them.

Remote scenario behavior: If the entire data grid that is hosting the application session data is unreachable from the web container client, the client instead uses the base web container in WAS for session management. The data grid might be unreachable in the following scenarios:

The number of session references kept in memory, specified by sessionTableSize parameter, is still maintained when the sessions are stored in the base web container. The least recently used sessions are invalidated from the web container session cache when the sessionTableSize value is exceeded. If the remote data grid becomes available, sessions that were invalidated from the web container cache can retrieve data from the remote data grid and load the data into a new session. If the entire remote data grid is not available and the session is invalidated from the session cache, the user session data is lost. Because of this issue, do not shut down the entire production remote data grid when the system is running under load.

Configure WebSphere Commerce to use WXS for dynamic cache to improve performance and scale

WebSphere Business Process Management and Connectivity integration


13.1.1.1. Automatically splicing applications for HTTP session management in WAS

We can configure your WAS application to persist sessions to a data grid. This data grid can be in an embedded container server that runs within WAS, or it can be in a remote data grid.

Before you change the configuration in WAS, you must have:


Results

You configured HTTP session manager to persist the sessions to a data grid. Entries are removed from the data grid when the sessions time out.


13.1.1.1.1. WXS session management settings

We can configure your WAS applications to use WXS or a WebSphere DataPower XC10 appliance for session persistence.

We can edit these settings in the enterprise application installation wizard, or on the application or server detail pages:

Enable session management

Enables session management to use WXS embedded or remote data grid or a WebSphere DataPower XC10 appliance for session persistence.

Manage session persistence by

Specifies how session persistence is managed. We can choose one of the following options:

The remaining settings that you configure depend on the session persistence mechanism you choose.

WebSphere DataPower XC10 appliance specific settings

The following settings are specific to configuring the WebSphere DataPower XC10 appliance for session persistence.

IP or host name of the WebSphere DataPower XC10 appliance IP or host name of the appliance to use for persisting sessions.
IBM WebSphere DataPower XC10 appliance administrative credentials Specifies the User name and Password that you use to log in to the DataPower XC10 Appliance user interface. Click Test Connection... to test the connection to your appliance.
Session persistence preference Specifies the data grid on which sessions are persisted. We can choose one of the following options:

  • Persist sessions in a new data grid on the IBM WebSphere DataPower XC10 appliance. We can then specify a Data grid name.
  • Persist sessions in an existing data grid on the IBM WebSphere DataPower XC10 appliance. We can then enter or browse for an Existing data grid name.

Remote WXS data grid configuration

Catalog service domain that manages the remote session data grid Catalog service domain to use to manage the sessions. If no catalog service domains are displayed, or we want to create a new catalog service domain, click...

    System administration | WXS | Catalog service domains
Remote data grid in which to store session information Name of the data grid in the catalog service domain in which we want to store the session information. The list of active remote grids is populated when you select a catalog service. The remote data grid must already exist in the WXS configuration.

Embedded WXS data grid configuration

The following settings are specific to configuring an embedded WXS configuration. In the embedded WXS scenario, the WXS processes are hosted by WAS processes.


13.1.2. Use WXS for SIP session management

Use WXS as a Session Initiation Protocol (SIP) replication mechanism as a reliable alternative to the data replication service (DRS) for SIP session replication.


SIP session management configuration

To use WXS as the SIP replication mechanism, set the com.ibm.sip.ha.replicator.type custom property. In the administrative console, select Application servers > my_application_server > SIP container > Custom properties for each server to add the custom property. Type

com.ibm.sip.ha.replicator.type for the Name and

OBJECTGRID for the Value.

Use the following properties to customize the behavior of the ObjectGrid used to store SIP sessions. In the administrative console, click...

for each server to add the custom property. Type the Name and Value. Each server must have the same properties set to function properly.

Property Value Default
com.ibm.sip.ha.replicator.type OBJECTGRID: use ObjectGrid as SIP session store
min.synchronous.replicas Minimum number of synchronous replicas 0
max.synchronous.replicas Maximum number of synchronous replicas 0
max.asynchronous.replicas Maximum number of asynchronous replicas 1
auto.replace.lost.shards See Configuring distributed deployments true
development.mode

  • true - allow replicas to be active on same node as primaries
  • false - replicas must be on different node than primaries

false


13.1.3. Configure HTTP session manager with WebSphere Portal

We can persist HTTP sessions from WebSphere Portal into a data grid.

Your WXS and WebSphere Portal environment must meet the following requirements:

Introducing WXS into a WebSphere Portal environment can be beneficial in the following scenarios:

Although the following scenarios introduce benefits, increased processor usage in the WebSphere Portal tier can result from introducing WXS into the environment.

  1. Splice the wps WebSphere Portal application and any custom portlets to enable the sessions to be stored in the data grid.

    We can splice the application by configuring HTTP session management when we deploy the application, or we can use custom properties to automatically splice the applications.

  2. If we are using the remote scenario, where your container servers are outside of the WAS, explicitly start remote WXS containers for remote HTTP session persistence scenarios. Start the containers with the XS/ObjectGrid/session/samples/objectGridStandAlone.xml and objectGridDeploymentStandAlone.xml configuration files. For example, you might use the following command:
    UNIX/Linux: 
    startOgServer.sh xsContainer1 
                 -catalogServiceEndPoints <host>:<port> 
                 -objectgridFile XS/ObjectGrid/session/samples/objectGridStandAlone.xml 
                 -deploymentPolicyFile XS/ObjectGrid/session/samples/objectGridDeploymentStandAlone.xml

    startXsServer.sh xsContainer1 
                 -catalogServiceEndPoints <host>:<port> 
                 -objectgridFile XS/ObjectGrid/session/samples/objectGridStandAlone.xml 
                 -deploymentPolicyFile XS/ObjectGrid/session/samples/objectGridDeploymentStandAlone.xml

  3. Restart the WebSphere Portal servers.


Results

We can access the WebSphere Portal Server, and HTTP session data for the configured custom portlets is persisted to the data grid.

If the entire data grid that is hosting the application session data is unreachable from the web container client, the client instead uses the base web container in WAS for session management. The data grid might be unreachable in the following scenarios:

The number of session references kept in memory, specified by sessionTableSize parameter, is still maintained when the sessions are stored in the base web container. The least recently used sessions are invalidated from the web container session cache when the sessionTableSize value is exceeded. If the remote data grid becomes available, sessions that were invalidated from the web container cache can retrieve data from the remote data grid and load the data into a new session. If the entire remote data grid is not available and the session is invalidated from the session cache, the user.s session data is lost. Because of this issue, you should not shut down the entire production remote data grid when the system is running under load.

Configure WebSphere Commerce to use WXS for dynamic cache to improve performance and scale

WebSphere Business Process Management and Connectivity integration


13.1.4. Configure the HTTP session manager for various application servers

WXS is bundled with a session management implementation that overrides the default session manager for a web container. This implementation provides session replication, high availability, better scalability, and configuration options. We can enable the WebSphere WXS session replication manager and generic embedded ObjectGrid container startup.

Use the HTTP session manager with other application servers that are not running WAS, such as WAS Community Edition. To configure other application servers to use the data grid, splice the application and incorporate WXS JAR files into the application.

  1. Splice the application so that it can use the session manager. To use the session manager, add the appropriate filter declarations to the web deployment descriptors for the application. In addition, session manager configuration parameters are passed in to the session manager in the form of servlet context initialization parameters in the deployment descriptors. There are three ways in which we can introduce this information into the application:

    • addObjectGridFilter script:

      Use a command-line script provided along with WXS to splice an application with filter declarations and configuration in the form of servlet context initialization parameters. Thewxs_home /session/bin/addObjectGridFilter.sh|bat script takes two parameters: the absolute path to the enterprise archive (EAR) file or web archive (WAR) file to splice, and the absolute path to the splicer properties file that contains various configuration properties. The usage format of this script is as follows:

      Windows: 

      addObjectGridFilter.bat <ear_or_war_file> <splicer_properties_file>

      addObjectGridFilter.sh <ear_or_war_file> <splicer_properties_file>

      Example using WXS installed in a stand-alone directory on UNIX:

      1. cd wxs_home /session/bin

      2. addObjectGridFilter.sh /tmp/mySessionTest.ear wxs_home /session/samples/splicer.properties

      The servlet filter that is spliced in maintains defaults for configuration values. We can override these default values with configuration options that you specify in the properties file in the second argument.

      We can modify and use the sample splicer.properties file that is provided with the WXS installation. We can also use the addObjectGridServlets script, which inserts the session manager by extending each servlet. However, the recommended script is the addObjectGridFilter script.

    • Ant build script:

      WXS ships with a build.xml file that can be used by Apache Ant, which is included in the was_root/bin folder of a WAS installation. We can modify the build.xml file to change the session manager configuration properties. The configuration properties are identical to the property names in the splicer.properties file. After the build.xml file has been modified, invoke the Ant process by running ant.sh, ws_ant.sh (UNIX) or ant.bat, ws_ant.bat (Windows).

    • Update the web descriptor manually:

      Edit the web.xml file that is packaged with the web application to incorporate the filter declaration, its servlet mapping, and servlet context initialization parameters. Do not use this method because it is prone to errors.

  2. Incorporate the WXS session replication manager JAR files into the application. We can embed the files into the application module WEB-INF/lib directory or in the application server classpath. The required JAR files vary depending on the type of containers that we are using:

    • Remote container servers: ogclient.jar and sessionobjectgrid.jar

    • Embedded container servers: objectgrid.jar and sessionobjectgrid.jar

  3. Optional: If you use remote container servers, start the container servers.

  4. Deploy the application. Deploy the application with your normal set of steps for a server or cluster. After we deploy the application, we can start the application.

  5. Access the application. We can now access the application, which interacts with the session manager and WXS.


What to do next

We can change a majority of the configuration attributes for the session manager when you instrument the application to use the session manager. These attributes include variations to the replication type (synchronous or asynchronous), in-memory session table size, and so on. Apart from the attributes that can be changed at application instrumentation time, the only other configuration attributes that we can change after the application deployment are the attributes that are related to the WXS server cluster topology and the way that their clients (session managers) connect to them.

Remote scenario behavior: If the entire data grid that is hosting the application session data is unreachable from the web container client, the client instead uses the base web container of the application server for session management. The data grid might be unreachable in the following scenarios:

The number of session references kept in memory, specified by sessionTableSize parameter, is still maintained when the sessions are stored in the base web container. The least recently used sessions are invalidated from the web container session cache when the sessionTableSize value is exceeded. If the remote data grid becomes available, sessions that were invalidated from the web container cache can retrieve data from the remote data grid and load the data into a new session. If the entire remote data grid is not available and the session is invalidated from the session cache, the user session data is lost. Because of this issue, do not shut down the entire production remote data grid when the system is running under load.

See also...

  1. Configure WebSphere Commerce to use WXS for dynamic cache to improve performance and scale
  2. WebSphere Business Process Management and Connectivity integration


13.1.5. XML files for HTTP session manager configuration

When you start a container server that stores HTTP session data, we can either use the default XML files or we can specify customized XML files. These files create specific ObjectGrid names, number of replicas, and so on.


Sample files location

These XML files are packaged in /path/to/ObjectGrid/session/samples for a stand-alone installation or was_root/optionalLibraries/ObjectGrid/session/samples for WXS installed in a WAS cell.


Embedded XML package

If we are configuring an embedded scenario, the container server starts in the web container tier. Use the objectGrid.xml file and objectGridDeployment.xml file, which are provided by default. We can update these files to customize the behavior of the HTTP session manager. 

<?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="session" txTimeout="30">
   <bean id="ObjectGridEventListener" className="com.ibm.ws.xs.sessionmanager.SessionHandleManager"/>
   <backingMap name="objectgridSessionMetadata" pluginCollectionRef="objectgridSessionMetadata" readOnly="false" 
     lockStrategy="PESSIMISTIC" ttlEvictorType="LAST_ACCESS_TIME" timeToLive="3600" copyMode="NO_COPY"/>
   <backingMap name="objectgridSessionAttribute.*" template="true" readOnly="false" lockStrategy="PESSIMISTIC" 
     ttlEvictorType="NONE" copyMode="NO_COPY"/>
       <backingMap name="objectgridSessionTTL.*" template="true" readOnly="false" lockStrategy="PESSIMISTIC" 
     ttlEvictorType="LAST_ACCESS_TIME" timeToLive="3600" copyMode="NO_COPY"/>
  </objectGrid>
 </objectGrids>
    <backingMapPluginCollections>
        <backingMapPluginCollection id="objectgridSessionMetadata">
            <bean id="MapEventListener" className="com.ibm.ws.xs.sessionmanager.MetadataMapListener"/>
        </backingMapPluginCollection>
    </backingMapPluginCollections>
</objectGridConfig>

Values we can change:

ObjectGrid name attribute

The value must match the following values in other configuration files:

  • The objectGridName property in the splicer.properties file used to splice the web application.

  • The objectgridName attribute in the objectGridDeployment.xml file.

 If you have multiple applications, and we want the session data to be stored in different data grids, those applications must have different ObjectGrid name attribute values.

ObjectGrid txTimeout attribute

This value determines how many seconds a transaction can be open before the container server triggers the transaction to time out. The default is 30 seconds, and can be changed depending on the environment. If the HTTP session persistence is configured with the replicationInterval servlet context initialization parameter value set greater than zero, transactions are batched on a thread. If the replicationInterval property is set to 0, a transaction typically starts when a web application retrieves a valid HttpSession object. The transaction commits at the end of the web application request. If your environment has requests that take longer than 30 seconds, set this value accordingly.

Values we cannot change:

ObjectGridEventListener

The ObjectGridEventListener line cannot be changed and is used internally.

objectgridSessionMetadata

The objectgridSessionMetadata line refers to the map where the HTTP session metadata is stored. There is one entry for every HTTP session stored in the data grid in this map.

objectgridSessionTTL.*

This value cannot be changed and is for future use.

objectgridSessionAttribute.*

The objectgridSessionAttribute.* text defines a dynamic map. This value is used to create the map in which HTTP session attributes are stored when the fragmentedSession parameter is set to true in the splicer.properties file. This dynamic map is called objectgridSessionAttribute. Another map is created based on this template called objectgridSessionAttributeEvicted, which stores sessions that have timed out, but the web container has not invalidated.

A time to live policy (TTL) is defined for the objectgridSessionMetadata map definition. The other map, objectgridSessionAttribute is dependant on this map and does not require a TTL parameter. For each active HTTP session, an entry gets created in the objectgridSessionMetadata map, and one entry in the objectgridSessionAttribute map for every session attribute. If an in-memory session does not exist due to an application server failure or a session is removed from the in-memory cache on the application server, the grid must initiate the session invalidation using the TTL eviction policy. At the time of eviction, the attributes are removed from the objectgridSessionAttribute map and inserted into a dynamically created map called objectgridSessionAttributeEvicted map. The data is stored in this map until an application server can remove the session and complete session invalidation. Therefore, the TTL parameter is only required in the objectgridSessionMetadata map definition. The objectgridSessionTTL is not used by WXS in the current release. The MapEventListener line is internal and cannot be modified. 

<?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="session">
  <mapSet name="sessionMapSet" numberOfPartitions="5" minSyncReplicas="0" maxSyncReplicas="0" 
    maxAsyncReplicas="1" developmentMode="false" placementStrategy="PER_CONTAINER">
             <map ref="objectgridSessionMetadata"/>
             <map ref="objectgridSessionAttribute.*"/>
             <map ref="objectgridSessionTTL.*"/>
    </mapSet>
   </objectgridDeployment>
</deploymentPolicy>

Values you can change:

ObjectGrid name attribute

The value must match the following values in other configuration files:

  • The objectGridName property in the splicer.properties file used to splice the web application.

  • The ObjectGrid name attribute in the objectGrid.xml file.

 If you have multiple applications, and we want the session data to be stored in different data grids, those applications must have different ObjectGrid name attribute values.

mapSet element attributes

We can change all mapSet properties except for the placementStrategy attribute.

Name

Can be updated to any value.

numberOfPartitions

Number of primary partitions that are started in each server that is hosting the web application. As you add partitions, the data becomes more spread out in the event of a failover. The default value is

5 partitions, and is fine for most applications.

minSyncReplicas, maxSyncReplicas, and maxAsyncReplicas

Number and type of replicas that store the HTTP session data. The default is

1 asynchronous replica, which is fine for most applications. Synchronous replication occurs during the request path, which can increase the response times for your web application.

developmentMode

Informs the WXS placement service whether the replica shards for a partition can be placed on the same node as its primary shard. We can set the value to true in a development environment, but disable this function in a production environment because a node failure could cause the loss of session data.

placementStrategy

Do not change the value of this attribute.
The rest of the file refers to the same map names as in the objectGrid.xml file. These names cannot be changed.
Values we cannot change:


Remote XML package

When using the remote mode, where the containers run as stand-alone processes, use the objectGridStandAlone.xml file and the objectGridDeploymentStandAlone.xml file to start the processes. We can update these files to modify the configuration.

objectGridStandAlone.xml file 

<?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="session" txTimeout="30">
   <bean id="ObjectGridEventListener" className="com.ibm.ws.xs.sessionmanager.SessionHandleManager"/>
            <backingMap name="objectgridSessionMetadata" pluginCollectionRef="objectgridSessionMetadata" 
       readOnly="false" lockStrategy="PESSIMISTIC" ttlEvictorType="LAST_ACCESS_TIME" timeToLive="3600" 
       copyMode="COPY_TO_BYTES"/>
            <backingMap name="objectgridSessionAttribute.*" template="true" readOnly="false" lockStrategy="PESSIMISTIC" 
       ttlEvictorType="NONE" copyMode="COPY_TO_BYTES"/>
            <backingMap name="objectgridSessionTTL.*" template="true" readOnly="false" lockStrategy="PESSIMISTIC" 
       ttlEvictorType="LAST_ACCESS_TIME" timeToLive="3600" copyMode="COPY_TO_BYTES"/>
  </objectGrid>
 </objectGrids>
    <backingMapPluginCollections>
        <backingMapPluginCollection id="objectgridSessionMetadata">
            <bean id="MapEventListener" className="com.ibm.ws.xs.sessionmanager.MetadataMapListener"/>
        </backingMapPluginCollection>
    </backingMapPluginCollections>
</objectGridConfig>

Values you can change:

ObjectGrid name attribute

The value must match the following values in other configuration files:

  • The objectGridName property in the splicer.properties file used to splice the web application.
  • The objectgridName attribute in the objectGridStandAlone.xml file.

 If you have multiple applications, and we want the session data to be stored in different data grids, those applications must have different ObjectGrid name attribute values.

ObjectGrid txTimeout attribute

This value determines how many seconds a transaction can be open before the container server triggers the transaction to time out. The default is 30 seconds, and can be changed depending on the environment. If the HTTP session persistence is configured with the replicationInterval servlet context initialization parameter value set greater than zero, transactions are batched on a thread. If the replicationInterval property is set to 0, a transaction typically starts when a web application retrieves a valid HttpSession object. The transaction commits at the end of the web application request. If your environment has requests that take longer than 30 seconds, set this value accordingly.

Values we cannot change:

ObjectGridEventListener

The ObjectGridEventListener line cannot be changed and is used internally.

objectgridSessionMetadata

The objectgridSessionMetadata line refers to the map where the HTTP session metadata is stored. There is one entry for every HTTP session stored in the data grid in this map.

objectgridSessionTTL.*

This value cannot be changed and is for future use.

objectgridSessionAttribute.*

The objectgridSessionAttribute.* text defines a dynamic map. This value is used to create the map in which HTTP session attributes are stored when the fragmentedSession parameter is set to true in the splicer.properties file. This dynamic map is called objectgridSessionAttribute. Another map is created based on this template called objectgridSessionAttributeEvicted, which stores sessions that have timed out, but the web container has not invalidated.

A time to live policy (TTL) is defined for the objectgridSessionMetadata map definition. The other map, objectgridSessionAttribute is dependant on this map and does not require a TTL parameter. For each active HTTP session, an entry gets created in the objectgridSessionMetadata map, and one entry in the objectgridSessionAttribute map for every session attribute. If an in-memory session does not exist due to an application server failure or a session is removed from the in-memory cache on the application server, the grid must initiate the session invalidation using the TTL eviction policy. At the time of eviction, the attributes are removed from the objectgridSessionAttribute map and inserted into a dynamically created map called objectgridSessionAttributeEvicted map. The data is stored in this map until an application server can remove the session and complete session invalidation. Therefore, the TTL parameter is only required in the objectgridSessionMetadata map definition. The objectgridSessionTTL is not used by WXS in the current release.

The MetadataMapListener line is internal and cannot be modified.

objectGridDeploymentStandAlone.xml file 

<?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="session">
  <mapSet name="sessionMapSet" numberOfPartitions="47" minSyncReplicas="0" maxSyncReplicas="0" 
   maxAsyncReplicas="1" developmentMode="false" placementStrategy="FIXED_PARTITIONS">
            <map ref="objectgridSessionMetadata"/>
            <map ref="objectgridSessionAttribute.*"/>
            <map ref="objectgridSessionTTL.*"/>
     </mapSet>
    </objectgridDeployment>
</deploymentPolicy>

Values you can change:

objectgridName attribute

The value must match the following values in other configuration files:

  • The objectGridName property in the splicer.properties file used to splice the web application.
  • The ObjectGrid name attribute in the objectGrid.xml file.

If you have multiple applications, and we want the session data to be stored in different data grids, those applications must have different ObjectGrid name attribute values.

mapSet element attributes

We can change all mapSet properties.

Name

Can be updated to any value.

numberOfPartitions

When using the default FIXED_PARTITIONS placement strategy, this specifies the number of total partitions that will be spread across all running grid containers. The default value is

47 partitions, and is fine for most applications. If a PER_CONTAINER placement strategy is used, then this specifies the number of primary partitions started in each grid container. As you add partitions, the data becomes more spread out in the event of a failover. The recommended value is

5 for the PER_CONTAINER strategy.

minSyncReplicas, maxSyncReplicas, and maxAsyncReplicas

Number of primary partitions that are started in each server that is hosting the web application. As you add partitions, the data becomes more spread out in the event of a failover. The default value is

5 partitions, and is fine for most applications.

developmentMode

Informs the WXS placement service whether the replica shards for a partition can be placed on the same node as its primary shard. We can set the value to true in a development environment, but disable this function in a production environment because a node failure could cause the loss of session data.

placementStrategy

We can change this attribute to one of the following:

  • FIXED_PARTITIONS This is the default value and is the preferred approach for using a remote HTTP Session topology. It is required if we are using Multi-Master replication

  • PER_CONTAINER This is still a supported configuration in a remote topology.


13.1.6. Servlet context initialization parameters

The following list of servlet context initialization parameters can be specified in the splicer properties file as required in the chosen splicing method.


Parameters

applicationQualifiedCookies

A string value of either true or false. Set to true if your environment contains multiple applications that use unique cookie names. Default is false, which assumes all applications are using the same cookie name.

authenticationRetryCount

Specifies the retry count for authentication if the credential is expired. If the value is set to 0, there will not be any authentication retry.

catalogHostPort

The catalog server can be contacted to obtain a client side ObjectGrid instance. The value must be of the form host:port<,host:port>. The host is the listener host on which the catalog server is running. The port is the listener port for that catalog server process. This list can be arbitrarily long and is used for bootstrapping only. The first viable address is used. It is optional inside WAS if the catalog.services.cluster property is configured.

credentialAuthentication

Client credential authentication support.The possible values are:

  • Never- The client does not support credential authentication.

  • Supported - The client supports the credential authentication if and only if the server supports too.

  • Required - The client requires the credential authentication. The default value is Supported.

cookieDomain

Specifies if you require sessions to be accessible across hosts. Set the value to the name of the common domain between the hosts.

cookiePath

Name of the class that implements the com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator interface. This class is used to get credentials for clients.

credentialGeneratorClass

The name of the class that implements the com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator interface. This class is used to obtain credentials for clients.

credentialGeneratorProps

The properties for the CredentialGenerator implementation class. The properties are set to the object with the setProperties(String) method. The credentialGeneratorProps value is used only if the value of the credentialGeneratorClass property is not null.

enableSessionStats

A string value of either true or false. Enables WXS client HTTP Sessions statistics tracking.

fragmentedSession

A string value of either true or false. Default is true. Use this setting to control whether the product stores session data as a whole entry, or stores each attribute separately.

Set the fragmentedSession parameter to true if the web application session has many attributes or attributes with large sizes. Set fragmentedSession to false if a session has few attributes, because all the attributes are stored in the same key in the data grid.

In the previous, filter-based implementation, this property was referred to as persistenceMechanism, with the possible values of ObjectGridStore (fragmented) and ObjectGridAtomicSessionStore (not fragmented).

objectGridType

A string value of either

REMOTE or EMBEDDED. The default is

REMOTE.

If it is set to REMOTE, the session data is stored outside of the server on which the web application is running.

If it is set to EMBEDDED, an embedded WXS container starts in the application server process on which the web application is running.

objectGridName

A string value that defines the name of the ObjectGrid instance used for a particular web application. The default name is session.

This property must reflect the objectGridName in both the ObjectGrid XML and deployment XML files used to start the WXS container servers.

objectGridXML

The file location of the objectgrid.xml file. The built-in XML file packaged in the WXS library is loaded automatically if

objectGridType=EMBEDDED and the objectGridXML property is not specified.

objectGridDeploymentXML

Location of the objectGrid deployment policy XML file. The built-in XML file packaged in the WXS library is loaded automatically if

objectGridType=EMBEDDED and the objectGridDeploymentXML property is not specified.

replicationInterval

An integer value (in seconds) that defines the time between writing of updated sessions to ObjectGrid. The default is

10 seconds. Possible values are from 0 to 60. 0 means that updated sessions are written to the ObjectGrid at the end of servlet service method call for each request. A higher replicationInterval value improves performance because fewer updates are written to the data grid. However, a higher value makes the configuration less fault tolerant.

This setting applies only when objectGridType is set to REMOTE.

reuseSessionID

A string value of either true or false. The default is false. Set to true if the underlying web container reuses session IDs across requests to different hosts. The value of this property must be the same as the value in the web container. If we are using WAS and configuring WXS HTTP session persistence using the administrative console or wsadmin tool scripting, the web container custom property

HttpSessionIdReuse=true is added by default. The reuseSessionID is also set to true. If you do not want the session IDs to be reused, set the HttpSessionIdReuse=false custom property on the web container custom property before you configure WXS session persistence.

sessionIdOverrideClass

The name of the class that implements the com.ibm.websphere.xs.sessionmanager.SessionIDOverride interface. This class is used to override the unique session identifier retrieved with the HttpSession.getId() method so that all applications have the same ID. The default is to use the user ID derived from the HttpSession.getId().

sessionStatsSpec = session.all = enabled

A string of WXS client HTTP statistics specification.

shareSessionsAcrossWebApps

A string value of either true or false. The default is false. Specifies if sessions are shared across web applications, specified as a string value of either true or false. The servlet specification states that HTTP Sessions cannot be shared across web applications. An extension to the servlet specification is provided to allow this sharing.

sessionTableSize

An integer value that defines the number of session references kept in memory. The default is

1000.

This setting pertains only to a REMOTE topology because the EMBEDDED topology already has the session data in the same tier as the web container.

Sessions are evicted from the in-memory table based on least recently used (LRU) logic. When a session is evicted from the in-memory table, it is invalidated from the web container. However, the data is not removed from the grid, so subsequent requests for that session can still retrieve the data. This value must be set higher than the web container maximum thread pool value, which reduces contention on the session cache.

securityEnabled

A string value of either true or false. The default value is false. This setting enables WXS client security. It must match the securityEnabled setting in the WXS server properties file. If the settings do not match, an exception occurs.

sessionIdOverrideClass

Overrides the retrieved session ID of an application. The default is to use the ID derived from the HttpSession.getId() method. Enables WXS client HTTP Sessions to override the unique session ID of an application so that all applications are retrieved with the same ID. Set to the implementation of the com.ibm.websphere.xs.sessionmanager.SessionIDOverride interface. This interface determines the HttpSession ID based on the HttpServletRequest object.

traceSpec

IBM WebSphere trace specification as a string value. Use this setting for application servers other than WAS.

traceFile

Specifies the trace file location as a string value. Use this setting for application servers other than WAS.

useURLEncoding

A string value of either true or false. The default is false. Set to true if we want to enable URL rewriting. The default value is false, which indicates that cookies are used to store session data. The value of this parameter must be the same as the web container settings for session management.

useCookies

A string value of either true or false. Set to true if the underlying web container will reuse session ID's across requests to different hosts. The default is false. The value of this should be the same as what is set in the web container.


13.1.7. splicer.properties file

The splicer.properties file contains all of the configuration options for configuring a servlet-filter-based session manager.


Sample splicer properties

If you choose to use any of the additional properties that are described in this file, be sure to uncomment the lines for the properties to enable. 

# Properties file that contains all the configuration 
# options that the servlet filter based ObjectGrid session
# manager can be configured to use.
#
# This properties file can be made to hold all the default 
# values to be assigned to these configuration settings, and 
# individual settings can be overridden using ANT Task
# properties, if this properties file is used in conjunction
# with the filtersplicer ANT task.

# A string value of either "REMOTE" or "EMBEDDED".  The default is REMOTE.
# If it is set to "REMOTE", the session data will be stored outside of
# the server on which the web application is running. If it is set to 
# "EMBEDDED", an embedded  WXS container will start
# in the application server process on which the web application is running.

objectGridType = REMOTE

# A string value that defines the name of the ObjectGrid 
# instance used for a particular web application. The default name
# is session. This property must reflect the objectGridName in both
# the objectgrid xml and deployment xml files used to start the eXtreme 
# Scale containers.

objectGridName = session

# Catalog Server can be contacted to obtain a client side 
# ObjectGrid instance.  The value needs to be of the 
# form "host:port<,host:port>", where the host is the listener host 
# on which the catalog server is running, and the port is the listener
# port for that catalog server process.
# This list can be arbitrarily long and is used for bootstrapping only. 
# The first viable address will be used.  It is optional inside WebSphere
# if the catalog.services.cluster property is configured.

# catalogHostPort = host:port<,host:port>

# An integer value (in seconds) that defines the time in seconds between
# writing of updated sessions to ObjectGrid. The default is 10. This property
# is only used when objectGridType is set to REMOTE. Possible values are 
# from 0 to 60. 0 means updated sessions are written to the ObjectGrid 
# at the end of servlet service method call for each request.

replicationInterval = 10

# An integer value that defines the number of session references 
# kept in memory. The default is 1000. This property is only used when
# objectGridType is set to REMOTE. When the number of sessions stored
# in memory in the web container exceeds this value, the least recently
# accessed session is invalidated from the web container. If a request
# comes in for that session after it's been invalidated, a new session
# will be created (with a new session ID if reuseSessionId=false), 
# populated with the invalidated session's attributes. This value should
# always be set to be higher than the maximum size of the web container 
# thread pool to avoid contention on this session cache.  

sessionTableSize = 1000

# A string value of either "true" or "false", default is "true".
# It is to control whether we store session data as a whole entry 
# or store each attribute separately.
# This property was referred to as persistenceMechanism in the 
# previous filter-based implementation, with the possible values
# of ObjectGridStore (fragmented) and ObjectGridAtomicSessionStore
# (not fragmented).

fragmentedSession = true

# A string value of either "true" or "false", default is "false".
# Enables WXS client security. This setting needs to match
# the securityEnabled setting in the WXS server properties
# file. If the settings do not match, an exception occurs.

securityEnabled = false

# Client credential authentication support.
#   The possible values are:
#   Never      - The client does not support credential authentication.
#   Supported* - The client supports the credential authentication if and only if the server
#                supports too.
#   Required   - The client requires the credential authentication.
#   The default value is Supported.

# credentialAuthentication =

# Specifies the retry count for authentication if the credential
# is expired. If the value is set to 0, there will not be 
# any authentication retry.

# authenticationRetryCount =

# Name of the class that implements the 
# com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator
# interface. This class is used to get credentials for clients.

# credentialGeneratorClass = 

# Properties for the CredentialGenerator implementation
# class. The properties are set to the object with the setProperties(String)
# method. The credentialGeneratorProps value is used only if the value of the 
# credentialGeneratorClass property is not null.

# credentialGeneratorProps = 

# The file location of the objectgrid xml file.  
# The built-in xml file packaged in the WXS library
# will automatically be loaded if this property
# is not specified and if objectGridType=EMBEDDED

# objectGridXML =

# The file location of the objectGrid deployment policy xml file.
# The built-in xml file packaged in the WXS library
# will automatically be loaded if this property
# is not specified and if objectGridType=EMBEDDED

# objectGridDeploymentXML =

# A string of IBM WebShere trace specification, 
# useful for all other application servers besides WebSphere.
 
# traceSpec =

# A string of trace file location. 
# useful for all other application servers besides WebSphere.

# traceFile=

# This property should be set if you require sessions to be 
# accessible across hosts. The value will be the name of the 
# common domain between the hosts.

# cookieDomain=

# This property should be set to the same path you have configured
# for the application server cookie settings. The default path
# is /.

# cookiePath

# Set to true if the underlying web container will reuse
# session ID's across requests to different hosts. false 
# is false. The value of this should be the same as what is
# set in the web container.

# reuseSessionId=

# A string value of either "true" or "false", the default is
# "false". Per the servlet specification, HTTP Sessions cannot
# be shared across web applications. An extension to the servlet
# specification is provided to allow this sharing.

# shareSessionsAcrossWebApps = false

# A string value of either "true" or "false", default is "false". 
# Set to true if we want to enable urlRewriting.  Default  is 
# false. The value of this should reflect what is set in the 
# web container settings for session management.

# useURLEncoding = false

# Set to false if we want to disable cookies as the session tracking
# mechanism.  Default  is true. The value of this should reflect what
# is set in the web container settings for session management.

# useCookies = true

# A string value of either "true" or "false", the default is "false".
# Enables WXS client HTTP Sessions statistics tracking.

# enableSessionStats = false

# Overrides the retrieved session ID of an application. 
# The default is to use the ID derived from the HttpSession.getId() method. 
# Enables WXS client HTTP Sessions to override 
# the unique session ID of an application so that all applications are retrieved 
# with the same ID.
# Set to the implementation of the 
# com.ibm.websphere.xs.sessionmanager.SessionIDOverride interface. 
# This interface determines the HttpSession ID based on 
# the HttpServletRequest object.

# sessionIdOverrideClass =  

# A string of WXS client HTTP statistics specification.

# sessionStatsSpec = session.all = enabled 

# Set to true if your environment contains multiple applications that
# use unique cookie names. Default  is false, which assumes all applications
# are using the same cookie name.

# applicationQualifiedCookies=false


13.1.8. Example: Overriding the session ID with the sessionIdOverrideClass interface

We can override the retrieved session ID of an application. The default is to use the ID derived from the HttpSession.getId() method.


Client-based preload example

The following sample code snippet shows .... 

public class CustomSessionID implements com.ibm.websphere.xs.sessionmanager.SessionIDOverride {

    public void init(InitializationContext ctx) {
    }

    public void destroy() {
    }

    public String getID(SessionIDContext ctx) {
        HttpServletRequest req = ctx.getRequest();

        String sessionId = (String) req.getAttribute("AppID");
        if (sessionId != null) {
            // sessionId is stored in the request as attribute "AppID" for this user             
            return sessionId;
        }
        
        Cookie[] cookies = req.getCookies();
        if (cookies != null) {
            for (int i = 0; i < cookies.length; i ++) {
                // if the request does not yet contain the AppID attribute, then the "AppID" cookie must exist
                if (cookies[i].getName().equals("AppID")) {
                    return cookies[i].getValue();
                }
            }
        }
        return null;
    }}


Configure dynamic cache instances

The WebSphere Dynamic Cache Service supports the creation of both a default cache instance (baseCache) as well as additional servlet and object cache instances.

The default cache instance (baseCache) was initially the only dynamic cache instance supported by the WAS and is currently the out-of-box dynamic cache instance used WebSphere Commerce Suite. The additional servlet and object cache instances were added in later releases of the WAS and are configured in a separate "cache instance" section of the WebSphere Administrative Console.


  1. Configure baseCache to use WXS as dynamic cache provider

    2. The default dynamic cache instance, also known as baseCache, is the default of a dynamic cache instance created by the WAS dynamic cache service. This servlet dynamic cache instance is used by products such as IBM WebSphere Commerce. Unlike other cache instances defined with WAS, baseCache is specific to a single server or cluster instance.

    Use this procedure to configure the baseCache instance in WAS for use with WXS as the dynamic cache provider.

    To use the dynamic cache provider, WXS must be installed on top of the WAS node deployments, including the dmgr node.

    WXS catalog service domain must be configured.

    A WXS grid environment, that consists of one or more catalog and container servers must be started.

    If the catalog servers within the catalog service domain have SSL enabled or we want to use SSL for a catalog service domain with SSL supported, then global security must be enabled in the WAS admin console. You require SSL for a catalog server by setting the transportType attribute to SSL-Required in the Server properties file .

    The steps in this procedure are for v8.0 of the WAS admin console.

    WXS v8.6 is not supported on versions of WAS prior to v7.0.

    The following procedure is specific to the remote WXS dynamic cache topology. All other topologies, including embedded, embedded-partitioned, and local, are now deprecated in WXS v8.6.

    1. Start the WAS admin console.

    2. In the top menu, click...

        Servers | Server Type | WebSphere application servers | server_name | Configuration | Container Services | Dynamic cache service

    3. From the Cache provider drop-down list, select...

        WebSphere eXtreme Scale

      If you do not see WXS as a dynamic cache provider, then your WAS profile has not been augmented for WebSphere WXS.

    4. Set cache size in the Cache size box.

      The cache size value specifies the maximum number of entries allowed in each partition within a WXS grid for this dynamic cache instance. The default is 2000 entries in each partition.

    5. Select the Enable cache replication box. Enabling this checkbox means that cached data is stored remotely in the grid and not locally. This box must be selected when using WXS as the cache provider.

    6. Click Apply or OK and save the configuration.

    7. In the top menu, click...

        Servers | Server Type | WebSphere application servers | server_name | Configuration | Web Container Settings | Web container

    8. Select the check box...

    9. Click Apply or OK and save the configuration.


  2. Configure object or servlet dynamic cache instances

    3. WAS allows us to configure multiple object or servlet dynamic cache instances in addition to the default instance. Use this procedure to configure additional object or servlet cache instances.

    To use the dynamic cache provider, WXS must be installed on top of the WAS node deployments, including the dmgr node.

    WXS catalog service domain must be configured.

    A WXS grid environment, that consists of one or more catalog and container servers must be started.

    If the catalog servers within the catalog service domain have SSL enabled or we want to use SSL for a catalog service domain with SSL supported, then global security must be enabled in the WAS admin console. You require SSL for a catalog server by setting the transportType attribute to SSL-Required in the Server properties file .

    There are two types of cache instances we can create with this procedure, object cache instances and servlet cache instances. An object cache instance is a location in addition to the default shared dynamic cache where J2EE applications can store objects. After configuring object cache instances, we can use the DistributedMap or DistributedObjectCache interfaces in the com.ibm.websphere.cache package to programmatically access the cache instances.

    Servlet cache instances are locations, in addition to the default dynamic cache, where dynamic cache can store the output and the side effects of an invoked servlet. The JNDI name specified for the cache instance in the administrative console maps to the cache instance element in cachespec.xml. Any <cache-entry> elements specified within a <cache-instance> element are created in that specific cache instance. Any <cache-entry> elements specified outside of a <cache-instance> element are stored in the default dynamic cache instance.

    The steps in this procedure are for v8.0 of the WAS admin console.

    WXS v8.6 is not supported on versions of WAS prior to v7.0.

    The following procedure is specific to the remote WXS dynamic cache topology. All other topologies, including embedded, embedded-partitioned, and local, are now deprecated in WXS v8.6.

    To configure an object or servlet cache with the WAS admin console...

    1. Start the WAS admin console.

    2. In the top menu, click...

        Resources | Cache instances | Object cache instances

    3. In the Object cache instances area, select the type of cache instance we want to create. This can be either...

      • Object cache instance
      • Servlet cache instance

    4. Specify the scope of the cache instance.

      Specify a scope of cell to make the cache instance available to all the servers that are in the cell. Node scope make the cache instance available to all servers in a node. Server scope makes the cache instance available to the selected server only. If necessary, we can mix the scopes.

    5. Click Apply and save the scope.

    6. Click New and define an object cache instance.

    7. From the Cache provider drop-down list, select...

        WebSphere eXtreme Scale

      If you do not see WXS as a dynamic cache provider, then your WAS profile has not been augmented for WXS.

    8. Specify a JNDI name for the dynamic cache instance.

      For object caches, this name will be used when the cache is looked up. For servlet caches, this is the name attribute specified in the <cache-instance> element in cachespec.xml.

    9. Specify a JNDI name for the dynamic cache object.

    10. Set cache size in the Cache size box.

      The cache size value specifies the maximum number of entries allowed in each partition within a WXS grid for this dynamic cache instance. The default is 2000 entries in each partition.

    11. To store cached data remotely in the grid and not locally, check box...

      Enable cache replication

      This box must be selected when using WXS as the cache provider.

    12. Click Apply or OK and save the configuration.

    13. To define custom properties for the cache instance, click New

    14. In the Name box, specify...

        com.ibm.websphere.xs.dynacache.topology

    15. In the Value box, specify remote.

    16. From the Type drop-down box, select...

        java.lang.String

    17. Click Apply or OK and save the configuration.

    18. Restart the Deployment Manager and all application server processes.

    To configure an object or servlet cache using the cacheinstances.properties file...

    1. Create a cacheinstances.properties file

    2. Place cacheinstances.properties in either the application server or application class path.

      • Application.war\WEB-INF\classes
      • server_root\classes


  3. Customize a dynamic cache instance

    4. We can set custom dynamic cache instance properties in one of the following ways:

    • Use the WAS console to set JVM custom property value.

    • Set a custom property on a cache instance in the WAS admin console

      1. Configure either a default cache instance or an additional object or servlet type cache instance.

      2. Start the WAS admin console.

        These steps cannot be used for a default (baseCache) instance until you have applied WAS APAR PM71992. This fix is available in WAS versions 7.0.0.27, 8.0.0.6, and 8.5.0.2 and greater.

      3. Navigate to the desired cache instance you had configured.

      4. From the cache instance panel, click...

          Additional Properties | Custom properties | New

      5. Specify the name of the custom property name and value.

      6. Click Apply or OK and save the configuration.

      7. Restart the Deployment Manager and all application server processes.

    • Set a custom property for a cache instance using cacheinstances.properties.

      1. Add the custom property to a cacheinstances.properties file.

      2. Place cacheinstances.properties in either the application server or application class path. For example, we can use either...

          app.war\WEB-INF\classes

        ...or create a server_root\classes directory and place the file there.

      These steps cannot be used for a default (baseCache) instance.

    Because the scope for JVM properties can span to all cache instances within a WAS JVM, using cache specific custom properties in the dmgr console, with APAR PM71992 for a default cache instance, or using a cacheinstances.properties file, is preferable in many circumstances.


  4. cacheinstances.properties

    5. We can configure an object or servlet cache using cacheinstances.properties.

    Property name . x is the instance number Required Scope Possible Value Description
    cache.instance.x Yes Per cache instance any string (no default set) Cache instance name or JNDI name.
    cache.instance.x.cacheSize No Per cache instance >0 (default=2000) Maximum number of entries that are allowed in a single partition within the WXS grid. Multiply this by the number of partitions to see the capacity of the cache in the WXS grid.
    cache.instance.x.createCacheAtServerStartup No Per cache instance True or false (default=false) Specifies whether the configured cache instance is created during the server startup.
    cache.instance.x.enableServletSupport No Per cache instance True or false (default=false) Specifies whether the cache instance is servlet cache or object cache.
    cache.instance.x.enableCacheReplication Yes (only until APAR) Per cache instance True or false (default=false) Indicates that the cache is remote from the application server. This property must be set to True in WXS remote topology .
    cache.instance.x.cacheProviderName Yes Per cache instance com.ibm.ws.objectgrid.dynacache.CacheProviderImpl Indicates the dynamic cache provider. Will default to WAS provider if WXS is not specified.
    cache.instance.x.ignoreValueInInvalidationEvent No Per cache instance True or false (default=false) Specifies whether the cache value of the Invalidation event is ignored. If it is true, the cache value of Invalidation event is set to NULL when the code is returned to the caller.
    cache.instance.x.<custom property> Depends on which property we want to add. Per cache instance Depends on which property we want to add. Any custom property can be added to this file.


  5. Dynamic cache custom properties

    6. Use this table as a reference to help you set custom properties for a default dynamic cache instance or a servlet or object cache instance.

    Property name Required Scope Possible value Description
    com.ibm.websphere.xs.dynacache.topology No Per cache instance (default=remote) Indicates the topology for the cache instance. Embedded, embedded-partitioned, and local topologies are deprecated.
    com.ibm.ws.cache.CacheConfig.ignoreValueInInvalidationEvent No Per cache instance true or false (default=false) Specifies whether the cache value of the Invalidation event is ignored. If it is true, the cache value of Invalidation event is set to NULL when the code is returned to the caller.
    com.ibm.websphere.xs.dynacache.ignore_value_in_change_event No Per cache instance true or false (default=false) Specifies whether the cache value of the Change event is ignored. If it is true, the cache value of Change event is set to NULL when the code is returned to the caller.
    com.ibm.websphere.xs.dynacache.cs_override No Per cache instance Catalog service endpoint (ex. 9.5.12.345:2819) Catalog service endpoint for the WXS grid to associate with this cach instance. This field is required if not specified in WAS Administrative Console.
    com.ibm.websphere.xs.dynacache.grid_name No Per cache instance Any String (default=DYNACACHE_REMOTE) Name of the remote ObjectGrid. This must match the name used when the ObjectGrid servers were started.
    com.ibm.websphere.xs.dynacache.map_name No Per cache instance Any String (not used by default) Specifies the ObjectGrid map to be associated with this cach instance. A template map is used by default. This is only used if a template map is not desired.
    com.ibm.websphere.xs.dynacache.map_template_name No Per cache instance Any String (default=IBM_DC_PARTITIONED_.*) Name of the template map prefix. This must match the name used when the ObjectGrid servers were started.
    com.ibm.websphere.xs.dynacache.cache_name No Per cache instance Any String (default= value in cache.instance.x) Name of the unique suffix used as the name of the template map. For example, IBM_DC_PARTITIONED.<cache_name>
    com.ibm.websphere.xs.dynacache.near_cache_size No Per cache instance > 0 (default=value specified in cache.instance.x.cacheSize) Maximum number of entries that are allowed in a near cache instance. By default this value will be the same and the maximum number of entries allowed in a single partition in the remote ObjectGrid for this cache instance.


JPA level 2 (L2) cache plug-in

WXS includes level 2 (L2) cache plug-ins for both OpenJPA and Hibernate JPA providers. When you use one of these plug-ins, the application uses the JPA API. A data grid is introduced between the application and the database, improving response times.

Using WXS as an L2 cache provider increases performance when we are reading and querying data and reduces load to the database. WXS has advantages over built-in cache implementations because the cache is automatically replicated between all processes. When one client caches a value, all other clients are able to use the cached value that is locally in-memory.

We can configure the topology and properties for the L2 cache provider in the persistence.xml file.

The JPA L2 cache plug-in requires an application that uses the JPA APIs. To use WXS APIs to access a JPA data source, use the JPA loader.


JPA L2 cache topology considerations

The following factors affect which type of topology to configure:

  1. How much data do you expect to be cached?

  2. What is the expected read-to-write ratio?

    The read-to-write ratio affects the performance of the L2 cache. Each topology handles read and write operations differently.

    Applications that are mostly read-only should use embedded and intra-domain topologies when possible. Applications that do more writing should use intra-domain topologies.

  3. What is percentage of data is queried versus found by a key?

    When enabled, query operations make use of the JPA query cache. Enable the JPA query cache for applications with high read to write ratios only, for example when we are approaching 99% read operations. If you use JPA query cache, use the Embedded topology or Intra-domain topology .

    The find-by-key operation fetches a target entity if the target entity does not have any relationship. If the target entity has relationships with the EAGER fetch type, these relationships are fetched along with the target entity. In JPA data cache, fetching these relationships causes a few cache hits to get all the relationship data.

  4. What is the tolerated staleness level of the data?

    In a system with few JVMs, data replication latency exists for write operations. The goal of the cache is to maintain an ultimate synchronized data view across all JVMs. When using the intra-domain topology, a data replication delay exists for write operations. Applications using this topology must be able to tolerate stale reads and simultaneous writes that might overwrite data.


Intra-domain topology

With an intra-domain topology, primary shards are placed on every container server in the topology. These primary shards contain the full set of data for the partition. Any of these primary shards can also complete cache write operations. This configuration eliminates the bottleneck in the embedded topology where all the cache write operations must go through a single primary shard .

In an intra-domain topology, no replica shards are created, even if you have defined replicas in the configuration files. Each redundant primary shard contains a full copy of the data, so each primary shard can also be considered as a replica shard. This configuration uses a single partition, similar to the embedded topology.

JPA intra-domain topology

Related JPA cache configuration properties for the intra-domain topology: 

ObjectGridName=objectgrid_name,ObjectGridType=EMBEDDED,PlacementScope=CONTAINER_SCOPE,PlacementScopeTopology=HUB | RING

Advantages:

Limitations:


Embedded topology

Consider using an intra-domain topology for the best performance.

An embedded topology creates a container server within the process space of each application. OpenJPA and Hibernate read the in-memory copy of the cache directly and write to all of the other copies. We can improve the write performance by using asynchronous replication. This default topology performs best when the amount of cached data is small enough to fit in a single process. With an embedded topology, create a single partition for the data.

JPA embedded topology

Related JPA cache configuration properties for the embedded topology: 

ObjectGridName=objectgrid_name,ObjectGridType=EMBEDDED,MaxNumberOfReplicas=num_replicas,ReplicaMode=SYNC | ASYNC | NONE

Advantages:

Limitations:


Embedded, partitioned topology

Consider using an intra-domain topology for the best performance.

CAUTION:

Do not use the JPA query cache with an embedded partitioned topology. The query cache stores query results that are a collection of entity keys. The query cache fetches all entity data from the data cache. Because the data cache is divided up between multiple processes, these additional calls can negate the benefits of the L2 cache.

When the cached data is too large to fit in a single process, we can use the embedded, partitioned topology. This topology divides the data over multiple processes. The data is divided between the primary shards, so each primary shard contains a subset of the data. We can still use this option when database latency is high.

JPA embedded, partitioned topology

Related JPA cache configuration properties for the embedded, partitioned topology: 

ObjectGridName=objectgrid_name,ObjectGridType=EMBEDDED_PARTITION,ReplicaMode=SYNC | ASYNC | NONE,
NumberOfPartitions=num_partitions,ReplicaReadEnabled=TRUE | FALSE

Advantages:

Limitation:

For example, to cache 10 GB of data with a maximum of 1 GB per JVM, 10 JVMs are required. The number of partitions must therefore be set to 10 or more. Ideally, the number of partitions must be set to a prime number where each shard stores a reasonable amount of memory. Usually, the numberOfPartitions setting is equal to the number of JVMs. With this setting, each JVM stores one partition. If you enable replication, you must increase the number of JVMs in the system. Otherwise, each JVM also stores one replica partition, which consumes as much memory as a primary partition.

For example, in a system with four JVMs, and the numberOfPartitions setting value of

4, each JVM hosts a primary partition. A read operation has a 25 percent chance of fetching data from a locally available partition, which is much faster compared to getting data from a remote JVM. If a read operation, such as running a query, needs to fetch a collection of data that involves 4 partitions evenly, 75 percent of the calls are remote and 25 percent of the calls are local. If the ReplicaMode setting is set to either

SYNC or ASYNC and the ReplicaReadEnabled setting is set to true, then four replica partitions are created and spread across four JVMs. Each JVM hosts one primary partition and one replica partition. The chance that the read operation runs locally increases to 50 percent. The read operation that fetches a collection of data that involves four partitions evenly has 50 percent remote calls and 50 percent local calls. Local calls are much faster than remote calls. Whenever remote calls occur, the performance drops.


Remote topology

CAUTION:

Do not use the JPA query cache with a remote topology . The query cache stores query results that are a collection of entity keys. The query cache fetches all entity data from the data cache. Because the data cache is remote, these additional calls can negate the benefits of the L2 cache.

Consider using an intra-domain topology for the best performance.

A remote topology stores all of the cached data in one or more separate processes, reducing memory use of the application processes. We can take advantage of distributing your data over separate processes by deploying a partitioned, replicated WXS data grid. As opposed to the embedded and embedded partitioned configurations described in the previous sections, if we want to manage the remote data grid, you must do so independent of the application and JPA provider.

JPA remote topology

Related JPA cache configuration properties for the remote topology: 

ObjectGridName=objectgrid_name,ObjectGridType=REMOTE

The REMOTE ObjectGrid type does not require any property settings because the ObjectGrid and deployment policy is defined separately from the JPA application. The JPA cache plug-in remotely connects to an existing remote ObjectGrid.

Because all interaction with the ObjectGrid is remote, this topology has the slowest performance among all ObjectGrid types.

Advantages:

Limitation:


Migrate to Hibernate v4.0

WXS v8.5 includes level 2 cache plug-ins for the Hibernate Version 3.0 JPA provider. To migrate to Hibernate Version 4.0, then you must change a L2 cache property.

Stop any servers that run applications with the Hibernate v3.0 plug-in or in a WAS environment.

In order to migrate to Hibernate v4.0, you must change the provider_class property to region.factory_class in the persistence.xml file.

  1. Open the persistence.xml file, and locate the following property: 
    <property name="hibernate.cache.provider_class"
 value="com.ibm.com.websphere.objectgrid.hibernate.cache.ObjectGridHibernateCacheProvider"/>

  2. Update the property to the following: 
    <property name="hibernate.cache.region.factory_class"
 value="com.ibm.com.ws.objectgrid.hibernate.cache.WXSRegionFactory"/>

Configuring the Hibernate cache plug-in


JPA cache configuration properties for Hibernate v4.0

WXS includes L2 cache plug-ins for Hibernate v4.0 JPA provider. To configure the L2 cache plug-in, update properties in the persistence.xml file.

The JPA L2 cache plug-in requires an application that uses the JPA APIs. To use WXS APIs to access a JPA data source, use the JPA loader.


Hibernate 4.0 properties location

We can configure these properties individually in the persistence.xml file. 

<property name="wxs.<name_of_property>"
 value="<value>"/>

We can set the properties on the DataCache or QueryCache, for example: 

<property name="wxs.objectgrid_name"
 value="BasicObjectGrid"/>


Properties

We can configure the Hibernate v4.0 JPA cache plug-in with the following properties. The default values are used if you do not specify a value in the configuration.

wxs.objectgrid_name

Specifies the unique ObjectGrid name. The default value is the defined persistence unit name. If the persistence unit name is not available from the JPA provider, a generated name is used.

wxs.objectgrid_type

Specifies the type of ObjectGrid.

Valid values:

EMBEDDED

The default and recommended configuration type. Its default settings include:

wxs.number_of_partitions=1,

wxs.replica_mode=SYNC,

wxs.replica_read_enabled=true and

wxs.max_number_of_replicas=47. Use the wxs.replica_mode parameter to set the replication mode and the wxs.max_number_of_replicas parameter to set the maximum number of replicas. If a system has more than 47 JVMs, set the wxs.max_number_of_replicas value to be equal to the number of JVMs.

EMBEDDED_PARTITION

The type to use when the system needs to cache a large amount of data in a distributed system. The default number of partitions is

47, with a replica mode of

NONE. In a small environment that has only a few JVMs, set the wxs.number_of_partitions value to be equal to or less than the number of JVMs. We can specify the wxs.replica_mode, wxs.number_of_partitions and wxs.replica_read_enabled values to tune the system.

REMOTE

The cache tries to connect to a remote, distributed ObjectGrid from the catalog service.

wxs.max_number_of_replicas

Maximum number of replicas to be used for the cache. This value applies to the EMBEDDED type only. This number must be equal to or greater than the number of JVMs in your environment. The default value is

47.

Valid values: Greater than or equal to 1

wxs.max_used_memory

Valid values:

TRUE or FALSE

Enables eviction of cache entries when memory becomes constrained. The default value is

TRUE and evicts data when the JVM heap utilization threshold exceeds 70 percent. We can modify the default JVM heap utilization threshold percentage by setting the memoryThresholdPercentage property in the objectGridServer.properties file and placing this file in the class path.

wxs.number_of_partitions

Valid values: Greater than or equal to 1

Number of partitions to be used for the cache. This property applies when the wxs.objectgrid_type value is set to EMBEDDED_PARTITION. The default value is

47. For the EMBEDDED type, the wxs.number_of_partitions value is always

1.

wxs.placement_scope

Indicates the granularity of a single instance of a map set.

Valid values:

DOMAIN_SCOPE

(false ) Places one primary shard for each partition on a container server within the catalog service domain. Replica shards for each partition are placed on the other container servers within the catalog service domain.

CONTAINER_SCOPE

Places a primary shard on each container server in the catalog service domain.

wxs.placement_scope_topology

Defines the linking topology of the container servers within the catalog service domain. This value is only used when the wxs.placement_scope value is set to something other than

DOMAIN_SCOPE.

Valid values:

HUB

(false ) If the hub topology is selected, then a single data grid is selected to be the hub. Every other data grid connects to the hub. This topology is fairly scalable because the spokes have a single connection. The hub can become a bottleneck and temporary single point of failure. The hub is relocated to another container server when it fails. The advantage to this configuration is more complex arbitration code can be written that allows a single point, the hub, to handle all collisions.

RING

If the ring topology is selected, each data grid is linked with two other data grids. The ordering of the links is not guaranteed. However, each container that starts is likely linked to the first container and last container to be added to the ring. This topology is the most scalable, but only two links can fail before being temporarily cut off. If the container servers fail, links are established among the survivors after the failure has been discovered.

wxs.replica_mode

Valid values:

SYNC/

ASYNC/

NONE

Method used to copy the cache to the replicas. This property applies when you have the wxs.objectgrid_type value set to EMBEDDED or EMBEDDED_PARTITION. The default value is

NONE for the EMBEDDED_PARTITION type and

SYNC for the EMBEDDED type. If the wxs.replica_mode value is set to NONE for the EMBEDDED wxs.objectgrid_type, the EMBEDDED type still uses a wxs.replica_mode of

SYNC.

wxs.replica_read_enabled

Valid values:

TRUE or FALSE

When enabled, clients read from replicas. This property applies to the EMBEDDED_PARTITION type. The default value is FALSE for the EMBEDDED_PARTITION type. The EMBEDDED type always sets the wxs.replica_read_enabled value to TRUE.

wxs.write_behind

For Hibernate providers only: When wxs.write_behind is enabled, updates are temporarily stored in a JVM-scoped data storage until either the wxs.write_behind_interval or wxs.write_behind_max_batch_size conditions are met.

Unless wxs.write_behind is enabled, the other write-behind configuration settings are disregarded.

Take care when using the wxs.write_behind function. Write-behind configurations introduce longer latency of data synchronization across all JVMs and a higher chance of lost updates. In a system that has write-behind configuration enabled with four or more JVMs, the update performed on one JVM has an approximate 15-second delay before the update becomes available to other JVMs. If any two JVMs update the same entry, the one that flushes the update first loses its update.

Valid values:

TRUE or FALSE

Default: FALSE

wxs.write_behind_interval

For Hibernate providers only: Specifies the time interval in milliseconds to flush updates to the cache.

Valid values: Greater than or equal to 1

Default: 5000 (5 seconds)

wxs.write_behind_pool_size

For Hibernate providers only: Maximum size of the thread pool used in flushing updates to the cache.

Valid values: Greater than or equal to 1

Default: 5

wxs.write_behind_max_batch_size

For Hibernate providers only: Maximum batch size per region cache in flushing updates to the cache. For example, if the size is set to 1000, and the updates stored in the write-behind storage of a region cache exceeds 1000 entries, the updates are flushed to the cache, even if the specified wxs.write_behind_interval condition is not met. Updates flush to the cache either approximately at the number of seconds specified by the wxs.write_behind_interval value or whenever the size of write behind storage of each region cache exceeds 1000 entries. Note, in the case of the wxs.write_behind_max_batch_size condition being met; only the region cache that meets this condition flushes its updates in write-behind storage to cache. A region cache usually corresponds to an entity or a query.

Valid values: Greater than or equal to 1

Default: 1000


Configure the OpenJPA cache plug-in

We can configure both DataCache and QueryCache implementations for OpenJPA.

  1. Set properties in your persistence.xml file to configure the OpenJPA cache plug-in: We can set these properties on either the DataCache or Query cache implementation.

    DataCache and QueryCache configurations are independent of one another. We can enable either configuration. However, if both configurations are enabled, the QueryCache configuration uses the same configuration as the DataCache configuration, and its configuration properties are discarded. 

    <property name="openjpa.DataCache"
          value="<object_grid_datacache_class(<property>=<value>,...)"/>
    or 
    <property name="openjpa.QueryCache"
          value="<object_grid_querycache_class(<property>=<value>,...)"/>
    We can enable the QueryCache configuration for embedded and embedded-intradomain topologies only.

    We can specify the ObjectGridName property, the ObjectGridType property, and other simple deployment policy-related properties in the property list of the ObjectGrid cache class to customize cache configuration. An example follows: 

    <property name="openjpa.DataCache"
          value="com.ibm.websphere.objectgrid.openjpa.ObjectGridDataCache(
          ObjectGridName=BasicTestObjectGrid,ObjectGridType=EMBEDDED, 
          maxNumberOfReplicas=4)"/>
<property name="openjpa.QueryCache"
          value="com.ibm.websphere.objectgrid.openjpa.ObjectGridQueryCache()"/>
<property name="openjpa.RemoteCommitProvider" value="sjvm"/>

  2. In the persistence.xml file, you also must set the openjpa.RemoteCommitProvider property to sjvm. 
    <property name="openjpa.RemoteCommitProvider" value="sjvm"/>

  3. Optional: To further customize the data grid used by the cache, we can provide additional settings with XML files.

    For most scenarios, setting cache properties should be sufficient. To further customize the ObjectGrid used by the cache, we can provide OpenJPA ObjectGrid configuration XML files in the META-INF directory similarly to the persistence.xml file. During initialization, the cache tries to locate these XML files and process them if found.

    There are three types of OpenJPA ObjectGrid configuration XML files:

    • openjpa-objectGrid.xml (ObjectGrid configuration)

      File path: META-INF/openjpa-objectGrid.xml

      This file is used to customize ObjectGrid configuration for both the EMBEDDED and EMBEDDED_PARTITION type. With the REMOTE type, this file is ignored. By default, each entity class is mapped to its own BackingMap configuration named as an entity class name within the ObjectGrid configuration. For example, com.mycompany.Employee entity class is mapped to com.mycompany.Employee BackingMap. The default BackingMap configuration is

      readOnly="false",

      copyKey="false",

      lockStrategy="NONE", and

      copyMode="NO_COPY". We can customize some BackingMaps with your chosen configuration. Use the ALL_ENTITY_MAPS reserved keyword to represent all maps excluding other customized maps listed in the openjpa-objectGrid.xml file. BackingMaps that are not listed in this openjpa-objectGrid.xml file use the default configuration. If customized BackingMaps do not specify the BackingMaps attribute or properties and these attributes are specified in the default configuration, the attribute values from the default configuration are applied. For example, if an entity class is annotated with

      timeToLive=30, the default BackingMap configuration for that entity has a timeToLive=30. If the custom openjpa-objectGrid.xml file also includes that BackingMap but does not specify timeToLive value, then the customize BackingMap has a timeToLive=30 value by default. The openjpa-objectGrid.xml file intends to override or extend the default configuration.

    • openjpa-objectGridDeployment.xml (deployment policy)

      File path: META-INF/openjpa-objectGridDeployment.xml

      This file is used to customize deployment policy. When customizing deployment policy, if the openjpa-objectGridDeployment.xml file is provided, the default deployment policy is discarded. All deployment policy attribute values are from the provided openjpa-objectGridDeployment.xml file.

    • openjpa-objectGrid-client-override.xml (client ObjectGrid override configuration)

      File path: META-INF/openjpa-objectGrid-client-override.xml

      This file is used to customize a client-side ObjectGrid. By default, the ObjectGrid cache applies a default client override ObjectGrid configuration that disables a near cache. We can enable the near cache by providing the openjpa-objectGrid-client-override.xml file that overrides this configuration. The way that the openjpa-objectGrid-client-override.xml file works is similar to the openjpa-objectGrid.xml file. It overrides or extends the default client ObjectGrid override configuration.

    Depending on the configured WXS topology, we can provide any one of these three XML files to customize that topology.

    For both the EMBEDDED and EMBEDDED_PARTITION types, we can provide any one of the three XML files to customize the ObjectGrid, deployment policy, and client ObjectGrid override configuration.

    For a REMOTE ObjectGrid, the ObjectGrid cache does not create a dynamic ObjectGrid. Instead, the cache only obtains a client-side ObjectGrid from the catalog service. We can only provide the openjpa-objectGrid-client-override.xml file to customize the client ObjectGrid override configuration.

  4. Optional: (Remote configurations only) Set up an external WXS system if we want to configure a cache with a REMOTE ObjectGrid type.

    Set up an external WXS system if we want to configure a cache with a REMOTE ObjectGrid type. You need both ObjectGrid and ObjectGridDeployment configuration XML files that are based on the persistence.xml file to set up an external system.


Results

EMBEDDED, EMBEDDED_PARTITION, or intra-domain configuration:

When an application starts, the plug-in automatically detects or starts a catalog service, starts a container server, and connect the container servers to the catalog service. The plug-in then communicates with the ObjectGrid container and its peers running in other application server processes using the client connection.

REMOTE configuration:

The deployment policy is specified separately from the JPA application. An external ObjectGrid system has both catalog service and container server processes. Start a catalog service before starting container servers.


What to do next


Example: OpenJPA ObjectGrid XML files

OpenJPA ObjectGrid XML files should be created based on the configuration of the persistence unit.


persistence.xml file

A persistence.xml file that is an example that represents the configuration of a persistence unit follows: 

<persistence xmlns="http://java.sun.com/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  version="1.0">
  <persistence-unit name="AnnuityGrid">
    <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
    <class>com.ibm.wssvt.acme.annuity.common.bean.jpa.AnnuityPersistebleObject</class>
    <class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Annuity</class>
    <class>com.ibm.wssvt.acme.annuity.common.bean.jpa.FixedAnnuity</class>
    <class>com.ibm.wssvt.acme.annuity.common.bean.jpa.EquityAnnuity</class>
    <class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Payout</class>
    <class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Rider</class>
    <class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Payor</class>
    <class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Person</class>
    <class>com.ibm.wssvt.acme.annuity.common.bean.jpa.AnnuityHolder</class>
    <class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Contact</class>
    <class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Address</class>
    <exclude-unlisted-classes>true</exclude-unlisted-classes>

    <properties>
    <!-- Database setting -->


    <!--  enable cache -->
      <property name="openjpa.DataCache"
        value="com.ibm.websphere.objectgrid.openjpa.ObjectGridDataCache(objectGridName=Annuity,
              objectGridType=EMBEDDED, maxNumberOfReplicas=4)" />
      <property name="openjpa.RemoteCommitProvider" value="sjvm" />
      <property name="openjpa.QueryCache" 
                value="com.ibm.websphere.objectgrid.openjpa.ObjectGridQueryCache()" />
    </properties>
  </persistence-unit>
</persistence>


openjpa-objectGrid.xml file

The openjpa-objectGrid.xml file is used to customize ObjectGrid configuration for both the EMBEDDED and EMBEDDED_PARTITION type. The openjpa-objectGrid.xml file that matches the persistence.xml file follows: 

<?xml version="1.0" encoding="UTF-8"?>
<?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="Annuity">
      <backingMap name="com.ibm.wssvt.acme.annuity.common.bean.jpa.Annuity" readOnly="false" copyKey="false"
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="com.ibm.wssvt.acme.annuity.common.bean.jpa.Annuity" />
      <backingMap name="com.ibm.wssvt.acme.annuity.common.bean.jpa.Address" readOnly="false" copyKey="false"
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="com.ibm.wssvt.acme.annuity.common.bean.jpa.Address" />
      <backingMap name="com.ibm.wssvt.acme.annuity.common.bean.jpa.Payor" readOnly="false" copyKey="false"
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="com.ibm.wssvt.acme.annuity.common.bean.jpa.Payor" />
      <backingMap name="com.ibm.wssvt.acme.annuity.common.bean.jpa.Person" readOnly="false" copyKey="false"
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="com.ibm.wssvt.acme.annuity.common.bean.jpa.Person" />
      <backingMap name="com.ibm.wssvt.acme.annuity.common.bean.jpa.Contact" readOnly="false" copyKey="false"
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="com.ibm.wssvt.acme.annuity.common.bean.jpa.Contact" />
      <backingMap name="com.ibm.wssvt.acme.annuity.common.bean.jpa.AnnuityPersistebleObject" 
                  readOnly="false" copyKey="false"
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="com.ibm.wssvt.acme.annuity.common.bean.jpa.AnnuityPersistebleObject" />
      <backingMap name="com.ibm.wssvt.acme.annuity.common.bean.jpa.Rider" readOnly="false" copyKey="false"
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="com.ibm.wssvt.acme.annuity.common.bean.jpa.Rider" />
      <backingMap name="com.ibm.wssvt.acme.annuity.common.bean.jpa.Payout" readOnly="false" copyKey="false"
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="com.ibm.wssvt.acme.annuity.common.bean.jpa.Payout" />
      <backingMap name="ObjectGridQueryCache" readOnly="false" copyKey="false"  
                  lockStrategy="NONE" copyMode="NO_COPY" pluginCollectionRef="ObjectGridQueryCache" 
                  evictionTriggers="MEMORY_USAGE_THRESHOLD"  />
    </objectGrid>
  </objectGrids>
  <backingMapPluginCollections>
    <backingMapPluginCollection id="com.ibm.wssvt.acme.annuity.common.bean.jpa.Annuity">
      <bean id="ObjectTransformer" 
            className="com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer" />
      <bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
      </bean>
    </backingMapPluginCollection>
    <backingMapPluginCollection id="com.ibm.wssvt.acme.annuity.common.bean.jpa.Address">
      <bean id="ObjectTransformer" 
            className="com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer" />
      <bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
      </bean>
    </backingMapPluginCollection>
    <backingMapPluginCollection id="com.ibm.wssvt.acme.annuity.common.bean.jpa.Payor">
      <bean id="ObjectTransformer" 
            className="com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer" />
      <bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
      </bean>
    </backingMapPluginCollection>
    <backingMapPluginCollection id="com.ibm.wssvt.acme.annuity.common.bean.jpa.Person">
      <bean id="ObjectTransformer" 
            className="com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer" />
      <bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
      </bean>
    </backingMapPluginCollection>
    <backingMapPluginCollection id="com.ibm.wssvt.acme.annuity.common.bean.jpa.Contact">
      <bean id="ObjectTransformer" 
            className="com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer" />
      <bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
      </bean>
    </backingMapPluginCollection>
    <backingMapPluginCollection 
            id="com.ibm.wssvt.acme.annuity.common.bean.jpa.AnnuityPersistebleObject">
      <bean id="ObjectTransformer" 
            className="com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer" />
      <bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
      </bean>
    </backingMapPluginCollection>
    <backingMapPluginCollection id="com.ibm.wssvt.acme.annuity.common.bean.jpa.Rider">
      <bean id="ObjectTransformer" 
            className="com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer" />
      <bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
      </bean>
    </backingMapPluginCollection>
    <backingMapPluginCollection id="com.ibm.wssvt.acme.annuity.common.bean.jpa.Payout">
      <bean id="ObjectTransformer" 
            className="com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer" />
      <bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
      </bean>
    </backingMapPluginCollection>
    <backingMapPluginCollection id="ObjectGridQueryCache">
      <bean id="MapIndexPlugin" className="com.ibm.websphere.objectgrid.plugins.index.HashIndex" >
          <property name="Name" type="java.lang.String" 
                    value="QueryCacheKeyIndex" description="name of index"/>
          <property name="POJOKeyIndex" type="boolean" value="true" description="POJO Key Index "/>
      </bean>
      <bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
      </bean>
    </backingMapPluginCollection>
  </backingMapPluginCollections>
</objectGridConfig>

  1. Each entity is mapped to a BackingMap named as the fully qualified entity class name.

    By default, entities are part of the second level cache. In the Entity classes which needs to be excluded from caching, We can include the @DataCache(enabled=false) annotation on the entity class to exclude from L2 cache: 

    import org.apache.openjpa.persistence.DataCache;
@Entity @DataCache(enabled=false)
public class OpenJPACacheTest { ... }

  2. If entity classes are in an inheritance hierarchy, child classes map to the parent BackingMap. The inheritance hierarchy shares a single BackingMap.

  3. The ObjectGridQueryCache map is required to support QueryCache.

  4. The backingMapPluginCollection for each entity map must have the ObjectTransformer using the com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer class.

  5. The backingMapPluginCollection for ObjectGridQueryCache map must have the key index named as QueryCacheKeyIndex as shown in the sample.

  6. The evictor is optional for each map.


openjpa-objectGridDeployment.xml file

The openjpa-objectGridDeployment.xml file is used to customize deployment policy. The openjpa-objectGridDeployment.xml file that matches the persistence.xml file follows: 

openjpa-objectGridDeployment.xml

<?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="Annuity">
    <mapSet name="MAPSET_Annuity" numberOfPartitions="1" numInitialContainers="1" 
            minSyncReplicas="0" maxSyncReplicas="4" maxAsyncReplicas="0" 
            replicaReadEnabled="true">
      <map ref="com.ibm.wssvt.acme.annuity.common.bean.jpa.Annuity" />
      <map ref="com.ibm.wssvt.acme.annuity.common.bean.jpa.Address" />
      <map ref="com.ibm.wssvt.acme.annuity.common.bean.jpa.Payor" />
      <map ref="com.ibm.wssvt.acme.annuity.common.bean.jpa.Person" />
      <map ref="com.ibm.wssvt.acme.annuity.common.bean.jpa.Contact" />
      <map ref="com.ibm.wssvt.acme.annuity.common.bean.jpa.AnnuityPersistebleObject" />
      <map ref="com.ibm.wssvt.acme.annuity.common.bean.jpa.Rider" />
      <map ref="com.ibm.wssvt.acme.annuity.common.bean.jpa.Payout" />
      <map ref="ObjectGridQueryCache" />
    </mapSet>
  </objectgridDeployment>
</deploymentPolicy>
The ObjectGridQueryCache map is required to support QueryCache.


Configure the Hibernate cache plug-in

We can enable the cache to use the Hibernate cache plug-in by specifying properties files.

  1. If we are using WAS, place the Java Archive (JAR) files in the appropriate locations for the configuration.

    The Hibernate cache plug-in is packaged in the wxshibernate.jar file and is installed in the /path/to/opt/IBM/eXtremeScale/ObjectGrid directory.

    In an integrated WAS environment, the plug-in is installed in thewas_root/optionalLibraries/ObjectGrid directory. To use the Hibernate cache plug-in, you have to include the wxshibernate.jar file in the Hibernate library. For example, if you include the Hibernate library in the application, also must include the wxshibernate.jar file. If you define a shared library to include Hibernate library, add the wxshibernate.jar file into the shared library directory.

    WXS does not install the cglib.jar file in the WAS environment. If you have existing applications or shared libraries, such as hibernate, which depend on the cglib.jar, locate the cglib.jar file and include it in the classpath. For example, if the application includes all hibernate library JAR files, but excludes the cglib.jar file available with hibernate, you must include the cglib.jar file that comes from Hibernate in the application.

  2. Set properties in your persistence.xml file to configure the Hibernate cache plug-in

    The syntax for setting properties in the persistence.xml file follows: 

    <property name="hibernate.cache.region.factory_class"
     value="com.ibm.ws.objectgrid.hibernate.cache.WXSRegionFactory"/>
<property name="hibernate.cache.use_second_level_cache" value="true"/>
<property name="hibernate.cache.use_query_cache" value="true"/>

    





     
      

    •   hibernate.cache.region.factory_class:
The value of the  region.factory_class property is the  com.ibm.ws.objectgrid.hibernate.cache.WXSRegionFactory class. 


    •  hibernate.cache.use_query_cache: To enable query cache, set the value to true on the use_query_cache property. 
  We can enable the query cache for embedded and embedded-intradomain topologies only.



    •  

        To enable write-behind caching, use the following write-behind attributes on the PROPERTY_WRITE_BEHIND
property. When write-behind caching  is enabled,  updates are temporarily stored in a JVM scope data storage until either the wxs.write_behind_interval or wxs.write_behind_max_batch_size conditions are met, when the data is flushed to the cache.


      wxs.write_behind=true, wxs.write_behind_interval=5000, wxs.write_behind_Pool_Size=10, wxs.write_behind_max_batch_size=1000
      


         Unless wxs.write_behind is enabled, the other write behind configuration settings are disregarded.




     



     
  3.  Optional: To further customize the data grid used by the cache, we can provide additional settings with XML files. 

      For most scenarios, setting cache properties should be sufficient.
To further customize the ObjectGrid used by the cache, we can provide Hibernate ObjectGrid configuration XML files in the META-INF directory similarly to the persistence.xml file. During initialization, the cache tries to locate these XML files and process them if found.  


      There are three types of Hibernate ObjectGrid configuration XML files: 



     
      

    •  hibernate-objectGrid.xml (ObjectGrid configuration)

        File path: META-INF/hibernate-objectGrid.xml 

        By default, each entity class has an associated regionName (default to entity class name) that is mapped to a BackingMap configuration named as regionName within the ObjectGrid configuration. For example, the com.mycompany.Employee entity class has an associated regionName default to com.mycompany.Employee BackingMap. The default BackingMap configuration is readOnly="false", copyKey="false", lockStrategy="NONE", and copyMode="NO_COPY".
We can customize some BackingMaps with a chosen configuration. The reserved key word "ALL_ENTITY_MAPS" can be used to represent all maps excluding other customized maps listed in the hibernate-objectGrid.xmlfile.
BackingMaps that are not listed in this hibernate-objectGrid.xml file use the default configuration.



    •  hibernate-objectGridDeployment.xml (deployment policy)

        File path: META-INF/hibernate-objectGridDeployment.xml 

        This file is used to customize deployment policy. When customizing deployment policy, if the hibernate-objectGridDeployment.xml is provided, the default deployment policy is discarded. All deployment policy attribute values will come from the provided hibernate-objectGridDeployment.xml file.



    •  hibernate-objectGrid-client-override.xml (client ObjectGrid override configuration)

        File path: META-INF/hibernate-objectGrid-client-override.xml 


        This file is used to customize a client-side ObjectGrid. By default, the ObjectGrid cache applies a default client override configuration that disables the near cache. We can enable the near cache by providing the hibernate-objectGrid-client-override.xml file that overrides this configuration. The way that the hibernate-objectGrid-client-override.xml file works is similar to the hibernate-objectGrid.xml file.
It overrides or extends the default client ObjectGrid override configuration.



     
Depending on the configured WXS topology,
we can provide any one of these three XML files to customize that topology.


      For both the EMBEDDED and EMBEDDED_PARTITION type,
we can provide any one of the three XML files to customize the ObjectGrid,
deployment policy, and client ObjectGrid override configuration.


      For a REMOTE ObjectGrid, the cache does not create a dynamic ObjectGrid.
The cache only obtains a client-side ObjectGrid from the catalog service.
We can only provide a hibernate-objectGrid-client-override.xml file to customize client ObjectGrid override configuration.



     
  4.  Optional: (Remote configurations only) Set up an external WXS system if we want to configure a cache with a REMOTE ObjectGrid type. 

      Set up an external WXS system if we want to configure a cache with a REMOTE ObjectGrid type. You need both ObjectGrid and ObjectGridDeployment configuration XML files that are based on the persistence.xml file to set up an external system. For examples of these configuration files, seeExample: Hibernate ObjectGrid XML files . 


 


 
 Results


  EMBEDDED or EMBEDDED_PARTITION configuration: 


  When an application starts, the plug-in automatically detects or starts a catalog service, starts a container server, and connect the container servers to the catalog service. The plug-in then communicates with the ObjectGrid container and its peers running in other application server processes using the client connection.


  Each JPA entity has an independent backing map assigned using the class name of the entity. Each BackingMap has the following attributes.




 
 



  REMOTE configuration: 


  The deployment policy is specified separately from the JPA application. An external ObjectGrid system has both catalog service and container server processes. Start a catalog service before starting container servers. 



 
 What to do next




 
 










  Example: Hibernate ObjectGrid XML files



  Create Hibernate ObjectGrid XML files based on the configuration of a persistence unit.

 
 
 persistence.xml file



<persistence xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">   
<persistence-unit name="AnnuityGrid">     
<provider>org.hibernate.ejb.HibernatePersistence</provider>      

<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.AnnuityPersistebleObject</class>
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Annuity</class>
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.FixedAnnuity</class>
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.EquityAnnuity</class>     
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Payout</class>     
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Rider</class>     
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Payor</class>     
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Person</class>     
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.AnnuityHolder</class>     
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Contact</class>     
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Address</class>      

<exclude-unlisted-classes>true</exclude-unlisted-classes>      

<properties>       
<property name="hibernate.show_sql" value="false" />       
<property name="hibernate.connection.url" value="jdbc:db2:Annuity" />       
<property name="hibernate.connection.driver_class" value="com.ibm.db2.jcc.DB2Driver" />       
<property name="hibernate.default_schema" value="EJB30" />        

<!-- Cache -->

<property name="hibernate.cache.region.factory_class" value="com.ibm.websphere.objectgrid.hibernate.cache.WXSRegionFactory"/>       
<property name="hibernate.cache.use_query_cache" value="true" />    
<property name="wxs.objectgrid_name" value="Annuity" />       
<property name="wxs.objectgrid_type" value="EMBEDDED" />    
<property name="wxs.max_number_of_replicas" value="4" />     
</properties>   

</persistence-unit>  

</persistence>




 
 
 hibernate-objectGridDeployment.xml file



?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="Annuity">
    <mapSet name="MAPSET_Annuity" numberOfPartitions="1" numInitialContainers="1" minSyncReplicas="0"
           maxSyncReplicas="4" maxAsyncReplicas="0" replicaReadEnabled="true">
      <map ref="IBM_HIBERNATE_GENERAL_.*" />
      <map ref="IBM_HIBERNATE_TIMESTAMPS_.*" />
    </mapSet>
  </objectgridDeployment>
</deploymentPolicy>




 
 
 hibernate-objectGrid.xml file



<?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="Annuity">
      <backingMap name="IBM_HIBERNATE_TIMESTAMPS_.*" readOnly="false" copyKey="false" 
                  lockStrategy="NONE" copyMode="NO_COPY"
                  pluginCollectionRef="IBM_HIBERNATE_TIMESTAMPS_.*"
                  template="true" />
      <backingMap name="IBM_HIBERNATE_GENERAL_.*" readOnly="false" copyKey="false" 
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="IBM_HIBERNATE_GENERAL_.*"
                  template="true" />
    </objectGrid>
  </objectGrids>
  <backingMapPluginCollections>
    <backingMapPluginCollection id="IBM_HIBERNATE_TIMESTAMPS_.*">
    </backingMapPluginCollection>
    <backingMapPluginCollection id="IBM_HIBERNATE_GENERAL_.*">
      <bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
      </bean>
    </backingMapPluginCollection>
  </backingMapPluginCollections>
</objectGridConfig>



  The IBM_HIBERNATE_GENERAL_.* and IBM_HIBERNATE_TIMESTAMPS_.*
maps are required.











  Configure a Spring cache provider



  Spring Framework v3.1 introduced a new cache abstraction. With this new abstraction, we can transparently add caching to an existing Spring application. Use  WXS as the cache provider for the cache abstraction. 





 
 



 By using the cache abstraction in the Spring framework, we can reduce the number of times that your Spring application methods run. When configured, the results of a particular method are placed in the cache. When the method is run again, the abstraction checks the cache to see if the method results are already in the cache. If the results are in the cache, the results are returned from the cache and the method does not run again. Therefore, we can reduce the number of times that expensive methods run, also decreasing the average response time of the application.




 
    

     
  1.   Configure your container servers to use the configuration files for Spring. 

      Start container servers before the Spring application that accesses the cache starts. 


      The default XML configuration files for starting a container server for the WXS Spring cache provider are in one of the following locations: 



     
      

    •  Stand-alone installations: /path/to/ObjectGrid/spring/etc 

    •  WAS installations: was_root/optionalLibraries/ObjectGrid/spring/etc 

     
 The files are named spring-remote-objectgrid.xml and spring-remote-deployment.xml. Use these files as-is, customize these files, or create your own configuration files.
 

      Run the following command to start a stand-alone container server for the WXS Spring cache provider.
Run the following command from the wxs_home /ObjectGrid/bin directory:
    Windows:  


    startOgServer.bat container1 
                  -objectGridFile ../spring/etc/spring-remote-objectgrid.xml 
                  -deploymentPolicyFile ../spring/etc/spring-remote-deployment.xml
    

     


    startOgServer.sh container1 
                  -objectGridFile ../spring/etc/spring-remote-objectgrid.xml 
                  -deploymentPolicyFile ../spring/etc/spring-remote-deployment.xml
    

    Windows:  


    startXsServer.bat container1 
                  -objectGridFile ../spring/etc/spring-remote-objectgrid.xml 
                  -deploymentPolicyFile ../spring/etc/spring-remote-deployment.xml
    

     


    startXsServer.sh container1 
                  -objectGridFile ../spring/etc/spring-remote-objectgrid.xml 
                  -deploymentPolicyFile ../spring/etc/spring-remote-deployment.xml
    




     
  2.  Configure Spring Inversion of Control (IoC) container to use  WXS as the cache provider. The WebSphere WXS cache implementation resides under the com.ibm.websphere.objectgrid.spring package. Define the following beans in your Spring IoC container configuration.


    <bean class="com.ibm.websphere.objectgrid.spring.ObjectGridCatalogServiceDomainBean"
  p:catalog-service-endpoints="CATALOG_SERVICE_ENDPOINTS" 
  p:client-override-xml="CLIENT_OVERRIDE_XML (optional)"
  p:client-security-config="CLIENT_SECURITY_CONFIG (optional)" />

<bean id="wxsGridClient" class="com.ibm.websphere.objectgrid.spring.ObjectGridClientBean" 
  p:object-grid-name="OBJECT_GRID_NAME(optional)"
  p:catalog-service-domain-ref="wxsCSDomain" />

<bean class="org.springframework.cache.support.SimpleCacheManager">
  <property name="caches">
    <set>   
      <bean class="com.ibm.websphere.objectgrid.spring.ObjectGridCache"
         p:name="CACHE_NAME"
         p:map-name="MAP_NAME (optional)"
         p:object-grid-client-ref="wxsGridClient" />
     </set>
   </property>
</bean>

    



     
    

     
     CATALOG_SERVICE_ENDPOINTS
    


     
     Specifies the ORB
host and port number.
    


     
     CLIENT_OVERRIDE_XML (optional)
    


     
     Specifies an absolute or relative path to an ObjectGrid XML file on which to alter settings on the client side as a Spring resource.
For information about specifying resources in Spring, see Spring Framework Reference Documentation: Resources .


       Example:  p:client-override-xml="file:/path/to/objectgrid.xml"

       Example:  p:client-override-xml="classpath:com/example/app/override-objectgrid.xml"

       Example:  p:client-override-xml="http://myserver/override-objectgrid.xml"

       Example:  p:client-override-xml="ftp://myserver/override-objectgrid.xml"

    


     
     CLIENT_SECURITY_CONFIG (optional)
    


     
     Specifies an absolute or relative path to a client.properties file as a Spring resource. For information about specifying resources in Spring, see Spring Framework Reference Documentation: Resources . 


      Example: 
     p:client-security-config="file:/path/to/client.properties"

    


     
     OBJECT_GRID_NAME (optional)
    


     
     Specifies the ObjectGrid name. This parameter is not needed if the container servers are started with the provided XML configuration files. This parameter must be consistent with the XML configuration files used to start the container servers.
    


     
     CACHE_NAME
    


     
     Name of the cache specified in your Spring caching application. 
    


     
     MAP_NAME (optional)
    


     
     Name of the backing map for a cache.  This parameter is not needed if the container servers are started with the provided XML configuration files. This parameter must be consistent with the XML configuration files used to start the container servers. If you use the provided XML configuration files, the MAP_NAME value is not needed. The maps for the data grid are created automatically when the Spring application runs. The dynamic map name starts with 
     IBM_SPRING_PARTITIONED_. For example: 
     IBM_SPRING_PARTITIONED_1, 
     IBM_SPRING_PARTITIONED_2, and so on.
    

    


 


 
 Example


  The following snippet creates two caches,
named 
 default and 
 books hosted by the catalog service domain at 
 localhost:2809.


<bean class="com.ibm.websphere.objectgrid.spring.ObjectGridCatalogServiceDomainBean" 
 p:catalog-service-endpoints ="localhost:2809" />  
<bean id="wxsGridClient" class="com.ibm.websphere.objectgrid.spring.ObjectGridClientBean"    
 p:catalog-service-domain-ref="wxsCSDomain" /> 
<bean class="org.springframework.cache.support.SimpleCacheManager">  
 <property name="caches">   
  <set>    
   <bean class="com.ibm.websphere.objectgrid.spring.ObjectGridCache" 
    p:name="default"     
    p:object-grid-client-ref="wxsGridClient" />   
   <bean class="com.ibm.websphere.objectgrid.spring.ObjectGridCache"     
    p:name="books"     
    p:object-grid-client-ref="wxsGridClient" />   
  </set>  
 </property>
</bean>

















  Configure database integration



  Use  WXS to lower the load on databases. Use a JPA
between  WXS and the database to integrate changes as a loader. 










  Configure JPA loaders



  A JPA Loader is a plug-in implementation that uses JPA to interact with the database.





 
 






 
    

     
  1.  Configure the necessary parameters that JPA requires to interact with a database. 

      The following parameters are required. These parameters are configured in the JPALoader or JPAEntityLoader bean,
and JPATxCallback bean.




     
      

    •  persistenceUnitName: Persistence unit name. This parameter is required for two purposes: for creating a JPA EntityManagerFactory, and for locating the JPA entity metadata in the persistence.xml file. This attribute is set on the JPATxCallback bean.


    •  JPAPropertyFactory: Specifies the factory to create a persistence property map to override the default persistence properties. This attribute is set on the JPATxCallback bean.
To set this attribute, Spring style configuration is required. 


    •  entityClassName: Entity class name that is required to use JPA methods, such as EntityManager.persist, EntityManager.find,
and so on. The JPALoader plug-in requires this parameter, but the parameter is optional for JPAEntityLoader.
For the JPAEntityLoader plug-in, if an entityClassName parameter is not configured, the entity class configured in the ObjectGrid entity map is used. You must use the same class for the WXS EntityManager and for the JPA provider. This attribute is set on the JPALoader or JPAEntityLoader bean. 


    •  preloadPartition: Partition at which the map preload is started. If the preload partition is less than zero, or greater than the total number of partitions minus 1,
the map preload is not started. The default value is -1, which means the preload does not start by default. This attribute is set on the JPALoader or JPAEntityLoader bean.


     


      Other than the four JPA parameters to be configured in WXS, JPA metadata are used to retrieve the key from the JPA entities. The JPA metadata can
be configured as annotation, or as an orm.xml file specified in the persistence.xml file. It is
not part of the WXS configuration.



     
  2.  Configure XML files for the JPA configuration. 



      Configure a JPATxCallback transaction callback along with the loader configuration . The following example is an ObjectGrid XML descriptor file (objectgrid.xml),
that has a JPAEntityLoader and JPATxCallback configured:



    configuring a loader including callback - XML example
<?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="JPAEM" entityMetadataXMLFile="jpaEMD.xml">
        <bean id="TransactionCallback" 
           className="com.ibm.websphere.objectgrid.jpa.JPATxCallback">
           <property 
              name="persistenceUnitName" 
              type="java.lang.String"  
              value="employeeEMPU" />
       </bean>
       <backingMap name="Employee" pluginCollectionRef="Employee" />
    </objectGrid>
  </objectGrids>

  <backingMapPluginCollections>
    <backingMapPluginCollection id="Employee">
        <bean id="Loader"
          className="com.ibm.websphere.objectgrid.jpa.JPAEntityLoader">
       <property 
               name="entityClassName" 
               type="java.lang.String"  
               value="com.ibm.ws.objectgrid.jpa.test.entity.Employee"/>
        </bean>
    </backingMapPluginCollection>
  </backingMapPluginCollections>
</objectGridConfig>

    


      To configure a JPAPropertyFactory,
you have to use a Spring style configuration. The following is an
XML configuration file sample,JPAEM_spring.xml which
configures a Spring bean to be used for WXS configurations.



    configuring a loader including JPA property factory - XML example
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:aop="http://www.springframework.org/schema/aop"
       xmlns:tx="http://www.springframework.org/schema/tx"
       xmlns:objectgrid="http://www.ibm.com/schema/objectgrid"
       xsi:schemaLocation="http://www.springframework.org/schema/beans 
           http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">

  <objectgrid:JPAEntityLoader id="jpaLoader" 
  entityClassName="com.ibm.ws.objectgrid.jpa.test.entity.Employee"/>
  <objectgrid:JPATxCallback id="jpaTxCallback" persistenceUnitName="employeeEMPU" />
</beans>

    


      The Objectgrid.xml configuration XML file follows. Notice the ObjectGrid name is 
     JPAEM,
which matches the ObjectGrid name in the JPAEM_spring.xml Spring
configuration file.



    JPAEM loader configuration  - XML example
<?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="JPAEM" entityMetadataXMLFile="jpaEMD.xml">
      <bean id="TransactionCallback" 
            className="{spring}jpaTxCallback"/>
        <backingMap name="Employee" pluginCollectionRef="Employee" 
                    writeBehind="T4"/>
      </objectGrid>
  </objectGrids>
    
  <backingMapPluginCollections>
    <backingMapPluginCollection id="Employee">
       <bean id="Loader" className="{spring}jpaLoader" />
    </backingMapPluginCollection>
  </backingMapPluginCollections>
</objectGridConfig>

    


      An entity can be annotated with both the JPA annotations
and WXS entity manager
annotations. Each annotation has an XML equivalent that can be used.
 Thus, WXS added
the Spring namespace. We can also configure these using the Spring
namespace support. 


 












  Configure a JPA time-based data updater



  We can configure
a time-based database update using XML
for a local or distributed WXS configuration. We can also configure a local configuration programmatically. 




  Create a timeBasedDBUpdate configuration.


 



 
 What to do next



Start the JPA time-based data updater.













  Configure REST data services



  Use  WXS REST
data service with WebSphere Application Server version
7.0,WebSphere Application Server Community Edition and Apache Tomcat.


 

  The included sample has source code and compiled
binaries
to run a partitioned data grid.  This sample demonstrates how to create
a simple data grid, model the data using entities and provides two
command-line client applications that allow adding and querying entities
using Java or C#.


  The sample Java client uses the Java EntityManager API to persist
and query data in the data grid.  This client can be run in Eclipse
or using a command-line script.  Note that the sample Java client does not demonstrate the REST data service, but allows updating data in the grid, so a web browser or other clients can read the data. 


  The sample Microsoft WCF Data Services C# client communicates
with the WXS data grid through the REST data service using the .NET framework.  The WCF Data Services client can be used to both update and query the data grid.


  Getting started sample topology.  HTTP
clients using the REST data service and Java clients
can access the same data grid.

  





 
    

     
  1.  Configure and start the WXS data grid. 


     
  2.  Configure and start the REST data service in a web server. 


     
  3.  Run a client to interact with the REST data service. Two
options are available:


     
      

    1.  Run the sample Java client to populate the grid with data using the EntityManager API and query
the data in the grid using a web browser and the WXS REST data service. 


    2.  Run the sample WCF Data Services C# client. 

     


 









  Enable the REST data service



  The REST data service can represent  WXS entity metadata to represent each entity as an EntitySet.

 
 
 Starting a sample WXS data grid



  In general, before starting the REST data service, start the WXS data grid.  The following steps will start a single WXS catalog service process and two container server processes.


   WXS can be installed using three different methods: 



 
 












  Scalable data model in WXS



  The Microsoft Northwind sample uses the Order Detail table to establish a many-to-many association between Orders and Products. 


  Object to relational mapping specifications (ORMs) such as the ADO.NET
Entity Framework and JPA can map the tables and relationships using entities.  However, this architecture does not scale.  Everything must be located on the same machine, or an expensive cluster of machines to perform well.


  Microsoft SQL Server Northwind sample schema diagram 
  


  To create a scalable version of the sample, the entities must be modeled so each entity or group of related entities can be partitioned based off a single key.  By creating partitions on a single key, requests can be spread out among multiple, independent servers.
 To achieve this configuration, the entities have been divided into two trees: the Customer and Order tree and the Product and Category tree.  In this model, each tree can be partitioned independently and therefore can grow at different rates, increasing scalability.


  Customer and Order entity schema diagram 
  


  For example, both Order and Product have unique, separate integers as keys.  In fact, the Order and Product tables are really independent of each other.  For example, consider the effect of the size of a catalog, the number of products you sell, with the total number of orders. Intuitively, it might seem that having many products implies also having many orders, but this is not necessarily the case.
 If this were true, you could increase sales by just adding more products to the catalog.  Orders and products have their own independent tables.  We can further extend this concept so that orders and products each have their own separate, data grids.  With independent data grids, we can control the number of partitions and servers, in addition to the size of each data grid separately so that your
application can scale.  If you double the size of the catalog, you must double the products data grid, but the order grid might be unchanged.
 The converse is true for an order surge, or expected order surge.


  In the schema, a Customer has zero or more Orders, and an Order has line items (OrderDetail), each with one specific product.  A Product is identified by ID (the Product key) in each OrderDetail.  A single data grid stores Customers, Orders, and OrderDetails with Customer as the root entity of the data grid.  We can retrieve Customers by ID, but you must get Orders starting with the Customer ID.  So customer ID is added to Order as part of its key.  Likewise, the customer ID
and order ID are part of the OrderDetail ID.


  Category and Product entity schema diagram 
  


  In the Category and Product schema, the Category is the schema root.  With this schema, customers can query products by category.
 










  Retrieve and updating data with REST



  The OData protocol requires that all entities can be addressed by their canonical form. This means that each entity must include the key of the partitioned, root entity, the schema root.


  The following is an example of how to use the association from a root entity to address a child in :


/Customer('ACME')/order(100)




  In WCF Data Services, the child entity must be directly addressable,
meaning that the key in the schema root must be a part of the key of the child:   /Order(customer_customerId='ACME', orderId=100).
This is achieved by creating an association to the root entity where the one-to-one or many-to-one association to the root entity is also identified as a key. When entities are included as part of the key, the attributes of the parent entity are exposed as key properties.


  Customer and Order entity schema diagram 
  


  The Customer/Order entity schema diagram illustrates how each entity is partitioned using the Customer.  The Order entity includes the Customer as part of its key and is therefore directly accessible.
 The REST data service exposes all key associations as individual properties:  Order has customer_customerId and OrderDetail has order_customer_customerId
and order_orderId.


  Using the EntityManager API, we can find
the Order using the Customer and order id:


  
transaction.begin();
// Look-up the Order using the Customer.  We only include the Id
// in the Customer class when building the OrderId key instance.
Order order = (Order) em.find(Order.class, 
    new OrderId(100, new Customer('ACME')));
...
transaction.commit();





  When using the REST data service, the Order can be retrieved with either of the URLs:



 
 



  The customer key is addressed using the attribute
name
of the Customer entity, an underscore character and the attribute
name of the customer id:  customer_customerId.


  An entity can
also include a non-root entity as part of its key if all of the ancestors
to the non-root entity have key associations to the root.  In this
example, OrderDetail has a key-association to Order and Order has
a key-association to the root Customer entity.  Using the EntityManager
API:


  
transaction.begin();
// Construct an OrderDetailId key instance.  It includes 
// The Order and Customer with only the keys set. 
Customer customerACME = new Customer("ACME");
Order order100 = new Order(100, customerACME);
OrderDetailId orderDetailKey = 
    new OrderDetailId(order100, "COMP");
OrderDetail orderDetail = (OrderDetail) 
    em.find(OrderDetail.class, orderDetailKey); 
...




  The REST data service allows addressing the OrderDetail directly:


  
/OrderDetail(productId=500, order_customer_customerId='ACME', order_orderId =100)




  The association from the OrderDetail entity to the Product
entity has been broken to allow partitioning  the Orders and Product
inventory independently.  The OrderDetail entity stores the category
and product id instead of a hard relationship.  By decoupling the two entity schemas, only one partition is accessed at a time.


  The Category and Product schema illustrated in the diagram shows
that the root entity is Category and each Product has an association
to a Category entity.  The Category entity is included in the Product
identity.  The REST data service exposes a key property:  category_categoryId
which allows directly addressing the Product.


  Because Category
is the root entity, in a partitioned environment, the Category must
be known to find the Product.  Using the EntityManager API,
the transaction must be pinned to the Category entity prior to finding
the Product.


  Using the EntityManager API:


  
transaction.begin();
// Create the Category root entity with only the key.  
// This allows us to construct a ProductId without needing to find
// The Category first.  The transaction is now pinned to the 
// partition where Category "COMP" is stored.
Category cat = new Category("COMP");
Product product = (Product) em.find(Product.class, 
    new ProductId(500, cat)); 
...




  The REST data service allows addressing the Product directly:


  
/Product(productId=500, category_categoryId='COMP')












  Starting a stand-alone data grid for REST data services



  Follow these steps to start the  WXS REST service sample
data grid for a stand-alone WXS deployment.




Install the  WXS Trial
or full product:



 
 



 Start the  WXS sample
data grid.




 
    

     
  1.  Start the catalog service process.
Open a command-line or terminal window and set the JAVA_HOME environment variable:


      

    •   
       export JAVA_HOME=java_home 

    •  Windows:  
       set JAVA_HOME=java_home 

     



     
  2.  
     cd restservice_home/gettingstarted
    


     
  3.  Start the catalog service process. To start the service without WXS security,
use the following commands.


      

    •   
       ./runcat.sh 

    •  Windows:  
       runcat.bat 

     
 To start the service withWXS security...


      

    •   
       ./runcat_secure.sh 

    •  Windows:  
       runcat_secure.bat 

     



     
  4.  Start two container server processes. Open another command-line or terminal window and set the JAVA_HOME environment variable:


      

    •   
       export JAVA_HOME=java_home 

    •  Windows:  
       set JAVA_HOME=java_home 

     



     
  5.  
     cd restservice_home/gettingstarted
    


     
  6.  Start a container server process: 

      To start the server without WXS security,
use the following commands:


      

    •   
       ./runcontainer.sh container0


    •  Windows:  
       runcontainer.bat container0


     
 To start the server withWXS security...


      

    •   
       ./runcontainer_secure.sh container0


    •  Windows:  
       runcontainer_secure.bat container0


     



     
  7.  Open another command-line or terminal window and set the JAVA_HOME environment variable:


      

    •   
       export JAVA_HOME=java_home 

    •  Windows:  
       set JAVA_HOME=java_home 

     



     
  8.  
     cd restservice_home/gettingstarted
    


     
  9.  Start a second container server process. 

      To start the server without WXS security,
use the following commands.


      

    •   
       ./runcontainer.sh container1


    •  Windows:  
       runcontainer.bat container1


     
 To start the server with WXS security...


      

    •   
       ./runcontainer_secure.sh container1


    •  Windows:  
       runcontainer_secure.bat container1


     


 


 
 Results



Wait until the WXS containers are ready before proceeding with the next steps.  The container servers are ready when the following message is displayed in the terminal window:

  CWOBJ1001I: ObjectGrid Server container_name is ready to process requests.
Where container_name is the name of the container that was started.









  Starting a data grid for REST data services in WAS



  Follow these steps to start a stand-alone  WXS REST service sample data grid for a WebSphere WXS deployment that is integrated with WAS.
 Although  WXS is integrated with WAS, these steps start a stand-alone WebSphere WXS catalog service process and container.




Install the product into a WAS v7.0.0.5 or later installation directory with security disabled. Augment at least one application server profile.


 Start the  WXS sample data grid.




 
    

     
  1.  Start the catalog service process.
Open a command-line or terminal window and set the JAVA_HOME environment variable:


      

    •   
       export JAVA_HOME=java_home 

    •  Windows:  
       set JAVA_HOME=java_home 

     
 
     cd restservice_home/gettingstarted 

     
  2.  Start the catalog service process. 

      To start the server without WXS security,
use the following commands.


      

    •   
       ./runcat.sh 

    •  Windows:  
       runcat.bat 

     
 To start the server withWXS security...


      

    •   
       ./runcat_secure.sh 

    •  Windows:  
       runcat_secure.bat 

     



     
  3.  Start two container server processes. Open another command-line or terminal window and set the JAVA_HOME environment variable:


      

    •   
       export JAVA_HOME=java_home 

    •  Windows:  
       set JAVA_HOME=java_home 

     



     
  4.  Start a container server process. 

      To start the server without WXS security,
use the following commands.



     
      

    1.  Open a command-line window.


    2.  
       cd restservice_home/gettingstarted
      


    3.  To start the server without WXS security... 



       
        

      •   
         ./runcontainer.sh container0


      •  Windows:  
         runcontainer.bat container0


       



    4.  To start the server with WXS security... 



       
        

      •   
         ./runcontainer_secure.sh container0


      •  Windows:  
         runcontainer_secure.bat container0


       


     



     
  5.  Start a second container server process.


     
      

    1.  Open a command-line window.


    2.  
       cd restservice_home/gettingstarted
      


    3.  To start the server without WXS security... 



       
        

      •   
         ./runcontainer.sh container1


      •  Windows:  
         runcontainer.bat container1


       



    4.  To start the server with WXS security... 



       
        

      •   
         ./runcontainer_secure.sh container1


      •  Windows:  
         runcontainer_secure.bat container1


       


     


 


 
 Results



Wait until the container servers are ready before proceeding with the next steps.  The container servers are ready when the following message is displayed:

  CWOBJ1001I: ObjectGrid Server container_name is ready to process requests.
Where container_name is the name of the container that was started in the previous step.









  Configure application servers for the REST data service



  We can configure various application servers to use the REST data service.


  
 









  Deploy the REST data service on WAS



  This topic describes how to configure the  WXS REST data service on WAS or WAS Network Deployment v or later.
 These instructions also apply to deployments where WXS is integrated with the WAS deployment.




You must have one of the following environments on your system to configure and deploy the REST data service for  WXS.



 
 





 
    

     
  1.  Configure and start a data grid.


     Verify that a client can connect to and access entities in the data grid.  



     
  2.  Build the WXS REST service configuration JAR or directory.  


     
  3.  Add the REST data service configuration JAR or directory to the application server classpath:


     
      

    1.  Open the WebSphere Application Server administrative console


    2.  Navigate to Environment > Shared libraries


    3.  Click New


    4.  Add the following entries into the appropriate
fields: 



       
        

      •  Name:  extremescale_rest_configuration


      •  Classpath:  <REST service configuration jar or directory>


       



    5.  Click OK


    6.  Save the changes to the master configuration 
     



     
  4.  Add the  WXS client runtime JAR, wsogclient.jar,  and the REST data service configuration JAR or directory to the application server classpath. This step is not necessary if  WXS is integrated with
the WebSphere Application Server installation. 

      


     
      

    1.  Open theWebSphere Application Server administrative console.


    2.  Navigate to Environment > Shared libraries.


    3.  Click New.


    4.  Add the following entries into the fields:



       
        

      •  Name:  extremescale_client_v71


      •  Classpath:
 wxs_home/lib/wsogclient.jar


       


        Remember: Add each path on a separate line.



    5.  Click OK.


    6.  Save the changes to the master configuration.

     




     
  5.  Install the REST data service EAR
file, wxsrestservice.ear, to the WAS using the administrative console:


     
      

    1.  Open the WAS admin console.


    2.  Click Applications > New application.


    3.  Browse to the /lib/wxsrestservice.ear file on the file system and select it and click Next. 



       
        

      •  If using WAS v7.0, click Next.


       



    4.  Choose the detailed installation option, and click Next.


    5.  On the application security warnings screen, click Continue.


    6.  Choose the default installation options, and click Next.


    7.  Choose a server to map the application to, and click Next.


    8.  On the JSP reloading page, use the defaults, and click Next.


    9.  On the shared libraries page, map the wxsrestservice.war module to the shared libraries that you defined: 



       
        

      •  extremescale_rest_configuration 

      •  extremescale_client_v71


       


         This shared library is required only if  WXS is not integrated with WAS.



    10.  On the map shared library relationship page, use the defaults, and click Next.


    11.  On the map virtual hosts page, use the defaults, and click Next.


    12.  On the map context roots page, set the context root to: wxsrestservice 


    13.  On the Summary screen,


      click Finish to complete the installation.


    14.  Save the changes to the master configuration.

     



     
  6.  Start the wxsrestservice REST data service application:


     
      

    1.  Go to the application in the administrative console. 



       
        

      •  WAS v7.0:


        In the administrative console, click...


          
 Applications | Application Types | WebSphere Applications

        


       



    2.  Check the check box next to the wxsrestservice application, and click Start.


    3.  Review the SystemOut.log file for the application server profile.  When the REST data service has started successfully, the following message is displayed in the SystemOut.log file for the server profile: 


        

          CWOBJ4000I: The  WXS REST data service has been started.

      


     



     
  7.  Verify the REST data service is working: The port number can be found in the SystemOut.log file within the application server profile logs directory by looking at the first port displayed for message identifier:  SRVE0250I.  The default port is 9080.

      For example:


      

       http://localhost:9080/wxsrestservice/restservice/NorthwindGrid/  Result: The AtomPub service document is displayed.

    


      For example: 


     
      
http://localhost:9080/wxsrestservice/restservice/NorthwindGrid/$metadata

    


     The Entity Model Data Extensions (EDMX) document is displayed.



     
  8.  To stop the data grid processes, use 
     CTRL+C in the respective command window.

 



  
 









  Starting REST data services with  WXS integrated in WAS 7.0



  This topic describes how to configure and start the WXS REST data service using WAS version 7.0 that has been integrated and augmented with  WXS. 




Verify that the sample stand-alone WXS data grid is started.
 


 To get started with the  WXS REST data service using WAS, follow these steps:




 
    

     
  1.  Add the  WXS REST data service sample configuration JAR to the classpath:


     
      

    1.  Open the WebSphere Administration Console 

    2.  Navigate to Environment -> Shared libraries 

    3.  Click New 

    4.  Add the following entries into the appropriate fields: 


       
        

      1.  Name:  extremescale_gettingstarted_config 

      2.  Classpath 


         
          

        •  restservice_home/gettingstarted/restclient/bin 

        •  restservice_home/gettingstarted/common/bin 

         


          Remember: Each path must appear on a different line.
 

       



    5.  Click OK


    6.  Save the changes to the master configuration 
     



     
  2.  Install the REST data service EAR file, wxsrestservice.ear,
to the WAS using the WebSphere administration console:


     
      

    1.  Open the WebSphere administration console 


    2.  Navigate to...


        
 Applications | New Application 

      `


    3.  Browse to...


        
 restservice_home/lib/wxsrestservice.ear 

      


    4.  Select the file and click Next.


    5.  Choose the detailed installation options, and click Next.


    6.  On the application security warnings screen, click Continue.


    7.  Choose the default installation options, and click Next.


    8.  Choose a server to map the wxsrestservice.war module to, and click Next.


    9.  On the JSP reloading page, use the defaults, and click Next.


    10.  On the shared libraries page, map the "wxsrestservice.war" module to the following shared libraries that were defined earlier.


    11.  On the map shared library relationship page, use the defaults, and click Next.


    12.  On the map virtual hosts page, use the defaults, and click Next.


    13.  On the map context roots page, set the context root to: wxsrestservice.


    14.  On the Summary screen,
click Finish to complete the installation.


    15.  Save the changes to the master configuration.

     



     
  3.  
     If the WXS data grid was started with WXS security enabled, set the following property in the restservice_home/gettingstarted/restclient/bin/wxsRestService.properties file.


    ogClientPropertyFile=restservice_home/gettingstarted/security/security.ogclient.properties
    



     
  4.  Start the application server and the "wxsrestservice " WXS REST data service application. 

      After the application is started review the SystemOut.log for the application server and verify that the following message appears:   CWOBJ4000I: The  WXS REST data service has been started.



     
  5.  Verify that the REST data service is working:


     
      

    1.  Open a browser and navigate to: 

        http://localhost:9080/wxsrestservice/restservice/NorthwindGrid 

        The service document for the NorthwindGrid is displayed.



    2.  Navigate to: 

        http://localhost:9080/wxsrestservice/restservice/NorthwindGrid/$metadata 

        The Entity Model Data Extensions (EDMX) document is displayed 

     



     
  6.  To stop the data grid processes, use CTRL+C in the respective command window to stop the process.

 









  Deploy the REST data service on WAS Community Edition



  We can configure the WXS REST data service on WAS Community Edition v2.1.1.3 or later.





 
 





 
    

     
  1.  Configure and start a data grid.


     Verify that a WXS client can connect to and access entities in the data grid.  



     
  2.  Build the WXS REST
service configuration JAR or directory.  


     
  3.  Start the WAS Community Edition server:


     
      

    1.  To start the server without Java SE security enabled... 

        UNIX/Linux:  
       wasce_root/bin/startup.sh 

        Windows:  
       wasce_root/bin/startup.bat 


    2.  To start the server with Java SE
security enabled, follow these steps: UNIX/Linux:  


       
        

      1.  Open a command-line or terminal window and run the following copy command (or copy the contents of the specified policy file into your existing policy): 
         cp restservice_home/gettingstarted/wasce/geronimo.policy wasce_root/bin 

      2.  Edit the wasce_root/bin/setenv.sh file 

      3.  After the line that contains "WASCE_JAVA_HOME=",
add the following: export JAVA_OPTS="-Djava.security.manager -Djava.security.policy=geronimo.policy"

       
Windows:  


       
        

      1.  Open a command-line window and run the following copy command or copy the contents of the specified policy file into your existing policy:

         copy restservice_home\gettingstarted\wasce\geronimo.policy\bin 


      2.  Edit the wasce_root\bin\setenv.bat file 

      3.  After the line that contains "set WASCE_JAVA_HOME=",
add the following:

          set JAVA_OPTS="-Djava.security.manager -Djava.security.policy=geronimo.policy"
 

       


     



     
  4.  Add the ObjectGrid client runtime JAR to the WAS Community Edition repository: 


     
      

    1.  Open the WAS Community Edition administration console and log in. The default URL is: 
       http://localhost:8080/console and the default userid is 
       system and password is 
       manager.


    2.  Click the Repository link on the left side of the console window, in the Services folder.


    3.  In the Add Archive to Repository section,
fill in the following into the input text boxes:

         

        
      

      
    Text box 
    Value 


      File 
    wxs_home/lib/ogclient.jar 

      Group 
    com.ibm.websphere.xs 

      Artifact 
    ogclient 

      Version 
    7.1 

      Type 
    JAR



      




    4.  Click the Install button 
     


      See the following tech note for details on different ways class and library dependencies can be configured:  Specifying external dependencies to applications running on WAS Community Edition .



     
  5.  Deploy and start the REST data service module, the wxsrestservice.war file, to the WAS Community Edition server.


     
      


    1.  Copy and edit the sample deployment plan XML file: restservice_home/gettingstarted/wasce/geronimo-web.xml to include path dependencies to your REST data service configuration JAR or directory.  See section  for an example on setting the classpath to include your wxsRestService.properties file and other configuration files and metadata classes. 


    2.  Open the WAS Community Edition administration console and log in.  
         The default URL is: 
       http://localhost:8080/console.  The default userid is 
       system and password is 
       manager.


    3.  Click on the Deploy Newlink on the left side of the console window.


    4.  On the Install New Applications page, enter the following values into the text boxes: 


        
      

      
    Text box 
    Value 


      Archive 
    restservice_home/lib/wxsrestservice.war 

      Plan 
    restservice_home/gettingstarted/wasce/geronimo-web.xml 


      



         Use the path to the geronimo-web.xml file that you copied and edited in step 3. 



    5.  Click on the Install button. The console page then indicates that the application was successfully installed and started.


    6.  Examine the WAS Community Edition system output log or console to verify that the REST data service has started successfully. The following message must appear:  

        CWOBJ4000I:
The  WXS REST data service has been started.


     



     
  6.  Start the WAS Community Edition server by running the following command:


      

    •  UNIX/Linux:  
       wasce_root/bin/startup.sh 

    •  Windows:  
       wasce_root/bin/startup.bat 

     



     
  7.  Install the WXS REST
data service and the provided sample into the WAS Community Edition server:


     
      

    1.  Add the ObjectGrid client runtime JAR to the WAS Community Edition repository: 


       
        

      1.  Open the WAS Community Edition administration console and log in.  The default URL is: 
         http://localhost:8080/console.
The default userid is 
         system and password is 
         manager.


      2.  Click the Repository link on the left side of the console window, in the Services folder. 


      3.  In the Add Archive to Repository section,
fill in the following into the input text boxes:

           

          
        

        
    Text box 
    Value 


         >File 
     >wxs_home/lib/ogclient.jar 

         >Group 
     >com.ibm.websphere.xs 

         >Artifact 
     >ogclient 

         >Version 
     >7.1


         >Type 
     >JAR



        




      4.  Click the install button.

           See the following technote for details on different ways class and library dependencies can be configured:  Specifying external dependencies to applications running on WAS Community Edition 


       



    2.  Deploy the REST data service module, wxsrestservice.war, to the WAS Community Edition server. 



       
        


      1.  Edit the sample restservice_home/gettingstarted/wasce/geronimo-web.xml deployment XML file to include path dependencies to the getting started sample classpath directories:



         
          

        •  Change the "classesDirs" for the two getting started client GBeans:


         
The "classesDirs" path for the GettingStarted_Client_SharedLib GBean should be set to: restservice_home/gettingstarted/restclient/bin 
          The "classesDirs" path for the GettingStarted_Common_SharedLib GBean should be set to: restservice_home/gettingstarted/common/bin 


      2.  Open the WAS Community Edition administration console and log in.


      3.  Click on the Deploy New link on the left side of the console window.


      4.  On the Install New Applications page, enter the following values into the text boxes:

           

          
        

        
    Text box 
    Value 


        Archive 
    restservice_home/lib/wxsrestservice.war 

        Plan 
    restservice_home/gettingstarted/wasce/geronimo-web.xml 


        




      5.  Click the Install button.

          The console page then indicates that the application has successfully installed and started.



      6.  Examine the WAS Community Edition system output log to verify that the REST data service has started successfully by verifying that the following message is present:

          CWOBJ4000I:
The  WXS REST data service has been started.


       


     



     
  8.  Verify that the REST data service is working: 

      Open a Web browser and navigate to the following URL: 
     http://<host>:<port>/<context root>/restservice/<Grid Name>


      The default port for WAS Community Edition is 8080 and is defined using the "HTTPPort" property in the /var/config/config-substitutions.properties file.


      For example: http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/


 


 
 Results



The AtomPub service document is displayed.



  
 









 15.2.2.1.  Starting the REST data service in WAS Community Edition



  This topic describes how to configure and start the WXS REST data service using WAS Community Edition.




Verify that the sample data grid is started.  




 
    

     
  1.  Download  and install WAS Community Edition v2.1.1.3 or later to wasce_root, such as: /opt/IBM/wasce 

     
  2.  Start the WAS Community Edition server by running the following command:


      

    •   wasce_root/bin/startup.sh 

    •  Windows:  wasce_root/bin/startup.bat 

     



     
  3.  
     If the WXS grid was started with WXS security enabled, set the following properties in the restservice_home/gettingstarted/restclient/bin/wxsRestService.properties file.


    ogClientPropertyFile=restservice_home/gettingstarted/security/security.ogclient.properties loginType=none
    



     
  4.  Install the WXS REST
data service and the provided sample into the WAS Community Edition server:


     
      

    1.  Add the ObjectGrid client runtime JAR to the WAS Community Edition repository: 


       
        

      1.  Open the WAS Community Edition administration console and log in. 

           The default URL is: 
         http://localhost:8080/console.
The default user ID is 
         system and password is 
         manager.




      2.  Click the Repository, in the Services folder.


      3.  In the Add Archive to Repository section,
fill in the following into the input text boxes:

           

          
        

        
    Text box 
    Value 


        File 
    wxs_home/lib/ogclient.jar 

        Group 
    com.ibm.websphere.xs 

        Artifact 
    ogclient 

        Version 
    7.0


        Type 
    jar 


        




      4.  Click the Install button.

           See the following tech note for details on different methods of configuration class and library dependencies:  Specifying external dependencies to applications running on WAS Community Edition .


       



    2.  Deploy the REST data service module, which is the wxsrestservice.war file, to the WAS Community Edition server. 


       
        

      1.  Edit the sample restservice_home/gettingstarted/wasce/geronimo-web.xml deployment XML file to include path dependencies to the getting started sample classpath directories:


          Change the classesDirs paths for the two getting started client GBeans:



         
          

        •  The "classesDirs" path for the GettingStarted_Client_SharedLib GBean should be set to: restservice_home/gettingstarted/restclient/bin 

        •  The "classesDirs" path for the GettingStarted_Common_SharedLib GBean should be set to: restservice_home/gettingstarted/common/bin 

         



             



      2.  Open the WAS Community Edition administrative console and log in.

           The default URL is: 
         http://localhost:8080/console.
The default user ID is 
         system and password is 
         manager.




      3.  Click Deploy New.


      4.  On the Install New Applications page, enter the following values into the text boxes:


          
        

        
    Text box 
    
    Value 


        Archive
    restservice_home/lib/wxsrestservice.war


        Plan
    restservice_home/gettingstarted/wasce/geronimo-web.xml 

        




      5.  Click on the Install
button.

          The console page should indicate
that the application was successfully installed and started.



      6.  Examine the WebSphere Application Server Community Edition system
output log or console to verify that the REST data service has started
successfully by verify that the following message is present:

          CWOBJ4000I:
The  WXS REST data service has been started.


       


     



     
  5.  Verify
that the REST data service is working:


     
      

    1.  Open the following link in a browser window: 
       http://localhost:8080/wxsrestservice/restservice/NorthwindGrid.
The service document for the NorthwindGrid grid is displayed.


    2.  Open the following link in a browser window: 
       http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/$metadata.
The Entity Model Data Extensions (EDMX) document is displayed.

     



     
  6.  To stop the grid processes, use 
     CTRL+C in
the respective command window to stop the process.


     
  7.  To stop WebSphere Application Server Community Edition,
use the following command:


      

    •  UNIX/Linux:  wasce_root/bin/shutdown.sh


    •  Windows:  wasce_root\bin\shutdown.bat


     
 

       The default user ID is 
     system and password is 
     manager. If we are using a custom
port, use the -port option.


 









 15.2.3.  Deploy the REST data service on Apache Tomcat



  This topic describes how to configure the WXS REST data service on Apache Tomcat v5.5 or later.


 



 
 





 
    

     
  1.  If using an Oracle JRE or JDK, install the IBM ORB into Tomcat:


     
      

    1.  Tomcat version 5.5: 

        Copy all of the JAR
files from:


        the wxs_home/lib/endorsed directory 

        to:


        the tomcat_root/common/endorsed directory 


    2.  Tomcat version 6.0:  

        Create an "endorsed"
directory:


        UNIX/Linux:  mkdir tomcat_root/endorsed 

        Windows:  md tomcat_root/endorsed 

        Copy all of the JAR files from:


        wxs_home/lib/endorsed 

        to:


        tomcat_root/common/endorsed 

     



     
  2.  Configure and start a data grid.


  3.  Verify that a WXS client can connect to and access entities in the grid.  

 



 
  •  Build the WXS REST service configuration JAR or directory.  


     
  •  Deploy the REST data service module: wxsrestservice.war to the Tomcat server. 

      Copy the wxsrestservice.war file from:


      restservice_home /lib 

      to:


      tomcat_root /webapps 


     
  •  Add the ObjectGrid client runtime JAR
and the application JAR to the shared classpath in Tomcat:


     
      

    1.  Edit the tomcat_root /conf/catalina.properties file 

    2.  Append the following path names to the end of the shared.loader property, separating each path name with a comma: 



       
       


     



     
  •  If we are using Java 2
security, add security permissions to the tomcat policy file: 



     
      

    •  If using Tomcat version 5.5:

        Merge the contents of the sample 5.5 catalina policy file found in 

         restservice_home /gettingstarted/tomcat/catalina-5_5.policy with the tomcat_root /conf/catalina.policy file.



    •  If using Tomcat version 6.0:

        Merge the contents of the sample 6.0 catalina policy file found in 

        restservice_home /gettingstarted/tomcat/catalina-6_0.policy with the tomcat_root /conf/catalina.policy file.



     



     
  •  Start the Tomcat server:


      

    •  

        If using Tomcat 5.5 on UNIX or Windows, or the Tomcat 6.0 ZIP
distribution: 



       
        

      1.  
         cd tomcat_root/bin 

      2.  Start the server:



         
          

        •  Without Java 2 security enabled:

            UNIX/Linux:  
           ./catalina.sh run 

            Windows:  
           catalina.bat run 


        •  With Java 2 security enabled:

            UNIX/Linux:  
           ./catalina.sh run -security 

            Windows:  
           catalina.bat run -security 


         



      3.  The Apache Tomcat logs are displayed to the console.   When the REST data service has started successfully, the following message is displayed in the administrative console:

          CWOBJ4000I:
The  WXS REST data service has been started.


       



    •  

        If using Tomcat 6.0 on Windows using the Windows installer distribution:


       
        

      1.  
         cd /bin 

      2.  Start the Apache Tomcat 6 configuration tool:

         tomcat6w.exe 


      3.  To enable Java 2 security (optional):

          Add the following entries to the Java Options in the Java tab in the Apache Tomcat 6 properties window:


         -Djava.security.manager 

         -Djava.security.policy=\conf\catalina.policy 



      4.  Click on the Start button on the Apache Tomcat 6 properties window to start the Tomcat server.


      5.  Review the following logs to verify that the Tomcat server has started successfully: 



         
          

        •  tomcat_root /bin/catalina.log 
            Displays the status of the Tomcat server engine 


        •  tomcat_root /bin/stdout.log 
             Displays the system output log 


         



      6.  When the REST data service has started successfully, the following message is displayed in the system output log:  

          CWOBJ4000I:
The  WXS REST data service has been started.


       




     



     
  •  Verify the REST data service is working. 


      Open a Web browser and navigate to the following URL: 


      http://host:port/context_root/restservice/grid_name
    



      The default port for Tomcat is 8080 and is configured in the tomcat_root /conf/server.xml file in the <Connector> element.


      For example:


      http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/
    



     


     
     Results
    


    The AtomPub service document is displayed. 



      
     









     15.2.3.1.  Starting REST data services in Apache Tomcat
    


      This topic describes how to configure and start the WXS REST data service using Apache Tomcat, version 5.5 or later.




    Verify that the sample WXS data grid is started.
 




     
      

       
    1.  Download  and install Apache Tomcat v5.5 or later to tomcat_root.   For example:  /opt/tomcat 

       
    2.  Install the WXS REST
data service and the provided sample into the Tomcat server as follows:


       
        

      1.  If we are using an Oracle JRE or JDK, install the IBM ORB into Tomcat: 



         
          

        •  For Tomcat version 5.5

            Copy all of the JAR files from:


            wxs_home/lib/endorsed 

            to 

            tomcat_root/common/endorsed 


        •  For Tomcat version 6.0


           
            

          1.  Create an "endorsed" directory 


             
              

            •  UNIX/Linux:  
               mkdir tomcat_root/endorsed 

            •  Windows:  
               md tomcat_root/endorsed 

             



          2.  Copy all of the JAR files from:

              wxs_home/lib/endorsed 

              to 

              tomcat_root/endorsed 

           



         



      2.  Deploy the REST data service module: wxsrestservice.war to the Tomcat server. 

          Copy the wxsrestservice.war file from:


          restservice_home/lib 

          to:


          tomcat_root/webapps 


      3.  Add the ObjectGrid client runtime JAR and the application JAR to the shared classpath in Tomcat: 


         
          

        1.  Edit the tomcat_root/conf/catalina.properties file 

        2.  Append the following path names to the end of the shared.loader property in the form of a comma-delimited list:



           
            

          •  wxs_home /lib/ogclient.jar 

          •  restservice_home/gettingstarted/restclient/bin 

          •  restservice_home/gettingstarted/common/bin 

           


             The path separator must be a forward slash.


         


       



       
    3.  
       If the WXS data grid was started with WXS security enabled, set the following properties in the restservice_home/gettingstarted/restclient/bin/wxsRestService.properties file.


      ogClientPropertyFile=restservice_home/gettingstarted/security/security.ogclient.properties loginType=none
      



       
    4.  Start the Tomcat server with the REST data service: 



       
        

      •  If using Tomcat 5.5 on UNIX or Windows, or Tomcat 6.0 on UNIX:


         
          

        1.  
           cd tomcat_root/bin 

        2.  Start the server:



           
            

          •  UNIX/Linux:  
             ./catalina.sh run 

          •  Windows:  
             catalina.bat run 

           



        3.  The console then displays the Apache Tomcat logs.   When the REST
data service has started successfully, the following message is displayed in the administration console: 

            CWOBJ4000I: The  WXS REST data service has been started.


         



      •  If using Tomcat 6.0 on Windows:


         
          

        1.  
           cd tomcat_root/bin 

        2.  Start the Apache Tomcat 6 configuration tool with the following command: 
           tomcat6w.exe 

        3.  Click on the Start button on the Apache Tomcat 6 properties window to start the Tomcat server.


        4.  Review the following logs to verify that the Tomcat server has started successfully:



           
            

          •  tomcat_root/bin/catalina.log 
              Displays the status of the Tomcat server engine 


          •  tomcat_root/bin/stdout.log 

              Displays the system output log.



           



        5.  When the REST data service has started successfully, the following message is displayed in the system output log:  CWOBJ4000I:
The  WXS REST data service has been started.

         



       



       
    5.  Verify that the REST
data service is working: 


       
        

      1.  Open a browser and navigate to:

          http://localhost:8080/wxsrestservice/restservice/NorthwindGrid 

          The service document for the NorthwindGrid is displayed.



      2.  Navigate to:

          http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/$metadata 

          The Entity Model Data Extensions (EDMX) document is displayed.


       



       
    6.  To stop the data grid processes, use CTRL+C
in the respective command window.


       
    7.  To stop Tomcat, use CTRL +C
in the window in which you started it.

     









      Configure Web browsers to access REST data service ATOM feeds
    


      The WXS REST
data service creates ATOM feeds by default when using a web browser.
 The ATOM feed format may not be compatible with older browsers or may be interpreted such that the data cannot be viewed as XML. We can configure Internet Explorer v8 and Firefox Version 3 to display the ATOM feeds and XML within the browser.


     The WXS REST
data service creates ATOM feeds by default when using a web browser.
 The ATOM feed format may not be compatible with older browsers or may be interpreted such that the data cannot be viewed as XML.  For older browsers, you will be prompted to save the files to disk.  Once the files are downloaded, use your favorite XML reader to look at the files.   The generated XML is not formatted to be displayed, so everything will be printed on one line.   Most XML reading programs,
such as Eclipse, support reformatting the XML into a readable format.

      For modern browsers, such as Microsoft Internet Explorer v8 and Firefox Version 3, the ATOM XML files can be displayed natively in the browser.  The following topics provide details on how to configure Internet Explorer Version 8 and Firefox Version 3 to display the ATOM feeds and XML within the browser.




      Configure Internet Explorer v8
      

       
    •  To enable Internet Explorer to read the ATOM feeds that the REST data service generates...


       
        

      1.  Click Tools > Internet Options 

      2.  Select the Content tab 

      3.  Click the Settings button in the Feeds and Web Slices section 

      4.  Uncheck the box:
 "Turn on feed reading view"


      5.  Click OK to return to the browser.


      6.  Restart Internet Explorer.

       



     

      Configure Firefox v3
      

       
    •  Firefox does not automatically display pages with content type:  application/atom+xml.  The first time a page is displayed, Firefox prompts you to save the file.  To display the page, open the file itself with Firefox as follows:


       
        

      1.  From the application chooser dialog box, select the "Open with" radio button and click the Browse button.


      2.  Navigate to your Firefox installation directory.
 For example:  C:\Program Files\Mozilla Firefox 

      3.  Select 
         firefox.exe and hit the OK button.


      4.  Check the .Do this automatically for files like this..
check box.


      5.  Click the OK button.


      6.  Next, Firefox displays the ATOM XML page in a new browser window or tab 
       



       
    •  Firefox automatically renders ATOM feeds in readable format.
 However, the feeds that the REST data service creates include XML.
 Firefox cannot display the XML unless you disable the feed renderer.
 Unlike Internet Explorer, in Firefox, the ATOM feed rendering plug-in must be explicitly edited.   To configure Firefox to read ATOM feeds as XML files, follow these steps:


       
        

      1.  Open the following file in a text editor: <firefoxInstallRoot>\components\FeedConverter.js.
In the path, <firefoxInstallRoot> is the root directory where Firefox is installed. 

          For Windows operating systems, the default directory is: C:\Program Files\Mozilla Firefox.



      2.  Search for the snippet that looks as follows: 

          
        // show the feed page if it wasn't sniffed and we have a document,
// or we have a document, title, and link or id if (result.doc && (!this._sniffed ||
    (result.doc.title && (result.doc.link || result.doc.id)))) {
        




      3.  Comment out the two lines that begin with if and result by placing // (two forward slashes) in front of them.


      4.  Append the following statement to the snippet: if(0)
{.


      5.  The resulting text should
look as follows: 

          
        // show the feed page if it wasn't sniffed and we have a document,
// or we have a document, title, and link or id
//if (result.doc && (!this._sniffed ||
//    (result.doc.title && (result.doc.link || result.doc.id)))) {
if(0) {
        




      6.  Save the file.


      7.  Restart Firefox


      8.  Now Firefox can automatically display all feeds in the browser.

       


       
    •  Test your setup by trying some URLs. 


     




     
     Example
    


      This section describes some example URLs that can be used to view the data that was added by the getting started sample provided with the REST data service.  Before using the following URLs, add the default data set to the WXS sample data grid using either the sample Java client or the sample Visual Studio WCF Data Services client.


      The following examples assume the port is 8080 which can vary.  



     
      


    •  View a single customer with the id of "ACME": 


        http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer('ACME') 
      



    •  View all of the orders for customer "ACME": 


        http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer('ACME')/orders 
      



    •  View the customer "ACME" and the orders:  


        http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer('ACME')?$expand=orders 
      



    •  View order 1000 for customer "ACME": 


        http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Order(orderId=1000,customer_customerId='ACME') 
      



    •  View order 1000 for customer "ACME" and its associated Customer: 


        http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Order(orderId=1000,customer_customerId='ACME')?$expand=customer
      



    •  View order 1000 for customer "ACME" and its associated Customer and OrderDetails: 


        http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Order(orderId=1000,customer_customerId='ACME')?$expand=customer,orderDetails 
      



    •  View all orders for customer "ACME" for the month of October, 2009 (GMT): 


      http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer(customerId='ACME')/orders?$filter=orderDate 
ge datetime'2009-10-01T00:00:00' 
and orderDate lt datetime'2009-11-01T00:00:00' 
      



    •  View all the first 3 orders and orderDetails for customer "ACME"
for the month of October, 2009 (GMT): 


      http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/Customer(customerId='ACME')/orders?$filter=orderDate 
ge datetime'2009-10-01T00:00:00' 
and orderDate lt datetime'2009-11-01T00:00:00'
&$orderby=orderDate&$top=3&$expand=orderDetails
      



     










      Use a Java client with REST data services
    


      The Java client application uses the WXS EntityManager API to insert data into the grid.


     The previous sections described how to create a WXS data grid and configure and start the WXS REST
data service.  The Java client application uses the WXS EntityManager API to insert data into the grid.  It does not demonstrate how to use the REST interfaces.  The purpose of this client is to demonstrate how the EntityManager API is used to interact with the WXS data grid, and allow modifying data in the grid.  To view data in the grid using the REST
data service, use a web browser  or use the Visual Studio 2008 client application . 



      To quickly add content to the WXS data grid, run the following command:


     
      

       
    1.  Open a command-line or terminal window and set the JAVA_HOME
environment variable:


        

      •   
         export JAVA_HOME=java_home 

      •  Windows:  
         set JAVA_HOME=java_home 

       



       
    2.  
       cd restservice_home/gettingstarted
      


       
    3.  Insert some data into the grid.  The data that is inserted will be retrieved later using a Web browser and the REST data service. 

        If the data grid was started withoutWXS security...


        
./runclient.sh load default 

       
 

        If the data grid was started withWXS security...


        

      •  UNIX/Linux:  
         ./runclient_secure.sh load default 

      •  Windows:  
         runclient_secure.bat load default 

       
 For a Java client, use the following command syntax:



       
        

      •  UNIX/Linux:  
         runclient.sh command 

      •  Windows:  
         runclient.bat command 

       
The following commands are available:



       
        

      •  
         load default 
          Loads a predefined set of Customer, Category and Product entities into the data grid and creates a random set of Orders for each customer.



      •  
         load category categoryId categoryName firstProductId num_products 
          Creates a product Category and a fixed number of Product entities in the data grid.  The firstProductId parameter identifies the id number of the first product and each subsequent product is assigned the next id until the specified number of products is created.



      •  
         load customer companyCode contactNamecompanyName numOrders firstOrderIdshipCity maxItems discountPct 
          Loads a new Customer into the data grid and creates a fixed set of Order entities for any random product currently loaded in the grid.  The number of Orders is determined by setting the <numOrders> parameter.
 Each Order will have a random number of OrderDetail entities up to <maxItems>



      •  
         display customer companyCode 
          Display a Customer entity and the associated Order and OrderDetail entities.



      •  
         display category categoryId 
          Display a product Category entity and the associated Product entities.



       


     


     
     Results
    



     
      

    •  
       runclient.bat load default 

    •  
       runclient.bat load customer IBM "John Doe" "IBM Corporation"
5 5000 Rochester 5 0.05


    •  
       runclient.bat load category 5 "Household Items" 100
5


    •  
       runclient.bat display customer IBM


    •  
       runclient.bat display category 5


     


 
     
     Run and building the sample data grid and Java client with Eclipse
    


      The REST data service getting started sample can be updated and enhanced using Eclipse.  For details on how to setup your Eclipse environment see the text document:  


      restservice_home/gettingstarted/ECLIPSE_README.txt
    


      After the WXSRestGettingStarted project is imported into Eclipse and is building successfully, the sample will automatically re-compile and the script files used to start the container server and client will automatically pick up the class files and XML files.  The REST data service will also automatically detect any changes since the Web server is configured to read the Eclipse build directories automatically.  
       When changing source or configuration files, both the WXS container server and the REST data service application must be restarted.  The WXS container server must be started before the REST data service Web application.  










      Visual Studio 2008 WCF client with REST data service
    


      The WXS REST
data service getting started sample includes a WCF Data Services client that can interact with the WXS REST data service.
 The sample is written as a command-line application in C#.


     
     Software requirements
    


    The WCF Data Services C# sample client requires the following:



     
     



     
     Building and running the getting started client
    

      The WCF Data Services sample client includes a Visual Studio 2008
project and solution and the source code for running the sample. 
The sample must be loaded into Visual Studio 2008 and compiled into a Windows runnable program before it can be run.  To build and run the sample, see the text document:


       restservice_home/gettingstarted/VS2008_README.txt
     


 
     
     WCF Data Services C# client command syntax
    

      Windows:  WXSRESTGettingStarted.exe <service URL> <command>


      The <service URL> is the URL of the WXS REST data service configured in section .


      The following commands are available:



     
      

    •  
       load default 
        Loads a predefined set of Customer, Category and Product entities into the data grid and creates a random set of Orders for each customer.



    •  
       load category <categoryId> <categoryName> <firstProductId>
<numProducts>

        Creates a product Category and a fixed number of Product entities in the data grid.  The firstProductId parameter identifies the id number of the first product and each subsequent product is assigned the next id until the specified number of products is created.



    •  
       load customer <companyCode>
<contactName> <companyName>
<numOrders> <firstOrderId> <shipCity> <maxItems> <discountPct>

        Loads a new Customer into the data grid and creates a fixed set of Order entities for any random product currently loaded in the data grid.  The number of Orders is determined by setting the <numOrders>
parameter.  Each Order will have a random number of OrderDetail entities up to <maxItems>



    •  
       display customer <companyCode>

        Display a Customer entity and the associated Order and OrderDetail entities.



    •  
       display category <categoryId>

        Display a product Category entity and the associated Product entities.



    •  
       unload 
        Remove all entities that were loaded using the "default load" command.



     




      The following examples illustrate various commands.



     
      

    •  
       WXSRestGettingStarted.exe http://localhost:8080/wxsrestservice/restservice/NorthwindGrid load default 

    •  
       WXSRestGettingStarted.exe http://localhost:8080/wxsrestservice/restservice/NorthwindGrid load customer 

    •  
       IBM "John Doe" "IBM Corporation"
5 5000 Rochester 5
0.05 


    •  WXSRestGettingStarted.exe http://localhost:8080/wxsrestservice/restservice/NorthwindGrid load category 5 "Household Items" 100 5


    •  WXSRestGettingStarted.exe http://localhost:8080/wxsrestservice/restservice/NorthwindGrid display customer IBM 


    •  WXSRestGettingStarted.exe http://localhost:8080/wxsrestservice/restservice/NorthwindGrid display category 5 


     










    



      Deploy the REST gateway
    


       We can deploy and configure the REST
gateway for  WXS in WAS or in a Liberty profile server.




    Verify that a Liberty profile server is created. 


     The REST gateway is a servlet that is defined in the wxsRESTGateway.war web archive (WAR) file. With this REST gateway, you use a Uniform Resource Identifier (URI) to access data in the data grid.




     
      

       
    1.  Enable the REST gateway feature by either manually editing server.xml or using the Liberty Profile Developer Tools. 


        


      •  Enable the REST gateway in the Liberty profile server.xml file.


        <featureManager>
  <feature>eXtremeScale.rest-1.1</feature>
</featureManager>

        




      •  Enable the REST gateway in the Liberty profile server.xml file using Liberty Profile Developer Tools.



         
          


        •  Start IBMWAS v8.6
Liberty Profile Developer Tools. 



        •  In the Design tab, select Feature Manager. Click Add in the Feature Manager Details section. Select and add the eXtremeScale.rest-1.1 feature.



        •  With the Feature Manager selected, click Add in the Feature Manager Details section. Select and add the servlet-3.0 feature.



        •  Save server.xml.


         




      •  Enable the REST gateway in WAS.



         
          


        •  Install  WXS with WAS. 



        •  Deploy the was_install_root\optionalLibraries\ObjectGrid\restgateway\wxsRESTGateway.war file on WAS.


         



       



       
    2.  Configure the REST gateway.


       
        


      1.  Configure the REST gateway in server.xml.
Enter the following line of code: 


        <xsREST contextRoot=.myContextRoot. remoteDomain=.myDomain./>

        


           The attributes, contextRoot and remoteDomain,
are optional. The default content root is resources.




      2.  Configure a WXS server.  



      3.  Configure a container service.  



       



       
    3.  Start the Liberty profile server to run the REST client gateway.

     


      When the REST gateway is enabled, anyone with access to the servlet can access data in a data grid. Therefore, use web application security in WAS to control authorization. For more information about securing your web applications that use this REST gateway, see Securing web applications  in the WAS Information Center.


      The wxsRESTGateway.war file, which contains the web.xml file for the security configuration is in the following locations, depending on the installation: 



     
      

    •  wlp_install_root/wxs/web/rest

    •  was_install_root/optionalLibraries/ObjectGrid/restgateway

    •  wxs_standalone_install_root/ObjectGrid/restgateway

     



       We can now begin using the REST data service in the Liberty profile to communicate with the data grid through a URI.  








    




       Configure OSGi-enabled plug-ins using the ObjectGrid descriptor XML file
    


      In this task, you add existing OSGi services to a descriptor XML file so that  WXS containers can recognize and load the OSGi-enabled plug-ins correctly.

    To configure your plug-ins, be sure to: 



     
      

    •  Create your package, and enable dynamic plug-ins for OSGi deployment.


    •  Have the names of the OSGi services that represent your plug-ins available.


     
        


     You have created an OSGi service to wrap your plug-in. Now,
these services must be defined in the objectgrid.xml file so that WXS containers can load and configure the plug-in or plug-ins successfully.




     
      

       
    1.  Any grid-specific plug-ins, such as TransactionCallback,
must be specified under the objectGrid element.  See the following example from the objectgrid.xml file:


      <?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="MyGrid" txTimeout="60">
            <bean id="myTranCallback" osgiService="myTranCallbackFactory"/>
            ...
        </objectGrid>
        ...
    </objectGrids>
    ...
/objectGridConfig>

      


         The osgiService attribute
value must match the ref attribute value that is
specified in the blueprint XML file, where the service was defined for myTranCallback PluginServiceFactory.



       
    2.  Any map-specific plug-ins, such
as loaders or serializers,
for example, must be specified in the backingMapPluginCollections element
and referenced from the backingMap element. See the following example from the objectgrid.xml file:


      <?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="MyGrid" txTimeout="60">
            <backingMap name="MyMap1" lockStrategy="PESSIMISTIC"
                copyMode="COPY_TO_BYTES" nullValuesSupported="false"
                pluginCollectionRef="myPluginCollectionRef1"/>
            <backingMap name="MyMap2" lockStrategy="PESSIMISTIC"
                copyMode="COPY_TO_BYTES" nullValuesSupported="false"
                pluginCollectionRef="myPluginCollectionRef2"/>
            ...
        </objectGrid>
        ...
    </objectGrids>
    ...
    <backingMapPluginCollections>
        <backingMapPluginCollection id="myPluginCollectionRef1">
            <bean id="MapSerializerPlugin" osgiService="mySerializerFactory"/>
        </backingMapPluginCollection>
        <backingMapPluginCollection id="myPluginCollectionRef2">
            <bean id="MapSerializerPlugin" osgiService="myOtherSerializerFactory"/>
            <bean id="Loader" osgiService="myLoader"/>
        </backingMapPluginCollection>
        ...
    </backingMapPluginCollections>
    ...
</objectGridConfig>

      


     


     
     Results
    


    The objectgrid.xml file in this example
tells WXS to create
a grid called MyGrid with two maps, MyMap1 and MyMap2.
The MyMap1 map uses the serializer wrapped by the OSGi service, mySerializerFactory. The MyMap2 map
uses a serializer from the OSGi service, myOtherSerializerFactory,
and a loader from the OSGi service, myLoader.












    



      Configure servers for OSGi
    


       WXS includes a server OSGi bundle, allowing starting and configuring servers and containers within an OSGi framework.  The configuration topics describe how to use the WXS server bundle, OSGi Blueprint service and WXS configuration to run WXS servers in an Eclipse Equinox OSGi framework.


     

      the following tasks are required to start a WXS server within Eclipse Equinox:





     
      

       
    1.  Create an OSGi bundle that will store the WXS plug-ins, exposing them as services and update the ObjectGrid descriptor XML file to reference the services.


       
    2.  Configure OSGi to start a WXS container server.


       
    3.  Install and start the WXS server bundle in the OSGi framework.


       
    4.  Install and start the OSGi bundle that contains the WXS plug-ins. 

        Eclipse Equinox process for installing and starting OSGi bundles with WXS plug-ins 
        



     







      Configure WXS plug-ins with OSGi Blueprint
    


      All WXS ObjectGrid and BackingMap plug-ins can be defined as OSGi beans and services using the OSGi Blueprint Service available with Eclipse Gemini or Apache Aries.



    Before we can configure your plug-ins as OSGi services, first package your plug-ins in an OSGi bundle, and understand the fundamental principles of the required plug-ins.  The bundle must import the  WXS server or client packages and other dependent packages required by the plug-ins, or create a bundle dependency on the WXS server or client bundles  This topic describes how to configure the Blueprint XML to create plug-in beans and expose them as OSGi services for WXS to use. 


      Beans and services are defined in a Blueprint XML file, and the Blueprint container discovers,  creates, and wires the beans together and exposes them as services. The process makes the beans available to other OSGi bundles, including the WXS server and client bundles.


      When creating custom plug-in services for use with WXS, the bundle that is to host the plug-ins, must be configured to use Blueprint. In addition, a Blueprint XML file must be created and stored within the bundle.  






     
      

       
    1.  Create a Blueprint XML file. We can name the file anything. However, you must include the blueprint namespace:


      <?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
...
</blueprint>

      



       
    2.  Create bean definitions in the Blueprint XML file for each WXS plug-in. 

        Beans are defined using the <bean> element and can be wired to other bean references and can include initialization parameters.
 

         When defining a bean, use the correct scope.  Blueprint supports the singleton and prototype scopes.  WXS also supports a custom shard scope.



        Define most WXS plug-ins as prototype or shard-scoped beans, since all of the beans must be unique for each ObjectGrid shard or BackingMap instance it is associated with. 
Shard-scoped beans can be useful when using the beans in other contexts to allow retrieving the correct instance.


        To define a prototype-scoped
bean, use the scope="prototype" attribute on the bean:


      <bean class="com.mycompany.MyBean" scope="prototype">
...
</bean>

      



        To define a shard-scoped bean, you must
add the objectgrid namespace to the  XML schema,
and use the scope="objectgrid:shard" attribute on the bean:


      <?xml version="1.0" encoding="UTF-8"?>

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:objectgrid="http://www.ibm.com/schema/objectgrid"
           
    xsi:schemaLocation="http://www.ibm.com/schema/objectgrid
                http://www.ibm.com/schema/objectgrid/objectgrid.xsd">
    
    <bean class="com.mycompany.MyBean" 
   scope="objectgrid:shard">
    ...
    </bean>

...
      




       
    3.  Create PluginServiceFactory bean definitions for each plug-in bean. All WXS beans must have a PluginServiceFactory bean defined so that the correct bean scope can be applied.  WXS includes a BlueprintServiceFactory that we can use. It includes two properties that must be set.  Set the blueprintContainer property to the blueprintContainer reference, and the beanId property must be set to the bean identifier name.  When WXS looks up the service to instantiate the appropriate beans, the server looks up the bean component instance using the Blueprint container.


      bean id="myPluginBeanFactory"
    class="com.ibm.websphere.objectgrid.plugins.osgi.BluePrintServiceFactory">
    <property name="blueprintContainer" ref="blueprintContainer" />
    <property name="beanId" value="myPluginBean" />
</bean>

      



       
    4.  Create a service manager for each PluginServiceFactory bean.  Each service manager exposes the PluginServiceFactory bean,
using the <service> element. The service element identifies the name to expose to OSGi, the reference to the PluginServiceFactory bean,
the interface to expose, and the ranking of the service.  WXS uses the service manager ranking to perform service upgrades when the WXS grid is active. 
 If the ranking is not specified, the OSGi framework assumes a ranking of 0. 

        Blueprint includes several options for configuring service managers.  To define
a simple service manager for a PluginServiceFactory bean,
create a <service> element for each PluginServiceFactory bean:


      <service ref="myPluginBeanFactory"
    interface="com.ibm.websphere.objectgrid.plugins.osgi.PluginServiceFactory"
    ranking="1">
</service> 
      




       
    5.  Store the Blueprint XML file in the plug-ins bundle.  The Blueprint XML file must be stored in the OSGI-INF/blueprint directory for the Blueprint container to be discovered.

        To store the Blueprint XML file in a different directory, specify the following Bundle-Blueprint manifest header:


      Bundle-Blueprint: OSGI-INF/blueprint.xml
      



     


     
     Results
    


    The WXS plug-ins are now configured to be exposed in an OSGi Blueprint container, In addition, the ObjectGrid descriptor XML file is configured to reference the plug-ins using the OSGi Blueprint service.















      Configure servers with OSGi Blueprint
    


      We can configure  WXS container servers using an OSGi blueprint XML file, allowing simplified packaging and development of self-contained server bundles. 

    This topic assumes that the following tasks have been completed:



     
      

    •  The Eclipse Equinox OSGi framework has been installed and started with either the Eclipse Gemini or Apache Aries blueprint container.


    •  The WXS server bundle has been installed and started.


    •  The WXS dynamic plug-ins bundle has been created.


    •  The WXS ObjectGrid descriptor XML file and deployment policy XML file have been created.


     
        


     

      This task describes how to configure a WXS server with a container using a blueprint XML file.  The result of the procedure is a container bundle.  When the container bundle is started, the WXS server bundle will track the bundle, parse the server XML and start a server and container.


      A container bundle can optionally be combined with the application and WXS plug-ins when dynamic plug-in updates are not required or the plug-ins do not support dynamic updating.





     
      

       
    1.  Create a Blueprint XML file with the objectgrid namespace included. We can name the file anything. However, it must include the blueprint namespace:


      <?xml version="1.0" encoding="UTF-8"?>

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance xmlns:objectgrid="http://www.ibm.com/schema/objectgrid"
           xsi:schemaLocation="http://www.ibm.com/schema/objectgrid
                http://www.ibm.com/schema/objectgrid/objectgrid.xsd">
...
</blueprint>

      



       
    2.  Add the XML definition for the WXS server with the appropriate server properties. See the Spring descriptor XML file for details on all available configuration properties. See the following example of the XML definition:


      <objectgrid:server id="xsServer" tracespec="ObjectGridOSGi=all=enabled" 
tracefile="logs/osgi/wxsserver/trace.log" jmxport="1199" listenerPort="2909">
<objectgrid:catalog host="catserver1.mycompany.com" port="2809" />
<objectgrid:catalog host="catserver2.mycompany.com" port="2809" />
</objectgrid:server>

      



       
    3.  Add the XML definition for the WXS container with the reference to the server definition and the ObjectGrid descriptor XML
and ObjectGrid deployment XML files embedded in the bundle; for example: 


      <objectgrid:container id="container"
    objectgridxml="/META-INF/objectGrid.xml" 
    deploymentxml="/META-INF/objectGridDeployment.xml"
    server="xsServer" />

      



       
    4.  Store the Blueprint XML file in the container bundle.  The Blueprint XML must be stored in the OSGI-INF/blueprint directory for the Blueprint container to be found.  

        To store the Blueprint XML in a different directory, specify the Bundle-Blueprint manifest header; for example:


      Bundle-Blueprint: OSGI-INF/blueprint.xml
      




       
    5.  Package the files into a single bundle JAR file. See the following example of a bundle directory hierarchy:


      MyBundle.jar /META-INF/manifest.mf /META-INF/objectGrid.xml /META-INF/objectGridDeployment.xml /OSGI-INF/blueprint/blueprint.xml
      


     


     
     Results
    


    An WXS container bundle is now created and can be installed in Eclipse Equinox.  When the container bundle is started, the WXS server runtime environment in the WXS server bundle, will automatically start the singleton WXS server using the parameters defined in the bundle, and starts a container server. 
The bundle can be stopped and started, which results in the container stopping and starting.  The server is a singleton and does not stop when the bundle is started the first time.












      Configure servers with OSGI config admin
    


      Use the OSGi configuration administration (config admin) service to configure  WXS container servers. 


     To configure a server, the ManagedService persistent identifier (PID), com.ibm.websphere.xs.server, is set to reference the ObjectGrid server properties file on the file system.
 To configure a container, the ManagedServiceFactory PID, com.ibm.websphere.xs.container, is set to reference the ObjectGrid deployment XML file and ObjectGrid deployment policy XML file on the file system.

      When the two PIDs are set in the config admin service, the WXS server service automatically initializes the server and start the container with the specified configuration files. Config admin PIDs are persisted to the OSGi configuration directory.  If the configuration is not cleared, the settings are retained between framework restarts.


      Several third-party utilities exist for setting config admin properties.
The following utilities are examples of tools that the product supports:



     
      

    •  The Luminis OSGi Configuration Admin command line client allows command line configuration. 


    •  Apache Felix File Install  allows specifying config admin PID settings in standard property files.


     



      To configure WXS container servers with the OSGi Configuration Administration command-line client for Luminis...




     
      

       
    1.  Create a managed service PID for the ObjectGrid server properties file in the OSGi console, by running the following commands: 


      osgi> cm create com.ibm.websphere.xs.server osgi> cm put com.ibm.websphere.xs.server objectgrid.server.props /mypath/server.properties
      



       
    2.  Create a managed service factory persistence identifier PID for the ObjectGrid container in the OSGi  console by running the following commands. 

         Use the PID
that is created with the createf config admin command.
The PID used in the following code snippet is only an example.



      osgi> cm createf com.ibm.websphere.xs.container PID: com.ibm.websphere.xs.container-123456789-0
osgi> cm put com.ibm.websphere.xs.container-123456789-0 objectgridFile /mypath/objectGrid.xml osgi> cm put com.ibm.websphere.xs.container-123456789-0 deploymentPolicyFile /mypath/deployment.xml
      


     


     
     Results
    WXS container servers are now configured to start in an Eclipse Equinox OSGi framework.


     
     What to do next
    


    Container servers can also be programmatically created using the ServerFactory API and OSGi bundle activators.  









     20.  Scenario: Configuring HTTP session failover in the Liberty profile
    


      We can configure a web application server so that, when the web server receives an HTTP request for session replication, the request is forwarded to one or more servers that run in the Liberty profile.




    To complete this task, you must install the Liberty profile. 


     The Liberty profile does not include session replication.
However, if you use  WXS with the Liberty profile, then we can replicate sessions. Therefore, if a server fails, then application users do not lose session data.


      When you add the  webApp feature to the server definition and configure the session manager, we can use session replication in your WXS applications that run in the Liberty profile.



      
    








      Enable the WXS web feature in the Liberty profile
    


      We can enable the web feature to use HTTP session failover in the Liberty profile.


     

       The web feature is deprecated.
Use the webApp feature instead. When you add the webApp feature to the server definition and configure the session manager, we can use session replication in your  WXS applications that run in the Liberty profile.


      When you install the WAS Liberty profile, it does not include session replication. However, if you use  WXS with the Liberty profile,
then we can replicate sessions so that if a server goes down, the application users do not lose session data.


      When you add the web feature to the server definition and configure the session manager,
we can use session replication in your WXS applications that run in the Liberty profile.




      Define a web application to run in the Liberty profile .


     
     What to do next
    


    Next, configure a web server plug-in to forward HTTP requests to multiple servers in the Liberty profile.





      Related reference:
    


      Liberty profile web feature properties 


      Liberty profile webGrid feature properties 


      Liberty profile webApp feature properties 








      Enable the WXS webGrid feature in the Liberty profile
    


       Use the webGrid feature to automatically start a container to host the clients for HTTP session replication in the Liberty profile.


     When you install the WAS Liberty profile, it does not include session replication. However, if you use  WXS with the Liberty profile,
then we can replicate sessions so that if a server goes down, the application users do not lose session data.

      When you add the webGrid feature to the server definition and configure the session manager,
we can use session replication in your WXS applications that run in the Liberty profile.




      Add the following webGrid feature to the Liberty profile server.xml file. The webGrid feature includes the client feature and the server feature.  You likely want to separate your web applications from the data grids. For example, you have one Liberty profile server for your web applications and a different Liberty profile server for hosting the data grid.


    <featureManager>
<feature>eXtremeScale_webGrid-1.1</feature>
</featureManager>

    



     
     Results
    


    Your web applications can now persist its session data in a  WXS grid.


     
     Example
    


    The webGrid feature has meta type properties that we can set on the xsWebGrid element of server.xml. See the following example of a server.xml file, which contains the webGrid feature that you use when you connect to the data grid remotely.


    <server description="Airport Entry eXtremeScale Getting Started Client Web Server">
<!--
This sample program is provided AS IS and may be used, executed, copied and modified without royalty payment by customer (a) for its own instruction and study,
(b) to develop applications designed to run with an IBM WebSphere product,
either for customer's own internal use or for redistribution by customer, as part of such an application, in customer's own products.
Licensed Materials - Property of IBM
5724-X67, 5655-V66 (C) COPYRIGHT International Business Machines Corp. 2012
-->
<!-- Enable features -->
<featureManager>
<feature>eXtremeScale.webGrid-1.1</feature>
</featureManager>

<xsServer catalogServer="true"/>

<xsWebGrid objectGridName="session" catalogHostPort="remoteHost:2809" securityEnabled="false" />

</server>

    












      Enable the WXS webApp feature in the Liberty profile
    


       A Liberty profile server can host a data grid that caches data for applications to replicate HTTP session data for fault tolerance.


     When you install the WAS Liberty profile, it does not include session replication. However, if you use  WXS with the Liberty profile,
then we can replicate sessions so that if a server goes down, the application users do not lose session data.

      When you add the webApp feature to the server definition and configure the session manager,
we can use session replication in your WXS applications that run in the Liberty profile.




      Add the following webApp feature to the Liberty profile server.xml file. The webApp feature includes the client feature;
however, it does not include the server feature.  You likely want to separate your web applications from the data grids. For example, you have one Liberty profile server for your web applications and a different Liberty profile server for hosting the data grid.


    <featureManager>
<feature>eXtremeScale_webapp-1.1</feature>
</featureManager>

    



     
     Results
    


    Your web applications can now persist its session data in a  WXS grid.


     
     Example
    


    See the following example of a server.xml file, which contains the webApp feature that you use when you connect to the data grid remotely.


    <server description="Airport Entry eXtremeScale Getting Started Client Web Server">
<!--
This sample program is provided AS IS and may be used, executed, copied and modified without royalty payment by customer (a) for its own instruction and study,
(b) to develop applications designed to run with an IBM WebSphere product,
either for customer's own internal use or for redistribution by customer, as part of such an application, in customer's own products.
Licensed Materials - Property of IBM
5724-X67, 5655-V66 (C) COPYRIGHT International Business Machines Corp. 2012
-->
<!-- Enable features -->
<featureManager>
<feature>eXtremeScale.webapp-1.1</feature>
</featureManager>

<httpEndpoint id="defaultHttpEndpoint"
host="*"
httpPort="${default.http.port}"
httpsPort="${default.https.port}" />

<xsWebApp objectGridName="session" catalogHostPort="remoteHost:2809" securityEnabled="false" />

</server>

    



     
     What to do next
    


    The webApp feature has meta type properties that we can set on the xsWebApp element of server.xml. 











      Configure a web server plug-in to forward requests to multiple servers in the Liberty profile
    


      Use this task to configure the web server plug-in to distribute HTTP server requests between multiple servers in the Liberty profile.




    Before you configure the web server plug-in to route HTTP
requests to multiple server, complete the following task:



     
     



     Configure the web server plug-in so that the web server receives an HTTP request for dynamic resources, the request is forwarded to multiple servers that run in the Liberty profile. 



      See Configuring the Liberty profile with a web server plug-in  in the WAS Information Center to complete this task.


     
     What to do next
    


    Next, merge the plugin-cfg.xml files from multiple application server cells. Also ensure that unique clone IDs exist for each application server that runs in the Liberty profile.










      Merge plug-in configuration files for deployment to the application server plug-in
    


      Generate plug-in configuration files after you configure a unique clone ID in the Liberty server.xml configuration file.




    If we are generating and merging plug-in configuration files to configure HTTP session failover in a Liberty profile, then you must complete the following tasks:



     
     



     Use the WAS admin console to complete this task.




     
      

       
    1.  Merge the plugin-cfg.xml files from multiple application server cells. We can either manually merge the plugin-cfg.xml files or use the pluginCfgMerge tool to automatically merge the plugin-cfg.xml file from multiple application server profiles into a single output file. The pluginCfgMerge.bat and pluginCfgMerge.sh files are in the install_root/bin directory.   

        



       
    2.  Ensure that the cloneID value for each application server is unique.  Examine the cloneID value for each application server in the merged file to ensure that this value is unique for each application server. If the cloneID values in the merged file are not all unique, or if we are running with memory to memory session replication in peer to peer mode, use the administrative console to configure unique HTTP session cloneIDs.  


        To configure a unique HTTP session clone ID with the WAS admin console...


       
        


      1.  Click...


          
 Servers | Server Types | WebSphere application servers | server_name | Container Settings | Web Container Settings | Web container | Additional Properties Custom properties | New

        




      2.  Enter HttpSessionCloneId in the Name field, and enter a unique value for the server in the Value field.  The unique value must be eight to nine alphanumeric characters in length. For example, test1234 is a valid cloneID value. 



      3.  Click Apply or OK.



      4.  Click Save to save the configuration changes to the master configuration.

       



       
    3.  Copy the merged plugin-cfg.xml file to the plugin_installation_root/config/web_server_name directory on the web server host.


       
    4.  Ensure that you defined the correct operating system, file access permissions for the merged plugin-cfg.xml file. These file access permissions allow the HTTP server plug-in process to read the file.

     


     
     Results
    


    When you complete this task, you have one plug-in configuration file for multiple application server cells, and your WXS applications that run in the Liberty profile are enabled for session replication.










     21.  Configure an Enterprise Data Grid for dynamic caching using a Liberty profile
    


       A Liberty profile server can host a data grid that caches data for applications that have dynamic cache enabled.





     
      

    •  Install the Liberty profile.



    •  Create an application that uses dynamic cache. 


     



      The Liberty profile hosts the data grid which supports dynamic-cache-enabled applications. This means that the application runs on a traditional installation of WAS. For those applications to be cached by the WXS runtime environment, configure WAS to use the catalog domain service and server properties that you specify in the Liberty profile. 




     
      

       
    1.  Enable the  WXS dynamic cache feature.


       
        

      1.  Add the dynamic cache feature to the Liberty profile server.xml file. For example, your server.xml file resembles the following stanza of code:


        <featureManager>
<feature>eXtremeScale.server-1.1</feature>
<feature>eXtremeScale.dynacacheGrid-1.1</feature>
</featureManager>

        


       



       
    2.  Optional: Set properties on the xsDynacacheGrid element in server.xml.  We can change any of the following properties; however, it is recommended that you accept the default values.

       
       globalIndexDisabled
      


       Global index invalidation  improves invalidation efficiency in a large, partitioned environment; for example, more than 40 partitions.
Default: false
      


       objectGridName
      


       Name of the data grid. Default: DYNACACHE_REMOTE.

      


       ojectGridTxTimeout 
      


       Amount of time in seconds that a transaction is allowed for completion. If a transaction does not complete in this amount of time, the transaction is marked for rollback and a TransactionTimeoutException exception results.  Default: 30 (in seconds)
      


       backingMapLockStrategy 
      


       Specifies if the internal lock manager is used whenever a map entry is accessed by a transaction. Set this attribute to one of three values: OPTIMISTIC, PESSIMISTIC,
or NONE. Default: PESSIMISTIC
      


       backingMapCopyMode
      


       Specifies if a get operation of an entry in the BackingMap instance returns the actual value, a copy of the value,
or a proxy for the value. If you use XDF so that both Java and .NET can access the same data grid, then the default and required copy mode is COPY_TO_BYTES. Otherwise, the copy mode, COPY_ON_READ_AND_COMMIT
is used.  Set the CopyMode attribute  to one of five values: 


       
      

       
       COPY_ON_READ_AND_COMMIT
      


       
       The default value is COPY_ON_READ_AND_COMMIT.
Set the value to COPY_ON_READ_AND_COMMIT to ensure that an application never has a reference to the value object that is in the BackingMap instance. Instead, the application is always working with a copy of the value that is in the BackingMap instance.
(Optional)
      


       
       COPY_ON_READ
      


       
       Set the value to COPY_ON_READ to improve performance over the COPY_ON_READ_AND_COMMIT value by eliminating the copy that occurs when a transaction is committed.
To preserve the integrity of the BackingMap data, the application commits to delete every reference to an entry after the transaction is committed. Setting this value results in an ObjectMap.get method returning a copy of the value instead of a reference to the value,
which ensures changes that are made by the application to the value does not affect the BackingMap element until the transaction is committed. 
      


       
       COPY_ON_WRITE
      


       
       Set the value to COPY_ON_WRITE to improve performance over the COPY_ON_READ_AND_COMMIT value by eliminating the copy that occurs when ObjectMap.get method is called for the first time by a transaction for a given key. Instead, the ObjectMap.get method returns a proxy to the value instead of a direct reference to the value object. The proxy ensures that a copy of the value is not made unless the application calls a set method on the value interface. 
      


       
       NO_COPY
      


       
       Set the value to NO_COPY to allow an application to never modify a value object that is obtained using an ObjectMap.get method in exchange for performance improvements. Set the value to NO_COPY for maps associated with EntityManager API entities.
      


       
       COPY_TO_BYTES
      


       
       Set the value to COPY_TO_BYTES to improve memory footprint for complex Object types and to improve performance when the copying of an Object relies on serialization to make the copy. If an Object is not Cloneable or a custom ObjectTransformer  with an efficient copyValue method is not provided,
the default copy mechanism is to serialize and inflate the object to make a copy. With the COPY_TO_BYTES setting,
inflate is only performed during a read and serialize is only performed during commit.
      

      


      Default: COPY_ON_READ_AND_COMMIT
      


       backingMapNearCacheEnabled
      


       Set true to enable the client local cache. To use a near cache, the lockStrategy attribute must be set to NONE or OPTIMISTIC.


      Default: false
      


       mapSetNumberOfPartitions
      


       Number of partitions for the mapSet element. 

      Default: 47
      


       mapSetMinSyncReplicas 
      


       Minimum number of synchronous replicas for each partition in the mapSet. Shards are not placed until the domain can support the minimum number of synchronous replicas. To support the minSyncReplicas value, you need one more container server than the minSyncReplicas value.
If the number of synchronous replicas falls below the minSyncReplicas value,
write transactions are no longer allowed for that partition. Default: 0
      


       mapSetMaxSyncReplicas
      


       Maximum number of synchronous replicas for each partition in the mapSet. No other synchronous replicas are placed for a partition after a domain reaches this number of synchronous replicas for that specific partition. Adding container servers that can support this ObjectGrid can result in an increased number of synchronous replicas if your maxSyncReplicas value has not already been met. Default: 0
      


       mapSetNumInitialContainers
      


       Number of container servers that are required before initial placement occurs for the shards in this mapSet element. This attribute can help save process and network bandwidth when bringing a data grid online from a cold startup. Default: 1
      


       mapSetDevelopmentMode
      


       With this attribute, we can influence where a shard is placed in relation to its peer shards. When the developmentMode attribute is set to false, no two shards from the same partition are placed on the same computer. When the developmentMode attribute is set to true, shards from the same partition can be placed on the same machine. In either case, no two shards from the same partition are ever placed in the same container server. Default: false
      


       mapSetReplicaReadEnabled
      


       If set true, read requests are distributed amongst a partition primary and its replicas.
If the replicaReadEnabled attribute is false,
read requests are routed to the primary only. Default: false
      

      
.


       
    3.  Configure WAS to point to the Liberty profile. 

        We can connect  WXS containers and dynamic-cache-enabled web applications to a catalog service domain running in another WAS cell or as stand-alone processes. Because remotely configured catalog servers do not automatically start in the cell, manually start any remotely configured catalog servers. 


        When you configure a remote catalog service domain, the domain name must match the domain name specified when you start the remote catalog servers.
The default catalog service domain name for stand-alone catalog servers is false Domain. Specify a catalog service domain name with the startOgServer or startXsServer command -domain parameter,
a server properties file, or with the embedded server API. Start each remote catalog server process in the remote domain with the same domain name. 


     











     22.  Configure WXS REST clients in the Liberty profile
    


       As an administrator, we can define multiple client domain endpoint configurations that can be used by client applications and other features, such as the  WXS REST gateway.


     As a developer, we can write applications without knowing which grid servers that the applications will connect to. For example, one of your customers might have separate servers for test and production.
An administrator can configure which environment the application references without making any code changes.




     
      

       
    1.  Define the client domain in server.xml. 
       In the following example, test is the default client domain.
If the remoteDomain attribute is not set, then the default domain is used. 


      <xsClientDomain default="test">
    <endpointConfig> test ; testHost1:2809,testHost2:2809 ; /home/testuser/client_security.props </endpointConfig>
    <endpointConfig> dev; localhost:2809,testHost2:2809 </endpointConfig>   <!-- note that client security props file is optional -->
    <endpointConfig> production; prodHost1:2809,prodHost2:2809,prodHost3:2809 ; /home/testuser/client_security.props </endpointConfig> 
</xsClientDomain>

      
The endpointConfig element is used to specify endpoint data for a data grid. This element has the following syntax:


      endpoint name ; comma-separated list of hostname:port pairs ; path to client security properties file
      
The path to the client security properties file is optional. If it is not specified, then the client connects with the assumption that data grid security is disabled.


       
    2.  Configure the REST gateway now that you have set the previous configuration; for example: 


      <xsREST remoteDomain="dev" />

      



       
    3.  Optional: As a developer, we can access the configured client domains; for example: 


      CatalogDomainManager catalogDomainManager = objectGridManager.getCatalogDomainManager();
CatalogDomainInfo catalogDomainInfo = catalogDomainManager.getDomainInfo("dev");
if (catalogDomainInfo == null) {
catalogDomainInfo = catalogDomainManager.getdefault DomainInfo();}
ClientClusterContext ccc = objectGridManager.connect(catalogDomainInfo.getClientCatalogServerEndpoints(),
catalogDomainInfo.getClientSecurityConfiguration(), null);
...