Hyrax - THREDDS Configuration

From OPeNDAP Documentation
Revision as of 14:10, 25 April 2015 by Ndp (talk | contribs) (useHyraxServices attribute)

1 Overview

Hyrax now uses its own implementation of the THREDDS catalog services and supports most of the THREDDS catalog service stack. The implementation relies on two DispatchHandlers in the OLFS and utilizes XSLT to provide HTML versions (presentation views) for human consumption.

  1. Dynamic THREDDS catalogs for holdings provided by the BES are provided by the opendap.bes.BESThreddsDispatchHandler.
  2. Static THREDDS catalogs are provided by the opendap.threddsHandler.StaticCatalogDispatch. The static catalogs allow catalog "graphs" to be decoupled from the filesystem "graph" of the data holdings, thus allowing data providers the ability to present and organize data collections independently of how they are organized in the underlying filesystem.

Static THREDDS catalogs are "rooted" in a master catalog file, catalog.xml, located in the (persistent) content directory for the OLFS (Typically $CATALINA_HOME/content/opendap). The default catalog.xml that comes with Hyrax contains a simple catalogRef element that points to the dynamic THREDDS catalogs generated from the BES holdings. The default catalog example also contains a (commented out) datasetScan element that provides (if enabled) a simple demonstration of the datasetScan capabilities. Additional catalog components may be added to the catalog.xml file to build (potentially large) static catalogs.

  • THREDDS datasetScan elements are now fully supported and can be used as a tool for altering the catalog presentation of any part of the BES catalog. These alterations include (but are not limited too) renaming, auto proxy generation, filtering, and metadata injection.

More details about the handlers, their configuration options, and other information can be found here.

Rather than provide an exhaustive explanation of the THREDDS catalog functionality and configuration I will appeal to the existing documents provided by our fine colleagues at UNIDATA:


Did you read all that? Excellent!



2 Configuration Instructions

  • The current default (olfs.xml) file comes with THREDDS configured correctly.
  • The THREDDS master catalog is stored in the file $CATALINA_HOME/content/opendap/catalog.xml it can be edited to provide additional static catalog access.

2.1 datasetScan

The datasetScan element is a powerful tool that can be used to sculpt the catalog's presentation of the BES catalog content. The Hyrax implementation has a couple of key points that need to be considered when developing an instance of the datasetScan element.

2.1.1 location attribute

When defining datasetScan elements in Hyrax THREDDS catalogs the location attribute specifies the place in the BES catalog graph that the datasetScan will be rooted. This value must be expressed relative to the BES catalog root (BES.Catalog.catalog.RootDirectory) and not in terms of the underlying BES file system.

Example
If BES.Catalog.catalog.RootDirectory=/Users/share/hyrax and the data directory to which you wish to apply the dataset scan is (in filesystem terms) located at /Users/share/hyrax/data/nc then the associated datasetScan element's location attribute would have a value of /data/nc
<datasetScan name="DatasetScanExample" path="hyrax" location="/data/nc">

2.1.2 name attribute

The name attribute specifies name that will be used to in the presentation (HTML) view for the catalog containing the datasetScan is viewed.

2.1.3 path attribute

The path attribute specifies the place in the THREDDS catalog graph that the datasetScan will be rooted. In effect it is a relative URL for the service. If path begins with a "/" then it is an absolute path - rooted at there server and port.

Relative path example
Consider a catalog accessed with the URL: http://localhost:8080/opendap/thredds/v27/Landsat/catalog.xml and that contains this datasetScan element:
<datasetScan name="DatasetScanExample" path="hyrax" location="/data/nc" />
In the client catalog the datasetScan becomes this catalogRef element:
<thredds:catalogRef
    name="DatasetScanExample"
    xlink:title="DatasetScanExample"
    xlink:href="hyrax/catalog.xml"
    xlink:type="simple"
/>
Then the top of datasetScan catalog graph will be found at the URL http://localhost:8080/opendap/thredds/v27/Landsat/hyrax/catalog.xml
Absolute path example
Consider a catalog accessed with the URL: http://localhost:8080/opendap/thredds/v27/Landsat/catalog.xml and that contains this datasetScan element:
<datasetScan name="DatasetScanExample" path="/hyrax" location="/data/nc" />
In the client catalog the datasetScan becomes this catalogRef element:
<thredds:catalogRef
    name="DatasetScanExample"
    xlink:title="DatasetScanExample"
    xlink:href="/hyrax/catalog.xml"
    xlink:type="simple"
/>
Then the top of datasetScan catalog graph will be found at the URL http://localhost:8080/hyrax/catalog.xml which may not be what you want. When using absolute paths you must be sure to prefix the path with the Hyrax THREDDS service path or you will direct the clients away from the service. In these examples the Hyrax THREDDS service path would be /opendap/thredds/". If we change the datasetScan path attribute value to /opendap/thredds/myDatasetScan:
<datasetScan name="DatasetScanExample" path="'/opendap/thredds/myDatasetScan" location="/data/nc" />
In the client catalog the datasetScan becomes this catalogRef element:
<thredds:catalogRef
    name="DatasetScanExample"
    xlink:title="DatasetScanExample"
    xlink:href="/opendap/thredds/myDatasetScan/catalog.xml"
    xlink:type="simple"
/>
Now the top of datasetScan catalog graph will be found at the URL http://localhost:8080/opendap/thredds/myDatasetScan/catalog.xml which keeps the URL referencing the Hyrax THREDDS service and not some other part of the web service stack.


2.1.4 useHyraxServices attribute

The Hyrax version of the datasetScan element employs the extra attribute useHyraxServices. This allows the datasetScan to automatically generate Hyrax data services definitions and access links for datasets in the catalog. The datasetScan can be used to augment the list of services (when useHyraxServices is set to true) or it can be used to completely replace the Hyrax service stack (when useHyraxServices is set to false).

  • If no services are referenced in the datasetScan and useHyraxServices is set to true, then Hyrax will provide catalogs with service definitions and access elements for all the datasets that the BES identifies as data.
  • If no services are referenced in the datasetScan and useHyraxServices is set to false, then the catalogs generated by the datasetScan will have no service definitions or access elements.

By default useHyraxServices is set to true.