Get started

Get started with the ArcGIS Runtime API for Java:

Review system requirements
Install and set up
Get an API key (to access services)
Start the Display a map tutorial

1. System requirements

Ensure your development environment meets the system requirements.

For an overview of this release, including enhancements, deprecations, and known issues, see the Release notes.

2. Install and set up

An app built with ArcGIS Runtime API for Java requires the following dependencies:

The arcgis-java jar
ArcGIS Runtime jniLibs, resources, and required libraries
OpenJFX 11 modules

There are three ways to get set up with the API:

Gradle
Maven
Downloaded .zip file

Get the API with Gradle

The buildscript below shows how to get these dependencies using the Gradle build tool.

For a starter project using Gradle with instructions for Eclipse and IntelliJ, download or clone the java-gradle-starter-project on GitHub.

plugins {
    id 'application'
    id 'org.openjfx.javafxplugin' version '0.0.8'
}

ext {
    arcgisVersion = '100.10.0'
}

javafx {
    version = "11.0.2"
    modules = [ 'javafx.controls', 'javafx.fxml', 'javafx.web', 'javafx.media' ]
}

compileJava.options.encoding = 'UTF-8'

repositories {
    jcenter()
    maven {
        url 'https://esri.jfrog.io/artifactory/arcgis'
    }
}

configurations {
    natives
}

dependencies {
    implementation "com.esri.arcgisruntime:arcgis-java:$arcgisVersion"
    natives "com.esri.arcgisruntime:arcgis-java-jnilibs:$arcgisVersion"
    natives "com.esri.arcgisruntime:arcgis-java-resources:$arcgisVersion"
}

task copyNatives(type: Copy) {
    description = "Copies the arcgis native libraries into the " +
            "project build directory for development."
    group = "build"
    configurations.natives.asFileTree.each {
        from(zipTree(it))
    }
    // store native libraries in a common location shared with other samples
    into "${System.properties.getProperty("user.home")}/.arcgis/$arcgisVersion"
}

run {
    dependsOn copyNatives
    mainClassName = 'com.example.app.App'
}

wrapper {
    gradleVersion = '6.5.1'
}

Run the Gradle copyNatives task. This will unpack the libraries into $USER_HOME/.arcgis. The API will automatically look in this directory to find the required libraries.

Configure the libraries

For your app to run, the API must be able to find the API's required libraries. If you got the API using Gradle, the libraries have been downloaded to your user directory in the .arcgis folder. Since the API can automatically find the required libraries at this location, no further configuration is necessary.

Get the API with Maven

The pom file below shows how to get the required dependencies using the Maven build tool.

For a starter project using Maven with instructions for Eclipse and IntelliJ, download or clone the java-maven-starter-project on GitHub.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>app</artifactId>
    <packaging>jar</packaging>
    <version>1.0-SNAPSHOT</version>
    <name>My Map App</name>
    <url>http://maven.apache.org</url>
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <arcgis.version>100.10.0</arcgis.version>
    </properties>
    <repositories>
        <repository>
            <id>arcgis</id>
            <url>https://esri.jfrog.io/artifactory/arcgis</url>
        </repository>
    </repositories>
    <dependencies>
        <!--JavaFX dependencies -->
        <dependency>
          <groupId>org.openjfx</groupId>
          <artifactId>javafx-controls</artifactId>
          <version>11</version>
        </dependency>
        <dependency>
          <groupId>org.openjfx</groupId>
          <artifactId>javafx-web</artifactId>
          <version>11</version>
        </dependency>
        <dependency>
          <groupId>org.openjfx</groupId>
          <artifactId>javafx-fxml</artifactId>
          <version>11</version>
        </dependency>
        <dependency>
          <groupId>org.openjfx</groupId>
          <artifactId>javafx-media</artifactId>
          <version>11</version>
        </dependency>
        <!--ArcGIS dependencies -->
        <dependency>
            <groupId>com.esri.arcgisruntime</groupId>
            <artifactId>arcgis-java</artifactId>
            <version>${arcgis.version}</version>
        </dependency>
        <dependency>
            <groupId>com.esri.arcgisruntime</groupId>
            <artifactId>arcgis-java-jnilibs</artifactId>
            <version>${arcgis.version}</version>
            <type>zip</type>
        </dependency>
        <dependency>
            <groupId>com.esri.arcgisruntime</groupId>
            <artifactId>arcgis-java-resources</artifactId>
            <version>${arcgis.version}</version>
            <type>zip</type>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-dependency-plugin</artifactId>
                <version>3.1.1</version>
                <configuration>
                    <artifactItems>
                        <artifactItem>
                            <groupId>com.esri.arcgisruntime</groupId>
                            <artifactId>arcgis-java-jnilibs</artifactId>
                            <version>${arcgis.version}</version>
                            <type>zip</type>
                            <overWrite>false</overWrite>
                            <outputDirectory>${user.home}/.arcgis/${arcgis.version}</outputDirectory>
                        </artifactItem>
                        <artifactItem>
                            <groupId>com.esri.arcgisruntime</groupId>
                            <artifactId>arcgis-java-resources</artifactId>
                            <version>${arcgis.version}</version>
                            <type>zip</type>
                            <overWrite>false</overWrite>
                            <outputDirectory>${user.home}/.arcgis/${arcgis.version}</outputDirectory>
                        </artifactItem>
                    </artifactItems>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.0</version>
                <configuration>
                    <release>11</release>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>1.6.0</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>java</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <mainClass>com.example.app.App</mainClass>
                </configuration>
            </plugin>
            <plugin>
                <groupId>io.takari</groupId>
                <artifactId>maven</artifactId>
                <version>0.7.4</version>
            </plugin>
        </plugins>
    </build>
</project>

Run the Maven dependency:unpack goal. This will unpack the required libraries into $USER_HOME/.arcgis.

Configure the libraries

For your app to run, the API must be able to find the required libraries. If you got the API using Maven, the libraries have been downloaded to your user directory in the ~/.arcgis folder. Since the API can automatically find the libraries at this location, no further configuration is necessary.

Getting the API manually

If you don't want to use a build tool like Gradle or Maven, you can download and set up the dependencies manually.

For a starter project using the API .zip file with instructions for Eclipse and IntelliJ, download or clone the java-zip-starter-project on GitHub.

For the ArcGIS Runtime API dependencies:

Download Java SDK for Windows

Download Java SDK for Linux

Download the ArcGIS Runtime SDK for Java as a .zip or .tgz.
Extract the archive contents and copy the libs, jniLibs, and resources folders into the root of your project directory.
Add all of the jars in the libs folder to your classpath.

For the OpenJFX dependencies:

Download the OpenJFX SDK (11.0.2) from Gluon.
Extract the archive contents and copy the directory into the root of your project directory.
Add the JavaFX jars to your module path. ArcGIS Runtime requires the javafx.controls, javafx.fxml, javafx.web, and javafx.media modules. Refer to Gluon's documentation for setup instructions.

Configure the native libraries

For your app to run, the API must be able to find the required libraries. You have a few options, ordered here by priority:

The absolute path to the downloaded API specified programmatically at the start of your app's code:

ArcGISRuntimeEnvironment.setInstallDirectory("C:/path/to/arcgis-runtime-api-java-100.10.0")

The current working directory according to Java's user.dir system property. This is usually the project's root directory when run from an IDE, or the directory from which you run your app's jar.
The location you specify by the environment variable ARCGISRUNTIMESDKJAVA_100_10_0.

If the native libraries are not properly configured, you will see an exception similar to the following:

Caused by: java.lang.RuntimeException: Could not find runtime in any of:
- A directory specified by calling ArcGISRuntimeEnvironment.setInstallDirectory()
- The current directory C:\Users\johndoe\my-project-directory
- A location specified by the environment variable ARCGISRUNTIMESDKJAVA_100_10_0
- Within the ".arcgis" directory in the user's home path C:\Users\johndoe\.arcgis

3. Get an API key

API keys are required to access ArcGIS services, such as basemaps, geocoding, routing, and others. Visit your dashboard and copy your default API key, or set custom scopes and referrers for your specific needs. Include your API key in the tutorials, samples, and sample apps where required in the instructions.

Log in to your dashboard
Copy your default API key, or generate a new one.

Learn more about API keys

4. Tutorials

Display a map

Add a point, line, and polyline

Deploy your app

No license is required to develop ArcGIS Runtime apps; there's no need to authorize your development machine or devices. As a member of the ArcGIS Developer Program, you have a free ArcGIS Developer Subscription (Essentials Plan). With this plan you can download and install any ArcGIS API and immediately have access to all the functionality of the APIs for development purposes. You can become a member of the developer program for free.

You must have an ArcGIS Developer Subscription with a plan in order to deploy your app to your users. The Essentials plan is free.

Go to dashboard, get your license string.

Learn more about Runtime licensing at license and deployment.

DocumentationArcGIS Runtime API for Java

Get started

Was this page helpful?

Was this page helpful?

Was this page helpful?

DocumentationArcGIS Runtime API for Java

Get started

1. System requirements

2. Install and set up

Get the API with Gradle

Configure the libraries

Get the API with Maven

Configure the libraries

Getting the API manually

Configure the native libraries

3. Get an API key

4. Tutorials

Display a map

Add a point, line, and polyline

Deploy your app

Next steps

Overview

Get started

Display a map

Was this page helpful?

Was this page helpful?

Was this page helpful?