Package com.esri.arcgisruntime.layers

Class ArcGISMapImageLayer

  • All Implemented Interfaces:
    TimeAware, RemoteResource, LayerContent, Loadable
    public final class ArcGISMapImageLayer
extends ImageAdjustmentLayer
implements RemoteResource, TimeAware
    Displays data from an ArcGIS Map service by using dynamically generated map images.

    ArcGIS map image layer displays maps from an ArcGIS map server. A map service can contain multiple layers, rendered by the server each time a request is made and returned to the client as a single raster image. While the image itself does not contain information about the features it displays, you can get the underlying data (service feature table) for each sublayer. This layer supports time-based filtering.

    Functional characteristics

    Map images are created and returned by the server on every request, so they always show the latest data at the time of the request. Characteristics of the image, such as brightness, contrast, gamma, and opacity can be specified. You can also control the visibility and symbols of sublayers and filter data with layer definition expressions. The spatial reference can be changed from the service's default and the service will re-project each image on the fly.

    The underlying service feature table for each map image sublayer (or for non-spatial tables used in the service) can be accessed. These tables can be queried using any valid combination of attribute, spatial, and temporal criteria. You can also query for summary statistics or to find related features in other tables.

    Performance characteristics

    The map service creates map images on the fly. Rendering time depends on the amount and complexity of the data in the map. This will typically be slower than fetching the equivalent map as pre-rendered tiles. 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 over time, or that require some sort of filtering by the user. Although rendering occurs on the server, the client has access to service feature tables for all sublayers (as well as non-spatial tables and relationships).

    Example for working with data from a ArcGIS Map Image Layer 

     // create a MapImageLayer with dynamically generated map images
 final ArcGISMapImageLayer mapImageLayer = new ArcGISMapImageLayer("http://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer");
 // Add a listener that is invoked when layer loading has completed.
 mapImageLayer.addDoneLoadingListener(() -> {
   if (mapImageLayer.getLoadStatus() == LoadStatus.LOADED) {
     ArcGISMapServiceInfo mapServiceInfo = mapImageLayer.getMapServiceInfo();
     // work with map service info here
   }
 });
 // create an empty map instance
 ArcGISMap map = new ArcGISMap();
 // add map image layer as operational layer
 map.getOperationalLayers().add(mapImageLayer);
 // set the map to be displayed in this view
 mapView.setMap(map);
    The layer is loaded when displayed in a MapView; if using the layer without a MapView, for example reading the map service metadata, call the Layer.loadAsync() method. Use the layer done loading event to determine when the layer is ready, and check the loaded status before using the layer.
    Since:
    100.0.0
    See Also:
    ArcGISMapServiceInfo, Layer, ArcGISSublayer

    • Constructor Detail

      • ArcGISMapImageLayer

        public ArcGISMapImageLayer​(PortalItem portalItem)
        Creates a new ArcGISMapImageLayer based on a map service PortalItem.

        If the portal item argument is not in LoadStatus#LOADED state it will be loaded automatically when this ArcGISMapImageLayer instance is loaded.

        Parameters:
        portalItem - a map service PortalItem
        Throws:
        java.lang.IllegalArgumentException - if portalItem is null
        Since:
        100.0.0

      • ArcGISMapImageLayer

        public ArcGISMapImageLayer​(java.lang.String url)
        Creates a new ArcGISMapImageLayer from a map service or map service portal item at the given URL.

        To use a credential, call setCredential(Credential) after this constructor and before loading or using this layer.

        Parameters:
        url - the map service or portal item URL
        Throws:
        java.lang.IllegalArgumentException - if the URL is null or empty
        Since:
        100.0.0

    • Method Detail

      • 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 java.lang.String getGeodatabaseVersion()
        Gets the version that this geodatabase is using.
        Returns:
        version of the geodatabase
        Since:
        100.0.0

      • setGeodatabaseVersion

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

      • getUri

        public java.lang.String getUri()
        Gets the web address of the map service resource.
        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 being used to generate map images on this layer.
        Returns:
        the image format being used to generate images
        Since:
        100.0.0

      • setImageFormat

        public void setImageFormat​(ArcGISMapImageLayer.ImageFormat imageFormat)
        Sets the image format being used to generate map images on this layer.
        Parameters:
        imageFormat - the image format to use when generating images
        Since:
        100.0.0

      • getMapServiceInfo

        public ArcGISMapServiceInfo getMapServiceInfo()
        Gets the map service info.

        The map service info accesses information about the map image layer for read only use.

        Returns:
        the map service info
        Since:
        100.0.0

      • getSublayers

        public SublayerList getSublayers()
        Gets the sublayers that make up this map image layer.

        The sublayers will only be requested the first time, sequential calls will return the original list of sublayers.

        Returns:
        the sub layers from this 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.

        Since:
        100.1.0
        See Also:
        ArcGISSublayer.getSublayers()

      • 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:
        java.lang.IllegalArgumentException - if milliseconds is less than zero
        Since:
        100.1.0

      • getTables

        public java.util.List<ServiceFeatureTable> getTables()
        Gets a list of tables in the map image layer.

        The collection of tables is specific to this map image layer. Tables are not loaded by default. Tables are loaded internally when asynchronous operations like query are performed. Alternatively, they can be loaded by calling loadTablesAndLayersAsync().

        Returns:
        an unmodifiable list of service feature tables
        Since:
        100.3.0

      • loadTablesAndLayersAsync

        public ListenableFuture<java.lang.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