You will learn: how to create a simple starter app that displays a basemap. This template project will be used in subsequent tutorials.

With the ArcGIS Runtime SDK for Java, it is easy to create a mapping app that displays a basemap. In this tutorial, you will use the Java SDK to build a simple mapping app to use as a starting place for the other Java tutorials.

This tutorial and subsequent tutorials assume you have experience with the Java programming language. Make sure your development environment meets the system requirements.

This guide is written in an IDE agnostic way. It also uses Gradle as a build tool. If you want to see how to create a project from scratch using the Eclipse IDE or you want to use Maven for a build tool, check out the in-depth guides.

Before you begin

Download ArcGIS Runtime SDK for Java

Login to ArcGIS for Developers to download and install the ArcGIS Runtime SDK for Java.


Create a starter app

  1. Download and unzip the starting template. This provides a skeleton Gradle project with no SDK dependencies added yet.

  2. Open the settings.gradle file in an editor of your choice and change the rootProject.name value to create-a-starter-app.

  3. Open the project's build.gradle file in an editor of your choice and add the following. Save the changes when complete.

      apply plugin: 'java'
      /* ** ADD ** */
      apply plugin: 'application'
      apply plugin: 'com.esri.arcgisruntime.java'
      buildscript {
        repositories {
          maven {
            url 'https://esri.bintray.com/arcgis'
        dependencies {
          classpath 'com.esri.arcgisruntime:gradle-arcgis-java-plugin:1.0.0'
      arcgis.version = '100.2.1' //100.x.y for other versions
      run {
        mainClassName = 'com.arcgis.developers.labs.App'
  4. Run the Gradle build task. The plugin added above will automatically fetch the jar and runtime libraries. To run the task in a terminal, run the following command from the project root:

    $ ./gradlew build

    On windows, use

    > gradlew.bat build

    You may also be able to run the task from your IDE. Consult your IDE's documentation for how to do this.

  5. Open the App.java file in the project's src/main/java/com/arcgis/developers/labs source directory. It should contain the following code:

    package com.arcgis.developers.labs;
    import javafx.application.Application;
    import javafx.scene.Scene;
    import javafx.scene.layout.StackPane;
    import javafx.stage.Stage;
    public class App extends Application {
      public void start(Stage stage) {
        StackPane stackPane = new StackPane();
        Scene scene = new Scene(stackPane);
      public static void main(String[] args) {

    Run your project now using the run task instead of the build task. Verify the app opens and shows an empty window titled "Tutorial".

Imports and variable declarations

  1. In the App class, add the following imports:

    import com.esri.arcgisruntime.mapping.ArcGISMap;
    import com.esri.arcgisruntime.mapping.Basemap;
    import com.esri.arcgisruntime.mapping.view.MapView;
  2. Create a private member variable mapView so you can refer to it in different parts of the application.

    public class App extends Application {
      /* *** ADD *** */
      private MapView mapView;

Add a map to your app

  1. Add a new private method called setupMap to initialize the map and set it to the map view.

    private void setupMap() {
      if (mapView != null) {
        Basemap.Type basemapType = Basemap.Type.STREETS_VECTOR;
        double latitude = 34.05293;
        double longitude = -118.24368;
        int levelOfDetail = 11;
        ArcGISMap map = new ArcGISMap(basemapType, latitude, longitude, levelOfDetail);
  2. Initialize the map view and call method that was created above.

    /* ** ADD ** */
    mapView = new MapView();
  3. To show the map view in the UI, add it as a child of the StackPane.

    /* ** ADD ** */
  4. Override the stop method to dispose of application resources when the app closes. Add this before the main method.

    public void stop() {
      if (mapView != null) {

Congratulations, you're done!

Your app should run and display the base map focused on the Los Angeles area.

You will refer back to this project as the starting project for many of the Java tutorials.


Explore basemaps

Visit the documentation to learn more about the different types of basemaps available, such as LIGHT_GRAY_CANVAS_VECTOR or STREETS_WITH_RELIEF_VECTOR. Experiment with a few of the many options before choosing your favorite for your project.

Change view

Try the other ArcGISMap constructors to set a different initial view by changing the latitude, longitude, and level of detail.