Thin Client

❗️

This is a legacy Apache Ignite documentation

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

Thin Client is a lightweight Ignite connection mode. It does not start in JVM process (Java is not required at all), does not participate in cluster, never holds any data (except for metadata), or performs computations.

What it does is establish a socket connection to one or more Ignite nodes, and perform all operations through these nodes.

Thin Client mode is perfect for short-lived and resource-restricted applications, memory and CPU usage is minimal.

Installation

Thin client API is distributed along with the Ignite C++ and shares many classes, headers and libraries with full Ignite C++ API, so you can easily switch from one API to another. Basic installation and building procedure is the same: Getting Started.

Requirements

All requirements are the same as for the thick client, except for the Java part: Java is NOT required.

Configuring Server Nodes

Thin client connector is enabled in Ignite server nodes by default. It can be disabled by setting IgniteConfiguration.clientConnectorConfiguration to null in Java or Spring XML.

Connector settings can be adjusted like this:

<bean  class="org.apache.ignite.configuration.IgniteConfiguration">
    <property name="clientConnectorConfiguration">
        <bean class="org.apache.ignite.configuration.ClientConnectorConfiguration">
            <property name="host" value="myHost"/>
            <property name="port" value="11110"/>
            <property name="portRange" value="30"/>
        </bean>
    </property>
</bean>

Connecting to Cluster

The API for thin client is located under the ignite::thin C++ namespace. The thin client API entry point is the IgniteClient::Start(IgniteClientConfiguration) method. You can use IgniteClientConfiguration class to specify client settings, such as list of server nodes to connect to, security credentials and SSL/TLS settings for the connection.

📘

Make sure that you have properly configured the server nodes if you are using authentication or a secure connection.

Here is an example on how to start a new thin client instance:

#include <ignite/thin/ignite_client.h>
#include <ignite/thin/ignite_client_configuration.h>
#include <ignite/thin/cache/ignite_client.h>

using namespace ignite::thin;

void TestClient()
{
  IgniteClientConfiguration cfg;
  
  //Endpoints list format is "<host>[port[..range]][,...]"
  cfg.SetEndPoints("127.0.0.1:11110,example.com:1234..1240");
  
  IgniteClient client = IgniteClient::Start(cfg);
  
  cache::CacheClient<int32_t, std::string> cacheClient =
    client.GetOrCreateCache<int32_t, std::string>("TestCache");
  
  cacheClient.Put(42, "Hello Ignite Thin Client!");
}

Partition Awareness

Partition awareness allows the thin client to send query requests directly to the node that owns the queried data. The client, as it were, is aware of the partition distribution.

Without partition awareness, an application that is connected to the cluster via a thin client executes all queries and operations via a single server node that acts as a proxy for the incoming requests. That node re-routes the operations to the node that stores the data that is being requested. This results in a bottleneck that adds additional latency.

With partition awareness in place, the thin client can directly send queries and operations to the nodes that own the data required for the queries. This eliminates the bottleneck, allowing the application to scale more easily.

The following code sample illustrates how to use the partition awareness feature with the C++ thin client.

#include <ignite/thin/ignite_client.h>
#include <ignite/thin/ignite_client_configuration.h>

using namespace ignite::thin;

void TestClientPartitionAwareness()
{
    IgniteClientConfiguration cfg;
    cfg.SetEndPoints("127.0.0.1:10800,217.29.2.1:10800,200.10.33.1:10800");
    cfg.SetPartitionAwareness(true);

    IgniteClient client = IgniteClient::Start(cfg);

    cache::CacheClient<int32_t, std::string> cacheClient =
        client.GetOrCreateCache<int32_t, std::string>("TestCache");

    cacheClient.Put(42, "Hello Ignite Partition Awareness!");

    cacheClient.RefreshAffinityMapping();

    // Getting a value
    std::string val = cacheClient.Get(42);
}

Authentication

User credentials must be provided if authentication is enabled on the server.

#include <ignite/thin/ignite_client.h>
#include <ignite/thin/ignite_client_configuration.h>
#include <ignite/thin/cache/ignite_client.h>

using namespace ignite::thin;

void TestClientWithAuth()
{
  IgniteClientConfiguration cfg;
  cfg.SetEndPoints("127.0.0.1:10800");
  
  // Use your own credentials here.
  cfg.SetUser("ignite");
  cfg.SetPassword("ignite");
  
  IgniteClient client = IgniteClient::Start(cfg);
  
  cache::CacheClient<int32_t, std::string> cacheClient =
    client.GetOrCreateCache<int32_t, std::string>("TestCache");
  
  cacheClient.Put(42, "Hello Ignite Thin Client with auth!");
}

<bean  class="org.apache.ignite.configuration.IgniteConfiguration">

    <property name="authenticationEnabled" value="true"/>

    <property name="persistentStoreConfiguration">
        <bean class="org.apache.ignite.configuration.PersistentStoreConfiguration"/>
    </property>
  
    <property name="clientConnectorConfiguration">
        <bean class="org.apache.ignite.configuration.ClientConnectorConfiguration">
            <property name="host" value="127.0.0.1"/>
            <property name="port" value="10800"/>
            <property name="portRange" value="10"/>
        </bean>
    </property>
  
</bean>

Performance Considerations

Thin client is not a part of the cluster topology. Therefore, it has limited information about the cluster and its data distribution. Because of this fact and additional network delays, latency of a single operation of thin client can be worse than that of a thick client. Some steps are taken to improve thin clients latency, such as Best Effort Affinity; however, we recommend to use bulk operations (e.g. GetAll(), SetAll()) for the best performance in terms of throughput over the operations on a single key-value.

Best Effort Affinity

Ignite C++ thin client tries to send data requests to proper nodes in the cluster to avoid additional network delays and provide the best throughput and latency. Therefore, C++ thin client retrieves data affinity mapping for every cache from a random node picked from the endpoints list the first time a CacheClient instance is created.

Since thin client is not a part of the cluster topology, it is not guaranteed that this mapping will always be up-to-date. To refresh the mapping, you can use the CacheClient::RefreshAffinityMapping method. Note that this method is required if the cluster topology has been updated.

🚧

Make sure that you list all cluster nodes' addresses in the configuration. If a cluster node address is not in the list, the client will not connect or send requests to it.

Here is an example:

#include <ignite/thin/ignite_client.h>
#include <ignite/thin/ignite_client_configuration.h>
#include <ignite/thin/cache/ignite_client.h>

using namespace ignite::thin;

void TestClientWithAuth()
{
  IgniteClientConfiguration cfg;
  cfg.SetEndPoints("127.0.0.1:10800");
    
  IgniteClient client = IgniteClient::Start(cfg);
  
  cache::CacheClient<int32_t, std::string> cacheClient =
    client.GetOrCreateCache<int32_t, std::string>("TestCache");
  
  cacheClient.Put(42, "Hello Ignite Thin Client with auth!");
  
  cache.RefreshAffinityMapping();
  
  // Getting
  std::string val = cacheClient.Gett(42);
}

Thin Client APIs

Thin client offers a subset of full Ignite C++ APIs. It is evolving and we plan to support most APIs in both thick and thin clients in the future.