Package com.esri.arcgisruntime.layers

Class WmsLayer

  • All Implemented Interfaces:
    TimeAware, RemoteResource, LayerContent, Loadable
    public final class WmsLayer
extends ImageAdjustmentLayer
implements RemoteResource, TimeAware
    Displays data from a WMS service. The service may be hosted in the cloud on ArcGIS Online, on a third party server, or on-premises with ArcGIS Server.

    Web Map Service (WMS) is an Open Geospatial Consortium (OGC) standard for delivering map images from an online service. WMS layer displays data from a web service that provides maps in the form of server-rendered images. ArcGIS Runtime supports WMS versions 1.1.0, 1.1.1, and 1.3.0. The service may be hosted in the cloud on ArcGIS Online, on a third party server, or on-premises ArcGIS Server.

    Functional characteristics

    A WMS service can contain multiple layers in a hierarchy. A Wms layer can be constructed directly with a URL to a service and the uniquely identifying name of the desired layer. Alternatively, a WmsService can be used to programmatically explore the available layers and allow the user to choose layers at run time.

    The maps provided by a WMS service use predefined symbology defined by the server. As a result, it is not possible to apply custom renderers or to visualize feature selection. WMS layers can have multiple style options. Your app can choose from the available styles.

    Some layers can be marked as opaque, which means that they cover most of the map area and are good candidates for use as a basemap.

    WMS layers support identify and time. They do not support selection or query. Note that due to the nature of WMS, it is not possible to retrieve feature geometry from WMS identify results. WMS layers support custom parameters, which can be specified for the service or an individual layer.

    Performance characteristics

    WMS servers render map images on demand, which can require more server resources than a similar tiled service. WMS requires a service connection at all times.

    Example of creating a WMS layer when the names of the layers of interest are known up-front 

     // Create a WMS layer from the service URL and names of layers of interest
 List<String> layerNames = new ArrayList<>();
 layerNames.add("cbsprovincies2012");
 final WmsLayer wmsLayer = new WmsLayer(
     "http://geodata.nationaalgeoregister.nl/cbsprovincies/ows?SERVICE=WMS&request=Getcapabilities", layerNames);

 // Add the layer to a map;
 // assuming the map is already being viewed, the layer is loaded automatically
 map.getOperationalLayers().add(wmsLayer);
 wmsLayer.addDoneLoadingListener(() -> {
   if (wmsLayer.getLoadStatus() == LoadStatus.LOADED) {
     // work with WMS layer here
   }
 });

    Example of creating a WMS layer when the layers of interest are retrieved from the WMS service: 

     // Create a WMS service and load it
 final WmsService wmsService = new WmsService(
     "http://geodata.nationaalgeoregister.nl/cbsprovincies/ows?SERVICE=WMS&request=Getcapabilities");
 wmsService.loadAsync();
 wmsService.addDoneLoadingListener(() -> {
   if (wmsService.getLoadStatus() == LoadStatus.LOADED) {

     // Create a WMS layer from the WMS layer infos of the service
     final WmsLayer wmsLayer = new WmsLayer(wmsService.getServiceInfo().getLayerInfos());

     // Add the layer to a map;
     // assuming the map is already being viewed, the layer is loaded automatically
     map.getOperationalLayers().add(wmsLayer);
     wmsLayer.addDoneLoadingListener(() -> {
       if (wmsLayer.getLoadStatus() == LoadStatus.LOADED) {
         // Work with WMS layer here
       }
     });
   }
 });

    The layer is loaded when displayed in a MapView or a SceneView; if using the layer without a MapView or a SceneView, 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.2.0
    See Also:
    ImageAdjustmentLayer, Layer, WmsLayerInfo, WmsService, WmsServiceInfo, WmsSublayer

    • Constructor Detail

      • WmsLayer

        public WmsLayer​(String url,
                Iterable<String> layerNames)
        Creates an instance of WmsLayer from a service URL and names of layers.
        Parameters:
        url - the URL of a WMS service
        layerNames - the names of layers of the service to be included in the WmsLayer
        Throws:
        IllegalArgumentException - if url or layerNames is null or empty
        Since:
        100.2.0

      • WmsLayer

        public WmsLayer​(Iterable<WmsLayerInfo> layerInfos)
        Creates an instance of WmsLayer from a collection of WmsLayerInfos.
        Parameters:
        layerInfos - WmsLayerInfos for the layers to be included in the WmsLayer
        Throws:
        IllegalArgumentException - if layerInfos is null or empty
        Since:
        100.2.0

    • Method Detail

      • setCredential

        public void setCredential​(Credential credential)
        Description copied from interface: RemoteResource
        Sets a Credential to be used by the network-enabled resource in the event of an authentication challenge. The default credential is null.

        Only applicable if the resource is secured.

        Specified by:
        setCredential in interface RemoteResource
        Parameters:
        credential - the Credential to be used for authentication

      • getCredential

        public Credential getCredential()
        Description copied from interface: RemoteResource
        Gets the Credential that is set on the network-enabled resource.

        Only applicable if the resource is secured.

        Specified by:
        getCredential in interface RemoteResource
        Returns:
        the Credential, or null if there is none

      • getUri

        public String getUri()
        Gets the URL of the WMS service associated with this WmsLayer.
        Specified by:
        getUri in interface RemoteResource
        Returns:
        the URL of the WMS service
        Since:
        100.2.0

      • getCustomParameters

        public Map<String,​String> getCustomParameters()
        Gets a java.util.Map containing custom parameters that are applied to WMS requests related to this layer. Modify this Map to change the parameters that are used. These values on the WmsLayer will take precedence if used together with a WmsService that specifies different values for the same parameters.
        Returns:
        a modifiable Map; the keys are parameter names and the values are parameter values
        Since:
        100.3.0

      • getLayerNames

        public List<String> getLayerNames()
        Gets the names of the layers included in this WmsLayer.
        Returns:
        an unmodifiable list of layer names
        Since:
        100.2.0

      • getLayerInfos

        public List<WmsLayerInfo> getLayerInfos()
        Gets a list of WmsLayerInfos for the layers included in this WmsLayer.
        Returns:
        an unmodifiable list of WmsLayerInfos; this will be empty if the WmsLayer was created using the WmsLayer(String, Iterable) constructor and has not been loaded yet
        Since:
        100.2.0

      • getPreferredImageFormat

        public ArcGISMapImageLayer.ImageFormat getPreferredImageFormat()
        Gets the preferred image format.
        Returns:
        the preferred image format
        Since:
        100.2.0

      • getSublayers

        public ListenableList<WmsSublayer> getSublayers()
        Gets a list of sublayers. These can be used to fetch legend information to build and display a table of contents.
        Returns:
        an unmodifiable list of sublayers
        Since:
        100.2.0

      • copy

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

      • getRefreshInterval

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

      • setRefreshInterval

        public void setRefreshInterval​(long refreshIntervalMilliseconds)
        Sets the refresh interval in milliseconds. The refresh interval is the time between automatic data requests being sent to the server. 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 refreshIntervalMilliseconds is less than zero
        Since:
        100.2.1

      • getVersion

        public WmsVersion getVersion()
        Gets the WMS version being used by this WmsLayer.
        Returns:
        the WMS version
        Since:
        100.2.1

      • 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