To simply load and visualize data from a WMS, you can create a model through TLcdWMSDataSource and TLcdOGCWMSProxyModelDecoder, as explained in the Basics. The information in this guide is only needed if you want to have additional customization options to load WMS data, such as the configuration of a background color or the preferred exception report format.

Using a proxy model

LuciadLightspeed uses proxy models for connections with OGC services. When added to a layer in a view, they automatically obtain the data (features, images …​) from the OGC service, making the service connection transparent to the user. The OGC client APIs create these proxy models by default, using a data source and model decoder.

To support customization possibilities, the OGC clients offer additional API related to the proxy model. Examples include the configuration of constraints on what data should be retrieved or which data exchange format should be used.

Exploring and configuring a WMS proxy model

A decoded WMS model has a model descriptor of type TLcdWMSProxyModelDescriptor. This can be used to recognize an ILcdModel representing a connection with a WMS service. The model contains a single element of type ALcdWMSProxy, which acts as proxy towards the service.

The proxy object has a double role, which is illustrated in Figure 1, “Main classes of the WMS Client API”.

Figure 1. Main classes of the WMS Client API

On the one hand, the proxy object provides access to the available WMS layers published in the capabilities of the service. The available layers are structured in a hierarchical list, of which the root can be obtained through the method getRootWMSNamedLayer.

This method takes an index, to support multiple layer roots. Although the WMS specification essentially defines the existence of one layer root, this flexibility has been added to increase interoperability with WMS services that do not adhere to this requirement. In general however, there is only one layer root and 0 can be supplied as index.

The result of this call is an ALcdWMSNamedLayer, which is a representation of a WMS named layer. An ALcdWMSNamedLayer can itself be composed of other ALcdWMSNamedLayer objects, according to the "Composite" design pattern of the GoF (Gamma et al., "Design Patterns"). Note that instances of ALcdWMSNamedLayer that are composed of other ALcdWMSNamedLayer objects do not always have a name, getNamedLayerName() returns null for example. In that case, the composed ALcdWMSNamedLayer is only a category or logical group for all the layers nested within. It cannot be used in requests.

On the other hand, the proxy object provides you with a way to select and configure one or more WMS layers that should be visualized on the map. You can do this by adding an instance of TLcdWMSStyledNamedLayerWrapper to the ALcdWMSProxy for each ALcdWMSNamedLayer that should be included in the view.

A TLcdWMSStyledNamedLayerWrapper can also contain an ALcdWMSNamedLayerStyle. This represents the style that is used to represent the ALcdWMSNamedLayer. If no ALcdWMSNamedLayerStyle is set on the TLcdWMSStyledNamedLayerWrapper, the default style will be used.

The number of possible ALcdWMSNamedLayerStyle objects for a ALcdWMSNamedLayer can be retrieved with the method getLocalNamedLayerStyleCount; the _n_th ALcdWMSNamedLayerStyle can be retrieved with the method getLocalNamedLayerStyle.

In the hierarchy of ALcdWMSNamedLayer objects an ALcdWMSNamedLayer can also be represented with an ALcdWMSNamedLayerStyle of one of its ancestors. The total number of possible ALcdWMSNamedLayerStyle objects for an ALcdWMSNamedLayer (i.e., including the styles from the ancestors) can be retrieved with the method getNamedLayerStyleCount; the _n_th ALcdWMSNamedLayerStyle can be retrieved with the method getNamedLayerStyle.

Specifying dimensional parameters

A WMS server can define one or more dimensions for a layer, to allow support for multi-dimensional datasets. The available dimensions for a layer can be retrieved through the methods getDimension(int) and getDimensionCount() in ALcdWMSNamedLayer. A dimension itself is represented by ALcdOGCWMSDimension, which contains all the dimension-related parameters, such as the name, the unit, etc. The available values or intervals for an ALcdOGCWMSDimension are represented by TLcdOGCWMSDimensionExtent.

To specify dimensional parameters in a request, an instance of TLcdOGCWMSDimensionWrapper must be created for each desired dimension. This class holds two objects:

  1. An ALcdOGCWMSDimension representing the dimension that must be included in a request.

  2. A TLcdOGCWMSDimensionExtent representing the value(s) or interval(s) that are defined by the client for the specified dimension.

After they have been properly initialized, you must add the TLcdOGCWMSDimensionWrapper objects to ALcdWMSProxy , using addDimension(TLcdOGCWMSDimensionWrapper) and related methods, to have them included in subsequent requests. As defined by the WMS specification, the dimensional parameters in a request are not directly linked with a layer. Instead, the server itself determines which dimensional parameters apply to which layer.

Setting an exception handler

It is possible to set an ILcdExceptionHandler on the proxy using the method setExceptionHandler(). This makes it possible to intercept exceptions that occur during communication with the server, and handle them appropriately.

Performing a FeatureInfo request

ALcdWMSProxy offers more high-level API to perform FeatureInfo requests. See createFeatureInfoInputStream(TLcdWMSGetFeatureInfoContext) for more information. You can retrieve the TLcdWMSGetFeatureInfoContext argument from the layers that are used to paint the WMS data. The context argument makes it possible to perform FeatureInfo requests that correspond exactly with what is shown in the view. See:

For a demonstration, see WMSGetFeatureInfoMouseListener in the WMS client samples.