Install and set up

Before installing the API, make sure your development machine meets the system requirements.

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.

                                                    
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
plugins {
    id 'application'
    id 'org.openjfx.javafxplugin' version '0.0.8'
}

ext {
    arcgisVersion = '100.11.2'
}

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.

                                                                                                                       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
<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.11.2</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 WindowsDownload Java SDK for Linux
  1. Download the ArcGIS Runtime SDK for Java as a .zip or .tgz.
  2. Extract the archive contents and copy the libs, jniLibs, and resources folders into the root of your project directory.
  3. Add all of the jars in the libs folder to your classpath.

For the OpenJFX dependencies:

  1. Download the OpenJFX SDK (11.0.2) from Gluon.
  2. Extract the archive contents and copy the directory into the root of your project directory.
  3. 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:

  1. The absolute path to the downloaded API specified programmatically at the start of your app's code:
 
1
ArcGISRuntimeEnvironment.setInstallDirectory("C:/path/to/arcgis-runtime-api-java-100.11.2")
  1. 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.
  2. The location you specify by the environment variable ARCGISRUNTIMESDKJAVA_100_11_2.

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

     
1
2
3
4
5
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_11_2
- Within the ".arcgis" directory in the user's home path C:\Users\johndoe\.arcgis

Additional downloads

You can do many things with this API, here are a few to consider:

Sample code

Review sample code in our complete sample directory, or download the code from our GitHub repository. Interact with live samples using the sample viewer app.

ArcGIS Runtime API for Java Toolkit

The ArcGIS Runtime SDK for Java Toolkit contains controls and utilities to simplify your app development. For example:

  • Compass: A control that shows orientation when a map is rotated.
  • OverviewMap: An overview map control that indicates the viewpoint of another map or scene view.
  • Scalebar: Scalebar control that shows an accurate distance that can be used to visually gauge distances on a map view.

StreetMap Premium

To use StreetMap Premium (the StreetMap Premium extension), download the demonstration data from the downloads page for development and testing. Please contact Esri Customer Service for access to the region of your choice for development and testing or to license StreetMap Premium data for deployment.

Supplemental data

To use grid-based transformations, download supporting Projection Engine files from the downloads page.

To work with Electronic Navigational Charts (ENC), download the hydrography directory from the downloads page.

Local Server

To run offline geoprocessing tasks in your app, install Local Server.

Next steps

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.