WebSphere eXtreme Scale Administration Guide >

Get started with WebSphere eXtreme Scale

Get started sample

The stand-alone installation of WebSphere eXtreme Scale includes a sample...

WXS_ROOT/ObjectGrid/gettingstarted

...that provides a quick introduction to eXtreme Scale functionality and basic operation. The sample consists of...

• Shell scripts designed to start a simple grid
• A client program, including source, to run create, read, update, and delete (CRUD) functions

In a WAS environment with WebSphere eXtreme Scale enabled, the most common scenario is a network-attached topology. The catalog server is hosted in the WAS deployment manager process. Each WAS instance hosts an eXtreme Scale server.

JEE applications should include the ObjectGrid descriptor and ObjectGrid deployment policy descriptor XML files in /META-INF, and the ObjectGrid becomes available automatically.

An application can then connect to a locally available catalog server and obtain an ObjectGrid instance to use.

Scripts

env.sh	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 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 start 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 client program that demonstrates how to...

• connect to a catalog server
• obtain an ObjectGrid instance
• use the ObjectMap API

...is...

WXS_ROOT/ObjectGrid/gettingstarted/src/Client.java file

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

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.

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

WXS_ROOT/ObjectGrid/gettingstarted/xml

...to start a container server.

• objectgrid.xml is the ObjectGrid descriptor
• deployment.xml is the ObjectGrid deployment policy descriptor

Both files together define a distributed ObjectGrid topology.

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>

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. Obtain a client ObjectGrid instance.
3. Get a Session instance.
4. Get an ObjectMap instance.
5. Use the ObjectMap methods.

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

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

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

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

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

+

Search Tips   |   Advanced Search