GridGain Developers Hub
GitHub logo GridGain iso GridGain.com
GridGain Software Documentation

GridGain for Java

This chapter explains system requirements for running GridGain, how to install GridGain, start a cluster and run a simple Hello World example.

Since GridGain is built on top of Apache Ignite, GridGain reuses Ignite’s system properties, environment properties, startup scripts, etc. wherever possible.

Prerequisites

GridGain was officially tested on:

JDK

Oracle JDK 8 and later, Open JDK 8 and later, IBM JDK 8 and later

OS

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

ISA

x86, x64, SPARC, PowerPC

Network

No restrictions (10G recommended)

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

Installing GridGain

GridGain is available in three editions: Community Edition (CE), Enterprise Edition (EE) and Ultimate Edition (UE). For this example, we’ll use the GridGain CE, which is distributed as binary, docker, and cloud images, and via RPM/DEB. This chapter explains how to install the GridGain CE binary distribution.

To get started with the GridGain CE binary distribution:

  1. Download the GridGain binary as a zip archive.

  2. Unzip the zip archive into the installation folder in your system.

  3. Move the ignite-rest-http folder from {gridgain}/libs/optional to {gridgain}/libs to enable the Ignite REST library for the cluster. The library is used by GridGain Web Console for cluster management and monitoring needs.

  4. (Optional) Enable required modules.

  5. (Optional) Set the IGNITE_HOME environment variable or Windows PATH to point to the installation folder and make sure there is no trailing / (or \ for Windows) in the path.

Starting a GridGain Node

You can start a GridGain node from the command line using the default configuration or by passing a custom configuration file. You can start as many nodes as you like and they will all automatically discover each other.

Navigate into the bin folder of GridGain installation directory from the command shell. Your command might look like this:

$ cd {gridgain}/bin/
$ cd {gridgain}\bin\

Start a GridGain node with a custom configuration file that is passed as a parameter to ignite.sh|bat like this:

$ ./ignite.sh examples/config/example-ignite.xml
$ ignite.bat examples\config\example-ignite.xml

You will see output similar to this:

[08:53:45] Ignite node started OK (id=7b30bc8e)
[08:53:45] Topology snapshot [ver=1, locNode=7b30bc8e, servers=1, clients=0, state=ACTIVE, CPUs=4, offheap=1.6GB, heap=2.0GB]

Open another tab from your command shell and run the same command again:

$ ./ignite.sh examples/config/example-ignite.xml
$ ignite.bat examples\config\example-ignite.xml

Check the Topology snapshot line in the output. Now you have a cluster of two server nodes with more CPUs and RAM available cluster-wide:

[08:54:34] Ignite node started OK (id=3a30b7a4)
[08:54:34] Topology snapshot [ver=2, locNode=3a30b7a4, servers=2, clients=0, state=ACTIVE, CPUs=4, offheap=3.2GB, heap=4.0GB]

Running Your First GridGain Application

Once the cluster is started, follow the steps below to run a simple HelloWorld example.

1. Add Maven Dependency

The easiest way to get started with GridGain in Java is to use Maven dependency management.

Create a new Maven project with your favorite IDE and add the following dependencies in your project’s pom.xml file.

<properties>
    <gridgain.version>8.7.8</gridgain.version>
</properties>

<repositories>
    <repository>
        <id>GridGain External Repository</id>
        <url>http://www.gridgainsystems.com/nexus/content/repositories/external</url>
    </repository>
</repositories>

<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>
</dependencies>

2. HelloWorld.java

Here is a sample HelloWord.java file that prints 'Hello World' and some other environment details on all the server nodes of the cluster. The sample shows how to prepare a cluster configuration with Java APIs, create a sample cache with some data in it, and execute custom Java logic on the server nodes.

public class HelloWorld {
    public static void main(String[] args) throws IgniteException {
        // Preparing IgniteConfiguration using Java APIs
        IgniteConfiguration cfg = new IgniteConfiguration();

        // The node will be started as a client node.
        cfg.setClientMode(true);

        // Classes of custom Java logic will be transferred over the wire from this app.
        cfg.setPeerClassLoadingEnabled(true);

        // Setting up an IP Finder to ensure the client can locate the servers.
        TcpDiscoveryMulticastIpFinder ipFinder = new TcpDiscoveryMulticastIpFinder();
        ipFinder.setAddresses(Collections.singletonList("127.0.0.1:47500..47509"));
        cfg.setDiscoverySpi(new TcpDiscoverySpi().setIpFinder(ipFinder));

        // Starting the node
        Ignite ignite = Ignition.start(cfg);

        // Create an IgniteCache and put some values in it.
        IgniteCache<Integer, String> cache = ignite.getOrCreateCache("myCache");
        cache.put(1, "Hello");
        cache.put(2, "World!");

        System.out.println(">> Created the cache and add the values.");

        // Executing custom Java compute task on server nodes.
        ignite.compute(ignite.cluster().forServers()).broadcast(new RemoteTask());

        System.out.println(">> Compute task is executed, check for output on the server nodes.");

        // Disconnect from the cluster.
        ignite.close();
    }

    /**
     * A compute tasks that prints out a node ID and some details about its OS and JRE.
     * Plus, the code shows how to access data stored in a cache from the compute task.
     */
    private static class RemoteTask implements IgniteRunnable {
        @IgniteInstanceResource
        Ignite ignite;

        @Override public void run() {
            System.out.println(">> Executing the compute task");

            System.out.println(
                "   Node ID: " + ignite.cluster().localNode().id() + "\n" +
                "   OS: " + System.getProperty("os.name") +
                "   JRE: " + System.getProperty("java.runtime.name"));

            IgniteCache<Integer, String> cache = ignite.cache("myCache");

            System.out.println(">> " + cache.get(1) + " " + cache.get(2));
        }
    }
}

3. Run HelloWorld.java

Run HelloWorld.java. You will see 'Hello World!' and other environment details printed on all the server nodes.

Next Steps

From here, you may want to:

Using GridGain Web Console

GridGain Web Console is an interactive configuration, management, and monitoring tool, built on top of Apache Ignite Web Console.

  1. Go to https://console.gridgain.com and create an account.

  2. Log in with your new account and go to the "Monitoring Dashboard" screen. Click the three horizontal lines at the top in order to expand the left-hand menu:

    Web Console Left Nav
  3. Click the "Download Agent" button as shown in the screenshot below:

    Download the Web Console Agent
  4. Extract the web agent into a separate folder.

  5. Navigate to the folder where you extracted the web agent files, and execute the ignite-web-agent.sh (or ignite-web-agent.bat) script.

  6. Ensure that the agent can connect to both console.gridgain.com and your single node cluster started earlier. Look for messages similar to the following in the agent’s log:

    Web Console Log
  7. Go back to the console.gridgain.com Monitoring Dashboard and refresh it. Confirm that the tool successfully displays metrics for your local single node cluster.

Further Examples

Your GridGain installation includes additional examples. These examples are shipped together with the primary GridGain package you downloaded as part of the GridGain installation above.

To run the examples project please follow these steps (which are provided for IntelliJ IDEA IDE, but should apply to similar IDEs such as Eclipse):

  1. Start IntelliJ IDEA, click the "Import Project" button:

    Importing a Project in IntelliJ
  2. Navigate to the {gridgain}/examples folder and select the {gridgain}/examples/pom.xml file. Click "OK".

  3. Click "Next" on each of the following screens and apply the suggested defaults to the project. Click "Finish".

  4. Wait while IntelliJ IDEA finishes setting up Maven, resolving dependencies, and loading modules.

  5. Set up JDK if needed.

  6. Run src/main/java/org.apache.examples/datagrid/CacheApiExample:

    Run a project in IntelliJ
  7. Make sure that the example has been started and executed successfully, as shown in the image below.

    Project in IntelliJ

Running GridGain with Java 9 or later

To run GridGain with Java 9/10/11, follow these steps:

  1. Set the JAVA_HOME environment variable or Windows PATH 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 (or ignite.bat for Windows), 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
    # Used to get access to java UNSAFE (access to offheap memory).
    
    --illegal-access=permit
    # Allows access to private fields without accessors, used for dependency injection in user classes (for example, @IgniteInstanceResource annotation).
    
    --add-exports=java.base/sun.nio.ch=ALL-UNNAMED
    # Used for java.nio Selector optimization.
    
    --add-exports=java.management/com.sun.jmx.mbeanserver=ALL-UNNAMED
    # Used to enable JMX monitoring capability.
    
    --add-exports=jdk.internal.jvmstat/sun.jvmstat.monitor=ALL-UNNAMED
    # Used to allow jvisualvm to connect to Ignite process.
    
    --add-exports=java.base/sun.reflect.generics.reflectiveObjects=ALL-UNNAMED
    # Used for fast object construction during marshalling/unmarshalling.
  3. 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.