Package com.luciad.wms.client.model

Class TLcdOGCWMSProxyModelDecoder

java.lang.Object
com.luciad.wms.client.model.TLcdOGCWMSProxyModelDecoder
All Implemented Interfaces:
ILcdDataSourceModelDecoder, ILcdModelDecoder
@LcdService(service=ILcdModelDecoder.class, priority=20000) public class TLcdOGCWMSProxyModelDecoder extends Object implements ILcdModelDecoder, ILcdDataSourceModelDecoder
An ILcdModelDecoder implementation that allows to access a WMS server and retrieve data from it.

Input

  • An instance of TLcdWMSDataSource, containing a WMS base URL and one or more WMS layer identifiers.
  • A String referring to the WMS base URL.
  • A String referring to the WMS base URL and a layer identifier, specified as a data=layerName key/value pair.

Supported transfer protocols

  • http
  • https

Model structure

The decode(String) and decodeSource(com.luciad.model.ILcdDataSource) methods returns an ILcdModel containing one ALcdWMSProxy element. This element can be used to access the capabilities of the OGC WMS server, and to configure the layer data to be retrieved (if not yet set through the input supplied to this decoder).

The returned model is also an ILcdMultiDimensionalModel, with support for OGC WMS dimensions time, elevation, depth and altitude. If a WMS layer is registered on the ALcdWMSProxy that defines one of more of these dimensions, they are automatically picked up by the model.

Model descriptor

All models returned by this decoder have a TLcdWMSProxyModelDescriptor.

Model reference

All models returned by this model decoder have WGS84 as reference. The actual model reference that is best used for requesting images from the WMS depends on the WMS layers that are configured within the ALcdWMSProxy object.

Model elements

The model contains a single ALcdWMSProxy object. This object can be configured for the actual WMS layers one is interested in. When the model is decoded just using a URL the ALcdWMSProxy is configured with the first WMS layer found in the capabilities. This behavior can be switched off by passing an argument within the constructor.

Thread safety

  • The decoding of models is thread-safe, as long as no properties are changed during the decoding.
  • The decoded models are thread-safe for read access.

Sample code

Decoding a WMS data source:

    String serverURL = "https://sampleservices.luciad.com/wms";
    String wmsLayerName = "cities";

    //Create the data source
    TLcdWMSDataSource dataSource = TLcdWMSDataSource.newBuilder()
                                                    .uri(serverURL)
                                                    .addLayer(wmsLayerName)
                                                    .build();

    //Decode the model
    ILcdModelDecoder decoder = new TLcdOGCWMSProxyModelDecoder();
    ILcdModel model = decoder.decodeSource(dataSource);

Decoding a string containing the server URL and WMS layer

    String serverURL = "https://sampleservices.luciad.com/wms";
    String wmsLayerName = "cities";

    //Concat the url and layer name to a single string
    String sourceName = String.format("%s?data=%s", serverURL, wmsLayerName);

    //Decode the model
    ILcdModelDecoder decoder = new TLcdOGCWMSProxyModelDecoder();
    ILcdModel model = decoder.decode(sourceName);
See Also:

  • Constructor Details

    • TLcdOGCWMSProxyModelDecoder

      public TLcdOGCWMSProxyModelDecoder()
      Creates a new TLcdOGCWMSProxyModelDecoder instance.

    • TLcdOGCWMSProxyModelDecoder

      public TLcdOGCWMSProxyModelDecoder(TLcdDataModel[] aSLDDataModels)
      Creates a new TLcdOGCWMSProxyModelDecoder instance, configured with the given SLD extension data models.

      SLD extension data models are needed if the client wants to submit an SLD to the WMS that uses an extension of the OGC SLD specification. For instance, if a custom symbolizer is introduced to address specific styling requirements. The data models of such extensions are needed to be able to encode any configured SLD (see ALcdWMSProxy.setStyledLayerDescriptor(com.luciad.wms.sld.model.TLcdSLDStyledLayerDescriptor)) to XML, for embedding in requests.

      Parameters:
      aSLDDataModels - a list of SLD extension data models

    • TLcdOGCWMSProxyModelDecoder

      public TLcdOGCWMSProxyModelDecoder(ILcdOWSTransport aTransport, TLcdDataModel[] aSLDDataModels)
      Creates a new TLcdOGCWMSProxyModelDecoder instance, configured with the given transport and SLD extension data models.

      SLD extension data models are needed if the client wants to submit an SLD to the WMS that uses an extension of the OGC SLD specification. For instance, if a custom symbolizer is introduced to address specific styling requirements. The data models of such extensions are needed to be able to encode any configured SLD (see ALcdWMSProxy.setStyledLayerDescriptor(com.luciad.wms.sld.model.TLcdSLDStyledLayerDescriptor)) to XML, for embedding in requests.

      Parameters:
      aTransport - The transport. Must not be null. The transport will be used when decoding the model, except when you call the decode(TLcdWMSClient) method directly.
      aSLDDataModels - a list of SLD extension data models. Use null or an empty array when no extensions are needed.
      Since:
      2018.0

  • Method Details

    • getDisplayName

      public String getDisplayName()
      Description copied from interface: ILcdModelDecoder
      Returns a short, displayable name for the format that is decoded by this ILcdModelDecoder.
      Specified by:
      getDisplayName in interface ILcdModelDecoder
      Returns:
      the displayable name of this ILcdModelDecoder.

    • setRequestProperty

      public void setRequestProperty(String aKey, String aValue)
      Sets the general request property. If a property with the key already exists, overwrite its value with the new value.
      Parameters:
      aKey - the keyword by which the request is known (e.g., "accept").
      aValue - the value associated with it.
      See Also:

    • setEntityLocation

      public void setEntityLocation(String aSystemEntity, URL aEntityURL)
      Sets the URL to be used for an entity defined in the WMS capabilities document provided by a server. Multiple mappings can be provided, but only one location per entity. If no locations are specified, the original entity locations defined in the XML document are used. If a location for an entity already exists, it is replaced with the new location. By specifying null as location for an entity, a previously specified location can be removed.

      A typical example of an entity definition in an XML document is a reference to a DTD or XML Schema. By using this method, one can replace such a reference with a reference to a locally stored copy of the DTD or XML Schema.

      Parameters:
      aSystemEntity - The entity to be relocated.
      aEntityURL - The URL to be used for a given entity.

    • setValidating

      public void setValidating(boolean aValidating)
      Specifies whether XML validation (DTD and XML Schema) is enabled for the WMS capabilities document provided by a server.

      By default, this value is set to false.

      Parameters:
      aValidating - Whether XML validation should be enabled.

    • isValidating

      public boolean isValidating()
      Returns whether XML validation is enabled for the XML capabilities document provided by a server. By default, this value is set to false.
      Returns:
      True if XML validation is enabled.

    • isUseEmptyProxyForUrlOnly

      public boolean isUseEmptyProxyForUrlOnly()
      Returns whether the decoder returns a model containing an empty wms proxy object. The default value is false. When decoding using a URL only the model returned by the decoder contains a wms proxy which is configured with one WMS layer such that you get a proper visualization of the WMS layer. When the value is true the wms proxy object within the model is not configured with any of the layers served by the WMS service. In this case you need to configure the layers you want yourself or nothing will be displayed on the map for this model.
      Returns:
      whether the decoder returns a model containing an empty wms proxy object.
      Since:
      2021.0

    • setUseEmptyProxyForUrlOnly

      public void setUseEmptyProxyForUrlOnly(boolean aUseEmptyProxyForUrlOnly)
      Sets the new value for how the model is constructed in case only a URL is provided.
      Parameters:
      aUseEmptyProxyForUrlOnly - the new value for how the model is constructed in case only a URL is provided.
      Since:
      2021.0
      See Also:

    • addAdditionalXYWorldReferenceFormatter

      public void addAdditionalXYWorldReferenceFormatter(ILcdXYWorldReferenceFormatter aXYWorldReferenceFormatter)
      Adds additional formatters for ILcdXYWorldReference objects onto a string representation.
      Parameters:
      aXYWorldReferenceFormatter - additional formatter.

    • setSAXParser

      @Deprecated public void setSAXParser(String aSAXParser)
      Deprecated.
      This method has been kept for compatibility reasons with LuciadMap. The method SAXParserFactory.newInstance() is now used to create a SAX parser.
      Sets the SAXParser used by the TLcdOGCWMSProxyModelDecoder.
      Parameters:
      aSAXParser - the new SAXParser class name.
      See Also:

    • getSAXParser

      @Deprecated public String getSAXParser()
      Deprecated.
      This method has been kept for compatibility reasons with LuciadMap. The method SAXParserFactory.newInstance() is now used to create a SAX parser.
      Returns the SAXParser used by the TLcdOGCWMSProxyModelDecoder.
      Returns:
      the SAXParser used by the TLcdOGCWMSProxyModelDecoder.
      See Also:

    • canDecodeSource

      public boolean canDecodeSource(String aServerURLAsString)
      Description copied from interface: ILcdModelDecoder
      Checks whether this model decoder can decode the specified data source. It is acceptable for this method to return true for a source name while decode throws an exception for that same source name.

      For performance reasons, we strongly recommend that this will only be a simple test. For example: check the file extension of a file, but not that the file exists or contains expected content.

      Specified by:
      canDecodeSource in interface ILcdModelDecoder
      Parameters:
      aServerURLAsString - the data source to be verified; typically a file name or a URL.
      Returns:
      true if this decoder can likely decode the data specified by the source name, false otherwise.
      See Also:

    • decode

      public ILcdModel decode(String aSourceName) throws IOException
      Creates an ILcdModel containing one ALcdWMSProxy element, which can be used to access the specified WMS server.

      The ALcdWMSProxy object contained in the returned model has the following properties:

      aSourceName the source to be decoded, can be a formatted as URI?data=LayerName to identify the server URI and layer name.
      • If you only provide the server URI, it returns a model which is configured with the first layer found in the WMS capabilities unless this decoder's property isUseEmptyProxyForUrlOnly() returns true.
      • If you provide both URI and layer name, it returns a model with the specified layer data.
      Specified by:
      decode in interface ILcdModelDecoder
      Parameters:
      aSourceName - The URL of the WMS server.
      Returns:
      an ILcdModel with a ALcdWMSProxy element.
      Throws:
      TLcdOGCWMSServiceException - when the server sends a service exception report.
      TLcdOGCWMSHttpException - when a HTTP error is received.
      TLcdOGCWMSException - in all other cases.
      IOException - for any exceptions caused by IO problems or invalid data. Since decoding invalid data almost always results in RunTimeExceptions (NullPointerException, IndexOutOfBoundsException, IllegalArgumentException, ...) on unexpected places, implementations are advised to catch RuntimeExceptions in their decode() method, and wrap them into an IOException, as illustrated in the code snippet below. 
      
   public ILcdModel decode( String aSourceName ) throws IOException {
      try (InputStream input = fInputStreamFactory.createInputStream(aSourceName)) {
         // Perform decoding ...
      } catch (RuntimeException e) {
         throw new IOException(e);
      }
   }
      See Also:

    • decode

      public ILcdModel decode(TLcdWMSClient aClient) throws IOException
      Creates an ILcdModel containing one ALcdWMSProxy element, which can be used to access the specified WMS server.

      The ALcdWMSProxy object contained in the returned model has the following properties:

      Parameters:
      aClient - The TLcdWMSClient which will be used to perform all requests in the ALcdWMSProxy
      Returns:
      an ILcdModel with a ALcdWMSProxy element.
      Throws:
      TLcdOGCWMSServiceException - when the server sends a service exception report.
      TLcdOGCWMSHttpException - when a HTTP error is received.
      TLcdOGCWMSException - in all other cases.
      IOException

    • canDecodeSource

      public boolean canDecodeSource(ILcdDataSource aDataSource)
      Description copied from interface: ILcdModelDecoder

      Checks whether this model decoder can decode the data source(s), identified by the passed ILcdDataSource.

      For performance reasons, we strongly recommend that this will only be a simple test. For example: check the instance class of aDataSource, or check the file extension if it is a TLcdDataSource.

      The default implementation of this method will check if the given ILcdDataSource is a TLcdDataSource. If not, this method returns false. Otherwise, it delegates the source to the ILcdModelDecoder.canDecodeSource(String) method.

      Specified by:
      canDecodeSource in interface ILcdModelDecoder
      Parameters:
      aDataSource - the ILcdModelSource to be verified.
      Returns:
      true if this decoder can likely decode the data specified by aDataSource, false otherwise.
      See Also:

    • decodeSource

      public ILcdModel decodeSource(ILcdDataSource aDataSource) throws IOException
      This method supports decoding a TLcdWMSDataSource and a TLcdDataSource. The latter data source behaves the same as calling the method decode(String).

      The minimum requirements for the TLcdWMSDataSource is the availability of the WMS server URI and one or more layers. Other values are optional and defaults are chosen.

      Mandatory information that has to be correct in the data source is the following.

      • WMS server URI.
      • The names of the layers. If the name of a layer is not offered by the WMS server the decoding fails.

      For the optional information the decoding is more lenient.

      • Layer with invalid style reference: The default style is used as fall-back.
      • Layer with queryable set to true when the server does not support querying for that layer. The querying is switched off to honour the capabilities of the server.
      • Invalid map format: the PNG format is used as default, if the server supports it, otherwise JPEG.
      Specified by:
      decodeSource in interface ILcdModelDecoder
      Parameters:
      aDataSource - the ILcdDataSource to be decoded.
      Returns:
      the model containing the WMS proxy object.
      Throws:
      IOException - when decoding the data source fails.
      See Also: