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

Initialization and Configuration

The IgniteClient API is the entry-point to the Java thin client. Learn how to configure and get references of the thin client APIs provided by Ignite.

Initialization

Ignition#startClient(ClientConfiguration) method initializes a thin client's connection to Ignite.

IgniteClient is an auto-closable resource. Use try-with-resources statement to initialize and release IgniteClient.

try (IgniteClient client = Ignition.startClient(
  new ClientConfiguration().setAddresses("127.0.0.1:10800")
)) { 
  // Do something here.
}

Configuration

Use ClientConfiguration and ClientCacheConfiguration to configure the thin client and client cache respectively.

ClientCache API

The ClientCache API represents a cache and can be used to perform key-value operations on the data stored in Ignite. You can use the following methods to obtain an instance of ClientCache:

  • IgniteClient#cache(String): assumes a cache with the specified name exists. The method does not communicate with Ignite to check if the cache really exists. Subsequent cache operations would fail if the cache does not exist.
  • IgniteClient#getOrCreateCache(String), IgniteClient#getOrCreateCache(ClientCacheConfiguration): get existing cache with the specified name or create the cache if it does not exist. The former operation creates a cache with default configuration.
  • IgniteClient#createCache(String), IgniteClient#createCache(ClientCacheConfiguration): create a cache with the specified name and fail if the cache already exists.

Use IgniteClient#cacheNames() to list all existing caches.

ClientCacheConfiguration cacheCfg = new ClientCacheConfiguration()
  .setName("References")
  .setCacheMode(CacheMode.REPLICATED)
  .setWriteSynchronizationMode(CacheWriteSynchronizationMode.FULL_SYNC);

ClientCache<Integer, String> cache = client.getOrCreateCache(cacheCfg);

Multithreading

Thin client is single-threaded and thread-safe. The only shared resource is the underlying communication channel, and only one thread reads/writes to the channel while other threads are waiting for the operation to complete.

Use multiple threads with thin client connection pool to improve performance

Presently thin client has no feature to create multiple threads to improve throughput. You can create multiple threads by getting thin client connection from a pool in your application to improve throughput.

Asynchronous API

Asynchronous API is not supported

Although binary client protocol is designed to support asynchronous API, the Java thin client presently does not support it. Asynchronous API will be added in the next releases.

Client-Server Compatibility

Thin client's ignite-core version has to be the same or smaller than the server's ignite-core version.

Ignite server tries to maintain binary protocol backward compatibility. A RuntimeException will be thrown if the client and server protocol version are not compatible.

Failover

Ignite does not support thin client failover on the server side. Thin client provides failover by automatically re-connecting to a different server and retrying an operation if the server that the client is connected to goes down.
Configure multiple servers to enable failover mechanism.

try (IgniteClient client = Ignition.startClient(
  new ClientConfiguration()
  .setAddresses("127.0.0.1:1080", "127.0.0.1:1081", "127.0.0.1:1082")
)) {
  ...
} catch (ClientConnectionException ex) {
    // All the servers are unavailable
}

Thin client randomly tries all the servers in the list and throws ClientConnectionException if all the servers are unavailable.

Unless all the servers become unavailable, the failover mechanism is almost transparent to the user code. The only implication is that failed over queries return duplicate entries, which is against the cache semantics. Consider this code:

Query<Cache.Entry<Integer, Person>> qry = new ScanQuery<Integer, Person>((i, p) -> p.getName().contains("Smith")).setPageSize(1000);


try (QueryCursor<Cache.Entry<Integer, Person>> cur = cache.query(qry)) {
   for (Cache.Entry<Integer, Person> entry : cur) {
     // Handle the entry ...
   }
}

Scan queries and SQL SELECT queries retrieve data in pages. If the server that the client is connected to goes down while the entries are being iterated, the client retries the query from the beginning. That makes the code above process entries that were already processed.
There are two approaches to address the issue:

  • If data is small enough to fit into memory then get all the data and put it in a map: Map<Integer, Person> res = cur.getAll().stream().collect(Collectors.toMap(Cache.Entry::getKey, Cache.Entry::getValue)). Map semantics fixes duplicate entries.
  • Remember about the duplicate entries issue and handle the entries idempotently.

Updated about a month ago

Initialization and Configuration


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.