Build a web mapping app

This tutorial guides you through the process of adding a web map to your Java app using ArcGIS Runtime SDK for Java. Web maps contain a basemap layer and one or more operational layers, as well as tasks, feature collections, and pop-ups. You can create a web map on ArcGIS Online, but for the purposes of this tutorial, you'll use a public web map already created and hosted on ArcGIS Online.

Learn more about ArcGIS Online

Display a web map

  1. Browse ArcGIS Online and locate the web map you want to add to your application; there are a variety of public web maps you can use for this exercise. Try searching for maps using the search box at the top of the website page, typing for example the name of a city you are interested in. You'll see a list of results, each result giving you the option to open the map in the online map viewer or to view more details about the item.
  2. Click the result of your choice to view either the map details (by clicking Details) or the map itself in the online map viewer (by clicking Open). In the next screen, the web map ID is displayed at the end of the URL in your browser's address bar. For example, for the Topographic map with the details URL http://www.arcgis.com/home/item.html?id=d5e02a0c1f2b4ec399823fdd3c2fdebd, the ID is d5e02a0c1f2b4ec399823fdd3c2fdebd. Copy the ID for your chosen web map and save it for later in this tutorial.
  3. Create a Java application to contain an empty JMap that will display the contents of your chosen web map. For example, use the SDK's Eclipse plug-in template project as your starting point as described in Create a simple map application. If you use this template, make sure to remove the code that creates a MapOptions instance and uses it to create a new JMap with a common basemap layer, as you do not want any layers in your map.
    // remove the following lines of code
    MapOptions mapOptions = new MapOptions(MapType.TOPO);
    map = new JMap(mapOptions);
    
    // add the following instead to create an empty JMap
    map = new JMap();
    
    // keep this next line which adds the map to your application window
    window.getContentPane().add(map);
  4. Create a new WebMap instance using the item ID of the web map and the portal it's hosted on. Hover over the class Portal to import the class from the com.esri.core.portal package, and do this again for the WebMap, ensuring you import the class from com.esri.core.portal.
    // ArcGIS Online portal, anonymous access
    Portal portal = new Portal("https://www.arcgis.com", null);
    // web map item ID on the above portal
    String itemID = "a898a3026eb34b23b8e618ea6ba72911";
    
    WebMap webMap = null;
    try {
      // create the WebMap instance
      webMap = WebMap.newInstance(itemID, portal);
    } catch (Exception e) {
      // handle any exception / display to the user
    }
    The details about a particular web map are stored in the JSON text format. The WebMap class supports reading the JSON of a web map stored on a portal such as ArcGIS Online. There are several WebMap.newInstance method overloads you can use, including the suggested overload, which takes an item ID and Portal instance. To use this overload, you must first create the Portal instance from the portal URL and any credentials used to access the portal and item. If you chose a public map on ArcGIS Online, the portal URL is http://www.arcgis.com, and you can pass in null for the credentials, since the map is public and allows anonymous access.
  5. Load the WebMap into your JMap by adding the line of code map.loadWebMap(webMap) as shown in the following example:
    ...
    try {
      // create the WebMap instance
      webMap = WebMap.newInstance(itemID, portal);
      // load the WebMap into the JMap
      map.loadWebMap(webMap);
    } catch (Exception e) {
      // handle any exception / display to the user
    }
    If the web map you chose in step 1 uses a Bing Maps basemap, use the loadWebMap overload, which takes a Bing key.
    map.loadWebMap(webMap, "yourBingKey");
  6. Compile and run your app.
    An example web map displaying in a Java app

Display pop-ups

Some web maps have pop-ups configured when authored on ArcGIS Online. The web map used in this tutorial and displayed above is such a web map. In this section, you'll learn how to display pop-ups in your Java app using the SDK's toolkit and a layer list event listener component.

  1. Add a layer list event listener to your JMap before the code where you load the web map into the JMap.
    map.getLayers().addLayerListEventListener(new LayerListEventListenerAdapter() {
          
      @Override
      public void multipleLayersAdded(LayerEvent event) {
    
      }
          
      @Override
      public void layerAdded(LayerEvent event) {
    
      }
    });

    The loadWebMap method call starts loading all the layers specified by the web map JSON into the JMap. The listener allows you to keep track of what layers are added to your JMap and to handle a specific layer in some way.

  2. Add the toolkit jar to your project. If you used the template project to start this tutorial, right-click your project and choose ArcGIS Tools > Add toolkit jar. If you created your project manually, ensure you are referencing the ArcGIS_Runtime_Java_Toolkit jar located at <installation directory>/sdk/jars.
  3. Create a new InfoPopupOverlay instance, ensuring you import the class from the com.esri.toolkit.overlays package. Add the final modifier to your instance variable, as shown below, so that you can use this overlay inside an inner class.
    final InfoPopupOverlay popupOverlay = new InfoPopupOverlay();

    You'll use the overlay in your listener to display pop-ups when a map feature is clicked.

  4. Add the overlay to your map.
    final InfoPopupOverlay popupOverlay = new InfoPopupOverlay();
    // add overlay to map
    map.addMapOverlay(popupOverlay);
  5. In the listener you created previously, add the following implementations to the multipleLayersAdded and layerAdded methods, respectively:
    ...
    map.addMapOverlay(popupOverlay);
    
    map.getLayers().addLayerListEventListener(new LayerListEventListenerAdapter() {
          
      @Override
      public void multipleLayersAdded(LayerEvent event) {
        for (Layer layer : event.getChangedLayers().values()) {
          if (layer instanceof ArcGISFeatureLayer) {
            popupOverlay.addLayer(layer);
          } else if (layer instanceof GroupLayer) {
            for (Layer groupedLayer: ((GroupLayer) layer).getLayers()) {
              if (groupedLayer instanceof ArcGISFeatureLayer) {
                popupOverlay.addLayer(groupedLayer);
              }
            }
          }
        }
      }
          
      @Override
      public void layerAdded(LayerEvent event) {
        Layer layer = event.getChangedLayer();
        if (layer instanceof ArcGISFeatureLayer) {
          popupOverlay.addLayer(layer);
        } else if (layer instanceof GroupLayer) {
          for (Layer groupedLayer: ((GroupLayer) layer).getLayers()) {
            if (groupedLayer instanceof ArcGISFeatureLayer) {
              popupOverlay.addLayer(groupedLayer);
            }
          }
        }
      }
    });

    In the code above, any instance of the class ArcGISFeatureLayer added to the JMap is added to the InfoPopupOverlay so that pop-ups display when a feature is clicked. Because an ArcGISFeatureLayer can be a sublayer of a group layer, any instance of GroupLayer is checked to see whether it contains an ArcGISFeatureLayer, and if so, that feature layer is added to the pop-up overlay.

  6. Compile and run your app. Click a feature (red or orange circle) to see a pop-up for that feature. The InfoPopupOverlay handles reading the pop-up info contained in the web map and creates a dialog with the relevant information for the clicked features or features.

Display web map bookmarks

When you author a web map on ArcGIS Online, you can bookmark and name map extents, and when you save your web map, the bookmarks are saved as part of the web map. For more information on creating bookmarks in a web map, see Bookmarking places. By following the steps below, you can display these web map bookmarks in your Java app.

  1. First you need a web map that has saved bookmarks. These will be stored in the web map's JSON as "bookmarks". See About authoring web maps and Bookmarking places if you have not previously authored ArcGIS web maps and want to do so for this exercise. You can also use an existing web map that has saved bookmarks.
  2. If the map you're using is different then the map you used in the first part of this tutorial, change the itemID string used in your app to be the ID of the web map containing the bookmarks.
    // ID of a public web map that has bookmarks
    String itemID = "095e264aea1040238de556c923991cd3";

    Ensure your new ID works by running your app and confirming that a map displays matching the map you found on ArcGIS Online. If you're using the ID in the code snippet above, ensure it matches this map on ArcGIS Online.

  3. Now that your web map is displayed, you need to display the bookmarks from the web map in a UI component. The simplest way to do so is to use the ArcGIS Runtime SDK for Java toolkit component called JExtentBookmark. As in the previous section, make sure you've added the toolkit jar to your project (ArcGIS Tools > Add toolkit jar). Add an import statement to your application to use this component as shown in the following example:
    import com.esri.toolkit.bookmarks.JExtentBookmark;
  4. Create an instance of JExtentBookmark using your JMap instance. Right after the line where you create your JMap, add the following line of code, hover over extentBookmarks, and choose the option to make it a field.
    ...
    map = new JMap();
    // create the extent bookmark UI component
    extentBookmarks = new JExtentBookmark(map);
    ...
  5. Populate the bookmarks component with the bookmarks from the web map. Once the JMap displaying your web map is initialized, obtain the bookmarks from the WebMap instance using getBookmarks(), and populate your extent bookmarks component. Below the code added in the previous step, add the following:
    map.addMapEventListener(new MapEventListenerAdapter() {
      @Override
      public void mapReady(MapEvent event) {
        extentBookmarks.addBookmarks(webMap.getBookmarks());
      }
    });

    Press Ctrl-Shift-O to import any unimported classes. Find the line of code where you declared a local variable for the web map: WebMap webMap = null;. Remove this line of code, and instead make webMap an application field, in the same way you did for extentBookmarks.

  6. Add the extent bookmarks component to the UI. Find and replace the line window.getContentPane().add(map); with the following:
    window.getContentPane().add(map, BorderLayout.CENTER);
    window.getContentPane().add(extentBookmarks, BorderLayout.WEST);

    The window or JFrame's content pane has a BorderLayout by default. In these two lines of code, you first add your main component, the map, to the CENTER area of the BorderLayout, where it will take up any extra space not used up by other components. Then you add your extent bookmarks component to the WEST area, where it will display on the left side of your app.

  7. Compile and run your app, ensuring your bookmarks component appears and is automatically populated with bookmarks. Your application should look similar to the following screen shot:

    Web map bookmarks app screen shot

    See the WebMap bookmarks sample in the SDK's sample application viewer for an interactive example.

Use the Portal API

In a more advanced workflow, you can discover web maps programmatically by using the Portal for ArcGIS API to access content.

The main difference is how you create the WebMap instance. In this tutorial, you created a WebMap instance using a WebMap.newInstance method that takes an item ID and portal. When using the Portal API to retrieve web maps from a portal search, construct your WebMap instance using an overload of the WebMap.newInstance method which takes a PortalItem instance as shown in the following example:

PortalItem portalItem = null;
// obtain a PortalItem by querying a portal
...       
WebMap webMap = null;
try {
  // create the WebMap instance
  webMap = WebMap.newInstance(portalItem);
} catch (Exception e) {
  // handle any exception / display to the user
}

See the Portal WebMap search sample in the ArcGIS Runtime for Java sample application viewer, which shows how to query a portal such as ArcGIS Online for web maps.