This page describes an older version of the product. The latest stable version is 16.4.

XAP in 5 Minutes


This tutorial explains how to deploy and use a XAP Data Grid from a Java client application.

Download and Install XAP
  • Download and unzip the latest XAP release from the downloads page
  • Unzip the distribution into a working directory; GS_HOME
  • Set the JAVA_HOME environment variable to point to the JDK root directory
  • Start your favorite Java IDE
  • Create a new project
  • Include all files from the GS_HOME/lib/required in the classpath

Starting a Service Grid

A Data Grid requires a Service Grid to host it. A service grid is composed of one or more machines (service grid nodes) running a Service Grid Agent (or GSA), and provides a framework to deploy and monitor applications on those machines, in our case the Data Grid.

In this tutorial you’ll launch a single node service grid on your machine. To start the service grid, simply run the gs-agent script from the product’s bin folder.

./gs-agent.sh
gs-agent.bat
Optional - The Web Console

XAP provides a web-based tool for monitoring and management. From the bin folder start the gs-webui script, then browse to localhost:8099. Click the ‘Login’ button and take a look at the Dashboard and Hosts tabs - you’ll see the service grid components created on your machine.

Deploying the Data Grid

The Data grid can be deployed from command line, from the web management tool or via an Administration API. In this tutorial we’ll use the command line.

Start a command line, navigate to the product’s bin folder and run the following command:

./gs.sh deploy-space -cluster total_members=2,1 myGrid
gs.bat deploy-space -cluster total_members=2,1 myGrid

This command deploys a Data Grid (aka space) called myGrid with 2 partitions and 1 backup per partition (hence the 2,1 syntax).

If you’re using the web console mentioned above to see what’s going on, you’ll see the data grid has been deployed.

Note that the Lite edition is limited to a single partition - if you’re using it, type total_members=1,1 instead.

Interacting with the Data Grid

Connecting to the Grid

Since the Data grid is not located in our client process, we need some sort of address to find it. Data grids are searched using a Space URL, for example: jini://*/*/myGrid. This roughly translates to: Find a remote space called myGrid (for more information see SpaceURL).

Now that we have an address, we can connect to the grid:

UrlSpaceConfigurer configurer = new UrlSpaceConfigurer("jini://*/*/myGrid");
GigaSpace gigaSpace = new GigaSpaceConfigurer(configurer).create();

The result is a GigaSpace instance, which is a proxy to the myGrid data grid.

The UrlSpaceConfigurer and GigaSpaceConfigurer provide additional options which are not covered in this tutorial.

Implementing a POJO

We now have a GigaSpace instance connected to our grid, which we can use to store and retrieve entries. But what shall we write? Actually, any POJO can be stored in the space, so long as it has a default constructor and an ID property. For this tutorial let’s define a Person class with the following properties:

import com.gigaspaces.annotation.pojo.SpaceId;

public class Person {

    private Integer ssn;
    private String firstName;
    private String lastName;

    // Default constructor (required by XAP)
    public Person() {}

    @SpaceId
    public Integer getSsn() {
        return ssn;
    }
    public void setSsn(Integer ssn) {
        this.ssn = ssn;
    }

    // Getters and Setters of firstName and lastName are omitted in this snippet.    
}

Note that we’ve annotated the ssn property’s getter with a custom XAP annotation @SpaceId to mark it as the entry’s ID.

The full source code of Person is available at the end of this tutorial.

Interacting with the grid

Now that we have a GigaSpace instance connected to our grid and a POJO which can be stored, we can store entries in the grid using the write() method and read them using various read() methods:

System.out.println("Write (store) a couple of entries in the data grid:");
gigaSpace.write(new Person(1, "Vincent", "Chase"));
gigaSpace.write(new Person(2, "Johnny", "Drama"));

System.out.println("Read (retrieve) an entry from the grid by its id:");
Person result1 = gigaSpace.readById(Person.class, 1);

System.out.println("Read an entry from the grid using a SQL-like query:");
Person result2 = gigaSpace.read(new SQLQuery<Person>(Person.class, "firstName=?", "Johnny"));

System.out.println("Read all entries of type Person from the grid:");
Person[] results = gigaSpace.readMultiple(new Person());

If you’re using the web console mentioned above to see what’s going on, you’ll see two entries stored in the grid, one in each partition.

Full Source Code

package com.gigaspaces.demo;

import com.j_spaces.core.client.SQLQuery;
import org.openspaces.core.GigaSpace;
import org.openspaces.core.GigaSpaceConfigurer;
import org.openspaces.core.space.UrlSpaceConfigurer;

public class Program {

    public static void main(String[] args) {
        String url = "jini://*/*/myGrid";
        System.out.println("Connecting to data grid " + url);
        UrlSpaceConfigurer configurer = new UrlSpaceConfigurer(url);
        GigaSpace gigaSpace = new GigaSpaceConfigurer(configurer).create();

        System.out.println("Write (store) a couple of entries in the data grid:");
        gigaSpace.write(new Person(1, "Vincent", "Chase"));
        gigaSpace.write(new Person(2, "Johnny", "Drama"));

        System.out.println("Read (retrieve) an entry from the grid by its id:");
        Person result1 = gigaSpace.readById(Person.class, 1);
        System.out.println("Result: " + result1);

        System.out.println("Read an entry from the grid using a SQL-like query:");
        Person result2 = gigaSpace.read(new SQLQuery<Person>(Person.class, "firstName=?", "Johnny"));
        System.out.println("Result: " + result2);

        System.out.println("Read all entries of type Person from the grid:");
        Person[] results = gigaSpace.readMultiple(new Person());
        System.out.println("Result: " + java.util.Arrays.toString(results));

        configurer.destroy();
    }
}
package com.gigaspaces.demo;

import com.gigaspaces.annotation.pojo.SpaceId;
import com.gigaspaces.annotation.pojo.SpaceIndex;
import com.gigaspaces.metadata.index.SpaceIndexType;

public class Person {

    private Integer ssn;
    private String firstName;
    private String lastName;

    // Default constructor (required by XAP)
    public Person() {}

    public Person(Integer ssn, String firstName, String lastName) {
        this.ssn = ssn;
        this.firstName = firstName;
        this.lastName = lastName;
    }

    @SpaceId(autoGenerate=false)
    public Integer getSsn() {
        return ssn;
    }
    public void setSsn(Integer ssn) {
        this.ssn = ssn;
    }

    @SpaceIndex(type=SpaceIndexType.BASIC)
    public String getFirstName() {
        return firstName;
    }
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public String getLastName() {
        return lastName;
    }
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    @Override
    public String toString() {
        return "Person #" + ssn + ": " + firstName + " " + lastName;
    }
}

What’s Next?

The Full XAP Java Tutorial will introduce you to the basic concepts and functionalities of XAP. Many ready to run examples are provided.

Read more about the GigaSpaces runtime environment, how to model your data in a clustered environment, and how to leverage the power capabilities of the Space.