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. This API 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:
  • Constructor Details

    • WmsLayer

      public WmsLayer(PortalItem portalItem)
      Creates a WMS layer object from a PortalItem.
      Parameters:
      portalItem - a PortalItem
      Throws:
      NullPointerException - if portalItem is null
      Since:
      200.1.0
      See Also:
    • 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 Details

    • 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
    • setRequestConfiguration

      public void setRequestConfiguration(RequestConfiguration requestConfiguration)
      Description copied from interface: RemoteResource
      Sets the RequestConfiguration used to modify the parameters of network requests made by this RemoteResource. If not set, the global RequestConfiguration will be used (see RequestConfiguration.getGlobalRequestConfiguration()).
      Specified by:
      setRequestConfiguration in interface RemoteResource
      Parameters:
      requestConfiguration - the RequestConfiguration used to modify network requests
    • getRequestConfiguration

      public RequestConfiguration getRequestConfiguration()
      Description copied from interface: RemoteResource
      Gets the RequestConfiguration used to modify the parameters of network requests made by this RemoteResource.
      Specified by:
      getRequestConfiguration in interface RemoteResource
      Returns:
      the RequestConfiguration used to modify network requests
    • 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
    • setPreferredImageFormat

      public void setPreferredImageFormat(ArcGISMapImageLayer.ImageFormat imageFormat)
      Sets the preferred image format.
      Parameters:
      imageFormat - the preferred image format
      Throws:
      IllegalArgumentException - if imageFormat is null
      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.

      This API supports the following WMS versions: 1.3.0, 1.1.1, and 1.1.0. By default this value is the latest supported WMS version.

      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
    • 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