Difference between revisions of "Hyrax - THREDDS Configuration"

From OPeNDAP Documentation
Line 1: Line 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.
 
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.
  
 
# Dynamic THREDDS catalogs for holdings provided by the BES are provided by  the opendap.bes.BESThreddsDispatchHandler.  
 
# Dynamic THREDDS catalogs for holdings provided by the BES are provided by  the opendap.bes.BESThreddsDispatchHandler.  
# Static THREDDS catalogs are provided by the opendap.threddsHandler.StaticCatalogDispatch  
+
# 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.
  
The default ([[Hyrax_-_OLFS_Configuration#olfs.xml_Configuration_File |olfs.xml]]) file now contains both of these handlers in the correct order/location for Hyrax operations.
+
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.  
  
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. Additional catalog components may be added to the ''catalog.xml'' file to build (potentially large) static catalogs. '''Existing THREDDS catalogs should work with this new implementation.'''
+
  '''Existing THREDDS catalogs should work with this new implementation.'''
  
*  THREDDS datasetScan elements are now supported and can be used as a mechanism for including inherited metadata down the catalog tree of the BES holdings.
+
*  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.
  
 
[[THREDDS_using_XSLT|More details about the handlers, their configuration options, and other information can be found here.]]
 
[[THREDDS_using_XSLT|More details about the handlers, their configuration options, and other information can be found here.]]
Line 18: Line 19:
 
* [http://www.unidata.ucar.edu/software/thredds/current/tds/tutorial/CatalogPrimer.html Catalog Primer]
 
* [http://www.unidata.ucar.edu/software/thredds/current/tds/tutorial/CatalogPrimer.html Catalog Primer]
 
* [http://www.unidata.ucar.edu/software/thredds/v4.6/tds/catalog/InvCatalogServerSpec.html CatalogServer Specification (Catalogs used as TDS configuration)]
 
* [http://www.unidata.ucar.edu/software/thredds/v4.6/tds/catalog/InvCatalogServerSpec.html CatalogServer Specification (Catalogs used as TDS configuration)]
* [http://www.unidata.ucar.edu/software/thredds/v4.6/tds/reference/DatasetScan.html ''datasetScan'' Element]
 
 
* [http://www.unidata.ucar.edu/projects/THREDDS/tech/catalog/InvCatalogSpec.html#dataset ''dataset'' Element]
 
* [http://www.unidata.ucar.edu/projects/THREDDS/tech/catalog/InvCatalogSpec.html#dataset ''dataset'' Element]
 +
* [http://www.unidata.ucar.edu/software/thredds/v4.6/tds/reference/DatasetScan.html ''datasetScan'' Element]
 +
  
 
Did you read all that? Excellent!
 
Did you read all that? Excellent!
Line 29: Line 31:
 
* The current default  ([[Hyrax_-_OLFS_Configuration#olfs.xml_Configuration_File |olfs.xml]]) file comes with THREDDS configured correctly.
 
* The current default  ([[Hyrax_-_OLFS_Configuration#olfs.xml_Configuration_File |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.
 
* 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.
 +
 +
=== 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.
 +
 +
==== 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''
 +
<source lang="xml">
 +
<datasetScan name="DatasetScanExample" path="hyrax" location="/data/nc">
 +
</source>
 +
 +
==== useHyraxServices attribute ====
 +
The Hyrax version of the '''datasetScan''' element employs a special attribute extension '''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.

Revision as of 12:58, 25 April 2015

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.

Existing THREDDS catalogs should work with this new implementation.
  • 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 useHyraxServices attribute

The Hyrax version of the datasetScan element employs a special attribute extension 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.