Product overview > Tutorials, examples, and samples



Run the getting started sample application

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 data grid and client can be used. The getting started sample is in the wxs_install_root/ObjectGrid/gettingstarted directory.

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


Scripts and their functions

This sample provides the following four scripts:

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

The runcat.sh starts the eXtreme Scale catalog service process on the local system.

The runcontainer.sh script starts 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.

The runclient.sh script runs the simple CRUD client and starts the given operation.

For command, use one of the following options:

The installRoot/ObjectGrid/ gettingstarted/src/Client.java file is the client program that demonstrates how to connect to a catalog server, obtain an ObjectGrid instance, and use the ObjectMap API.


Basic steps

Use the following steps to start your first data grid and run a client to interact with the data grid.

  1. Open a terminal session or command line window.

  2. Use the following command to navigate to the gettingstarted directory:

    cd wxs_install_root/ObjectGrid/gettingstarted

    Substitute wxs_install_root with the path to the eXtreme Scale installation root directory or the root file path of the extracted eXtreme Scale trial wxs_install_root.

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

    • [Unix][Linux] ./runcat.sh

    • [Windows] runcat.bat

    The catalog service process runs in the current terminal window.

  4. Open another terminal session or command line window, and run the following command to start a container server instance:

    • [Unix][Linux] ./runcontainer.sh server0

    • [Windows] runcontainer.bat server0

    The container server runs in the current terminal window. You can repeat this step with a different server name if you want to start more container server instances to support replication.

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

    • Add data to the data grid:

      • [Unix][Linux] ./runclient.sh i key1 helloWorld

      • [Windows] runclient.bat i key1 helloWorld

    • Search and display the value:

      • [Unix][Linux] ./runclient.sh g key1

      • [Windows] runclient.bat g key1

    • Update the value:

      • [Unix][Linux] ./runclient.sh u key1 goodbyeWorld

      • [Windows] runclient.bat u key1 goodbyeWorld

    • Delete the value:

      • [Unix][Linux] ./runclient.sh d key1

      • [Windows] runclient.bat d key1

  6. 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_install_root/ObjectGrid/gettingstarted/xml directory to start a container server. The objectgrid.xml file is the ObjectGrid descriptor XML file. The deployment.xml file is the ObjectGrid deployment policy descriptor XML file. These 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 startup. 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 data 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 the wxs_install_root/ObjectGrid/gettingstarted/client/src/ directory 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. Connect 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 only requires catalog server endpoint in the format of hostname:port. You can indicate multiple catalog server endpoints by separating the list of hostname:port values with commas. 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);
    

    If the connections to the catalog servers succeed, the connect method returns a ClientClusterContext instance. The ClientClusterContext instance is required to obtain the ObjectGrid from ObjectGridManager API.

  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 data grid instance. The ClientClusterContext instance is obtained during the connection to catalog server. The name of ObjectGrid instance is Grid that is specified in the objectgrid.xml file. The following code snippet demonstrates how to obtain the data grid by calling the getObjectGrid method of the ObjectGridManager API.

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

  3. Get a Session instance

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

    Session sess = grid.getSession();
    

  4. Get an ObjectMap instance

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

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

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

  5. Use the ObjectMap methods

    After an ObjectMap is obtained, you can use the ObjectMap API. Remember that the ObjectMap interface 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 in the application, the ObjectMap operations run with auto-commit transactions.

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

    map1.insert(key1, value1);
    

    The following code snippet demonstrates how to use the 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 deployment manager process and each WebSphere Application Server instance hosts a container server automatically. Java™ Platform, Enterprise Edition 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.


Parent topic:

Tutorials, examples, and samples