> For the complete documentation index, see [llms.txt](https://mariadb.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mariadb.com/docs/gridgain/gridgain-8/gridgain8-get-started/quick-start/java.md).
# Java
Install GridGain, start a cluster, and run your first Java application, from system requirements and Maven setup to a Hello World compute example.
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.
{% hint style="info" %}
[Complimentary, Instructor-Led Developer Training - Apache Ignite Essentials](https://www.gridgain.com/products/services/training/apache-ignite-essentials)
If you are getting started with Ignite or GridGain, we recommend attending [an upcoming training session](https://www.gridgain.com/products/services/training#public-training-listing) to learn about the key design principles for building data-intensive applications.
{% endhint %}
## Prerequisites
This section describes the platform requirements for machines running GridGain. GridGain system requirements scale depending on the size of the cluster.
| Requirement | Details |
| ----------- | ---------------------------------------------------------------------------------------------------- |
| JDK | Oracle JDK 17 or later |
| OS | Linux (any flavor), Windows (10 and up). For Docker environment, we provide Linux docker containers. |
| ISA | x86-64, SPARC, PowerPC |
| Network | No restrictions (10G recommended) |
GridGain requires Java 17 or later. See [Running GridGain with Java 17 or Later](#running-gridgain-with-java-17-or-later) for the JVM parameters it needs.
### (Optional) Open Ports
Depending on your environment and what your plan is, you may want to open additional ports. GridGain uses the following ports:
* 47100-47200 — ports used by GridGain nodes to communicate. Specific ports used depend on node configuration.
* 47500-47600 — ports used by GridGain nodes to discover other nodes in the network. Specific ports used depend on node configuration.
* 10800 — the port used for [thin clients](/docs/connectors/gridgain-8/clients/getting-started-with-thin-clients.md), [JDBC](/docs/connectors/gridgain-8/sql/jdbc/jdbc-driver.md) and [ODBC](/docs/connectors/gridgain-8/sql/odbc/odbc-driver.md) connections.
* 8080 — the port used for [REST API](/docs/gridgain/gridgain-8/reference/rest-api.md).
* 11211 — the port used by [control script](/docs/gridgain/gridgain-8/reference/cli-tool.md) calls. This port should only be opened on nodes that need to send control script messages to other nodes.
## Installing GridGain
GridGain is distributed as binary, docker, and cloud images, and via RPM/DEB. This chapter explains how to install the binary distribution.
To get started with the GridGain binary distribution:
1. Download the [GridGain binary](https://www.gridgain.com/resources/download) 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 Control Center for cluster management and monitoring needs.
4. (Optional) Enable required [modules](/docs/gridgain/gridgain-8/gridgain8-development/project-setup.md#enabling-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:
{% tabs %}
{% tab title="Unix" %}
```shell
cd {gridgain}/bin/
```
{% endtab %}
{% tab title="Windows" %}
```shell
cd {gridgain}\bin\
```
{% endtab %}
{% endtabs %}
Start a node with a custom configuration file that is passed as a parameter to `ignite.sh|bat` like this:
{% tabs %}
{% tab title="Unix" %}
```shell
./ignite.sh ../examples/config/example-ignite.xml
```
{% endtab %}
{% tab title="Windows" %}
```shell
ignite.bat ..\examples\config\example-ignite.xml
```
{% endtab %}
{% endtabs %}
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:
{% tabs %}
{% tab title="Unix" %}
```shell
./ignite.sh ../examples/config/example-ignite.xml
```
{% endtab %}
{% tab title="Windows" %}
```shell
ignite.bat ..\examples\config\example-ignite.xml
```
{% endtab %}
{% endtabs %}
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]
```
{% hint style="info" %}
By default, `ignite.sh|bat` starts a node with the default configuration file: `config/default-config.xml`.
{% endhint %}
## 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.
```xml
8.10.0GridGain External Repositoryhttps://www.gridgainsystems.com/nexus/content/repositories/externalorg.gridgainignite-core${gridgain.version}org.gridgainignite-spring${gridgain.version}
```
### 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.
```java
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 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 cache = ignite.cache("myCache");
System.out.println(">> " + cache.get(1) + " " + cache.get(2));
}
}
}
```
{% hint style="info" %}
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 a Java compiler from a version earlier than 17:
```xml
org.apache.maven.pluginsmaven-compiler-plugin1717
```
{% endhint %}
### 3. Run HelloWorld.java
Run HelloWorld.java. You will see 'Hello World!' and other environment details printed on all the server nodes.
{% hint style="warning" %}
`HelloWorld` sets `peerClassLoadingEnabled` to `true`, and this value must match on every node. The default node configuration and `example-ignite.xml` leave peer class loading off, so a server started with them rejects the client with `Remote node has peer class loading enabled flag different from local`. Start the servers with `peerClassLoadingEnabled` set to `true`, for example in your own configuration file.
{% endhint %}
## Next Steps
From here, you may want to:
* Read more about using GridGain
* Work through the [GridGain 8 Tutorials](/docs/gridgain/gridgain-8/gridgain8-get-started/learning-paths.md) for hands-on, step-by-step practice
* Use [GridGain Control Center](/docs/tools/enterprise/control-center.md) to monitor your 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.
The source code of the examples is also available in the [gg8-examples](https://github.com/GridGain-Demos/gg8-examples) GitHub repository.
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:
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 17 or later if needed.
6. Run `src/main/java/org/apache/ignite/examples/datagrid/CacheApiExample`:
7. Make sure that the example has been started and executed successfully, as shown in the image below.
## Running GridGain with Java 17 or Later
To run GridGain with Java 17 or later:
* Set the `JAVA_HOME` environment variable to point to the Java installation directory.
* Pass specific flags to JVM to make proprietary SDK 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
--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=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.net=ALL-UNNAMED
--add-opens=java.base/java.nio=ALL-UNNAMED
--add-opens=java.base/java.security.cert=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.lang.reflect=ALL-UNNAMED
--add-opens=java.base/java.math=ALL-UNNAMED
--add-opens=java.base/java.time=ALL-UNNAMED
--add-opens=java.base/java.text=ALL-UNNAMED
--add-opens=java.base/sun.security.ssl=ALL-UNNAMED
--add-opens=java.base/sun.security.x509=ALL-UNNAMED
--add-opens=java.logging/java.util.logging=ALL-UNNAMED
--add-opens=java.management/sun.management=ALL-UNNAMED
--add-opens=java.desktop/java.awt.font=ALL-UNNAMED
--add-opens=java.sql/java.sql=ALL-UNNAMED
```
{% hint style="info" %}
Other parameters, for example, [Detailed GC Logs](/docs/gridgain/gridgain-8/tuning-and-troubleshooting/troubleshooting.md#detailed-gc-logs), may be version-dependent as well.
{% endhint %}
Your GridGain cluster nodes may start successfully and reach `ACTIVE` status, but certain runtime operations can still fail with module access errors caused by Java module system (JPMS) restrictions. This happens when your application's objects use a package that is not opened by the parameters above. Below is an example of an error you may encounter:
```
java.lang.reflect.InaccessibleObjectException: module java.base does not "opens java.util.regex" to unnamed module
```
To resolve this issue, add the appropriate JVM option (`--add-opens`) for the module and package mentioned in the error. For example, for the error above, you would add the following:
```
--add-opens=java.base/java.util.regex=ALL-UNNAMED
```
{% hint style="info" %}
The specific option depends on the object types used by the application.
{% endhint %}
Then, restart each node where you updated access permission.