Package com.luciad.wms.client.model

Class ALcdWMSProxy

java.lang.Object
com.luciad.wms.client.model.ALcdWMSProxy
All Implemented Interfaces:
ILcdBounded, ILcdCache, Cloneable
public abstract class ALcdWMSProxy extends Object implements Cloneable, ILcdCache, ILcdBounded
An ALcdWMSProxy is an object that acts as a proxy towards a Web Map Service (WMS).

It is used as domain object inside an ILcdModel decoded by TLcdOGCWMSProxyModelDecoder and has the following roles:

  • Description of the WMS server: it contains the capabilities of the WMS server, which can be retrieved through the method getWMSCapabilities(). These capabilities describe the hierarchy of available layers and styles at the server, service metadata, supported formats, etc. The root of the layer hierarchy can be retrieved through ALcdOGCWMSCapabilities.getWMSRootNamedLayer(int). Each layer is represented by an ALcdWMSNamedLayer object, and optionally contains a set of child layers.
  • Configuration of the WMS client: it describes the configuration at the WMS client, namely
    • the layers that should be included in a map or feature info query,
    • the formats to be used for a map query or feature info query,
    • the desired exception format to be used by the server to encode service exceptions,
    • whether returned maps should use a transparent background color,
    • any additional request parameters that should be used for the connection (e.g., proxy server configuration).
    To configure the layers that should be included in a query, an instance of TLcdWMSStyledNamedLayerWrapper must be added to this proxy for each desired ALcdWMSLayer (see addStyledNamedLayer(TLcdWMSStyledNamedLayerWrapper)).
  • Sending queries to the WMS server: it offers methods to send out a query based on the current configuration of the layers and formats, and retrieve the result as an InputStream, namely

  • Constructor Details

    • ALcdWMSProxy

      public ALcdWMSProxy()

  • Method Details

    • createImage

      public Image createImage(int aWidth, int aHeight, ILcdXYWorldReference aXYWorldReference, ILcdBounds aBounds, Color aBackgroundColor)
      Deprecated.
      Use the method createImageInputStream, to which this default implementation delegates.
      Sends a GetMap request with the given parameters to the WMS server configured in the capabilities (see getWMSCapabilities()), and returns the result as an Image object, if recognized as such. If the result is not an image (e.g., a service exception or an HTTP error), null is returned.

      This method delegates by default to createImageInputStream(int, int, com.luciad.view.ILcdXYWorldReference, com.luciad.shape.ILcdBounds, java.awt.Color).

      Parameters:
      aWidth - the width of the map.
      aHeight - the height of the map.
      aXYWorldReference - the reference in which the map should be returned.
      aBounds - the area of interest, specified in the reference of the map to be returned.
      aBackgroundColor - the background color to use for the map.
      Returns:
      an Image containing the map returned by the WMS, or null if the result is not recognized.

    • createImageInputStream

      public abstract InputStream createImageInputStream(int aWidth, int aHeight, ILcdXYWorldReference aXYWorldReference, ILcdBounds aBounds, Color aBackgroundColor) throws IOException
      Deprecated.
      use createImageInputStream(TLcdWMSGetMapContext) instead
      Sends a GetMap request with the given parameters to the WMS configured in the capabilities (see getWMSCapabilities()), and returns the result as an InputStream object.
      Parameters:
      aWidth - the width of the map.
      aHeight - the height of the map.
      aXYWorldReference - the reference in which the map should be returned.
      aBounds - the area of interest, specified in the reference of the map to be returned.
      aBackgroundColor - the background color to use for the map.
      Returns:
      an InputStream containing the result of a WMS GetMap request with the given parameters.
      Throws:
      TLcdOGCWMSServiceException - when the server sends a service exception report.
      TLcdOGCWMSHttpException - when a HTTP error is received.
      TLcdOGCWMSException - in all other cases (e.g. incorrect request properties, unrecognized result of the server, ...).
      IOException

    • createImageInputStream

      public abstract InputStream createImageInputStream(TLcdWMSGetMapContext aGetMapContext) throws IOException
      Sends a GetMap request with the given parameters to the WMS configured in the capabilities (see getWMSCapabilities()), and returns the result as an InputStream object.
      Parameters:
      aGetMapContext - the GetMap context
      Returns:
      an InputStream containing the result of a WMS GetMap request with the given parameters.
      Throws:
      TLcdOGCWMSServiceException - when the server sends a service exception report.
      TLcdOGCWMSHttpException - when a HTTP error is received.
      TLcdOGCWMSException - in all other cases (e.g. incorrect request properties, unrecognized result of the server, ...).
      IOException

    • createFeatureInfoInputStream

      public abstract InputStream createFeatureInfoInputStream(int aWidth, int aHeight, ILcdXYWorldReference aXYWorldReference, ILcdBounds aBounds, Color aBackgroundColor, int aX, int aY, int aFeatureCount) throws IOException
      Deprecated.
      use createFeatureInfoInputStream(TLcdWMSGetFeatureInfoContext, TLcdWMSGetFeatureInfoParameters) instead
      Sends a GetFeatureInfo request with the given parameters to the WMS configured in the capabilities (see getWMSCapabilities()), and returns the result as an InputStream object.
      Parameters:
      aWidth - the width of the map of interest.
      aHeight - the height of the map of interest.
      aXYWorldReference - the reference in which the map should be generated.
      aBounds - the area of interest, specified in the reference of the generated map.
      aBackgroundColor - the background color to use for the map (note: the result of a GetFeatureInfo request can also be a map with the feature painted selected and/or labeled, instead of just textual information).
      aX - the x coordinate in pixels of the point of interest.
      aY - the y coordinate in pixels of the point of interest.
      aFeatureCount - the maximum number of features per layer for which feature information shall be returned. If other than a positive integer, the default value 1 will be used, following the WMS specification.
      Returns:
      an InputStream containing the result of a WMS GetFeatureInfo request with the given parameters.
      Throws:
      TLcdOGCWMSServiceException - when the server sends a service exception report.
      TLcdOGCWMSHttpException - when a HTTP error is received.
      TLcdOGCWMSException - in all other cases (e.g. incorrect request properties, unrecognized result of the server, ...).
      IOException

    • createFeatureInfoInputStream

      public abstract InputStream createFeatureInfoInputStream(TLcdWMSGetFeatureInfoContext aGetFeatureInfoContext, TLcdWMSGetFeatureInfoParameters aGetFeatureInfoParameters) throws IOException

      Sends a GetFeatureInfo request with the given parameters to the WMS configured in the capabilities (see getWMSCapabilities()), and returns the result as an InputStream object. It is possible to specify additional query parameters using the given TLcdWMSGetFeatureInfoParameters object.

      When the given TLcdWMSGetFeatureInfoParameters object doesn't specify a certain parameter, a default parameter is used. For example, when not specifying a feature info format, the feature info format set on this object will be used. When not specifying a set of layers to query, all layers will be queried.

      Parameters:
      aGetFeatureInfoContext - The GetFeatureInfo context
      aGetFeatureInfoParameters - The (optional) GetFeatureInfo parameters. Should not be null.
      Returns:
      an InputStream containing the result of a WMS GetFeatureInfo request with the given parameters.
      Throws:
      TLcdOGCWMSServiceException - when the server sends a service exception report.
      TLcdOGCWMSHttpException - when a HTTP error is received.
      TLcdOGCWMSException - in all other cases (e.g. incorrect request properties, unrecognized result of the server, ...).
      IOException

    • getMapFormat

      public String getMapFormat()
      Returns the map format value that is used when sending GetMap requests to the WMS. Its value is one of the supported map formats (specified by its MIME-type).
      Returns:
      the value of the mapFormat property.
      See Also:

    • setMapFormat

      public void setMapFormat(String aMapFormat)
      Sets the map format value to be used when sending GetMap requests to the WMS. Its value has to be one of the map formats returned by ALcdOGCWMSCapabilities.getSupportedMapFormat(int).
      Parameters:
      aMapFormat - the value of the map format property.
      See Also:

    • getFeatureInfoFormat

      public String getFeatureInfoFormat()
      Returns the feature info format value that is used when sending GetFeatureInfo requests to the WMS. Its value is one of the supported feature info formats (specified by its MIME-type).
      Returns:
      the value of the mapFormat property.
      See Also:

    • setFeatureInfoFormat

      public void setFeatureInfoFormat(String aFeatureInfoFormat)
      Sets the feature info format value to be used when sending GetFeatureInfo requests to the WMS. Its value has to be one of the feature info formats returned by ALcdOGCWMSCapabilities.getSupportedFeatureInfoFormat(int).
      Parameters:
      aFeatureInfoFormat - the value of the feature info format property.
      See Also:

    • getExceptionFormat

      public String getExceptionFormat()
      Returns the exception format value that is used by the WMS to encode service exception reports. Its value is one of the supported exception formats or null for the default.
      Returns:
      the value of the exception format property.
      See Also:

    • setExceptionFormat

      public void setExceptionFormat(String aExceptionFormat)
      Sets the exception format value to be used by the WMS to encode service exception reports. Its value has to be one of the exception formats returned by ALcdOGCWMSCapabilities.getSupportedExceptionFormat(int) or null for the default exception format.
      Parameters:
      aExceptionFormat - the value of the exception format property.
      See Also:

    • getSupportedMapFormatCount

      public abstract int getSupportedMapFormatCount()
      Returns the number of map formats supported by the WMS. This is equivalent with getWMSCapabilities().getSupportedMapFormatCount().
      Returns:
      the number of map formats supported by the WMS.

    • getSupportedMapFormat

      public abstract String getSupportedMapFormat(int aIndex) throws IndexOutOfBoundsException
      Returns the supported map format at the given index. The format is specified by its MIME-type. This is equivalent with getWMSCapabilities().getSupportedMapFormat(int).
      Parameters:
      aIndex - the index of the map format to return.
      Returns:
      the supported map format at a given index.
      Throws:
      IndexOutOfBoundsException - in case of an invalid index.

    • getWMSRootNamedLayerCount

      public abstract int getWMSRootNamedLayerCount()
      Returns the number of top level ALcdWMSNamedLayer instances. This is equivalent with getWMSCapabilities().getWMSRootNamedLayerCount().
      Returns:
      the number of top level ALcdWMSNamedLayer instances.

    • getWMSRootNamedLayer

      public abstract ALcdWMSNamedLayer getWMSRootNamedLayer(int aIndex) throws IndexOutOfBoundsException
      Returns the top level layer at a given index. This is equivalent with getWMSCapabilities().getWMSRootNamedLayer(int).
      Parameters:
      aIndex - the index of the top level layer.
      Returns:
      the top level layer at a given index.
      Throws:
      IndexOutOfBoundsException - if the index is out of bounds.

    • addStyledNamedLayer

      public abstract void addStyledNamedLayer(TLcdWMSStyledNamedLayerWrapper aStyledNamedLayer)
      Adds a wrapper class for a named layer having a style to the list of layers to request from the WMS. Only wrapper instances having a visible state true are requested from the WMS.
      Parameters:
      aStyledNamedLayer - the styled named layer.

    • getStyledNamedLayerCount

      public abstract int getStyledNamedLayerCount()
      Returns the number of styled named layer objects within the request to the WMS.
      Returns:
      the number of styled named layer objects within the request to the WMS.

    • getStyledNamedLayer

      public abstract TLcdWMSStyledNamedLayerWrapper getStyledNamedLayer(int aIndex) throws IndexOutOfBoundsException
      Returns the TLcdWMSStyledNamedLayerWrapper at an index.
      Parameters:
      aIndex - the index of the TLcdWMSStyledNamedLayerWrapper.
      Returns:
      the TLcdWMSStyledNamedLayerWrapper at an index.
      Throws:
      IndexOutOfBoundsException - in case of an invalid index value.

    • moveStyledNamedLayer

      public abstract void moveStyledNamedLayer(TLcdWMSStyledNamedLayerWrapper aStyledNamedLayer, int aToIndex) throws IndexOutOfBoundsException, NoSuchElementException
      Moves the TLcdWMSStyledNamedLayerWrapper from its current position to another specified index.
      Parameters:
      aStyledNamedLayer - the TLcdWMSStyledNamedLayerWrapper to move.
      aToIndex - the index to move to.
      Throws:
      IndexOutOfBoundsException - in case of an invalid index value.
      NoSuchElementException - if the TLcdWMSStyledNamedLayerWrapper does not exists within the list.

    • removeStyledNamedLayer

      public abstract void removeStyledNamedLayer(int aIndex) throws IndexOutOfBoundsException
      Removes the TLcdWMSStyledNamedLayerWrapper at an index.
      Parameters:
      aIndex - the index of the TLcdWMSStyledNamedLayerWrapper to remove.
      Throws:
      IndexOutOfBoundsException - in case of an invalid index value.

    • clearStyledNamedLayers

      public abstract void clearStyledNamedLayers()
      Clears all the TLcdWMSStyledNamedLayerWrappers.

    • setStyledLayerDescriptor

      public void setStyledLayerDescriptor(TLcdSLDStyledLayerDescriptor aSLD)
      Sets a Styled Layer Descriptor (SLD) to send along with requests. The specified SLD will be embedded as XML in the request.

      Another approach to configure an SLD is to specify an URL that points to the SLD. This is possible through the method setStyledLayerDescriptorURL(java.net.URL).

      Only one SLD can be specified at a given time. Setting an SLD with this method therefore overrides any configured SLD URL (see getStyledLayerDescriptorURL()) and vice versa.

      Parameters:
      aSLD - A valid SLD.
      See Also:

    • getStyledLayerDescriptor

      public TLcdSLDStyledLayerDescriptor getStyledLayerDescriptor()
      Returns the Styled Layer Descriptor (SLD) which will be sent along with requests. By default, null is returned.
      Returns:
      an SLD or null if no SLD has been specified.

    • setStyledLayerDescriptorURL

      public void setStyledLayerDescriptorURL(URL aURL)
      Sets an URL pointing to a valid Styled Layer Descriptor (SLD), to send along with requests. The URL will be included in the request, not the SLD itself. The server therefore needs to be able to access the URL, in order to use the SLD.

      Another approach to configure an SLD is to set an SLD domain object that will be embedded in the request itself. This is possible through the method setStyledLayerDescriptor(com.luciad.wms.sld.model.TLcdSLDStyledLayerDescriptor).

      Only one SLD can be specified at a given time. Setting a link to an SLD with this method therefore overrides any configured SLD domain object (see getStyledLayerDescriptor()) and vice versa.

      Parameters:
      aURL - A URL which points to a valid SLD.
      See Also:

    • getStyledLayerDescriptorURL

      public URL getStyledLayerDescriptorURL()
      Return the URL pointing to a valid Styled Layer Descriptor (SLD), which will be sent along with requests. By default, null is returned.
      Returns:
      an URL pointing to an SLD or null if no URL has been specified.

    • getNamedLayers

      public final List<ALcdWMSNamedLayer> getNamedLayers(boolean aOnlyVisible, boolean aOnlyQueryable)

      This method returns a list of named layers that are registered on this proxy object. The returned list contains:

      Parameters:
      aOnlyVisible - true to only return visible named layers.
      aOnlyQueryable - true to only return queryable named layer, i.e. layers for which GetFeatureInfo requests are enabled.
      Returns:
      a list of named layers that are registered on this proxy object, or an empty list if no layers are found never null.
      Since:
      2016.1

    • addDimension

      public void addDimension(TLcdOGCWMSDimensionWrapper aDimension)
      Adds a wrapper class for a dimension having an extent to the list of dimensions to be used in the request.
      Parameters:
      aDimension - the dimension with the extent.

    • getDimensionCount

      public int getDimensionCount()
      Returns the number of dimension objects within the request to the WMS.
      Returns:
      the number of dimension objects within the request to the WMS.

    • getDimension

      public TLcdOGCWMSDimensionWrapper getDimension(int aIndex) throws IndexOutOfBoundsException
      Returns the TLcdOGCWMSDimensionWrapper at the specified index.
      Parameters:
      aIndex - the index of the TLcdOGCWMSDimensionWrapper.
      Returns:
      the TLcdOGCWMSDimensionWrapper at the specified index.
      Throws:
      IndexOutOfBoundsException - in case of an invalid index value.

    • removeDimension

      public void removeDimension(int aIndex)
      Removes the TLcdOGCWMSDimensionWrapper at the specified index.
      Parameters:
      aIndex - the index of the TLcdOGCWMSDimensionWrapper to remove.
      Throws:
      IndexOutOfBoundsException - in case of an invalid index value.

    • clearDimensions

      public void clearDimensions()
      Clears all the TLcdOGCWMSDimensionWrappers.

    • setBackgroundImageTransparent

      public void setBackgroundImageTransparent(boolean aTransparent)
      Sets if the WMS should return an image whose background is transparent. For this to be useful the requested map format should be capable of representing a transparent background.
      Parameters:
      aTransparent - the new transparent property value.
      See Also:

    • isBackgroundImageTransparent

      public boolean isBackgroundImageTransparent()
      Returns if the WMS is request to return an image with a transparent background.
      Returns:
      if the WMS is request to return an image with a transparent background.
      See Also:

    • setPixelSize

      public void setPixelSize(double aPixelSize)
      Sets the pixel size that should be passed to the WMS server. If the WMS server supports the PIXELSIZE parameter, it can take it into account when evaluation scale ranges.
      Parameters:
      aPixelSize - The size of a pixel on the client screen, in mm. Should be larger than 0.

    • getPixelSize

      public double getPixelSize()
      Returns the configured pixel size.
      Returns:
      The pixel size in mm. The default value is calculated based on the resolution of the client screen.
      See Also:

    • putAdditionalParameter

      public abstract void putAdditionalParameter(String aParameterName, String aParameterValue) throws IllegalArgumentException
      Sets an additional parameter for connecting to the WMS.
      Parameters:
      aParameterName - the name of the parameter.
      aParameterValue - the corresponding value.
      Throws:
      IllegalArgumentException - if the parameter name is illegal.

    • removeAdditionalParameter

      public abstract void removeAdditionalParameter(String aParameterName)
      Removes the additional parameter with the given name.
      Parameters:
      aParameterName - the name of the parameter to be removed.

    • isSupportedXYworldReference

      public abstract boolean isSupportedXYworldReference(ILcdXYWorldReference aXYWorldReference, ALcdWMSNamedLayer aWMSNamedLayer)
      Tests if the given ILcdXYWorldReference is supported for the given layer.
      Parameters:
      aXYWorldReference - the world reference to test.
      aWMSNamedLayer - the named layer to check against.
      Returns:
      true if the given ILcdXYWorldReference is supported for the given layer.

    • getWMSCapabilities

      public abstract ALcdOGCWMSCapabilities getWMSCapabilities()
      Returns an ALcdOGCWMSCapabilities instance that contains the capabilities of the WMS.
      Returns:
      an ALcdOGCWMSService instance that contains the capabilities of the WMS.

    • isCacheImage

      public abstract boolean isCacheImage()
      Returns whether the images returned by the WMS are cached.
      Returns:
      True if the images returned by the WMS are cached.

    • setCacheImage

      public abstract void setCacheImage(boolean aCacheImage)
      Sets whether the images returned by the WMS should be cached. Note that image caching improves the performance but also requires more memory.

      Implementations of this class are recommended to take into account this property.

      Parameters:
      aCacheImage - the new image caching property value.

    • getExceptionHandler

      public ILcdExceptionHandler getExceptionHandler()
      Returns the exception handler of this ALcdWMSProxy
      Returns:
      The exception handler set by setExceptionHandler, null if none has been set.

    • setExceptionHandler

      public void setExceptionHandler(ILcdExceptionHandler aExceptionHandler)
      Sets the exception handler which is to be used by this proxy. By default, it is set to null.
      Parameters:
      aExceptionHandler - A valid exception handler, or null to remove the current exception handler.

    • isInvertXYForEPSG4326

      public boolean isInvertXYForEPSG4326()
      Returns true if the bounding box coordinates should be inverted in case the world reference of the request is EPSG:4326 and the WMS version is 1.3.0. This means that instead of x=lon and y=lat, x=lat and y=lon will be used.
      Returns:
      True if coordinates are inverted for EPSG:4326.

    • setInvertXYForEPSG4326

      public void setInvertXYForEPSG4326(boolean aInvertXYForEPSG4326)
      Sets whether the bounding box coordinates should be inverted in case the world reference of the request is EPSG:4326 and the WMS version is 1.3.0. This means that instead of x=lon and y=lat, x=lat and y=lon will be used.

      For WMS version 1.1.1, the order is defined as x=lon, y=lat. In version 1.3.0 it was decided that the order should be consistent with the order defined in the EPSG:4326 reference which is lat/lon. Consequently, some WMS 1.3.0 servers have changed their interpretation of EPSG:4326 coordinates, while others sticked to the old (WMS 1.1.1) interpretation.

      Also note that EPSG:4326 is officially deprecated, so this problem can be avoided if the server supports different reference systems.

      By default this is set to false.

      Parameters:
      aInvertXYForEPSG4326 - True if coordinates should be inverted for EPSG:4326 and WMS 1.3.0.

    • getBounds

      public ILcdBounds getBounds()
      Description copied from interface: ILcdBounded
      Returns the ILcdBounds by which the geometry of this ILcdBounded object is bounded.

      If the geometry does not allow retrieving valid bounds (for example a polyline with 0 points) the return value is unspecified. It is highly recommended to return an undefined bounds. You can create undefined bounds using the default constructors of TLcdLonLatBounds or TLcdXYBounds.

      Specified by:
      getBounds in interface ILcdBounded
      Returns:
      the ILcdBounds by which the geometry of this ILcdBounded object is bounded.

    • insertIntoCache

      public void insertIntoCache(Object aKey, Object aObject)
      Description copied from interface: ILcdCache
      Inserts a cache Object corresponding to the given key Object.
      Specified by:
      insertIntoCache in interface ILcdCache
      Parameters:
      aKey - the key Object that will be used to identify the Object. The key must therefore be a unique identifier, typically the caller itself: insertIntoCache(this, ...).
      aObject - the Object to be cached.

    • getCachedObject

      public Object getCachedObject(Object aKey)
      Description copied from interface: ILcdCache
      Looks up and returns the cached Object corresponding to the given key.
      Specified by:
      getCachedObject in interface ILcdCache
      Parameters:
      aKey - the key Object that was used for storing the cache Object.
      Returns:
      the cached Object, or null if there is no Object corresponding to the given key.

    • removeCachedObject

      public Object removeCachedObject(Object aKey)
      Description copied from interface: ILcdCache
      Looks up and removes the cached Object corresponding to the given key.
      Specified by:
      removeCachedObject in interface ILcdCache
      Parameters:
      aKey - the key Object that was used for storing the cache Object.
      Returns:
      the cached Object, or null if there was no Object corresponding to the given key.

    • clearCache

      public void clearCache()
      Description copied from interface: ILcdCache
      Clears the cache.
      Specified by:
      clearCache in interface ILcdCache

    • findWMSNamedLayer

      public final ALcdWMSNamedLayer findWMSNamedLayer(String aNamedLayerName)

      Returns the WMS layer from the capabilities for which the unique layer name equals the given name.

      Parameters:
      aNamedLayerName - The name of the searched WMS named layer
      Returns:
      the ALcdWMSNamedLayer from the WMS capabilities with name aNamedLayerName, or null when no such layer can be found.

    • clone

      public Object clone()
      Creates and returns a shallow copy of this object.
      Overrides:
      clone in class Object

    • toDataSource

      public static TLcdWMSDataSource toDataSource(ALcdWMSProxy aWMSProxy)
      Converts the settings configured in the {@link ALcdWMSProxy WMS proxy} object into a WMS data source representation.

      The following settings are taken into account:

      • The server URI.
      • The chosen map format.
      • The selected layers along with their selected layer style, visibility and participation within feature info requests.
      • The transparency of the image background.
      • If the coordinates are inverted for EPSG:4326
      • The {@link TLcdSLDStyledLayerDescriptor} styled layer descriptor.
      Parameters:
      aWMSProxy - the WMS proxy object.
      Returns:
      the WMS data source representation.
      Since:
      2017.0