GridGain Documentation

The GridGain Developer Hub

Welcome to the GridGain developer hub. You'll find comprehensive guides and documentation to help you start working with GridGain as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Getting Started

This page will help you get started with GridGain. You'll be up and running in a jiffy!

Prerequisites

GridGain was officially tested on:

Name
Value

JDK

Oracle JDK 8
Open JDK 8
IBM JDK 8

If you use Java version 9 or later, see Running GridGain with Java 9 or later for details.

OS

Linux (any flavor),
Mac OSX (10.6 and up)
Windows (XP and up),
Windows Server (2008 and up)
Oracle Solaris

ISA

x86, x64, SPARC, PowerPC

Network

No restrictions (10G recommended)

Running GridGain with Java 9/10/11

To run GridGain with Java 9/10/11, perform the following steps:

  1. Set the JAVA_HOME variable to point to the Java installation directory.

  2. GridGain uses proprietary SDK APIs that are not available by default. You need to pass specific flags to JVM to make these APIs available. If you use the start-up script ignite.sh, you do not need to do anything because these flags are already set up in the script. Otherwise, provide the following parameters to the JVM of your application:

--add-exports=java.base/jdk.internal.misc=ALL-UNNAMED 
--add-exports=java.base/sun.nio.ch=ALL-UNNAMED 
--add-exports=java.management/com.sun.jmx.mbeanserver=ALL-UNNAMED 
--add-exports=jdk.internal.jvmstat/sun.jvmstat.monitor=ALL-UNNAMED
--add-exports=java.base/sun.reflect.generics.reflectiveObjects=ALL-UNNAMED
--illegal-access=permit
-Djdk.tls.client.protocols=TLSv1.2
 
  1. TLSv1.3, which is available in Java 11, is not supported at the moment. Consider adding -Djdk.tls.client.protocols=TLSv1.2 if SSL between nodes is used.

Installation

Here is the quick summary on installation of GridGain Enterprise Edition:

  • Download GridGain IMDF as ZIP archive from http://www.gridgain.com/download/editions/
  • Unzip the ZIP archive into the installation folder on your system
  • Set IGNITE_HOME environment variable to point to the installation folder and make sure there is no trailing / in the path (this step is optional)

GridGain reuses Ignite's system properties, environment properties, startup scripts, etc. wherever possible. E.g., you will start a GridGain node with ignite.sh script, but you will get all enterprise features, because GridGain plugin will be automatically enabled.

Start From Command Line

A GridGain node can be started from command line either with default configuration or by passing a configuration file. You can start as many nodes as you like and they will all automatically discover each other.

With Default Configuration

To start a grid node with default configuration, open the command shell and, assuming you are in IGNITE_HOME (GridGain installation folder), just type this:

$ bin/ignite.sh

and you will see the output similar to this:

[02:49:12] Ignite node started OK (id=ab5d18a6)
[02:49:12] Topology snapshot [ver=1, nodes=1, CPUs=8, heap=1.0GB]

By default, ignite.sh starts a node with the default configuration: config/default-config.xml.

Passing Configuration File

To pass a configuration file explicitly, from the command line, you can type ignite.sh <path-to-your-configuration-file> from within your Ignite installation folder. For example:

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

Path to configuration file can be absolute, or relative to either IGNITE_HOME (GridGain installation folder) or META-INF folder in your classpath.

Interactive Mode

To pick a configuration file in interactive mode just pass -i flag, like so: ignite.sh -i.

Get It With Maven

Another easy way to get started with GridGain in your project is to use Maven's dependency management. To use Maven dependencies for GridGain, you need to do the following:

  1. Add GridGain's External Repository to your application's POM.xml file.
<repositories>
    <repository>
        <id>GridGain External Repository</id>
        <url>http://www.gridgainsystems.com/nexus/content/repositories/external</url>
    </repository>
</repositories>
  1. Add the following maven dependencies. Make sure to replace ${gridgain.version} with the actual GridGain version you want to use.
<dependencies>

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

    <dependency>
        <groupId>org.gridgain</groupId>
        <artifactId>ignite-spring</artifactId>
        <version>${gridgain.version}</version>
    </dependency>

    <dependency>
        <groupId>org.gridgain</groupId>
        <artifactId>ignite-indexing</artifactId>
        <version>${gridgain.version}</version>
    </dependency>

    <!-- Add this dependency to use GridGain Enterprise Edition features -->
    <!--dependency>
        <groupId>org.gridgain</groupId>
        <artifactId>gridgain-core</artifactId>
        <version>${gridgain.version}</version>
    </dependency-->

    <!-- Add this dependency to use GridGain Ultimate Edition features. -->
    <!--dependency>
        <groupId>org.gridgain</groupId>
        <artifactId>gridgain-ultimate</artifactId>
        <version>${gridgain.version}</version>
    </dependency-->

</dependencies> 

GridGain requires only one ignite-core as a mandatory dependency. Usually you will also need to add ignite-spring for spring-based XML configuration and ignite-indexing for SQL queries.

  1. Add gridgain-core dependency if you want to use GridGain Enterprise Edition.
  2. Add gridgain-core and gridgain-ultimate dependency if you want to use GridGain Ultimate Edition.

First GridGain Compute Application

Let's write our first grid application which will count a number of non-white-space characters in a sentence. As an example, we will take a sentence, split it into multiple words, and have every compute job count number of characters in each individual word. At the end we simply add up results received from individual jobs to get our total count.

try (Ignite ignite = Ignition.start("examples/config/example-ignite.xml")) {
  Collection<IgniteCallable<Integer>> calls = new ArrayList<>();
 
  // Iterate through all the words in the sentence and create Callable jobs.
  for (final String word : "Count characters using callable".split(" "))
    calls.add(word::length);
 
  // Execute collection of Callables on the grid.
  Collection<Integer> res = ignite.compute().call(calls);
 
  // Add up all the results.
  int sum = res.stream().mapToInt(Integer::intValue).sum();
  
  System.out.println("Total number of characters is '" + sum + "'.");
} 
try (Ignite ignite = Ignition.start("examples/config/example-ignite.xml")) {
    Collection<IgniteCallable<Integer>> calls = new ArrayList<>();
  
    // Iterate through all the words in the sentence and create Callable jobs.
    for (final String word : "Count characters using callable".split(" ")) {
        calls.add(new IgniteCallable<Integer>() {
            @Override public Integer call() throws Exception {
                return word.length();
            }
        });
    }
  
    // Execute collection of Callables on the grid.
    Collection<Integer> res = ignite.compute().call(calls);
  
    int sum = 0;
  
    // Add up individual word lengths received from remote nodes.
    for (int len : res)
        sum += len;
  
    System.out.println(">>> Total number of characters in the phrase is '" + sum + "'.");
} 

Zero Deployment

Note that because of Zero Deployment feature, when running the above application from your IDE, remote nodes will execute received jobs without explicit deployment.

First GridGain Data Grid Application

Now let's write a simple set of mini-examples which will put and get values to/from distributed cache, and perform basic transactions.

Since we are using cache in this example, we should make sure that it is configured. Let's use example configuration shipped with Ignite that already has several caches configured:

$ bin/ignite.sh examples/config/example-cache.xml
try (Ignite ignite = Ignition.start("examples/config/example-cache.xml")) {
    IgniteCache<Integer, String> cache = ignite.getOrCreateCache("myCacheName");
  
    // Store keys in cache (values will end up on different cache nodes).
    for (int i = 0; i < 10; i++)
        cache.put(i, Integer.toString(i));
  
    for (int i = 0; i < 10; i++)
        System.out.println("Got [key=" + i + ", val=" + cache.get(i) + ']');
}
// Put-if-absent which returns previous value.
Integer oldVal = cache.getAndPutIfAbsent("Hello", 11);
   
// Put-if-absent which returns boolean success flag.
boolean success = cache.putIfAbsent("World", 22);
   
// Replace-if-exists operation (opposite of getAndPutIfAbsent), returns previous value.
oldVal = cache.getAndReplace("Hello", 11);
  
// Replace-if-exists operation (opposite of putIfAbsent), returns boolean success flag.
success = cache.replace("World", 22);
   
// Replace-if-matches operation.
success = cache.replace("World", 2, 22);
   
// Remove-if-matches operation.
success = cache.remove("Hello", 1); 
try (Transaction tx = ignite.transactions().txStart()) {
    Integer hello = cache.get("Hello");
   
    if (hello == 1)
        cache.put("Hello", 11);
   
    cache.put("World", 22);
   
    tx.commit();
} 
// Lock cache key "Hello".
Lock lock = cache.lock("Hello");
  
lock.lock();
  
try {
    cache.put("Hello", 11);
    cache.put("World", 22);
}
finally {
    lock.unlock();
}

Configuration

GridGain is based on the Apache Ignite project and adds enterprise features as a plugin. All functionality that is available in Ignite is available in GridGain without any API changes. Refer to the Ignite documentation for more information.

GridGain plugin is enabled automatically with default settings. If you need to modify them (add security, snapshots, data center replication, etc.), you should use GridGainConfiguration class. This implements Ignite's PluginConfiguration interface that can be set using the IgniteConfiguration.setPluginConfigurations() configuration property.

For example, if you want to enable security, you can configure it using GridGainConfiguration.setSecurityCredentialsProvider() method:

// Ignite configuration.
IgniteConfiguration igniteCfg = new IgniteConfiguration();
 
// GridGain plugin configuration.
GridGainConfiguration gridCfg = new GridGainConfiguration();

// Create security credentials.
SecurityCredentials creds = new SecurityCredentials("username", "password");

// Create basic security provider.
SecurityCredentialsBasicProvider provider = new SecurityCredentialsBasicProvider(creds);

// Specify security provider in GridGain Configuration.
gridCfg.setSecurityCredentialsProvider(provider);

GridGain Visor Admin Console

The easiest way to examine the content of the data grid as well as perform a long list of other management and monitoring operations is to use GridGain Visor GUI Utility.

To start Visor simply run:

$ bin/ggvisorui.sh