Configure a WMS server

The WMS server uses an ILcdModelDecoderFactory to create model decoders that load the data. Its method createModelDecoder(String) is invoked with a data source name as argument and returns an ILcdModelDecoder that can read the data from that source. The data source can be a single file, an URL, a database, and so on. The command dispatcher factory must provide an array of one or more valid model decoder factories, or the WMS will not be able to load any data. To optimize performance, TLcdOGCWMSCommandDispatcher maintains a cache of models so that they do not need to be decoded on every request.

The default implementation within the ALcdOGCWMSCommandDispatcherFactory creates a TLcdModelDecoderFactory that retrieves ILcdModelDecoder instances using the service look-up mechanism.

To decode models, the server does not use the model decoder factories and model decoders directly. Instead, the server uses an ILcdModelProvider which provides central access to all models. A model provider holds a reference to the model decoder factories and uses them to decode the actual data. The main advantage of this centralized approach is that it allows implementations to define additional functionality, that is global for all model decoders. A typical example is a caching mechanism, to improve the performance.

The default implementation returns a model provider that maintains a cache for all decoded models. To prevent memory problems, it makes use of java.lang.ref.SoftReference objects, which are cleared at the discretion of the garbage collector in response to memory demand. Soft references are most often used to implement memory-sensitive caches.

In general, it is not necessary to create a custom implementation of ILcdModelProvider. A situation where it can be useful is when a server needs to be dynamic, in the sense that its capabilities can be updated at runtime. If a certain dataset has been updated or removed, the cache of the model provider needs to be updated in some cases. A removed dataset typically does not pose any problems in that case, since the default implementation uses soft references for the cached models. An updated dataset can cause a problem however, since the cached model will not be up to date anymore. Configuration of the capabilities further explains the concept of dynamic capabilities.

Once a model decoder has been created with the appropriate model decoder factory, the server is ready to actually load data. To create layers for the decoded models, the WMS server uses an ILcdWMSGXYLayerFactory. The command dispatcher factory must provide an array of one or more valid layer factories, or the WMS will not be able to render any data.

The default implementation within the ALcdOGCWMSCommandDispatcherFactory creates a ILcdWMSGXYLayerFactory that uses the service look-up mechanism to pick implementations of ILcdWMSGXYLayerFactory, ILcdSLDGXYLayerFactory, and ILcdGXYLayerFactory to make a composite layer factory.

Finally, the created layers are added to an internal view, which is positioned at the requested bounding box and has the requested dimensions. This view is a TLcdGXYViewBufferedImage, which is an implementation of the ILcdGXYView interface using an off-screen image. It does not depend on AWT or Swing components, and is well-suited for generating images on the server-side to be sent to clients. The construction and initialization of the view is done via the factory class TLcdWMSGXYViewFactory, returned by default in createWMSGXYViewFactory().

TLcdWMSGXYViewFactory creates and initializes regular TLcdGXYViewBufferedImage instances, but other implementations may be defined that return extensions of TLcdGXYViewBufferedImage or that set additional configuration properties on a view. For example, if each map returned by a GetMap request should contain a fixed logo, an implementation could be defined that adds this logo to each created view instance, by using the method putCornerIcon() available in TLcdGXYViewBufferedImage.

As soon as the WMS server has constructed the view with the requested layers in a GetMap request, it must be encoded to a pictorial format like JPEG or PNG before it can be sent to the client. To encode a view, the WMS server uses an ILcdGXYViewEncoder. To determine the output format, the interface contains a method getContentType() which returns a MIME^[1] type. The command dispatcher factory must provide an array of one or more valid view encoders, or the WMS will not be able to encode a view. The default implementation in ALcdOGCWMSCommandDispatcherFactory returns an array containing a subset of the available view encoders in the package com.luciad.wms.server.viewencoder:

The default implementation within the ALcdOGCWMSCommandDispatcherFactory creates a list of ILcdGXYViewEncoder implementations using the service look-up mechanism.

The GetFeatureInfo request is an optional operation designed to retrieve feature information for a specified location on a map. When the server receives such a request, it automatically searches the objects that are located at the given location in the layers of the map. The selected objects are then placed in a ILcdGXYLayerSubsetList, which defines a list of one or more ILcdGXYLayer subset(s). As soon as the ILcdGXYLayerSubsetList is created, it is submitted to an ILcdWMSGetFeatureInfoRequestEncoder. This interface is used to retrieve the feature information from the selected object(s) in the ILcdGXYLayerSubsetList and to encode it to a specific format. The format of a ILcdWMSGetFeatureInfoRequestEncoder is determined by a MIME type returned by the method getContentType(). Which information about the selected objects is actually returned, can be chosen freely by the ILcdWMSGetFeatureInfoRequestEncoder implementation, as this cannot be specified within a GetFeatureInfo request.

The creation and initialization of a ILcdGXYLayerSubsetList with the selected objects is done automatically by the command dispatcher. The initialization and registration of one or more ILcdWMSGetFeatureInfoRequestEncoder implementations is left to the user of the API, because the user needs to decide which output formats for a GetFeatureInfo request are available and which information must be returned in practice.

The default implementation of createWMSGetFeatureInfoEncoders() creates a list of ILcdWMSGetFeatureInfoRequestEncoder encoders using the service look-up mechanism. By default the API contains an implementation that can generate the feature info result as JSON.

To offer support for the GetFeatureInfo request, an implementation of createWMSGetFeatureInfoEncoders() must return one or more valid encoders. Furthermore, the capabilities of the server should reflect that support for the GetFeatureInfo request is offered: one or more available layers should be marked queryable and the capabilities should list the available output formats for the GetFeatureInfo request. How to configure the capabilities of a server is further described in createWMSCapabilitiesDecoder().

The capabilities of a server refer to the content that it offers. This includes a list of the available layers, the supported output formats, the supported reference systems, and some metadata about the server itself. The capabilities of a server can be queried by a client using a GetCapabilities request. To model these capabilities, the WMS server uses the abstract class ALcdWMSCapabilities. When a client sends a GetCapabilities request, the information stored in ALcdWMSCapabilities is encoded to the WMS capabilities format defined by the OGC WMS specification and sent to the client.

Figure 3, “Structure of ALcdWMSCapabilities” shows the structure of this class. Note that the available layers in the capabilities are of the type ALcdWMSLayer and not of the type ILcdGXYLayer. An ILcdGXYLayer is used for displaying the objects of an ILcdModel in an ILcdGXYView. An ALcdWMSLayer on the other hand is not used for visualization but for declaring that a layer is available at the server. As illustrated in Figure 3, “Structure of ALcdWMSCapabilities”, ALcdWMSLayer instances can be arranged in a hierarchical way. Its most important properties are:

The full list of properties can be found in the LuciadLightspeed reference documentation.

The implementation of the interface ILcdWMSCapabilitiesProvider is the main entry point to determine which data is served by the WMS server.

The interface is built such that for operations other than GetCapabilities only a sub-set of the information is requested to handle the request. This allows for implementations that load as little information in memory as possible.

The capabilities provider generates the capabilities only when a client request is performed. It avoids loading (data) in memory during server start up.

The use of the capabilities provider interface makes it easy to create a dynamic WMS server in which the capabilities are updated during the server’s runtime.

Take the following guidelines into account when you are implementing a capabilities provider that is dynamic:

The WMS server API comes with a capabilities decoder, an implementation of the interface ILcdWMSCapabilitiesDecoder, that decodes the ALcdWMSCapabilities from a configuration file.

The default capabilities provider created within TLcdOGCWMSCommandDispatcherFactory uses the capabilities decoder to read from configuration what data needs to be served to client applications.

During server startup, a capabilities decoder is created using the method createWMSCapabilitiesDecoder() in ALcdOGCWMSCommandDispatcherFactory, as illustrated in the sequence diagram in Figure 2, “Sequence diagram of the WMS initialization procedure.”. Subsequently, the method decodeWMSCapabilities(String) on the capabilities decoder is invoked to retrieve the capabilities.

The single parameter in the method decodeWMSCapabilities(String) contains the source name of this capabilities file. It is stored as a servlet parameter in the deployment descriptor of the WMS servlet, which is described in Installing an OGC web server.

A dimension is represented by the class ALcdWMSDimension. It holds the dimension-related parameters, such as the name, the unit, and so on. The available values or intervals for an ALcdWMSDimension are represented by TLcdWMSDimensionExtent. One or more ALcdWMSDimension objects can be added to an ALcdWMSLayer to define a multi-dimensional layer. When a client sends a GetCapabilities request, the dimension information will be encoded automatically in the returned capabilities document. How to configure the capabilities of a server is described in createWMSCapabilitiesDecoder().

As explained in Reading data, the WMS server uses an ILcdModelProvider as a central access point for all data sources. Its single method getModel(String) retrieves an ILcdModel for a given source name. The source name itself is retrieved from the ALcdWMSLayer requested by a client. In case of a multi-dimensional layer however, there is no exact mapping between the ALcdWMSLayer and a source name. In this situation, determining the source name depends both on the ALcdWMSLayer and dimensional parameters provided by the client. To model this step, an extension of ILcdModelProvider is introduced, namely ALcdMultiDimensionalModelProvider. This class serves two purposes:

To register an ALcdMultiDimensionalModelProvider implementation, the method createModelProvider(ILcdModelDecoderFactory[]) in ALcdOGCWMSCommandDispatcherFactory must be implemented, as described in Reading data.