Get started with the ArcGIS Runtime API for Java:
- Review system requirements
- Install and set up
- Get an access token (to access location 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-javajar - ArcGIS Runtime jniLibs, resources, and required libraries
- OpenJFX 11 or OpenJFX 17 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.13'
}
ext {
arcgisVersion = '100.15.0'
}
repositories {
mavenCentral()
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"
runtimeOnly "org.slf4j:slf4j-nop:1.7.32"
}
javafx {
version = "17.0.2"
modules = [ 'javafx.controls' ]
}
task copyNatives(type: Copy) {
description = "Copies the arcgis native libraries into the .arcgis directory for development."
group = "build"
configurations.natives.asFileTree.each {
from(zipTree(it))
}
into "${System.properties.getProperty("user.home")}/.arcgis/$arcgisVersion"
}
run {
dependsOn copyNatives
mainClassName = 'com.mycompany.app.App'
}The copyNatives task in this Gradle build script will automatically download and unpack the libraries into $USER_HOME/.arcgis directory. The API looks 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.mycompany</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.15.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>17.0.2</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>
<!--SLF4J dependencies-->
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-nop</artifactId>
<version>1.7.32</version>
</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.mycompany.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 $.
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 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, andjavafx.mediamodules. 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:
Use dark colors for code blocks Copy ArcGISRuntimeEnvironment.setInstallDirectory("C:/path/to/arcgis-runtime-api-java-100.15.6") -
The current working directory according to Java's
user.dirsystem 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 _15 _6
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_15_6
- Within the ".arcgis" directory in the user's home path C:\Users\johndoe\.arcgis3. Get an access token
To access secure ArcGIS services and resources, you need to use an access token. The easiest way to get started is to obtain an access token from an API Key. Learn more about access tokens and authentication in Security and authentication.
4. Tutorials
Follow step-by-step instructions to build apps that incorporate ArcGIS Runtime functionality.
Deploy your app
When you begin developing ArcGIS Runtime apps, you are accepting Esri's end user license agreement (EULA); there is no need to authorize your development machine or devices. Once you have finished building your application, you are required to obtain a license before deploying it to production. Licensing ensures that you have the necessary permissions and legal rights to distribute and use your application in a commercial or public environment. For more information, see the License and deployment topic for details.