Ignite Quick Start Guide for Java
This page explains system requirements for running Ignite, how to install Ignite, start a cluster and run a simple Hello World example.
Prerequisites
Ignite was officially tested on:
JDK |
Oracle JDK 8, 11 or 17 Open JDK 8, 11 or 17, IBM JDK 8, 11 or 17 |
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) |
If you use Java version 11 or later, see Running Ignite with Java 11 or later for details.
Installing Ignite
To get started with the Apache Ignite binary distribution:
-
Download the Ignite binary as a zip archive.
-
Unzip the zip archive into the installation folder in your system.
-
(Optional) Enable required modules.
-
(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 Node
You can start a 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 the Ignite installation directory from the command shell.
Your command might look like this:
cd {IGNITE_HOME}/bin/
cd {IGNITE_HOME}\bin\
Start a 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]
Note
|
By default, ignite.sh|bat starts a node with the default configuration file: config/default-config.xml .
|
Running Your First 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 Ignite 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>
<ignite.version>2.16.0</ignite.version>
</properties>
<dependencies>
<dependency>
<groupId>org.apache.ignite</groupId>
<artifactId>ignite-core</artifactId>
<version>${ignite.version}</version>
</dependency>
<dependency>
<groupId>org.apache.ignite</groupId>
<artifactId>ignite-spring</artifactId>
<version>${ignite.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));
}
}
}
Note
|
Don’t forget to add imports for HelloWorld.java. It should be trivial as long as Maven solves all of the dependencies. Plus, you might need to add these settings to your pom.xml if the IDE keeps using Java compiler from a version earlier than 1.8:
|
3. Run HelloWorld.java
Run HelloWorld.java. You will see 'Hello World!' and other environment details printed on all the server nodes.
Further Examples
Your Ignite installation includes additional examples. These examples are shipped together with the primary Ignite package you downloaded as part of the Ignite 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):
-
Start IntelliJ IDEA, click the "Import Project" button:
-
Navigate to the
{IGNITE_HOME}/examples
folder and select the{IGNITE}/examples/pom.xml
file. Click "OK". -
Click "Next" on each of the following screens and apply the suggested defaults to the project. Click "Finish".
-
Wait while IntelliJ IDEA finishes setting up Maven, resolving dependencies, and loading modules.
-
Set up JDK if needed.
-
Run
src/main/java/org/apache/ignite/examples/datagrid/CacheApiExample
: -
Make sure that the example has been started and executed successfully, as shown in the image below.
Running Ignite with Java 11 or later
To run Ignite with Java 11 or later, follow these steps:
-
Set the
JAVA_HOME
environment variable to point to the Java installation directory. -
Ignite 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
(orignite.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 --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 --add-opens=jdk.management/com.sun.management.internal=ALL-UNNAMED --illegal-access=permit
--add-opens=java.base/jdk.internal.access=ALL-UNNAMED --add-opens=java.base/jdk.internal.misc=ALL-UNNAMED --add-opens=java.base/sun.nio.ch=ALL-UNNAMED --add-opens=java.base/sun.util.calendar=ALL-UNNAMED --add-opens=java.management/com.sun.jmx.mbeanserver=ALL-UNNAMED --add-opens=jdk.internal.jvmstat/sun.jvmstat.monitor=ALL-UNNAMED --add-opens=java.base/sun.reflect.generics.reflectiveObjects=ALL-UNNAMED --add-opens=jdk.management/com.sun.management.internal=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.base/java.nio=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.locks=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.math=ALL-UNNAMED --add-opens=java.sql/java.sql=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.time=ALL-UNNAMED --add-opens=java.base/java.text=ALL-UNNAMED --add-opens=java.management/sun.management=ALL-UNNAMED --add-opens java.desktop/java.awt.font=ALL-UNNAMED
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.