Overview

This article describes the LuciadLightspeed WCS Server API, which provides its users with an easy framework for setting up a Web Coverage Service. The WCS is implemented as a Java servlet with all required request handling facilities, and can serve coverages in GeoTIFF format out of the box.

The main task that remains for the user of the API is to implement the server-side data store for the WCS. The user may choose to read geographic data from files, retrieve it from a database, or use any other method to obtain data.

Configuring a WCS

The LuciadLightspeed WCS is a Java HTTP servlet. A Java HTTP servlet must implement the abstract class javax.servlet.http.HttpServlet, which is located in the Java EE API. The class TLcdWCSServlet in the WCS Server API provides an implementation of this class. This servlet uses an instance of ALcdOGCCommandDispatcher to handle all incoming requests. The ALcdOGCCommandDispatcher instance is created during server startup, and is used throughout the lifetime of the servlet. The creation of an ALcdOGCCommandDispatcher instance uses a Factory pattern: the method createCommandDispatcher(ILcdInitializationConfig) of the factory class ALcdOGCWCSCommandDispatcherFactory allows to create and return a specific implementation of ALcdOGCCommandDispatcher. This mechanism is illustrated in Figure 1, “Main classes of the LuciadLightspeed WCS Server API.”.

WCSServletDiagram
Figure 1. Main classes of the LuciadLightspeed WCS Server API.

It is up to the user to provide an implementation of ALcdOGCWCSCommandDispatcherFactory that initializes an ALcdOGCCommandDispatcher. The protected methods that must be implemented by the user set up the server-side data store, and determine in which formats data can be sent to the client.

The following paragraphs describe each of the command dispatcher factory’s methods. For implementation details, please refer to the API reference documentation or to the included samples.

Reading data

Loading data sources: createModelDecoderFactory()

The WCS 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 default implementation is the TLcdOGCModelDecoderFactory that uses the TLcdServiceLoader to retrieve all available ILcdModelDecoder instances.

Caching data sources: createModelProvider(ILcdOGCModelDecoderFactory)

To decode models, the server does not use the model decoder factory and model decoders directly. Instead, the server uses an ILcdOGCModelProvider which provides central access to all models. A model provider holds a reference to the model decoder factory and uses it to decode the actual data. This centralized access allows implementations to define additional functionality, like a cache mechanism.

The default implementation returns a TLcdOGCModelProvider 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. In general, it is not necessary to create a custom implementation of ILcdOGCModelProvider.

createWCSCapabilitiesProvider(ILcdOGCModelProvider)

This is the main method of the WCS command dispatcher factory to implement. It offers an easy way to implement access control, and it allows to return coverage offerings lazily. It creates a ILcdWCSCapabilitiesProvider instance that loads the data. This class in turn provides metadata about each coverage offering in the form of an ILcdCoverageOffering object. The latter interface provides access to the semantics of the coverage data and describes the data’s domain.

The createWCSCapabilitiesProvider method is passed the ILcdOGCModelProvider, that can be used by the capabilities provider implementation to read data into an ILcdModel. The method ILcdWCSCapabilitiesProvider.getCoverageOfferings(ILcdRequest) is used for the GetCapabilities request. It returns a number of ILcdCoverageOffering objects, each of which represent one coverage data set that may be queried by clients. The other methods of the interface are used for the other requests. They allow for retrieving only a sub-set of the information that is needed for validation and processing of the request.

Sending data to the client

createModelEncoderFactory()

A WCS server responds to requests by sending coverage data back to the client. By default, the returned data is encoded in GeoTIFF format. It is possible to expose additional output formats by implementing an ILcdWCSModelEncoderFactory. If such an encoder factory is available, it receives the output format parameter from WCS requests and returns the corresponding ILcdModelEncoder. Additional output formats supported by the encoder factory are automatically listed in the WCS capabilities document.

Before calling ILcdModelEncoder.export, the WCS server framework takes care of the heavy lifting for the preparation of the model, so that the model encoder does not need to. The server framework:

  • Clips the input model to the correct bounds according to the GetCoverage request parameters.

  • Transforms the input model to the correct reference if necessary, according to the GetCoverage request parameters.

  • Converts the legacy ILcdRaster elements in the model to a single ALcdImage element.

  • Picks the most appropriate level for the desired resolution according to the GetCoverage request parameters.

  • Composites multiple elements into a single ALcdImage element.

  • Preserves the input data’s sampling mode.

The model passed as argument to ILcdModelEncoder.export has the following properties:

  • It has an ILcdImageModelDescriptor.

  • It has a single element, which is either an ALcdBasicImage or an ALcdImageMosaic.

  • The ALcdImage element has a sampling mode corresponding to that of the input data. When the input data is a multi-level image with different sampling modes at different levels, the sampling mode of the most detailed level prevails. DMED is the typical example: the overview image is area-sampled, while the actual DTED levels are point-sampled.

The WCS server framework will never call ILcdModelEncoder.canSave or save. Implementations may safely throw UnsupportedOperationExceptions for those methods.

Service identification and provider metadata

ILcdWCSCapabilitiesProvider.getServiceIdentification()

The getServiceIdentification() method of ILcdWCSCapabilitiesProvider allows API users to customize the contents of the Service section of the WCS capabilities document. The method returns an TLcdOWSServiceIdentification object which contains metadata about the specific server. This information will be written to the capabilities document. Please refer to the API reference documentation for more information on the methods of TLcdOWSServiceIdentification.