Apache Ignite Documentation

GridGain Developer Hub - Apache Ignitetm

Welcome to the Apache Ignite developer hub run by GridGain. Here you'll find comprehensive guides and documentation to help you start working with Apache Ignite as quickly as possible, as well as support if you get stuck.

 

GridGain also provides Community Edition which is a distribution of Apache Ignite made available by GridGain. It is the fastest and easiest way to get started with Apache Ignite. The Community Edition is generally more stable than the Apache Ignite release available from the Apache Ignite website and may contain extra bug fixes and features that have not made it yet into the release on the Apache website.

 

Let's jump right in!

 

Documentation     Ask a Question     Download

 

Javadoc     Scaladoc     Examples

Clients and Servers

Automatically distinguish between client and server nodes.

Overview

Ignite has an optional notion of client and server nodes. Server nodes participate in caching, compute execution, stream processing, etc., while the native client nodes provide ability to connect to the servers remotely. Ignite native clients allow using the whole set of Ignite APIs, including near caching, transactions, compute, streaming, services, etc. from the client side.

By default, all Ignite nodes are started as server nodes, and client mode needs to be explicitly enabled.

Configuring Clients and Servers

You can configure a node to be either a client or a server via IgniteConfiguration.setClientMode(...) property.

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
    ...   
    <!-- Enable client mode. -->
    <property name="clientMode" value="true"/>
    ...
</bean>
IgniteConfiguration cfg = new IgniteConfiguration();

// Enable client mode.
cfg.setClientMode(true);

// Start Ignite in client mode.
Ignite ignite = Ignition.start(cfg);

Alternatively, for convenience, you can also enable or disable the client mode on the Ignition class to allow clients and servers reuse the same configuration.

Ignition.setClientMode(true);

// Start Ignite in client mode.
Ignite ignite = Ignition.start();

Creating Distributed Caches

Whenever creating caches in Ignite, either in XML or via any of the Ignite.createCache(...) or Ignite.getOrCreateCache(...) methods, Ignite will automatically deploy the distributed cache on all server nodes.

Once a distributed cache is created, it will be automatically deployed on all the existing and future server nodes.

// Enable client mode locally.
Ignition.setClientMode(true);

// Start Ignite in client mode.
Ignite ignite = Ignition.start();

CacheConfiguration cfg = new CacheConfiguration("myCache");

// Set required cache configuration properties.
...

// Create cache on all the existing and future server nodes.
// Note that since the local node is a client, it will not 
// be caching any data.
IgniteCache<?, ?> cache = ignite.getOrCreateCache(cfg);

Computing on Clients or Servers

By default, IgniteCompute will execute jobs on all the server nodes. However, you can choose to execute jobs only on server nodes or only on client nodes by creating a corresponding cluster group.

IgniteCompute compute = ignite.compute();

// Execute computation on the server nodes (default behavior).
compute.broadcast(() -> System.out.println("Hello Server"));
ClusterGroup clientGroup = ignite.cluster().forClients();

IgniteCompute clientCompute = ignite.compute(clientGroup);

// Execute computation on the client nodes.
clientCompute.broadcast(() -> System.out.println("Hello Client"));

Managing Slow Clients

In many deployments, client nodes are launched outside of the main cluster on slower machines with worse network. In these scenarios, it is possible that servers will generate load (such as continuous queries notification, for example) that clients will not be able to handle resulting in growing queue of outbound messages on servers. This may eventually cause either an out-of-memory situation on the server or block the whole cluster if the back-pressure control is enabled.

To manage these situations, you can configure the maximum number of allowed outgoing messages for client nodes. If the size of the outbound queue exceeds this value, the client node will be disconnected from the cluster, preventing global slowdown.

The examples below show how to configure a slow client queue limit in code and XML configuration.

IgniteConfiguration cfg = new IgniteConfiguration();

// Configure Ignite here.

TcpCommunicationSpi commSpi = new TcpCommunicationSpi();
commSpi.setSlowClientQueueLimit(1000);

cfg.setCommunicationSpi(commSpi);
<bean id="grid.cfg" class="org.apache.ignite.configuration.IgniteConfiguration">
  <!-- Configure Ignite here. -->
  
  <property name="communicationSpi">
    <bean class="org.apache.ignite.spi.communication.tcp.TcpCommunicationSpi">
      <property name="slowClientQueueLimit" value="1000"/>
    </bean>
  </property>
</bean>

Reconnecting a Client

A client node can get disconnected from the cluster in several cases:

  • When a client node cannot re-establish the connection with the server node due to network issues.
  • Connection with the server node was broken for some time; the client node is able to re-establish the connection with the server, but the server already dropped the client node since the server did not receive client heartbeats
  • Slow clients can be kicked out by server nodes.

When a client determines that it is disconnected from the cluster, it assigns a new node 'id' to itself and tries to reconnect to the cluster. Note that this has a side effect - the 'id' property of the local ClusterNode will change in case of a client reconnection. This means that any application logic that relied on the 'id' value may be affected.

While a client is in a disconnected state and an attempt to reconnect is in progress, the Ignite API throws a special exception - IgniteClientDisconnectedException. This exception provides a future which will be completed when the client reconnects with the cluster (IgniteCache API throws CacheException which has IgniteClientDisconnectedException as its cause). This future can also be obtained using the IgniteCluster.clientReconnectFuture() method.

Also, there are special events for client reconnection (these events are local, i.e. they are fired only on the client node):

  • EventType.EVT_CLIENT_NODE_DISCONNECTED
  • EventType.EVT_CLIENT_NODE_RECONNECTED

The following example shows how to use IgniteClientDisconnectedException.

IgniteCompute compute = ignite.compute();

while (true) {
    try {
        compute.run(job);
    }
    catch (IgniteClientDisconnectedException e) {
        e.reconnectFuture().get(); // Wait for reconnection.

        // Can proceed and use the same IgniteCompute instance.
    }
}
IgniteCache cache = ignite.getOrCreateCache(new CacheConfiguration<>());

while (true) {
  try {
    cache.put(key, val);
  }
  catch (CacheException e) {
    if (e.getCause() instanceof IgniteClientDisconnectedException) {
      IgniteClientDisconnectedException cause =
        (IgniteClientDisconnectedException)e.getCause();

      cause.reconnectFuture().get(); // Wait for reconnection.

      // Can proceed and use the same IgniteCache instance.
    }
  }
}

Automatic client reconnection can be disabled using the 'clientReconnectDisabled' property on TcpDiscoverySpi. When reconnection is disabled, client node is stopped.

IgniteConfiguration cfg = new IgniteConfiguration();

// Configure Ignite here.

TcpDiscoverySpi discoverySpi = new TcpDiscoverySpi();

discoverySpi.setClientReconnectDisabled(true);

cfg.setDiscoverySpi(discoverySpi);

Forcing Server Mode on Client Nodes

Client nodes require live server nodes in the topology to start.

However, to start a client node without a running server node, you can force server mode discovery on client nodes the following way:

IgniteConfiguration cfg = new IgniteConfiguration();

cfg.setClientMode(true);

// Configure Ignite here.

TcpDiscoverySpi discoverySpi = new TcpDiscoverySpi();

discoverySpi.setForceServerMode(true);

cfg.setDiscoverySpi(discoverySpi);

In this case, discovery will happen as if all the nodes in topology were server nodes.

Note that in this case, all addresses used by the discovery SPI on all the nodes should be mutually reachable in order for the discovery to work properly.

Clients and Servers

Automatically distinguish between client and server nodes.