Using Apache Ignite Thin Client

From the version 2.4.0, Apache Ignite introduced a new way to connect to the Ignite cluster, which allows communication with the Ignite cluster without starting an Ignite client node. Historically, Apache Ignite provides two notions of client and server nodes. Ignite client node is intended as lightweight mode, which does not store data (however, it can store near cache) and does not execute any compute tasks. Mainly, the client node is used to communicate with the server remotely and allows manipulating the Ignite Caches using the whole set of Ignite API’s. There are two main downsides with the Ignite Client node:

• Whenever Ignite client node connects to the Ignite cluster, it becomes the part of the cluster topology. The bigger the topology is, the harder it is for maintaining.
• In the client mode, Apache Ignite node consumes a lot of resources for performing cache operations

To solve the above problems, Apache Ignite provides a new binary client protocol for implementing thin Ignite client in any programming language or platforms.

Note that the word thin means it doesn’t start any Ignite node for communicating with the Ignite cluster and doesn’t implement any discovery/communication SPI logic.

Thin client connects to the Ignite cluster through a TCP socket and performs CRUD operations using a well-defined binary protocol. The protocol is a fully socket-based, request-response style protocol. The protocol is designed to be strict enough to ensure standardization in the communication (such as connection handshake, message length, etc.), but still flexible enough that developers may expand upon the protocol to implement custom features.

Portions of this article were taken from the book The Apache Ignite book. If it got you interested, check out the rest of the book for more helpful information. There is a special 20% discount for the DZone readers, please use the following coupon.

Apache Ignite provides brief data formats and communication details in the documentation for using the binary protocol. Ignite already supports .NET, and Java thin client builds on top of the protocol and plans to release a thin client for major languages such as goLang, python, etc. However, you can implement your thin client in any favorite programming language of your choice by using the binary protocol.

Also note that the performance of the Apache Ignite thin client is slightly lower than Ignite client node as it works through an intermediary node. Assume that, you have two nodes of the Apache Ignite A, B and you are using a thin client C for retrieving data from the cluster. With the thin client C, you have connected to the node B, and whenever you try to retrieve any data that belongs to the node A, the requests always go through the client B. In case of the Ignite client node, it sends the request directly to the node A.

Most of the times, you should not care about how the message formats look or the socket handshake performs. Thin client for every programming language encapsulates the ugly hard work under the hood for you. Anyway, if you want to have a deep dive into the Ignite binary protocol or if you have any issues to create with your own thin client, please refer to the Ignite documentation.

Before moving on to more advanced topics, let’s have a look at a simple application to use Ignite thin client. In this simple application, I show you the bits and pieces you need to get started with the thin client. The source code for the examples is available at the GitHub repository, see chapter-2.

Step 1. Clone or download the project from the GitHub repository. If you are planning to develop the project from scratch, add the following maven dependency in your pom.xml file. The only ignite-core library need for the thin client, the rest of the libraries only used for logging.

<dependency>
    <groupId>org.apache.ignite</groupId>
    <artifactId>ignite-core</artifactId>
    <version>2.6.0</version>
</dependency>
<!-- Logging wih SLF4J -->
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>1.6.1</version>
</dependency>
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.0.1</version>
</dependency>
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-core</artifactId>
    <version>1.0.1</version>
</dependency>

Step 2. Now, let's create a new Java class with the name HelloThinClient.

Step 3. Copy and paste the following source code. Do not forget to save the file.

import org.apache.ignite.IgniteException;
import org.apache.ignite.Ignition;
import org.apache.ignite.client.ClientCache;
import org.apache.ignite.client.IgniteClient;
import org.apache.ignite.configuration.ClientConfiguration;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class HelloThinClient {
 private static final Logger logger = LoggerFactory.getLogger(HelloThinClient.class);
 private static final String HOST = "127.0.0.1";
 private static final String PORT = "10800";
 private static final String CACHE_NAME = "thin-cache";

 public static void main(String[] args) {
  logger.info("Simple Ignite thin client example working over TCP socket.");
  ClientConfiguration cfg = new ClientConfiguration().setAddresses(HOST + ":" + PORT);
  try (IgniteClient igniteClient = Ignition.startClient(cfg)) {
   ClientCache < String, String > clientCache = igniteClient.getOrCreateCache(CACHE\ _NAME);
   // put a few value
   clientCache.put("Moscow", "095");
   clientCache.put("Vladimir", "033");
   // get the region code of the Vladimir String val = clientCache.get("Vladimir");
   logger.info("Print value: {}", val);
  } catch (IgniteException e) {
   logger.error("Ignite exception:", e.getMessage());
  } catch (Exception e) {
   logger.error("Ignite exception:", e.getMessage());
  }
 }
}

Step 4. Let's have a closer look at the program we have written above.

private static final Logger logger = LoggerFactory.getLogger(HelloThinClient.class);
private static final String HOST = "127.0.0.1";
private static final String PORT = "10800";
private static final String CACHE_NAME = "thin-cache";

First, we have declared a few constants: logger, host IP address, port, and the cache name that we are going to create. If you have a different IP address, you should change it here. Port 10800 is the default for Ignite thin client.

СlientConfiguration cfg = new ClientConfiguration().setAddresses(HOST+":"+PORT);

These are our next exciting lines in the program. We have created an instance of the Ignite СlientConfiguration and passed the address we declared above. In the next try-catch block, we have defined a new cache with name thin-cache and put 2 key-value pairs. We also used the Ignition.start Client method to initialize a connection to Ignite node.

try (IgniteClient igniteClient = Ignition.startClient(cfg)) {
   ClientCache < String, String > clientCache = igniteClient.getOrCreateCache(CACHE\ _NAME);
   // put a few value
   clientCache.put("Moscow", "095");
   clientCache.put("Vladimir", "033");
   // get the region code of the Vladimir String val = clientCache.get("Vladimir");
   logger.info("Print value: {}", val);
  } catch (IgniteException e) {
   logger.error("Ignite exception:", e.getMessage());
  } catch (Exception e) {
   logger.error("Ignite exception:", e.getMessage());
  }
}

Later, we retrieved the value of key Vladimir and printed the value in the console.

Step 5. Start your Apache Ignite single node cluster if it is not started yet. Use the following command in your favorite terminal.

$ IGNITE_HOME/bin/ignite.sh

Step 6. To build the project, issue the following command.

$ mvn clean install

This will run Maven, telling it to execute the install goal. This goal will compile, test, and package your project code and then copy it into the local dependency repository. The first time the build process will take a few minutes to complete, after successful compilation, an executable jar named HelloThinClient-runnable.jar will be created in the target directory.

Step 7. Run the application by typing the following command.

$ java -jar .\target\HelloThinClient-runnable.jar

You should see a lot of logs in the terminal. At the end of the log, you should find something like this.

The application is connected through the TCP socket to the Ignite node and performed put and get operations on cache thin-cache. If you take a look at the Ignite node console, you should notice that Ignite cluster topology has not been changed.