We’re excited to introduce a new blog series, covering all things XAP, including insider tips and tricks from our team of architects and developers working around the clock to make XAP work for you. The GigaSpaces blog has evolved substantially, and our goal is to ensure you are kept in the loop with product updates, in-depth tutorials, and how-tos in order to help you up your professional game and offer real value to your team. In 2017, the blog will grow to provide even more content, so be sure to check back regularly as we have heaps of new information on the way. This is the second post in the series

Tutorial: How to Use Remote Read Eval Print Loop (REPL) to Control XAP

With XAP 12.1, we’ve developed an admin REST API that makes it possible to perform administration action on the grid. In this tutorial, I will show how to install XAP 12.1 and run the new REST API. I will describe the REST functionality and will show how to use a Scala REPL which has embedded client to this rest server to automate tasks on the grid remotely.

Getting Started with XAP 12.1 REPL

First, you’ll need to download XAP 12.1 in order to have the latest version with the REST Cloud-Native Orchestration. Once you’ve downloaded XAP 12.1, go ahead and unpack the zip.

Next, you will have to get the license from the GigaSpaces site. Once you have it, add it to the file xap-license.txt in the dir that was created by the zip.

Edit the file setenv-overrides.sh  

Add the line export XAP_MANAGER_SERVERS=your-host-name

Replace your-host-name with your real hostname

Now you are ready to run the system in local mode. To do so, type ‘./gs-agent.sh –manager-local’ from a terminal that has opened in XAP the bin directory. If you browse to http://localhost:8090/v1/index.html you will see a nice swagger page describing the admin REST API. Give it a try.

swagger1For example, go to Hosts view, type “GET /hosts” and get all the hosts in the system. At this time, there should be only one host with no containers.

hosts-get

To create a new container, open the containers section and click on the first “POST /containers” (where the description is “creates a new container”). Fill in the host parameter as shown in the image and click the Try It Out button.

 

create-container-on-host

You can verify that a container was created by getting all hosts and seeing that your host has a container.

 

host-with-container

Using this REST API, it is possible to manage the grid from anywhere using the language of your choice.

It is possible to upload jars to the grid and then deploy processes using those jars. You can also choose to deploy an instance of spaces on a node in the grid.

One specific client we provide is the Admin REPL. It is a Scala-based REPL that has the REST embedded as primitives commands.

Our REPL has the following features:

  • Supports autocomplete
  • It is asynchronous by nature
  • Provides Scala as a glue language for the REST primitives
  • The command is implemented in a way which makes it easy to compose commands together
  • It enable running batch scripts that are doing work against the system

Let’s start up the REPL and see how it works.

Unzip the file: demo-repl.zip and go into the directory where the file aadmin-repl.sh is found and define the system environment:

restUrl export restUrl=<YOUR_REST_URL>.  In my case – export  restUrl=http://your-host-name:8090/v1. 

Make sure to replace your-host-name with your real hostname.

The REPL should start with the URL and end with @ as a prompt

Type hosts as the first rest command:

Ooh, what happened there? since every REST command is asynchronous in the REPL, it returns a Scala future. We can wait on the Future or add a Listener that will be called upon when the future will be resolved.

Let’s begin with the option of waiting on the Future:

This is much better, now we can work with it.

Let’s try to create two JVM (GSC) on our machine.

We have two containers so we can deploy space on those containers.

Note that deploySpace returns a future that contains space which will be resolved when the space deployment either fails or succeeds. While on the REST API, you will only get the request submitted code, therefore you have to do the polling yourself to get results.

You can type help to see all the REPL REST commands.

A Scala program that uses REST commands can be run as a batch using the command  admin-repl.sh program.sc 

Now let’s start writing something more interesting using the REPL script.

Put the following Scala code into the file  deploy-example.sc 

You can run this code (and passing arguments to it) using the command ./admin-repl.sh deploy-example.sc  foo bar

The output of the println should be  ArrayBuffer(foo, bar) 

Let’s add some REPL commands to the script.

You should get the empty list when running this command.

Now let’s try to create three JVMs concurrently and wait for them to start

This script first removes all containers on the system and then starts three containers, waits for them to be ready and then prints their ids. The output should be:

Similarly, we can write a script that uploads the processing unit sources and at the same time start containers. When all the downloads and containers are ready, it will deploy all of the processing units concurrently and wait for them to finish.

We can combine REST commands in the following ways:

1. Sequentially one after another using flat and flat map for example. For instance, given two container ids which we’d wish to restart one after another. We can write the following code:

We can now call this function with ids of two containers to restart since it returns future with a tuple of the container ids we can wait on the result with get. Notice that we will get two new ids because the container id contains the process id and the process is new.

We can write restart2 using Scala for comprehension.

2. Or we can send all the action concurrently (since the containers are not dependent on each other) and wait for the results:

This code should run at half the time. Give it a go.
Again we can use Scala for comprehension:

You must be thinking, OK this is nice but I don’t have just two containers, I have many of them. Can I compose a list of containers either sequentially or in parallel? As it turns out, you can and it’s super easy. Here’s how:

And now do it concurrency, it will be faster.

We can now restart all existing containers concurrently using:

containers return Future[List[DeploymentInstanceContainer]] we flat map on the future to the list of deployments and then extract the ids and send them to restart.

Final Thoughts

The shell we are using here is based on Ammonite, which means it is a real shell and not just a REPL. For example, C-C does not exist, it just stops the current execution. You will need to hit the C-D to exit the shell. One more feature of the Ammonite shell is that it can be used to interact with the system. For example, ls.! will return a Seq of the files in the current directory. This means that you can combine XAP admin commands with system commands to write even more meaningful scripts.

Visit our website to learn more about what GigaSpaces has to offer. For more on how to make XAP work for you, visit here. 

Make XAP Work for You: How to Use Remote Read Eval Print Loop (REPL) to Control XAP
Barak Bar-Orion on GithubBarak Bar-Orion on LinkedinBarak Bar-Orion on Twitter
Barak Bar-Orion
Director of In-Memory Computing R&D @ GigaSpaces
Barak is a software engineer with 7 years experience in team building and leading and more than 17 years experience in software development.
Tagged on: