Basic Usage

The Java ScaleOut client API is used to interact with the ScaleOut product suite. The following section illustrates the following:

• Connecting to a ScaleOut in-memory datagrid

• Creating a cache to read/write objects

• Registering for events from a ScaleOut in-memory datagrid

Connecting to ScaleOut Service

Connecting to the ScaleOut Service is done by instantiating a GridConnection. At it’s base level, a GridConnection is a maintained set of TCP connections to a ScaleOut in-memory datagrid. Internally, the GridConnection load balances requests and handles request retries when TCP failures occur.

A GridConnection is instantiated by calling the static connect(String) method on the GridConnection class. For example:

GridConnection connection = GridConnection.connect("bootstrapGateways=server1:721,server2:721;");

Full details on available parameters for the connection string are available in the configuration section.

Creating a Cache

After connecting to the ScaleOut Service, a Cache<K,V> instance can be created. The Cache abstraction allows for reading/writing objects and querying the service.

A Cache<K,V> is created using a CacheBuilder. The CacheBuilder<K,V> can build the cache with a variety of different configurations. Cache’s are strongly typed to ensure the values stored and retrieved are of the same type.

Cache<Integer, String> cache = new CacheBuilder<Integer, String>(connection, "example", Integer.class)
        .build();

Full details on configuring and building a Cache are available in the configuration section.

Registering for Events

Some operations trigger events that the ScaleOut service will fire. Applications that are registered (listening) for events, can have a piece of code execute when the event is fired.

The ServiceEvents static class is used to register for different types of events with the ScaleOut service. To register for events, supply a Cache<K,V> and the appropriate lambda (or implementing class) to the ServiceEvents static method. For example, here is how to register for expiration events:

ServiceEvents.setExpirationHandler(cache, new CacheEntryExpirationHandler<Integer, String>() {
        @Override
        public CacheEntryDisposition handleExpirationEvent(Cache<Integer, String> cache, Integer key) {
                System.out.println("ObjectExpired: " + key);

                return CacheEntryDisposition.Remove;
        }
});

Full Sample

The following example illustrates how to instantiate a Cache<K, V> instance and use it to perform traditional CRUD (Create/Read/Update/Delete) operations against a ScaleOut in-memory data grid.

package com.scaleout.client.samples.caching;
import com.scaleout.client.GridConnection;
import com.scaleout.client.caching.*;
public class Main {
        public static void main(String[] args) throws Exception {
                GridConnection connection = GridConnection.connect("bootstrapGateways=server1:721,server2:721;");
                Cache<Integer, String> cache = new CacheBuilder<Integer, String>(connection, "example", Integer.class)
                                .build();
                try {
                        // create the object
                        CacheResponse<String, String> response = cache.add(6, "John Adams");
                        if(response.getStatus() != RequestStatus.ObjectAdded)
                                System.out.println("Unexpected request status " + response.getStatus());
                        // read the object
                        response = cache.read(6);
                        if (response.getStatus() == RequestStatus.ObjectRetrieved)
                                System.out.println("6th US president: " + response.getValue());
                        else
                                System.out.println("Unexpected request status " + response.getStatus());
                        // update the object
                        response = cache.update(6, "John *Quincy* Adams");
                        if (response.getStatus() != RequestStatus.ObjectUpdated)
                                System.out.println("Unexpected request status " + response.getStatus());
                        // delete the object
                        response = cache.remove(6);
                        if (response.getStatus() != RequestStatus.ObjectRemoved)
                                System.out.println("Unexpected request status " + response.getStatus());
                } catch (Exception e) {
                        e.printStackTrace();
                }
        }
}