WebSphere eXtreme Scale Programming Guide >


Get started with WebSphere eXtreme Scale


After you install WebSphere eXtreme Scale in a stand-alone environment, use the following steps as a simple introduction to its capability as an in-memory data grid.

The stand-alone installation of WebSphere eXtreme Scale includes a sample that you can use to verify the installation and to see how a simple eXtreme Scale grid and client can be used. The getting started sample is in...

WXS_ROOT/ObjectGrid/gettingstarted

The getting started sample provides a quick introduction to eXtreme Scale functionality and basic operation. The sample consists of shell and batch scripts designed to start a simple grid with very little customization needed. In addition, a client program, including source, is provided to run simple create, read, update, and delete (CRUD) functions to this basic grid.


Scripts and their functions

This sample provides the following four scripts:

env.sh script Called by the other scripts to set needed environment variables. Normally you do not need to change this script.

    ./env.sh
runcat.sh Start the eXtreme Scale catalog service process on the local system.

    ./runcat.sh
runcontainer.sh Start a container server process. You can run this script multiple times with unique server names specified to start any number of containers. These instances can work together to host partitioned and redundant information in the grid.

    ./runcontainer.sh unique_server_name
runclient.sh Run the simple CRUD client and starts the given operation.

    ./runclient.sh command value1 value2

For command, use one of the following options:

i Insert value2 into grid with key value1
u Update object keyed by value1 to value2
d Delete object keyed by value1
g Retrieve and display object keyed by value1

The file...

WXS_ROOT/ObjectGrid/gettingstarted/src/Client.java

...is the client program that demonstrates how to connect to a catalog server, obtain an ObjectGrid instance, and use the ObjectMap API.


Basic steps

To start your first grid and run a client to interact with the grid.

  1. Open a terminal session.

  2. Navigate to the gettingstarted directory:

    cd WXS_ROOT/ObjectGrid/gettingstarted

  3. Set or export the JAVA_HOME environmental variable to reference a valid JDK or JRE v1.5 or later installation directory.

    export JAVA_HOME=Java_home_directory

    [Windows] set JAVA_HOME=Java_home_directory

  4. Run the following script to start a catalog service process on localhost:

    • ./runcat.sh

    The catalog service process runs in the current terminal window.

  5. Open another terminal session or command line window, and start a container server instance:

      ./runcontainer.sh server0

    The container server runs in the current terminal window. You can start more container server instances to support replication.

  6. Open another terminal session or command line window to run client commands.

    • Add data to the grid:

        ./runclient.sh i key1 helloWorld

    • Search and display the value:

        ./runclient.sh g key1

    • Update the value:

        ./runclient.sh u key1 goodbyeWorld

    • Delete the value:

        ./runclient.sh d key1

  7. Use <ctrl+c> to stop the catalog service process and container servers in the respective windows.


Define an ObjectGrid

The sample uses the objectgrid.xml and deployment.xml files that are in the WXS_ROOT/ObjectGrid/gettingstarted/xml directory to start a container server. The objectgrid.xml file is the ObjectGrid descriptor XML file and the deployment.xml file is the ObjectGrid deployment policy descriptor XML file. Both files together define a distributed ObjectGrid topology.


ObjectGrid descriptor XML file

An ObjectGrid descriptor XML file is used to define the structure of the ObjectGrid that is used by the application. It includes a list of BackingMap configurations. These BackingMaps are the actual data storage for cached data. The following example is a sample objectgrid.xml file. The first few lines of the file include the required header for each ObjectGrid XML file. This example file defines the Grid ObjectGrid with Map1 and Map2 BackingMaps.

<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" /> 
            <backingMap name="Map2" /> 
        </objectGrid> 
    </objectGrids> 

</objectGridConfig>


Deployment policy descriptor XML file

A deployment policy descriptor XML file is passed to an ObjectGrid container server during start-up. A deployment policy must be used with an ObjectGrid XML file and must be compatible with the ObjectGrid XML that is used with it. For each objectgridDeployment element in the deployment policy, have a corresponding ObjectGrid element in the ObjectGrid XML. The backingMap elements that are defined within the objectgridDeployment element must be consistent with the backingMaps found in the ObjectGrid XML. Every backingMap must be referenced within one and only one mapSet.

The deployment policy descriptor XML file is intended to be paired with the corresponding ObjectGrid XML, the objectgrid.xml file. In the following example, the first few lines of the deployment.xml file include the required header for each deployment policy XML file. The file defines the objectgridDeployment element for the Grid ObjectGrid that is defined in the objectgrid.xml file. Both the Map1 and Map2 BackingMaps that are defined within the Grid ObjectGrid are included in the mapSet mapSet that has the numberOfPartitions, minSyncReplicas, and maxSyncReplicas attributes configured.

<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="Grid"> 
        <mapSet name="mapSet" numberOfPartitions="13" minSyncReplicas="0" maxSyncReplicas="1" > 
            <map ref="Map1"/> 
            <map ref="Map2"/> 
        </mapSet> 
    </objectgridDeployment> 

</deploymentPolicy>

The numberOfPartitions attribute of the mapSet element specifies the number of partitions for the mapSet. It is an optional attribute and the default is 1. The number should be appropriate for the anticipated capacity of the grid.

The minSyncReplicas attribute of mapSet is to specify the minimum number of synchronous replicas for each partition in the mapSet. It is an optional attribute and the default is 0. Primary and replica are not placed until the domain can support the minimum number of synchronous replicas.

To support the minSyncReplicas value, you need one more container than the value of minSyncReplicas. If the number of synchronous replicas falls below the value of minSyncReplicas, write transactions are no longer allowed for that partition.

The maxSyncReplicas attribute of mapSet is to specify the maximum number of synchronous replicas for each partition in the mapSet. It is an optional attribute and the default is 0. No other synchronous replicas are placed for a partition after a domain reaches this number of synchronous replicas for that specific partition. Adding containers that can support this ObjectGrid can result in an increased number of synchronous replicas if the maxSyncReplicas value has not already been met. The sample set the maxSyncReplicas to 1 means the domain will at most place one synchronous replica. If you start more than one container server instance, there will be only one synchronous replica placed in one of the container server instances.


Use ObjectGrid

The Client.java file in...

WXS_ROOT/ObjectGrid/gettingstarted/src/

...is the client program that demonstrates how to connect to catalog server, obtain ObjectGrid instance, and use ObjectMap API.

From the perspective of a client application, using WebSphere eXtreme Scale can be divided into the following steps.

  1. Connect to the catalog service by obtaining a ClientClusterContext instance.
  2. Obtaining a client ObjectGrid instance.
  3. Get a Session instance.
  4. Get an ObjectMap instance.
  5. Use the ObjectMap methods.


1. Connecting to the catalog service by obtaining a ClientClusterContext instance

To connect to the catalog server, use the connect method of ObjectGridManager API.

The connect method that is used by this sample only requires catalog server endpoint in the format of hostname:port, such as localhost:2809. If the connection to the catalog server succeeds, the connect method returns a ClientClusterContext instance. The ClientClusterContext instance is required to obtain the ObjectGrid from ObjectGridManager API.

The following code snippet demonstrates how to connect to a catalog server and obtain a ClientClusterContext instance.

ClientClusterContext ccc = ObjectGridManagerFactory.getObjectGridManager().connect(localhost:2809, null, null);


2. Obtaining an ObjectGrid instance

To obtain ObjectGrid instance, use the getObjectGrid method of the ObjectGridManager API. The getObjectGrid method requires both the ClientClusterContext instance and the name of the ObjectGrid instance. The ClientClusterContext instance is obtained during connecting to catalog server. The name of ObjectGrid is “Grid” that is specified in the objectgrid.xml file. The following code snippet demonstrates how to obtain ObjectGrid by calling getObjectGrid method of ObjectGridManager API.

ObjectGrid grid = ObjectGridManagerFactory.getObjectGridManager().getObjectGrid(ccc, “Grid”);


3. Getting a Session instance

You can get a Session from the obtained ObjectGrid instance. A Session instance is required to get ObjectMap, and perform transaction demarcation. The following code snippet demonstrates how to get Session by calling getSession method of ObjectGrid API.

Session sess = grid.getSession();


4. Getting an ObjectMap instance

After getting a Session, you can get ObjectMap from a Session by calling getMap method of Session API. You have to pass the name of map as parameter to getMap method in order to get the ObjectMap. The following code snippet demonstrates how to obtain ObjectMap by calling getMap method of Session API.

ObjectMap map1 = sess.getMap("Map1");


5. Using the ObjectMap methods

After an ObjectMap is obtained, you can use ObjectMap API. Remember ObjectMap is a transactional map and requires transaction demarcation by using the begin and commit methods of the Session API. If there is no explicit transaction demarcation, ObjectMap operations run with auto-commit transactions.

The following code snippet demonstrates how to use ObjectMap API with auto-commit transaction.

map1.insert(key1, value1);

The following code snippet demonstrates how to use ObjectMap API with explicit transaction demarcation.

sess.begin();
map1.insert(key1, value1);
sess.commit();


Additional information

This sample demonstrates how to start catalog server and container server and using ObjectMap API in stand-alone environment. You can also use the EntityManager API.

In a WebSphere Application Server environment with WebSphere eXtreme Scale installed or enabled, the most common scenario is a network-attached topology. In a network-attached topology, the catalog server is hosted in the WebSphere Application Server deployment manager process and each WebSphere Application Server instance hosts an eXtreme Scale server automatically. JEE applications only need to include both the ObjectGrid descriptor XML file and the ObjectGrid deployment policy descriptor XML file in the META-INF directory of any module and the ObjectGrid becomes available automatically. An application can then connect to a locally available catalog server and obtain an ObjectGrid instance to use.


+

Search Tips   |   Advanced Search