Java Thin Client

❗️

This is a legacy Apache Ignite documentation

The new documentation is hosted here: https://ignite.apache.org/docs/latest/

Overview

The Java Thin Client exposes Binary Client Protocol features to Java developers.

The thin client is a lightweight Ignite client that connects to the cluster via a standard socket connection. It does not become a part of the cluster topology, never holds any data, and is not used as a destination for compute grid calculations. The thin client simply establishes a socket connection to a standard Ignite node​ and performs all operations through that node.

For more information, visit:

• Initialization and Configuration to learn how to configure and obtain references of the thin client APIs currently supported.
• Key-Value Operations to learn which JCache APIs are supported.
• SQL Queries to learn how use SQL with the Java thin client API.
• Binary Types to learn how use the Ignite Binary Objects API with the Java thin client API.
• Security to see the thin client has enough protection to connect to an enterprise Ignite cluster over Internet.

Quick Start

Follow the steps below to learn thin client API and development environment basics.

1. Maven Setup

You need single ignite-core dependency to use all of the thin client API:

<properties>
        <ignite.version>2.5.0</ignite.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.apache.ignite</groupId>
            <artifactId>ignite-core</artifactId>
            <version>${ignite.version}</version>
        </dependency>      
    </dependencies>

def igniteVersion = '2.5.0'

dependencies {
    compile group: 'org.apache.ignite', name: 'ignite-core', version: igniteVersion
}

📘

Ignite Version

Thin client and Ignite server versions can be different as long as the binary protocol versions are compatible.

2. Simple Application

public static void main(String[] args) {
    ClientConfiguration cfg = new ClientConfiguration().setAddresses("127.0.0.1:10800");

    try (IgniteClient igniteClient = Ignition.startClient(cfg)) {
        System.out.println();
        System.out.println(">>> Thin client put-get example started.");

        final String CACHE_NAME = "put-get-example";

        ClientCache<Integer, Address> cache = igniteClient.getOrCreateCache(CACHE_NAME);

        System.out.format(">>> Created cache [%s].\n", CACHE_NAME);

        Integer key = 1;
        Address val = new Address("1545 Jackson Street", 94612);

        cache.put(key, val);

        System.out.format(">>> Saved [%s] in the cache.\n", val);

        Address cachedVal = cache.get(key);

        System.out.format(">>> Loaded [%s] from the cache.\n", cachedVal);
    }
    catch (ClientException e) {
        System.err.println(e.getMessage());
    }
    catch (Exception e) {
        System.err.format("Unexpected failure: %s\n", e);
    }
}

The application demonstrates:

• Using Ignition#startClient(clientCfg) to initialise a thin client connection to Ignite server running on localhost 127.0.0.1.
• Using IgniteClient#getOrCreateCache(cacheName) to ensure a cache with the specified name is created in Ignite.
• Using ClientCache#put(key, val)} and ClientCache#get(key) to store and retrieve data in Ignite.

3. Start Ignite Cluster

Start Ignite server node on the local machine:

$IGNITE_HOME/bin/ignite.sh $IGNITE_HOME/examples/config/example-ignite.xml

...
[27-02-2018 19:21:00][INFO ][main][GridDiscoveryManager] Topology snapshot [ver=1, servers=1, clients=0, CPUs=8, offheap=1.0GB, heap=1.0GB]

%IGNITE_HOME%\bin\ignite.bat %IGNITE_HOME%\examples\config\example-ignite.xml

...
[27-02-2018 19:21:00][INFO ][main][GridDiscoveryManager] Topology snapshot [ver=1, servers=1, clients=0, CPUs=8, offheap=1.0GB, heap=1.0GB]

📘

Wait for the server to start ...

Unlike Ignite Client node, which waits for the first Ignite server to start, the thin client fails at once if it does not find the configured server(s).

4. Start Application

Run the simple application in your IDE and see the output:

>>> Thin client put-get example started.
>>> Created cache [put-get-example].
>>> Saved [Address [street=1545 Jackson Street, zip=94612]] in the cache.
>>> Loaded [Address [street=1545 Jackson Street, zip=94612]] from the cache.

Notice that the cluster topology did not change. The thin client application does not become a member of the cluster: it is a lightweight app that communicates with the cluster over a single TCP socket using binary client protocol.