WCS Service version 1.1

---

Overview

This WCS service is designed to be used in conjunction with one or more Hyrax data servers. The Hyrax servers may be either local or remote to the WCS service.

See also: WCS Technical Description

Catalog Implementation

One of the challenges encountered when implementing a WCS service for Hyrax is catalog generation: How do we generate a list of coverages from existing holdings in Hyrax? The DAP contains the mechanism for transmitting the information, but lacks the explicit semantics required to describe a WCS Coverage. Luckily many of the users of DAP servers have provided metadata that complies to some type of metadata convention or standard. This WCS service can build its catalog by using semantic web technology to crosswalk from existing DAP data sets which use the Climate Forecast (CF-1.0) and Unidtata Dataset Discovery v1.0 metadata conventions into the WCS metadata space.

WCS Catalog

The WCS catalog uses semantic web technologies to create mappings between DAP data sets and WCS Coverages. A WCS Coverage is a very specific data type and is much more constrained than the more general DAP data model. Thus, only certain DAP data sets will be representable as WCS Coverages. Evaluating which ones can be represented as WCS Coverages requires analysis of the metadata associated with each data set. Since the DAP has no actual semantic metadata requirements for metadata it is necessary (at least for the moment) to look only at DAP data sets that have metadata that conforms to some well known metadata convention or standard. Since the semantics of the convention are known it is possible to write inferencing rules that relate pieces of information in one convention/standard to the equivalent information in another convention/standard.

Requirements

The WCS service needs:

• Java 1.6 virtual machine or newer.
• Tomcat 6.x (The WCS service has not been tested against Tomcat 7.x)

In addition, the WCS service requires DAP datasets served by Hyrax 1.8 or newer.

Installation

Install The Software

• Download and install Tomcat 6.x
• Download the WCS Service distribution, a gzipped tar file, and it's associated gpg signature.
• Verify the distribution. (You will need to get the public security key for OPeNDAP first) In the directory containing the file and the downloaded signature run the command:

gpg --verify <file>.sig

If that fails - don't proceed and please contact support@opendap.org

• Unpack the distribution
• Copy the WCS.war file to $CATALINA_HOME/webapps
• Start Tomcat. Make sure that you tell Tomcat to use a JVM with at minimum 1GB of memory. You can do this easily by setting the environment variable JAVA_OPTS to 1000MB prior to launching Tomcat. (csh: 'setenv JAVA_OPTS -Xmx1000m', bash: 'export JAVA_OPTS=-Xmx1000m')

Wait...

Once the server is up it won't show any Coverages for a few minutes. The default set of Coverages will take from between 2 - 30 minutes to process, depending on network speeds (loading documents) and the host system's processing capability. You can watch the processing by viewing the log file $CATALINA_HOME/logs/catalina.out

Once the semantic engine completes it's run the WCS catalog should be updated and you should be able to see the default coverages generated by datasets on http://test.opendap.org:8080/opendap/

If that's not the case and no coverages are found then STOP and start trouble shooting.

Testing the sample data

The WCS service comes with some sample datasets already configured. To view a web page listing these, type the following URL in a browser: http://localhost:8080/WCS. Of course, adjust localhost:8080 to match your site.

To force the service to update its catalog, either:

1. Start and stop Tomcat
2. If enabled in the web.xml for the WCS service you can access the URL http://localhost:8080/WCS/update().

If you choose the later, go back to the main web page for the WCS service (http://localhost:8080/WCS) and refresh that page. While the catalog is rebuilding the main page will display the message: "WCS catalog is currently being updated." that will change to "WCS catalog is up to date." when the process is complete. What is happening here? The inferencing software is reevaluating the information describing your datasets and then using that new information to build coverages.

Configuration

Note: Configuration changes will not take effect until Tomcat is restarted.

In order to correctly configure your WCS service you will need to:

1. Localize the WCS service metadata
   • Edit $CATALINA_HOME/content/WCS/ServiceProvider.xml so that the specific information about the contact point, address and other information about the service reflect the needs of your organization. (Jump to Service Provider localization details on this page.)
   • Edit $CATALINA_HOME/content/WCS/ServiceIdentification.xml so that the Title and Abstract sections reflect your needs. DO NOT alter the ServiceType or ServiceTypeVersion element content. (Jump to Service Identification localization details on this page.)
   • Edit $CATALINA_HOME/content/WCS/OperationsMetadata.xml so that the links to the service reflect the domain names and ports upon which you are running the service. (Jump to Operations Metadata localization details on this page.)
2. Configure the catalog (i.e. add datasets) for the WCS service. Jump to WCS Catalog Configuration details on this page.
3. Stop and restart Tomcat.

WCS Service Configuration

The WCS Service utilizes its own configuration directory and files which are stored in a well known location within the directory content/context directory (where context of the web application that the WCS service is running. By default context='WCS'):

$CATALINA_HOME/content/<context>

where <context> is context of the WCS web application. By default this value is WCS.

In the WCS Service directory ($CATALINA_HOME/content/WCS) is kept various documents used by the WCS Service including:

wcs_service.xml

The wcs_service.xml file controls which datasets are contained in the catalog and the catalog update behavior..

ServiceIdentification.xml

The ServiceIdentification.xml file contains WCS metadata used in the wcs:Capabilities document.

ServiceProvider.xml

The ServiceProvider.xml file contains WCS metadata used in the wcs:Capabilities document.

OperationsMetadata.xml

The OperationsMetadata.xml file contains WCS metadata used in the wcs:Capabilities document.

Every installation of a WCS service requires a localization step in which much of the required metadata about the particular service instance and its keepers is captured so that it can be returned to clients.

From a client's perspective a WCS service is made up of three commands:

1. wcs:GetCapabilities
2. wcs:DescribeCoverage
3. wcs:GetCoverage

The response for a wcs:GetCapaibilities request requires localization information that can only be determined by the individual(s) that are installing the service. The responses for both the wcs:DescribeCoverage and wcs:GetCoverage requests can be generated directly from the WCS "catalog".

The wcs:Capabilites document contains 4 sections:

• Service Identification (ows:ServiceIdentification)
• Service Provider (ows:ServiceProvider)
• Operations Metadata (ows:OperationsMetadata)
• Contents (wcs:Contents)

For any given installation of a WCS service the first three sections must be carefully localized. Their contents cannot realistically be ascertained by an automation. Thus, they are really part of the WCS configuration activity that must be performed by the service installer. The last section, Contents, can be automatically generated from the catalog of Coverages.

In this WCS implementation the ows:ServiceIdentification, ows:ServiceProvider and ows:OperationsMetadata sections are each stored as a separate XML file that is loaded by the server at startup. Default versions of these files are installed into the OLFS's persistent content directory the first time that the WCS Service is launched. They can be found in the directory:

$CATALINA_HOME/content/<context>

where <context> is defined by the Tomcat service context in which the WCS web application is running. By default the value of <context> is WCS

Service Identification

The Service Identification metadata as described in section 7.4.4 of OGC document OGC 06-121r3.

Localization should include (but may not be limited to) updating the ows:Keytwords, ows:Fees and ows:AccessConstraints

Example Document

<?xml version="1.0" encoding="UTF-8"?>
<!-- ************************************************************ -->
<!-- * SERVICE IDENTIFICATION SECTION                           * -->
<!-- ************************************************************ -->
<ows:ServiceIdentification xmlns="http://www.opengis.net/wcs/1.1"
xmlns:ows="http://www.opengis.net/ows/1.1"
xmlns:xlink="http://www.w3.org/1999/xlink" >
  <ows:Title>OPeNDAP Hyrax Prototype WCS Service</ows:Title>
  <ows:Abstract>A prototype WCS server intended to provide WCS 1.1 (1.1.2) access to DAP datasets</ows:Abstract>
  <ows:Keywords>
     <ows:Keyword>Web Coverage Service</ows:Keyword>
     <ows:Keyword>OPeNDAP</ows:Keyword>
     <ows:Keyword>nectcdf</ows:Keyword>
     <ows:Keyword>DAP</ows:Keyword>
  </ows:Keywords>
  <ows:ServiceType>WCS</ows:ServiceType>
  <ows:ServiceTypeVersion>1.1.2</ows:ServiceTypeVersion>
  <ows:Fees>NONE</ows:Fees>
  <ows:AccessConstraints>NONE</ows:AccessConstraints>
</ows:ServiceIdentification>

File Location

$CATALINA_HOME/content/<context>/ServiceIdentification.xml where <context> is the Tomcat service context in which the WCS web application is running. By default this 'WCS'. (So the default location of the ServiceIdentification.xml file would be:$CATALINA_HOME/content/WCS/ServiceIdentification.xml)

Service Provider

The Service Provider metadata as described in section 7.4.5 of OGC document OGC 06-121r3.

The ows:ServiceProvider section should be localized to identify the local operator of the system. Typically this would be the name and contact information of the individual or group responsible for installing and maintaing the WCS service.

Example Document

<?xml version="1.0" encoding="UTF-8"?>
<!-- ************************************************************ -->
<!-- * SERVICE PROVIDER SECTION                                 * -->
<!-- ************************************************************ -->
<ows:ServiceProvider  xmlns="http://www.opengis.net/wcs/1.1"
xmlns:ows="http://www.opengis.net/ows/1.1"
xmlns:xlink="http://www.w3.org/1999/xlink">
  <ows:ProviderName>OPeNDAP Inc.</ows:ProviderName>
  <ows:ProviderSite xlink:href="http://www.opendap.org"/>
  <ows:ServiceContact>
     <ows:IndividualName>Nathan D. Potter</ows:IndividualName>
     <ows:PositionName>Senior Software Engineer</ows:PositionName>
     <ows:ContactInfo>
        <ows:Phone>
           <ows:Voice>123-456-7890</ows:Voice>
           <ows:Facsimile>234-567-8901</ows:Facsimile>
        </ows:Phone>
        <ows:Address>
           <ows:DeliveryPoint>165 Dean Knauss Dr</ows:DeliveryPoint>
           <ows:City>Narragansett</ows:City>
           <ows:AdministrativeArea>Rhode Island</ows:AdministrativeArea>
           <ows:PostalCode>02882</ows:PostalCode>
           <ows:Country>USA</ows:Country>
           <ows:ElectronicMailAddress>support[a.t]opendap[d.o.t]org</ows:ElectronicMailAddress>
        </ows:Address>
        <ows:OnlineResource xlink:href="http://ndp.opendap.org:8080/opendap/"/>
        <ows:HoursOfService>24x7x365</ows:HoursOfService>
        <ows:ContactInstructions>email</ows:ContactInstructions>
     </ows:ContactInfo>
     <ows:Role>Developer</ows:Role>
  </ows:ServiceContact>
</ows:ServiceProvider>

File Location

$CATALINA_HOME/content/<context>/ServiceProvider.xml where <context> is the Tomcat service context in which the WCS web application is running. By default this 'WCS'. (So the default location of the ServiceProvider.xml file would be:$CATALINA_HOME/content/WCS/ServiceProvider.xml)

Operations Metadata

The Operations Metadata as described in section 7.4.6 of OGC document OGC 06-121r3.

The service will look at the xlink:href links in the Operations Metadata document and it will detect the default value of http://your.domain.name:8080/opendap/WCS' and replace it with the service URL that it determines from the incoming request. For most situations this will be completely adequate and the Operations Metadata will require no localization.

However, if the server is behind a firewall which is port-forwarding the incoming requests the URL's may only reflect the local network configuration and not the clients view of the service from outside the firewall. Careful localization of this information is crucial to the correct function of the WCS service. Many clients will use this section of the wcs:Capabilities document to ascertain where and how they can interact with the service. It is required that the Get and Post URL's for each WCS operation point to the correct terminus on your server.

Edit this file very thoughtfully

Example Document

<?xml version="1.0" encoding="UTF-8"?>
<!-- ************************************************************ -->
<!-- * OPERATIONS METADATA                                      * -->
<!-- ************************************************************ -->
<ows:OperationsMetadata xmlns="http://www.opengis.net/wcs/1.1"
                        xmlns:ows="http://www.opengis.net/ows/1.1"
                        xmlns:xlink="http://www.w3.org/1999/xlink">
    <ows:Operation name="GetCapabilities">
        <ows:DCP>
            <ows:HTTP>
                <ows:Get xlink:href="http://ndp.opendap.org:8080/opendap/WCS?"/>
                <ows:Post xlink:href="http://ndp.opendap.org:8080/opendap/WCS/post">
                    <ows:Constraint name="PostEncoding">
                        <ows:AllowedValues>
                            <ows:Value>XML</ows:Value>
                        </ows:AllowedValues>
                    </ows:Constraint>
                </ows:Post>
                <ows:Post xlink:href="http://ndp.opendap.org:8080/opendap/WCS/soap">
                    <ows:Constraint name="PostEncoding">
                        <ows:AllowedValues>
                            <ows:Value>SOAP</ows:Value>
                        </ows:AllowedValues>
                    </ows:Constraint>
                </ows:Post>
            </ows:HTTP>
        </ows:DCP>
    </ows:Operation>
    <ows:Operation name="GetCoverage">
        <ows:DCP>
            <ows:HTTP>
                <ows:Get xlink:href="http://ndp.opendap.org:8080/opendap/WCS?"/>
                <ows:Post xlink:href="http://ndp.opendap.org:8080/opendap/WCS/post">
                    <ows:Constraint name="PostEncoding">
                        <ows:AllowedValues>
                            <ows:Value>XML</ows:Value>
                        </ows:AllowedValues>
                    </ows:Constraint>
                </ows:Post>
                <ows:Post xlink:href="http://ndp.opendap.org:8080/opendap/WCS/soap">
                    <ows:Constraint name="PostEncoding">
                        <ows:AllowedValues>
                            <ows:Value>SOAP</ows:Value>
                        </ows:AllowedValues>
                    </ows:Constraint>
                </ows:Post>
            </ows:HTTP>
        </ows:DCP>
        <ows:Parameter name="Format">
            <ows:AllowedValues>
                <ows:Value>application/x-netcdf-cf1.0</ows:Value>
                <ows:Value>application/x-dap2.0</ows:Value>
            </ows:AllowedValues>
        </ows:Parameter>
    </ows:Operation>
    <ows:Operation name="DescribeCoverage">
        <ows:DCP>
            <ows:HTTP>
                <ows:Get xlink:href="http://ndp.opendap.org:8080/opendap/WCS?"/>
                <ows:Post xlink:href="http://ndp.opendap.org:8080/opendap/WCS/post">
                    <ows:Constraint name="PostEncoding">
                        <ows:AllowedValues>
                            <ows:Value>XML</ows:Value>
                        </ows:AllowedValues>
                    </ows:Constraint>
                </ows:Post>
                <ows:Post xlink:href="http://ndp.opendap.org:8080/opendap/WCS/soap">
                    <ows:Constraint name="PostEncoding">
                        <ows:AllowedValues>
                            <ows:Value>SOAP</ows:Value>
                        </ows:AllowedValues>
                    </ows:Constraint>
                </ows:Post>
            </ows:HTTP>
        </ows:DCP>
        <ows:Parameter name="Format">
            <ows:AllowedValues>
                <ows:Value>text/xml</ows:Value>
            </ows:AllowedValues>
        </ows:Parameter>
    </ows:Operation>
</ows:OperationsMetadata>

File Location

$CATALINA_HOME/content/<context>/OperationsMeadata.xml where <context> is the Tomcat service context in which the WCS web application is running. By default this 'WCS'. (So the default location of the OperationsMetadata.xml file would be:$CATALINA_HOME/content/WCS/OperationsMetadata.xml)

WCS Catalog Configuration

The WCS service must maintain a catalog of Coverages. In the Hyrax WCS service, the implementation of this catalog is identified at server start-up from the WCS service configuration file.

File Location

The configuration file is located (by default) here: $CATALINA_HOME/content/WCS/wcs_service.xml.

The default location of the file can be changed by changing the name of the WCS servlet's service context. If you do that, the catalog file will be located at: $CATALINA_HOME/content/<context>/wcs_service.xml, where <context> is the Tomcat service context in which the WCS web application is running.

The default wcs_service.xml file contains:

<WcsService>
    <WcsCatalog>
        <useUpdateCatalogThread updateInterval="28800" firstUpdateDelay="10"/>

        <dataset>http://test.opendap.org:8080/opendap/ioos/200803061600_HFRadar_USEGC_6km_rtv_SIO.ncml</dataset>
        <dataset>http://test.opendap.org:8080/opendap/ioos/ECMWF_ERA-40_subset.ncml</dataset>
        <dataset>http://test.opendap.org:8080/opendap/ioos/mday_joinExist.ncml.ddx</dataset>

    </WcsCatalog>
</WcsService>

Adding Datasets To The Catalog

In order for the WCS service to work it must know which DAP data sets are to be served as WCS coverages. Datasets can be added to the catalog in the following ways.

<dataset>

A dataset element identifies a single DAP data set that is to be served as a WCS coverage. The dataset element must contain the fully qualified data access URL for a DAP data set. This URL will be examined and the software will attempt to get the RDF version of the data set's DDX from the DAP server.

Example:

 <WcsCatalog>
   <dataset>http://localhost:8080/opendap/data/nc/examples/200803061600_HFRadar_USEGC_6km_rtv_SIO.nc.ddx</dataset>
 </WcsCatalog>

<ThreddsCatalog>

A ThreddsCatalog element identifies a THREDDS catalog which contains DAP data access URLs that point to DAP data sets that will be served as WCS coverages. Each DAP data set in the catalog will be served as a separate wcs:Coverage. The recurse attribute determines if the software will follow catalogRef links in the THREDDS catalog to ingest the entire catalog hierarchy starting at the node identified by the URL.

Example:

 <WcsCatalog>
    <ThreddsCatalog recurse="false" >http://test.opendap.org:8080/opendap/coverage/catalog.xml</ThreddsCatalog>
 </WcsCatalog>

Controlling Catalog Update Behavior

The useUpdateCatalogThread element is used to control the way in which the catalog updates its semantic repository and Coverage catalog. Using this element will cause the catalog to spawn a worker thread that will update the semantic repository (and thus the WCS catalog holdings) in the background. If the useUpdateCatalogThread element is omitted the catalog will not spawn a worker thread, and will attempt to update it's holdings at startup, and no additional catalog update attempts will be made.

The firstUpdateDelay attribute controls how long (in seconds) the worker thread will wait before making the first update, I like to use 10 seconds, or whatever number allows tomcat to fully start before the worker thread goes to work. It also makes the log easier to understand.

The updateInterval attribute is used to specify how frequently (in seconds) the catalog should be updated.

Example:

 <WcsCatalog>
    <useUpdateCatalogThread updateInterval="3600" firstUpdateDelay="60"/>
 </WcsCatalog>

More detailed catalog configuration instructions can be found here