Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.layers

Class ArcGISMapImageLayer

java.lang.Object
com.esri.arcgisruntime.layers.Layer
com.esri.arcgisruntime.layers.ImageAdjustmentLayer
com.esri.arcgisruntime.layers.ArcGISMapImageLayer
All Implemented Interfaces:
TimeAware, RemoteResource, LayerContent, Loadable
public final class ArcGISMapImageLayer extends ImageAdjustmentLayer implements RemoteResource, TimeAware
A layer that can visualize data from an ArcGIS map service using dynamically generated map images.

An ArcGIS map image layer displays a map from an ArcGIS MapServer REST service endpoint. Each time a request is made to the map server, layers contained in the map are rendered by the server and returned to the client as a single image of the map. While the image itself does not contain information about the features it displays, you can access and control the visual appearance of the layers using the getSublayers() collection.

Functional characteristics

Map images are created and returned by the server on every request, so they show the latest data at the time of the request. You can specify characteristics of the image, such as ImageAdjustmentLayer.getBrightness(), ImageAdjustmentLayer.getContrast(), ImageAdjustmentLayer.getGamma(), and Layer.getOpacity(). If you obtain the associated sublayers of the ArcGISMapImageLayer using the ArcGISMapImageLayer.getMapImageSublayers() property, you can control the sublayer's visibility and its ArcGISSublayer.getDefinitionExpression(). If you want the background color for the map image to be transparent, you must set the getImageFormat() to PNG.

The underlying ServiceFeatureTable, for each map image sublayer or for non-spatial tables used in the service, can be accessed via the getTables() property. These tables can be queried using any valid combination of attribute, spatial, and temporal criteria via the numerous query methods. You can also query for FeatureTable.queryStatisticsAsync(StatisticsQueryParameters) to see summary statistics or to find related features in other tables via the numerous query methods.

This layer supports time-based filtering.

Performance characteristics

The ArcGIS map service creates map images on the fly. This rendering time depends on the amount and complexity of the data in the map. It will typically be slower than fetching the equivalent map as previously rendered and cached tiles via an ArcGISTiledLayer. Because the server renders the map, map image layers require less processing time on the client than similar maps rendered locally.

ArcGIS map image layers are good candidates for showing features that change periodically, or that require filtering by the user. Although rendering occurs on the server, you have access to service feature tables for all sublayers (as well as non-spatial tables and relationships).

More information and reference samples on the ArcGIS developer website:

Since:
100.0.0
See Also:

  • Constructor Details

    • ArcGISMapImageLayer

      public ArcGISMapImageLayer(PortalItem portalItem)
      Creates an ArcGIS map image layer from a PortalItem representing an ArcGIS map service.

      The item's type should be PortalItem.Type.MAP_SERVICE.

      Parameters:
      portalItem - a portal item of type PortalItem.Type.MAP_SERVICE
      Throws:
      IllegalArgumentException - if portalItem is null
      Since:
      100.0.0

    • ArcGISMapImageLayer

      public ArcGISMapImageLayer(String url)
      Creates an ArcGIS map image layer from the specified URI.

      If the specified URI is a map service URL, the MapServer must have "Single Fused Map Cache" set to false in its ArcGIS REST Services Directory. If the specified URI is a portal item URL, the underlying PortalItem is created and can be accessed through Layer.getItem(). See PortalItem.fromJson(String, Portal) for the supported URL formats.

      Parameters:
      url - the URL to the endpoint of an ArcGIS map service or to an ArcGIS map service portal item
      Throws:
      IllegalArgumentException - if the URL is null or empty
      Since:
      100.0.0

  • Method Details

    • copy

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

    • setCredential

      public void setCredential(Credential credential)
      Sets the credential used to authenticate the user with the map service.
      Specified by:
      setCredential in interface RemoteResource
      Parameters:
      credential - the credential used to authenticate the user with the map service.
      Since:
      100.0.0

    • getCredential

      public Credential getCredential()
      Gets the credential used to authenticate the user with the map service.
      Specified by:
      getCredential in interface RemoteResource
      Returns:
      the credential used to authenticate the user with the map service
      Since:
      100.0.0

    • setRequestConfiguration

      public void setRequestConfiguration(RequestConfiguration requestConfiguration)
      Sets the configuration parameters used for sending a network request using this layer object. The global RequestConfiguration is used if no RequestConfiguration is set.
      Specified by:
      setRequestConfiguration in interface RemoteResource
      Parameters:
      requestConfiguration - object containing the parameters to use
      Since:
      100.0.0

    • getRequestConfiguration

      public RequestConfiguration getRequestConfiguration()
      Gets the RequestConfiguration object that contains parameters used when making a request by this layer.
      Specified by:
      getRequestConfiguration in interface RemoteResource
      Returns:
      the RequestConfiguration object or default vales if nothing was set
      Since:
      100.0.0

    • getGeodatabaseVersion

      public String getGeodatabaseVersion()
      Gets the version that this geodatabase is using.
      Returns:
      version of the geodatabase
      Since:
      100.0.0

    • setGeodatabaseVersion

      public void setGeodatabaseVersion(String geodatabaseVersion)
      Sets the version that this geodatabase is using.
      Parameters:
      geodatabaseVersion - the new geodatabase version
      Since:
      100.0.0

    • getUri

      public String getUri()
      The URL to the REST endpoint of an ArcGIS map service.

      The URI is available after the layer has successfully loaded.

      Specified by:
      getUri in interface RemoteResource
      Returns:
      the URL of the map service
      Since:
      100.0.0

    • getImageFormat

      public ArcGISMapImageLayer.ImageFormat getImageFormat()
      Gets the image format used to generate map images on this layer.

      If imageFormat value is ArcGISMapImageLayer.ImageFormat.DEFAULT, the default image format is defined by the service.

      Returns:
      the image format being used to generate images
      Since:
      100.0.0

    • setImageFormat

      public void setImageFormat(ArcGISMapImageLayer.ImageFormat imageFormat)
      Sets the image format used to generate map images on this layer.

      If imageFormat value is ArcGISMapImageLayer.ImageFormat.DEFAULT, the default image format is defined by the service.

      Parameters:
      imageFormat - the image format to use when generating images
      Since:
      100.0.0

    • getMapServiceInfo

      public ArcGISMapServiceInfo getMapServiceInfo()
      Gets the ArcGIS map service information.

      This information is available after the layer has successfully loaded.

      Returns:
      the map service info
      Since:
      100.0.0

    • getSublayers

      public SublayerList getSublayers()
      Gets the sublayers of an ArcGIS map image layer.

      The collection is specific to a layer so you can't reuse a sublayer collection coming from another ArcGISMapImageLayer or ArcGISSublayer. You have to create a new layer collection.

      Returns:
      the sublayers of an ArcGIS map image layer
      Since:
      100.0.0

    • resetSublayers

      public void resetSublayers()
      Resets the sublayers of a map image layer to the default values defined by the service.

      After this call, any changes to the sublayers (either by using an ArcGISMapImageSublayer setter or by changing the sublayer collections) are lost. The sublayer hierarchy returns to its initial state (defined by the service) and image requests to display the layer will no longer use the dynamic layer capabilities of the service. All ArcGISMapImageSublayer objects will be recreated.

      Since:
      100.1.0
      See Also:

    • getRefreshInterval

      public long getRefreshInterval()
      Gets the refresh interval in milliseconds. The refresh interval is the time between automatic layer requests. A value of zero means the layer is never refreshed. The default value is zero.
      Returns:
      the refresh interval in milliseconds
      Since:
      100.1.0

    • setRefreshInterval

      public void setRefreshInterval(long refreshIntervalMilliseconds)
      Sets the refresh interval in milliseconds. The refresh interval is the time between automatic layer requests. A value of zero means the layer is never refreshed. The default value is zero.
      Parameters:
      refreshIntervalMilliseconds - the refresh interval in milliseconds
      Throws:
      IllegalArgumentException - if milliseconds is less than zero
      Since:
      100.1.0

    • getTables

      public List<ServiceFeatureTable> getTables()
      Gets the read-only collection of non-spatial tables in the map image layer.

      The collection is specific to this map image layer. Tables are not loaded by default. You can load a table by calling FeatureTable.loadAsync() or loadTablesAndLayersAsync(). Alternatively, tables are loaded internally when asynchronous operations like query are performed.

      Returns:
      the read-only collection of non-spatial tables in the map image layer
      Since:
      100.3.0

    • loadTablesAndLayersAsync

      public ListenableFuture<Void> loadTablesAndLayersAsync()
      Loads all of the map service's sublayers and non spatial tables.
      Returns:
      a ListenableFuture to load the tables and sublayers asynchronously. Add a listener to the Future to know when the loading is done.
      Since:
      100.3.0

    • getFullTimeExtent

      public TimeExtent getFullTimeExtent()
      Description copied from interface: TimeAware
      Returns the full time extent of the object. Will be null if the object is not time aware.
      Specified by:
      getFullTimeExtent in interface TimeAware
      Returns:
      the time extent, or null if the object is not time aware

    • getTimeInterval

      public TimeValue getTimeInterval()
      Description copied from interface: TimeAware
      Returns the suggested time slider step size for this time aware object. Can be null if no time interval is suggested for this time aware object.
      Specified by:
      getTimeInterval in interface TimeAware
      Returns:
      the time interval, or null if there is no time interval

    • getTimeOffset

      public TimeValue getTimeOffset()
      Description copied from interface: TimeAware
      Returns the time offset applied to this object. The offset is subtracted from the time extent set on the owning GeoView. This allows for data from different periods of time to be compared.
      Specified by:
      getTimeOffset in interface TimeAware
      Returns:
      the time offset, or null if no offset has been set

    • isTimeFilteringEnabled

      public boolean isTimeFilteringEnabled()
      Description copied from interface: TimeAware
      Returns whether or not the object must use the time extent defined on the owning GeoView to filter its data.
      Specified by:
      isTimeFilteringEnabled in interface TimeAware
      Returns:
      true if time filtering is enabled; otherwise false

    • setIsTimeFilteringEnabled

      public void setIsTimeFilteringEnabled(boolean enabled)
      Description copied from interface: TimeAware
      Enables or disables whether the object must use the time extent defined on the owning GeoView to filter its data.
      Specified by:
      setIsTimeFilteringEnabled in interface TimeAware
      Parameters:
      enabled - true to enable time filtering; otherwise false

    • isTimeFilteringSupported

      public boolean isTimeFilteringSupported()
      Description copied from interface: TimeAware
      Returns whether or not the object supports filtering its contents by time values with the extent set on the owning GeoView.
      Specified by:
      isTimeFilteringSupported in interface TimeAware
      Returns:
      true if time filtering is supported; otherwise false

    • setTimeOffset

      public void setTimeOffset(TimeValue timeOffset)
      Description copied from interface: TimeAware
      Sets a time offset for this object. The time offset is subtracted from the time extent set on the owning GeoView. This allows for data from different periods of time to be compared. Can be null if there is no time offset.
      Specified by:
      setTimeOffset in interface TimeAware
      Parameters:
      timeOffset - the time offset, or null if there is no time offset

    • addFullTimeExtentChangedListener

      public void addFullTimeExtentChangedListener(FullTimeExtentChangedListener listener)
      Description copied from interface: TimeAware
      Adds a listener that will fire when there is a change to the full time extent.
      Specified by:
      addFullTimeExtentChangedListener in interface TimeAware
      Parameters:
      listener - the listener to add

    • removeFullTimeExtentChangedListener

      public boolean removeFullTimeExtentChangedListener(FullTimeExtentChangedListener listener)
      Description copied from interface: TimeAware
      Removes a full time extent changed listener.
      Specified by:
      removeFullTimeExtentChangedListener in interface TimeAware
      Parameters:
      listener - the listener to remove
      Returns:
      true if the listener was removed, otherwise false