deegree3 OGC web service configuration

An important general requirement is the improvement of the service configuration. The main goal here is to make the task of configuring deegree3 services easier and less error-prone than it is the case with deegree2.

We try to realize this by following these key concepts:

• Use a main configuration file to define general options for all services. This includes metadata (ServiceProvider) and service URLs (as returned by GetCapabilities-requests) as well as the definition of JDBC connections.

• Each service has a specific configuration document format that only contains those options that actually are configurable. In deegree2, a modified OGC capabilities file was used as a configuration file for each service and this implied that they often contained redundant elements or ones that had no effect on the behaviour of the service. Another issue were the different versions of service specifications (and capabilities documents): a capabilities document of an 1.0.0 WMS has a different structure as an 1.3.0 WMS capabilities document.
• Provide schema files for the main configuration as well as all service configuration documents. This way, validation is availabe (for people who edit configuration files manually) and parsers can be generated automatically (using JAXB).

1. Interaction of the configuration files

Webservices in deegree are Java web applications and have to be deployed in a servlet container (e.g. Tomcat, Jetty, etc). The following configuration aspects are involved in the configuration of deegree3 webservices:

1. datasource/ (datasource configuration (access to coverage, feature and other geospatial data))
2. jdbc/ (database connections)
3. services/ (service specific configurations)
4. proxy.xml (proxy settings)
5. authentication.xml (authentication settings)

Here's an example for the configuration file structure of deegree3 (all these files reside in the folder $WEBAPP/WEB-INF/conf):

.
|-- datasources
|   |-- coverage
|   |   |-- coverage1.xml
|   |   `-- coverage2.xml
|   |-- feature
|   |   |-- fs1.xml
|   |   `-- fs2.xml
|   |-- observation
|   `-- record
|       `-- iso19115.xml
|-- jdbc
|   |-- db1.xml
|   `-- db2.xml
|-- services
|   |-- csw.xml
|   |-- csw_metadata.xml
|   |-- main.xml
|   |-- metadata.xml
|   |-- sos.xml
|   |-- sos_metadata.xml
|   |-- wcs.xml
|   |-- wcs_metadata.xml
|   |-- wfs.xml
|   |-- wfs_metadata.xml
|   |-- wms.xml
|   |-- wms_metadata.xml
|   |-- wps.xml
|   |-- wps_metadata.xml
|   |-- wpvs.xml
|   `-- wpvs_metadata.xml
|-- styles
|   |-- style1.sld
|   `-- style2.sld
`-- proxy.xml

2. ServletContainer configuration

The web.xml is the standard configuration file for Java web applications. For deegree3 OGC webservices, it must expose the OGCFrontController servlet, which acts as the single HTTP communication entry point and request dispatcher.

The relevant configuration parameter is the definition of a servlet that refers to class org.deegree.services.controller.OGCFrontController and a mapping to a url-pattern (usually /services).

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4">
  <display-name>deegree 3 OGC webservices</display-name>
  <servlet>
    <servlet-name>services</servlet-name>
    <servlet-class>org.deegree.services.controller.OGCFrontController</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>services</servlet-name>
    <url-pattern>/services</url-pattern>
  </servlet-mapping>
</web-app>

There's no need to provide any other configuration information for the OGCFrontController servlet. By default, it loads the main service configuration from file ./conf/metadata.xml.

3. Main service configuration

The main service configuration resides in file ./conf/metadata.xml. Here's an example:

<?xml version="1.0" encoding="UTF-8"?>
<dgws:deegreeServicesMetadata configVersion="0.1" xsi:schemaLocation="http://www.deegree.org/schemas/webservices ../../schema/services_metadata.xsd" xmlns:dgws="http://www.deegree.org/schemas/webservices" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <dgws:ServiceProvider>
    <dgws:ProviderName>lat-lon GmbH</dgws:ProviderName>
    <dgws:ProviderSite>http://www.lat-lon.de</dgws:ProviderSite>
    <dgws:ServiceContact>
      <dgws:IndividualName>Andreas Poth</dgws:IndividualName>
      <dgws:PositionName>Technical Director</dgws:PositionName>
      <dgws:Phone>0228/184-96-0</dgws:Phone>
      <dgws:Facsimile>0228/184-96-29</dgws:Facsimile>
      <dgws:ElectronicMailAddress>info@lat-lon.de</dgws:ElectronicMailAddress>
      <dgws:Address>
        <dgws:DeliveryPoint>Aenchenstr. 19</dgws:DeliveryPoint>
        <dgws:City>Bonn</dgws:City>
        <dgws:AdministrativeArea>NRW</dgws:AdministrativeArea>
        <dgws:PostalCode>53117</dgws:PostalCode>
        <dgws:Country>Bonn</dgws:Country>
      </dgws:Address>
      <dgws:OnlineResource>http://www.deegree.org</dgws:OnlineResource>
      <dgws:HoursOfService>24-7</dgws:HoursOfService>
      <dgws:ContactInstructions>Don't hesitate to call</dgws:ContactInstructions>
      <dgws:Role>PointOfContact</dgws:Role>
    </dgws:ServiceContact>
  </dgws:ServiceProvider>
  <dgws:DCP>
    <dgws:HTTPGet>http://localhost:8080/deegree/services?</dgws:HTTPGet>
    <dgws:HTTPPost>http://localhost:8080/deegree/services?</dgws:HTTPPost>
    <dgws:SOAP>http://localhost:8080/deegree/services?</dgws:SOAP>
  </dgws:DCP>
</dgws:deegreeServicesMetadata>

This file is also used for setting other global parameters that apply to all services, such as JdbcConnections and ProxyConfiguration.

4. Service specific configuration

By default, the OGCFrontController scans for service specific configuration files at $service/$service_configuration.xml -- this path is relative to the main service configuration file. It looks for configuration files for each service type known to the OGCFrontController.

This table lists the searched locations:

The options of a service configuration file are specific to the service type, but they all follow a general structure:

• The root element is always called deegree$SERVICE, e.g. deegreeWPS or deegreeSOS and it has two child elements: ServiceConfiguration and PublishedInformation. All elements of a service configuration document are in the namespace http://www.deegree.org/schemas/services/$SERVICE.

• The ServiceConfiguration element contains information that are relevant for the "internal" service configuration.

• The PublishedInformation element contains configuration information that are relevant to the service-specific controller, e.g. activated OGC protocol versions and requests.

The separation of an OGC web service configuration into PublishedInformation and ServiceConfiguration sections is a consequence of the architectural concept to separate the OGC and the internal service layer.

Here's an example for a WPS configuration (wps_configuration.xml):

<?xml version="1.0" encoding="UTF-8"?>
<deegreeWPS configVersion="0.1.0" xmlns="http://www.deegree.org/services/wps" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.deegree.org/services/wps ../../../schema/wps/0.1.0/wps_configuration.xsd">
  <PublishedInformation>
    <OfferedVersions>
      <Version>1.0.0</Version>
    </OfferedVersions>
  </PublishedInformation>
  <ServiceConfiguration>
    <ProcessesDirectory>processes</ProcessesDirectory>
  </ServiceConfiguration>
</deegreeWPS>

Note: WPS processes are described through individual configuration documents that are deposited in the ProcessesDirectory specified in the WPS configuration. For creating and configuring your own WPS processes please have a look at the HowTo.

4.1. Version management of service configuration file format

It is not possible to fixate all details of the configuration document format. To reduce confusion and frustration of early adopters -- those who start to use deegree3 services, such as the WPS, SOS or WCS, before the configuration format has been fixated -- we need to add some kind of version information to the configuration documents. A deegree 3 web service installation can check if it is able to read a given configuration document (e.g. an SOS configuration) or not by checking the version information. Of course a document may still be erroneous, but that's another kettle of fish. If deegree is not able to cope with the configuration version, it should produce a meaningful message. There a generally two cases:

• Configuration format > deegree3.jar supported version: Gives a message like: 'Configuration document uses configuration format 0.4, but this deegree version only supports version 0.3. Please check http://wiki.deegree.org/deegreeWiki/deegree3/ConfigurationVersions for details and information on updating your deegree version.'

• Configuration format < deegree3.jar supported version: Gives a message like: 'Configuration document uses configuration format 0.3, but this deegree version only supports version 0.4. Please check http://wiki.deegree.org/deegreeWiki/deegree3/ConfigurationVersions for details and information on converting your configuration document.'

Please note that it's generally not targeted to support all outdated configuration formats. The primary aim is to have a definitive means that allows deegree to check if it supports the configuration format and report this if not. However, after deegree 3 becomes stable, all configuration format versions from that point should stay usable with newer deegree3 versions.

4.1.1. Impact of supporting multiple configuration formats

In the deegree 3 development process, we use JAXB for the automatic generation of XML configuration file parsers and beans. Thus, if the need for a configuration format change arises, we need to:

1. Adapt the configuration syntax file (XML schema)
2. Let JAXB (re-) generate the configuration beans
3. Change the service code to cope with the new options

By nature, the service code is bound very tightly to the configuration beans. It's a very unattractive outlook to write service code that has to cope with multiple sets of these beans. Thus, we should follow two basic strategies to minimize the impact of this problem:

1. Before deegree 3 becomes stable, we should reduce parser and configuration code complexity by supporting just the latest configuration format. This means that there's only one set of configuration beans.
2. After deegree 3 is stable, successive releases need to cope with all older (stable) configuration versions. If multiple sets of beans exist for a service configuration, the service should only work with the latest set of beans. For older formats, we should write code to transform the older beans into beans of the latest version.

Please note that we must also provide the corresponding schema files, so a user may perform a syntactic check when editing a deegree 3 service configuration document. We think it is a good practice to provide theses schema files online. To support users that are still working with outdated deegree3 versions (and want to keep doing so), we must account for multiple versions. For the SOS, this may look like this:

• http://schemas.deegree.org/sos (base directory for all SOS schema files)

• http://schemas.deegree.org/sos/0.1/sos_configuration.xsd (schema for version 0.1 of the SOS configuration)

• http://schemas.deegree.org/sos/0.2/sos_configuration.xsd (schema for version 0.2 of the SOS configuration)

• http://schemas.deegree.org/sos/0.3/sos_configuration.xsd (schema for version 0.3 of the SOS configuration)

• ...

4.1.2. Minimizing the number of format versions

It's very desirable to keep the number of configuration versions as low as possible. Therefore, not every minor change should result in a new version that has to be supported (e.g. by providing the schema online). It is suggested that a process is installed to decide when a new version is reached and should be published (by putting the schema online). This means that we have to cope with interim versions during the process. Here's a possible scenario:

1. SOS configuration version is at 0.1, schema is available online
2. A change is necessary, an optional element X is added to the configuration root element, the version is now called 0.2-pre.
3. Another change is necessary, an optional element Y is added to the configuration root element.
4. It turns out that X is no longer necessary and the options are integrated into element Y.
5. To make the new version available to the public, the current state of the SOS configuration version is now named 0.2, schema is made available online.

Note that there is no consistent schema during steps 2.-4. available. Any "x.y-pre" schema *will* definitely be removed from the schema repository at some time in the future.

4.1.3. Indication of format version

The version used by a configuration file is indicated by the mandatory configVersion) attribute in the root element:

Example for version attribute:

<deegreeSOS xmlns="http://www.deegree.org/services/sos" configVersion="0.4"...>
...
</deegreeSOS>

4.2. Serving the schema files for configuration documents

The configuration schemas are provided online (http://schemas.deegree.org/) and should always be used in this way in all of our configuration instance documents (i.e. we should avoid using references to local copies). This way, it is possible to validate them on every machine in an XML editor -- given that the machine has internet access. If a developer has no internet access, a good solution could be to mirror the schemas locally. This involves setting up a local HTTP server with a copy of the schemas and add an entry (schemas.deegree.org 127.0.0.1) to the hosts file (also used by windows machines -- C:\windows\hosts).

CategoryDeegree3