Architecture

Figure 1, “Overview of the LuciadFusion CSW Server architecture and functionality” shows the typical architecture of a CSW Server, and the components that are offered by the CSW Server API.

csw overview
Figure 1. Overview of the LuciadFusion CSW Server architecture and functionality

To help you get started, the framework contains a sample CSW servlet with all required request handling facilities, including OpenSearch support. The sample is configured to provide Dublin Core, ISO 19115, and ATOM metadata records as output.

Your main configuration task consists of implementing the server-side data store for the CSW. You can choose to read metadata from files, retrieve it from a database, or use any other method to obtain data.

Design considerations

Both the metadata model and the database structure will have an impact on the implementation. We advise you to carefully consider both topics.

Decide on your main metadata model

LuciadFusion has extensive support for OGC CSW (Dublin core) and ISO 19115 metadata records. You can transform metadata between those formats as desired. For custom metadata extensions, we advise creating an XML-based TLcdDataModel, as described in the LuciadLightspeed Developer’s Guide. This allows decoding and encoding the metadata from and to XML. If needed, create the necessary transformations to other output formats that you want to support, typically TLcdCSWRecord.

Decide how to persist your metadata into your repository

You can map all metadata properties you need to individual fields in a database table. For increased flexibility, you could also store your original metadata as an XML object in your table. For spatial queries, a spatial database such as PostGIS or SpatiaLite is strongly recommended.

Implementation steps

Configure the server by implementing the capabilities provider

To get started with the configuration of a CSW, your main entry point in the API is the class ALcdCSWCommandDispatcherFactory. This abstract class is used during server startup to set up the necessary request handlers for every CSW operation. The dispatcher factory delegates to an ILcdCSWCapabilitiesProvider that exposes and implements the server capabilities.

When you are implementing the provider:

  • Think about how the data will be queried: getInputRecordTypes and getInputRecordProperties. Which queryable properties, such as title and abstract, are relevant? Do you want to support queries that are formulated in a different metadata model, such as queries for apiso:title or dc:format.

  • Think about how the output data will be restricted: getOutputRecordTypes and getOutputRecordProperties. What output properties can be selected?

  • Consider what versions of CSW you want to support: getSupportedVersions. CSW version 3.0.0 supports OpenSearch, but does not have an official specification for adding ISO metadata support.

  • Collect the service and service provider metadata:`createServiceIdentification` and createServiceProvider. This information is used for the generation of both the capabilities document and the OpenSearch description document, and will be visible to the users of your service.

  • Decide what OGC Filter conditions you want to support: getFilterCapabilities.

Prepare to retrieve metadata records from your data repository

The ILcdCSWQueryHandler is an abstraction interface for retrieving metadata from the catalog. It is responsible for analyzing the query constraints, and performing the correct actions to generate the desired metadata result. To integrate CSW directly with a database, it is necessary to write your own ILcdCSWQueryHandler that transforms OGC Filter queries to SQL or QueryDSL queries, and returns the result. The most important aspects of the filter are:

  • The PropertyIsLike condition, describing textual queries

  • The BBOX condition, describing spatial queries

  • The SortBy condition, describing the requested sorting criteria

The sample code contains a basic implementation of ILcdCSWQueryHandler. It implements support for a fixed set of in-memory records. The class is called CSWRecordQueryHandler. It extends ALcdCSWFilterQueryHandler, which is an abstract implementation of the ILcdCSWQueryHandler with a few default values for common operations.

Once you have transformed the OGC Filter to your own internal database query, your last step is to transform the result into the output format requested by the client. The CSW API provides decoding, encoding and transformation API for the most common metadata models used in CSW:

  • CSW 2.0.2 Records

  • CSW 3.0 Records

  • ISO 19139 GMD MD_Metadata

  • ATOM feeds

To transform records between any of these metadata models, use the TLcdCSWRecordTransformationFactory.

Add OpenSearch support

The CSW Server automatically converts OpenSearch queries into ILcdCSWQueryHandler calls. OpenSearch queries are configured by implementing ILcdCSWCapabilitiesProvider.getOpenSearchTemplates. The ALcdCSWCapabilitiesProvider implementation provides OpenSearch URL templates for CSW and ATOM results, consisting of searchTerms, bbox, startIndex, and count parameters.

To add more templates, override the getOpenSearchTemplates method, and make it return a custom set of OpenSearch templates. You can generate templates using the TLcdCSWOpenSearchTemplate.newBuilder() method, as demonstrated in the example below:

Program: Example of customizing the OpenSearch templates
@Override
public List<TLcdCSWOpenSearchTemplate> getOpenSearchTemplates(ILcdRequest aRequest) {
  List<TLcdCSWOpenSearchTemplate> openSearchTemplates = new ArrayList<>();
  //Any text search + bbox
  openSearchTemplates.add(TLcdCSWOpenSearchTemplate.newBuilder()
                                                   .addAnyTextKeyword("q", true)
                                                   .addBBoxKeyword("bbox", true)
                                                   .outputFormat(CSW_202).build());
  openSearchTemplates.add(TLcdCSWOpenSearchTemplate.newBuilder()
                                                   .addAnyTextKeyword("q", true)
                                                   .addBBoxKeyword("bbox", true)
                                                   .outputFormat(ISO).build());
  //Template based on time
  openSearchTemplates.add(TLcdCSWOpenSearchTemplate.newBuilder()
                                                   .addTimeKeyword("time", false)
                                                   .addTimeRelationKeyword("trelation", true)
                                                   .outputFormat(CSW_300).build());
  openSearchTemplates.add(TLcdCSWOpenSearchTemplate.newBuilder()
                                                   .addTimeKeyword("time", false)
                                                   .addTimeRelationKeyword("trelation", true)
                                                   .outputFormat(ISO).build());
  return openSearchTemplates;
}

The configured templates automatically appear in the OpenSearch description document of your CSW service. The server’s command dispatcher passes OpenSearch queries to a request handler that converts the query to a GetRecords request with an OGC Filter for a common set of OpenSearch parameters, including the OpenSearch Geo and Time extensions. For a description of those extensions, see http://www.opengeospatial.org/standards/opensearchgeo.

Add Inspire support

If your server needs to support the European INSPIRE Directive, you need to configure and plug in both a TLcdCSWISOProfile and TLcdCSWInspireProfile instance into your ALcdCSWCapabilitiesProvider. The CSW server will pick up these profiles and expose the necessary capabilities to be identified as an INSPIRE-compliant discovery service.

The INSPIRE directive also imposes requirements on what information to include in your ISO metadata records. See the INSPIRE technical guidelines for more information.

Extend your server

Once you have the basic functionality up and running, you can consider:

  • Supporting additional OGC Filter conditions

  • Adding text indexing, to improve textual searches using Apache Lucene (see https://lucene.apache.org), for example

If you need to support custom OpenSearch parameters, you can customize your ALcdCSWCommandDispatcherFactory and wrap or replace the ILcdRequestHandler for the OpenSearch request.