Getting Started With XAP Open Source

If you follow GigaSpaces, you would have heard last month that XAP is now open source. In this post, we’ll cover the basics of how to get started with XAP 12 by exploring the hello world example that ships with XAP open source.

If you already know your way around XAP from previous releases, you’ll find most of this familiar, but we recommend you have a quick look through since a few things have been updated.

So whether you’re a brand new user or you’ve been with us for years, read on and we’ll show you how to set up your IDE and create aj=n XAP project, how to create/connect to a data grid, and how to store and retrieve objects from that data grid.

1. How to Get XAP Open Source

You can get XAP Open Source in three different ways:

1. Download the binary package from http://www.gigaspaces.com/xap-download.
2. Get the source code from github.com/xap and build it yourself.
3. Use Docker (Coming Soon).

2. Importing the Project

A “hello world” example is located at XAP_HOME/examples/hello-world. Both the example and XAP itself are Maven-friendly, so you can use any IDE which supports Maven (Eclipse, IntelliJ IDEA, etc.) and import the hello world Maven project to get started. While you’re there, take a peek in the pom.xml file. If you do, you’ll see the following:

<repositories>
  <repository>
      <id>org.openspaces</id>
      <url>http://Maven-repository.openspaces.org</url>
  </repository>
</repositories>
<dependencies>
  <dependency>
      <groupId>org.gigaspaces</groupId>
      <artifactId>xap-openspaces</artifactId>
      <version>12.0.0</version>
  </dependency>
</dependencies>

All XAP Maven artifacts are published under the org.gigaspaces groupId. However, you only need one artifact to get started: xap-openspaces (since we’re using Maven, its dependencies are retrieved implicitly). In addition, since XAP Maven artifacts are currently not published to the central Maven repository, you also need to configure the repository which hosts them. In future releases, we’ll publish to the central repo so that step will no longer be necessary.

(Note: If you can’t use Maven for some reason, no worries—simply add all the JARs in XAP_HOME/lib/required to your project’s classpath.)

3. The Message Class

The data grid can store entries of various forms, the most common of which is POJO (Plain ol’ Java Object), which is what the hello world example uses. Take a look at the Message class:

public class Message {
  private String msg;
  public Message() {
  }
  public Message(String msg) {
      this.msg = msg;
  }
 
  @SpaceId(autoGenerate = false)
  public String getMsg() {
      return msg;
  }
  public void setMsg(String msg) {
      this.msg = msg;
  }
}

As you can see, it has a single String field with a standard getter and setter. Of course, you may add additional properties with different types, but the minimum requirements are:

• A default constructor (required for instantiating the objects when retrieving them from the data grid)
• Annotating one of the properties with @SpaceId, which the space uses as a unique identifier for objects of this class (like a primary key in databases)

Finally, there are additional space annotations to control indexing, routing, and other features, which you can explore once you get going on your own.

4. Interacting With the Data Grid

The code is located at the HelloWorld class. It’s pretty straightforward:

• Set up a data grid connection.
• Write (store) objects to the grid.
• Read (retrieve) objects from the grid.

Creating or Finding the Data Grid

The main class for interacting with the data grid is called GigaSpace. This is an interface which abstracts the details of the space, so interacting with an embedded space, a remote space, or a partitioned cluster of spaces are all done via the same API. In this program, we use command line arguments to determine which space to connect to.

Creating an embedded (in-process) space is done via the following code:

GigaSpace space = new GigaSpaceConfigurer(new EmbeddedSpaceConfigurer(spaceName)).gigaSpace();

Connecting to a remote space (hosted in a different process) is done via:

GigaSpace space = new GigaSpaceConfigurer(new SpaceProxyConfigurer(spaceName)).gigaSpace();

Storing Entries in the Data Grid

As you can see from the code, simply use the space.write() method to write entries in the space. For example, the following code writes two Message entries to the space:

space.write(new Message(“Hello”));

space.write(new Message(“World!”));

Retrieving Entries from the Data Grid

Next, we want to read all “Message” entries and print them.

The data grid supports three kinds of queries:

• Query by ID.
• Template matching.
• SQL Query.

In this example, we’ll show template matching, which basically means the query is an object of the same class you want to match, and only properties which are non-null are matched against the entries in the space. So the template new Message() effectively matches all Message entries.

All we need to do now is use that in conjunction with the space.readMultiple() method:

Message[] results = space.readMultiple(new Message());

System.out.println(“read – ” + Arrays.toString(results));

5. Running the Example

Now let’s see how to run the example with different data grids.

Running With an Embedded Data Grid

To run the example with an embedded data grid, run it with the following arguments:

-name myDataGrid -mode embedded

Output

Created embedded data-grid: myDataGrid write – ‘Hello’ write – ‘World!’ read – [‘Hello’, ‘World!’]

Running with Embedded Data Grid

Running With Remote Data Grid

To start an independent, standalone data grid instance, use the space-instance script located in the product’s bin folder (XAP_HOME/bin/space-instance.sh or .bat).

For example:

./space-instance.sh -name myDataGrid

Then, run the example with the following arguments:

-name myDataGrid -mode remote

Output

Connected to remote data-grid: myDataGrid write – ‘Hello’ write – ‘World!’ read – [‘Hello’, ‘World!’]

Running with Remote Data Grid

Running With a Partitioned Data Grid

A XAP data grid can be partitioned across multiple instances. The data grid proxy routes entries using a routing ID (If not set, the SpaceId is used for routing, which is what happens in our case).

The space-instance script can also be used to form a cluster of spaces. For example, to start a partitioned cluster with two nodes, run the following:

Partition #1:

./space-instance.sh -name myDataGrid

-cluster schema=partitioned total_members=2 id=1 

Partition #2:

./space-instance.sh -name myDataGrid

-cluster schema=partitioned total_members=2 id=2 

Note that we’re running two instances with a different ID. If you run the same command without the ID argument, it would look like this:

./space-instance.sh -name myDataGrid -cluster schema=partitioned total_members=2 

Then both partitions would be instantiated within the same process. This is sometimes useful for dev environments, but in production, you’d probably want a process-per-instance.

Next, run the example with the following arguments:

 -name myDataGrid -mode remote 

Output

Connected to remote data-grid: myDataGrid write – ‘Hello’ write – ‘World!’ read – [‘Hello’, ‘World!’]

Running with a Partitioned Data Grid

Running With a Partitioned Highly Available Data Grid

An XAP data grid supports the notion of hot backups, so that if an instance fails, its designated backup automatically kicks in and takes over, making the failover process transparent to the user.

To start a partitioned cluster with backups, change the total_members argument to specify the number of backups (e.g. 2,1), and start backup instances with backup_id=1. For example:

Partition #1:

./space-instance.sh -name myDataGrid -cluster schema=partitioned total_members=2,1 id=1

./space-instance.sh -name myDataGrid -cluster schema=partitioned total_members=2,1 id=1 backup_id=1

Partition #2:

./space-instance.sh -name myDataGrid -cluster schema=partitioned total_members=2,1 id=2

./space-instance.sh -name myDataGrid -cluster schema=partitioned total_members=2,1 id=2 backup_id=1

Next, run the example with the following arguments:

-name myDataGrid -mode remote

Output

Connected to remote data-grid: myDataGrid write – ‘Hello’ write – ‘World!’ read – [‘Hello’, ‘World!’]

Running with a Partitioned Highly Available Data Grid

Summary

In this blog post we’ve learned:

• How to set up a XAP project with or without Maven.
• How to create an embedded space or connect to a remote space.
• How to store and retrieve entries from the space.
• How to start various types of data grids using the space-instance utility.