Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.mapping

Class ArcGISMap

java.lang.Object
com.esri.arcgisruntime.mapping.GeoModel
com.esri.arcgisruntime.mapping.ArcGISMap
All Implemented Interfaces:
JsonSerializable, Loadable
public final class ArcGISMap extends GeoModel implements JsonSerializable
A map is a container for layers. Use a map together with a MapView to display layers of geographic data in 2D.

ArcGISMap contains layers of mapping data and information such as basemaps, popups, renderers, and labels which define the map's capabilities. You can access ArcGISMap content directly or visualize the map in a MapView.

In an MVC architecture, ArcGISMap represents the model and MapView represents the view. ArcGISMap specifies how the geographic data is organized, and MapView renders the data on the screen and allows users to interact with it.

A map can contain a basemap and one or more operational layers:

  • A basemap is a map layer that helps orient the user of the map. Typically it sits behind operational layers and shows roads and parcel boundaries to give context to operational layers. Basemaps can also contain layers which are drawn over the top operational layers such as label layers.
  • An operational layer provides content that is of unique interest to the app and the task at hand, such as data about earthquakes, traffic, or weather. Its content might change frequently.
You can create a map from an existing web map using its URL or PortalItem. Alternatively, you can get a map directly from a MobileMapPackage.getMaps() collection. ArcGISMap properties will be hydrated when the map is loaded.

If you create a new map, the spatial reference of the first layer you add, which is typically the first layer in the Basemap, defines the spatial reference of the entire map,

See Maps 2D for more information about maps.

Since:
100.0.0
See Also:

  • Constructor Details

    • ArcGISMap

      public ArcGISMap()
      Creates an empty ArcGISMap instance. The map will need layers added to it before it can be used.
      Since:
      100.0.0
      See Also:

    • ArcGISMap

      public ArcGISMap(Basemap basemap)
      Creates an ArcGISMap instance which will contain just a Basemap.
      Parameters:
      basemap - the Basemap used with this ArcGISMap
      Throws:
      IllegalArgumentException - if the basemap is null
      Since:
      100.0.0
      See Also:

    • ArcGISMap

      public ArcGISMap(BasemapStyle basemapStyle)
      Creates an ArcGISMap with a BasemapStyle.

      These basemaps are secured and access requires either an ArcGISRuntimeEnvironment.setApiKey(String) or a named user.

      Parameters:
      basemapStyle - a basemap style
      Throws:
      IllegalArgumentException - if the basemapStyle is null
      Since:
      100.10.0

    • ArcGISMap

      public ArcGISMap(PortalItem portalItem)
      Creates a map with a portal item of type PortalItem.Type.WEBMAP.

      The PortalItem automatically loads when the ArcGISMap loads. If the loaded PortalItem is not a portal item of type Type.WEBMAP, the map fails to load.

      Parameters:
      portalItem - a web map PortalItem
      Throws:
      IllegalArgumentException - if the portalItem is null
      Since:
      100.0.0
      See Also:

    • ArcGISMap

      public ArcGISMap(SpatialReference spatialReference)
      Creates a map with the specified spatial reference.
      Parameters:
      spatialReference - a spatial reference object, may be null
      Since:
      100.0.0
      See Also:

    • ArcGISMap

      public ArcGISMap(String webMapUrl)
      Creates a map with the URL to a web map.

      If the specified URL is a portal item URL, the underlying PortalItem is created and can be accessed through GeoModel.getItem(). The URL can be a URL to web map JSON content or the URL of a portal item. Examples of supported URL formats:

      • The web map viewer page, for example: https://www.arcgis.com/apps/mapviewer/index.html?webmap=55ebf90799fa4a3fa57562700a68c405
      • The web map viewer page (classic), for example: https://www.arcgis.com/home/webmap/viewer.html?webmap=55ebf90799fa4a3fa57562700a68c405
      • The web map item details page, for example: https://www.arcgis.com/home/item.html?id=55ebf90799fa4a3fa57562700a68c405
      • The REST sharing API data page, for example: https://www.arcgis.com/sharing/rest/content/items/55ebf90799fa4a3fa57562700a68c405/data
      • The REST sharing API page (with or without the query parameter f=json), for example: https://www.arcgis.com/sharing/rest/content/items/55ebf90799fa4a3fa57562700a68c405?f=json.
      Parameters:
      webMapUrl - URL of a web map on ArcGIS Online or ArcGIS Enterprise portal
      Throws:
      IllegalArgumentException - if the URL is null or empty
      IllegalArgumentException - if the URL does not match the basic URL types
      Since:
      100.0.0
      See Also:

  • Method Details

    • getMinScale

      public double getMinScale()
      Gets the minimum scale of the ArcGISMap.

      A value of zero indicates that there is no minimum scale and the user can zoom out indefinitely. The default value is 0.0.

      Returns:
      the minimum scale of the ArcGISMap; will be zero if the map is not loaded or there is no minimum scale and the user can zoom out indefinitely
      Since:
      100.0.0

    • setMinScale

      public void setMinScale(double minScale)
      Sets the minimum scale of the ArcGISMap.

      A value of zero indicates that there is no minimum scale and the user can zoom out indefinitely. The default value is 0.0.

      Parameters:
      minScale - the minimum scale to set; a value of zero indicates that there is no minimum scale and the user can zoom out indefinitely
      Throws:
      IllegalArgumentException - if minScale is negative
      Since:
      100.0.0

    • getMaxScale

      public double getMaxScale()
      Gets the maximum scale of the ArcGISMap.

      A value of zero indicates that there is no maximum scale and the user can zoom in indefinitely. The default value is 0.0.

      Returns:
      the maximum scale of the ArcGISMap; will be zero if the map is not loaded or there is no maximum scale and the user can zoom in indefinitely
      Since:
      100.0.0

    • setMaxScale

      public void setMaxScale(double maxScale)
      Sets the maximum scale of the ArcGISMap.

      A value of zero indicates that there is no maximum scale and the user can zoom in indefinitely. The default value is 0.0.

      Parameters:
      maxScale - the maximum scale to set; a value of zero indicates that there is no maximum scale and the user can zoom in indefinitely
      Throws:
      IllegalArgumentException - if maxScale is negative
      Since:
      100.0.0

    • getMaxExtent

      public Envelope getMaxExtent()
      Gets the extent that constrains the display of the ArcGISMap to a specific region.

      The max extent is initialized when the map loads or when you set it explicitly. This value limits panning in the MapView to a specific area of the map.

      If the max extent is null when the map loads, or you set it to null, max extent is calculated from the union of the full extent of all basemap layers. If there is no basemap, it is set as the full extent of the map's first operational layer.

      If the GeoModel.getInitialViewpoint() is not set, the max extent is used as the initial viewpoint. If the GeoModel.getInitialViewpoint() is set, but is outside of the max extent, the max extent takes precedence and the display will initially show the max extent.

      Returns:
      the extent that constrains the display of the ArcGISMap to a specific region, or null if none
      Since:
      100.14.0

    • setMaxExtent

      public void setMaxExtent(Envelope maxExtent)
      Sets the extent that constrains the display of the ArcGISMap to a specific region.

      The max extent is initialized when the map loads or when you set it explicitly. This value limits panning in the MapView to a specific area of the map.

      If the max extent is null when the map loads, or you set it to null, max extent is calculated from the union of the full extent of all basemap layers. If there is no basemap, it is set as the full extent of the map's first operational layer.

      If the GeoModel.getInitialViewpoint() is not set, the max extent is used as the initial viewpoint. If the GeoModel.getInitialViewpoint() is set, but is outside of the max extent, the max extent takes precedence and the display will initially show the max extent.

      Parameters:
      maxExtent - the extent that constrains the display of the ArcGISMap to a specific region
      Since:
      100.14.0

    • getReferenceScale

      public double getReferenceScale()
      Gets the reference scale of the ArcGISMap.

      The reference scale is the scale at which feature symbols and text will appear at their authored size. If the viewing scale is different from the reference scale, then the symbology and text graphics will be scaled to keep the same size on the map. Only those layers for which scaleSymbols is true will be scaled. For example, FeatureLayer.isScaleSymbols().

      The default value is 0.0. Zero reference scale means that no reference scale is set and all symbology and text graphics will be drawn at their default screen size.

      Updates to the reference scale will redraw other layers that use the reference scale, and may redraw other layers that depend on them. For example, dynamic labels may need to re-position to avoid overlaps.

      Returns:
      the reference scale of the ArcGISMap; will be zero if the map is not loaded or there is no reference scale
      Since:
      100.5.0

    • setReferenceScale

      public void setReferenceScale(double referenceScale)
      Sets the reference scale of the ArcGISMap.

      The reference scale is the scale at which feature symbols and text will appear at their authored size. If the viewing scale is different from the reference scale, then the symbology and text graphics will be scaled to keep the same size on the map. Only those layers for which scaleSymbols is true will be scaled. For example, FeatureLayer.isScaleSymbols().

      The default value is 0.0. Zero reference scale means that no reference scale is set and all symbology and text graphics will be drawn at their default screen size.

      Updates to the reference scale will redraw other layers that use the reference scale, and may redraw other layers that depend on them. For example, dynamic labels may need to re-position to avoid overlaps.

      Parameters:
      referenceScale - the reference scale to set; a value of zero indicates that there is no reference scale
      Throws:
      IllegalArgumentException - if referenceScale is negative
      Since:
      100.5.0

    • copy

      public ArcGISMap copy()
      Creates a copy of this ArcGISMap instance.
      Returns:
      a deep copy of this ArcGISMap instance, which means that copies of all fields of this map are made including its loading state.
      Since:
      100.0.0

    • fromJson

      public static ArcGISMap fromJson(String json)
      Creates an ArcGISMap instance from a JSON string.
      Parameters:
      json - the JSON representation of an ArcGISMap
      Returns:
      an ArcGISMap instance deserialized from the JSON string
      Throws:
      IllegalArgumentException - if json is null or empty
      Since:
      100.0.0

    • toJson

      public String toJson()
      Serializes this ArcGISMap to a JSON string.
      Specified by:
      toJson in interface JsonSerializable
      Returns:
      the JSON representation of this ArcGISMap
      Since:
      100.0.0

    • getUnknownJson

      public Map<String,Object> getUnknownJson()
      Description copied from interface: JsonSerializable
      Gets unknown data from the source JSON.

      Unknown JSON is a Map of values not defined in the ArcGIS specification used to create this object but found in the source JSON. If the object is written back to JSON, any unknown JSON data is not persisted. The ArcGIS specification may be for a web map, web scene, REST API, and so on.

      Specified by:
      getUnknownJson in interface JsonSerializable
      Returns:
      an unmodifiable Map containing unknown data from the source JSON

    • getUnsupportedJson

      public Map<String,Object> getUnsupportedJson()
      Description copied from interface: JsonSerializable
      Gets unsupported data from the source JSON.

      Unsupported JSON is a Map of values defined in the ArcGIS specification used to create this object but not currently used in this API. If the object is written back to JSON, any unsupported JSON data is persisted. The ArcGIS specification may be from a web map, web scene, REST API, and so on.

      Specified by:
      getUnsupportedJson in interface JsonSerializable
      Returns:
      an unmodifiable Map containing unsupported data from the source JSON

    • getUtilityNetworks

      public ListenableList<UtilityNetwork> getUtilityNetworks()
      Gets a mutable list of utility networks in the map.

      This collection of UtilityNetwork is specific to this map.

      An ArcGISMap created with a web map portal item with utility networks will pre-populate this collection.

      When this ArcGISMap is used to create a UtilityNetwork, the UtilityNetwork that was created will be added to this collection.

      Only a UtilityNetwork that is not loaded may be added to this collection. An attempt to add a UtilityNetwork that is loaded or loading will throw an ArcGISRuntimeException.

      An attempt to add an UtilityNetwork instance that is already in a list will throw a ArcGISRuntimeException error. A different instance of UtilityNetwork that is backed by the same feature server or service geodatabase may be added to a list.

      An attempt to add a null UtilityNetwork to this collection will throw an IllegalArgumentException.

      Returns:
      a mutable list of utility networks in the map. The list may be empty but never null.
      Since:
      100.10.0

    • addBasemapChangedListener

      public void addBasemapChangedListener(ArcGISMap.BasemapChangedListener listener)
      Adds a BasemapChangedListener to this ArcGISMap that gets invoked when the Basemap has changed.

      Adding this listener on the UI thread will cause it to be invoked on the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

      Parameters:
      listener - a BasemapChangedListener that gets invoked when the Basemap has changed
      Throws:
      IllegalArgumentException - if the listener is null
      Since:
      100.0.0

    • removeBasemapChangedListener

      public boolean removeBasemapChangedListener(ArcGISMap.BasemapChangedListener listener)
      Removes a BasemapChangedListener from this ArcGISMap.
      Parameters:
      listener - the BasemapChangedListener to remove
      Returns:
      true if the BasemapChangedListener has been removed, otherwise false
      Throws:
      IllegalArgumentException - if the listener is null
      Since:
      100.0.0

    • saveAsync

      public ListenableFuture<PortalItem> saveAsync(boolean forceSaveToSupportedVersion)
      Executes an asynchronous operation to save any changes that have been made to the map. The map must be associated with a PortalItem object, and must be loaded. The result is a reference to the map's PortalItem object.

      Saving an existing webmap will keep the portal item extent in sync with the initial viewpoint of the map set using the GeoModel.setInitialViewpoint(Viewpoint) method.

      Updates the map content data on the portal and also updates the portal item properties stored on the portal to match those stored within the map's PortalItem object.

      When saving a webmap it is always saved as the currently supported webmap version of the API (see system requirements). This may cause data loss as JsonSerializable.getUnknownJson(), unknown objects (e.g. UnknownLayers) and other properties unknown to the webmap specification (e.g. new layer types or local data paths) are not saved. JsonSerializable.getUnsupportedJson() is maintained and saved in the map as it is known to the webmap specification but not explicitly exposed by this API. This operation includes the forceSaveToSupportedVersion flag which can be used to provide a warning to users that some map data may be lost when the map is saved.

      Parameters:
      forceSaveToSupportedVersion - flag to indicate whether the map should be saved to the supported webmap version that the API supports (see system requirements). This may cause data loss as unknown data is not saved. If true, unknown data will be removed and the map will be saved. If false, the asynchronous operation will fail if the map contains unknown data that will not be saved. This flag can be used to provide a warning to users that some map data may be lost when the map is saved.
      Returns:
      a ListenableFuture for tracking when the operation is done and getting the result; also allows cancellation. Calling get() on the returned future may throw an ExecutionException with its cause set to an exception as follows:
      Throws:
      IllegalStateException - if the map is not loaded or is not associated with a PortalItem object
      ArcGISRuntimeException - if the current LicenseLevel is too low for this operation (LicenseLevel.BASIC or higher is required to save maps to a portal)
      Since:
      100.0.0

    • saveAsAsync

      public ListenableFuture<PortalItem> saveAsAsync(Portal portal, PortalFolder portalFolder, String title, Iterable<String> tags, String description, byte[] thumbnailData, boolean forceSaveToSupportedVersion)
      Executes an asynchronous operation to save this map by creating a new map on the given portal in the given folder. Once completed, the map will be associated with a new PortalItem object. The new item will belong to the user currently signed in to the portal and its access level will be PortalItem.Access.PRIVATE.

      Note that if the map was already associated with a PortalItem object (either because the map was created using a PortalItem or was previously saved), that object will be replaced with a new PortalItem, effectively 'duplicating' the map on the portal.

      When saving a webmap it is always saved as the currently supported webmap version of the API (see system requirements). This may cause data loss as JsonSerializable.getUnknownJson(), unknown objects (e.g. UnknownLayers) and other properties unknown to the webmap specification (e.g. new layer types or local data paths) are not saved. JsonSerializable.getUnsupportedJson() is maintained and saved in the map as it is known to the webmap specification but not explicitly exposed by this API. This operation includes the forceSaveToSupportedVersion flag which can be used to provide a warning to users that some map data may be lost when the map is saved.

      The result is a reference to the map's PortalItem object.

      Saving a map does not automatically include the extent of the current MapView. If you want to save the current extent with the map, then get the GeoView.getCurrentViewpoint(Viewpoint.Type) and pass it to the GeoModel.setInitialViewpoint(Viewpoint) method to ensure the current extent is saved with the map. For example: 

       Viewpoint vp = mapView.getCurrentViewpoint(Viewpoint.Type.BOUNDING_GEOMETRY);
 map.setInitialViewpoint(vp);
      Parameters:
      portal - the portal on which to save the map; must not be null and must not be loaded anonymously; to ensure it's not loaded anonymously, either set a credential on it using Portal.setCredential(Credential) before the portal is loaded, or use the Portal(String, boolean) constructor with loginRequired set to true
      portalFolder - a PortalFolder belonging to the current user in which to save the map, or null to save it in the user's root folder
      title - a title for the map; must not be null or empty
      tags - a list of tags to associate with the map, or null if none
      description - a description for the map, or null if none
      thumbnailData - thumbnail data for the map, or null if none
      forceSaveToSupportedVersion - flag to indicate whether the map should be saved to the supported webmap version that the API supports (see system requirements). This may cause data loss as unknown data is not saved. If true, unknown data will be removed and the map will be saved. If false, the asynchronous operation will fail if the map contains unknown data that will not be saved. This flag can be used to provide a warning to users that some map data may be lost when the map is saved.
      Returns:
      a ListenableFuture for tracking when the operation is done and getting the result; also allows cancellation. Calling get() on the returned future may throw an ExecutionException with its cause set to an exception as follows:
      Throws:
      IllegalArgumentException - if portal or title is null, or title is an empty string
      IllegalStateException - if the map is not loaded
      ArcGISRuntimeException - if the current LicenseLevel is too low for this operation (LicenseLevel.BASIC or higher is required to save maps to a portal)
      Since:
      100.0.0

    • getNamedTraceConfigurationsFromUtilityNetworkAsync

      public ListenableFuture<List<UtilityNamedTraceConfiguration>> getNamedTraceConfigurationsFromUtilityNetworkAsync(UtilityNetwork utilityNetwork)
      Returns a collection of all the UtilityNamedTraceConfiguration objects referenced by UtilityNetwork's map.

      An empty collection is returned if the UtilityNetwork does not belong to the map or if the map does not contain any UtilityNamedTraceConfiguration objects.

      Parameters:
      utilityNetwork - the UtilityNetwork
      Returns:
      a list of the UtilityNamedTraceConfiguration objects referenced by the UtilityNetwork's map
      Throws:
      IllegalArgumentException - if utilityNetwork is null
      Since:
      100.11.0

    • getOfflineSettings

      public OfflineSettings getOfflineSettings()
      Gets the offline settings, configured by the author of an online web map (if appropriate).

      Offline settings optimize the data that is delivered during download and synchronization. For example, they can control feature and attachment delivery or define whether the map's basemap is created using a tile package already on the device.

      This property is null unless the map represents an online web map and the author has configured the offline settings.

      Returns:
      the offline settings or null if the property is not set or the map is not a web map
      Since:
      100.5.0
      See Also:

    • setBackgroundColor

      @Deprecated(since="200.0.0", forRemoval=true) public void setBackgroundColor(Integer color)
      Deprecated, for removal: This API element is subject to removal in a future version.
      as of 200.0.0, replaced by setBackgroundColor(Color)
      Sets the background color of the map.

      This value specifies the color to be displayed behind the map. This color will be displayed in transparent areas of the map and areas where there is no basemap or operational data.

      When a map is set on a MapView, changes to getBackgroundColor() take immediate effect.

      The default value is null. In this case, the MapView.getBackgroundGrid() specifies the background color.

      Parameters:
      color - an Integer representing the color as 0xAARRGGBB, or null for no background color
      Since:
      100.7.0

    • getBackgroundColor

      public Color getBackgroundColor()
      Get the background color of the map.

      This value specifies the color to be displayed behind the map. This color will be displayed in transparent areas of the map and areas where there is no basemap or operational data.

      When a map is set on a MapView, changes to getBackgroundColor() take immediate effect.

      The default value is null. In this case, the MapView.getBackgroundGrid() specifies the background color.

      Returns:
      the background color
      Since:
      200.0.0

    • setBackgroundColor

      public void setBackgroundColor(Color color)
      Set the background color of the map.

      The value determines the color to be displayed behind the map. This color will be displayed in transparent areas of the map as well as areas where there is no basemap or operational data.

      When a map is set on a MapView, changes to the background color will immediately take effect.

      The default value is null. In this case, the MapView.getBackgroundGrid() is used to determine the background color to display.

      Parameters:
      color - the background color
      Since:
      200.0.0