Improve NCSS docs and upgrade guide

Call out changes to NCSS service elements in 5.x (i.e. GRID and POINT have different service elements). Addresses #544.
Unidata · Nov 20, 2024 · f79495f · f79495f
1 parent e7d12ac
commit f79495f
Show file tree

Hide file tree

Showing 21 changed files with 135 additions and 49 deletions.
diff --git a/docs/adminguide/src/site/pages/tds_tutorial/tds_configuration/AddingNcss.md b/docs/adminguide/src/site/pages/tds_tutorial/tds_configuration/AddingNcss.md
@@ -32,21 +32,28 @@ Details on other configuration options for NCSS are available in the [`threddsCo
 
 ## Serving Datasets With NCSS
 
-In your configuration catalogs, you must define the service like this:
+In your configuration catalogs, you must define the service based on the type of data being served.
+For Feature Type `GRID`, use:
 
 ~~~xml
-<service name="subsetServer" serviceType="NetcdfSubset" base="/thredds/ncss/" />
+<service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
+~~~
+
+For Feature Types `POINT` or `STATION`, use:
+
+~~~xml
+<service name="ncssPoint" serviceType="NetcdfSubset" base="/thredds/ncss/point/" />
 ~~~
 
 Then as usual, add the service to any datasets that you want served, e.g.:
 
 ~~~xml
 <dataset name="datasetName" ID="datasetID" urlPath="/my/urlPath"> 
-   <serviceName>subsetServer</serviceName> 
+   <serviceName>ncssGrid</serviceName> 
 </dataset> 
 ~~~
 
-Note that the name of the service (`subsetServer` in this example) is arbitrary, but the `serviceType` and base must be _exactly_ as shown.
+Note that the name of the service (`ncssGrid` in this example) is arbitrary, but the `serviceType` and base must be _exactly_ as shown.
 
 ## Restrictions On What Files Can Be Served
 

diff --git a/docs/adminguide/src/site/pages/tds_tutorial/tds_configuration/ConfigCatalog.md b/docs/adminguide/src/site/pages/tds_tutorial/tds_configuration/ConfigCatalog.md
@@ -111,13 +111,13 @@ Therefore, it is required that service base URLs must [exactly match the values
 
 * NetCDF Subset Service (Grid Data)
    ~~~xml
-   <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
+   <service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
    ~~~
 
 * NetCDF Subset Service (Point Data)
 
    ~~~xml
-   <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/point/" />
+   <service name="ncssPoint" serviceType="NetcdfSubset" base="/thredds/ncss/point/" />
    ~~~
 
 * WCS

diff --git a/docs/adminguide/src/site/pages/thredds/TdsServices.md b/docs/adminguide/src/site/pages/thredds/TdsServices.md
@@ -229,13 +229,23 @@ The `serviceType` and `base` values are **required** in the following examples:
 ~~~
 
 #### NetCDF Subset Service
-
+
+## Serving Datasets With NCSS
+
+For Feature Type `GRID`, use:
+
+~~~xml
+<service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
+~~~
+
+For Feature Types `POINT` or `STATION`, use:
+
 ~~~xml
-  <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/"/>
+<service name="ncssPoint" serviceType="NetcdfSubset" base="/thredds/ncss/point/" />
 ~~~
 
 #### WCS
-  
+
 ~~~xml
   <service name="wcs" serviceType="WCS" base="/thredds/wcs/"/>
 ~~~
@@ -275,7 +285,7 @@ The `serviceType` and `base` values are **required** in the following examples:
 <service name="all" serviceType="Compound" base="">
   <service name="HTTPServer" serviceType="HTTPServer" base="/thredds/fileServer/"/>
   <service name="opendap" serviceType="OPENDAP" base="/thredds/dodsC/"/>
-  <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/"/>
+  <service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/"/>
   <service name="cdmremote" serviceType="CdmRemote" base="/thredds/cdmremote/"/>
 
   <service name="wcs" serviceType="WCS" base="/thredds/wcs/"/>

diff --git a/docs/adminguide/src/site/pages/thredds/ViewersRef.md b/docs/adminguide/src/site/pages/thredds/ViewersRef.md
@@ -119,7 +119,7 @@ Use the service type inside of curly brackets to select which access URL to use.
   <service name="http" serviceType="HTTPServer" base="/thredds/fileServer/"/>
   <service name="wcs" serviceType="WCS" base="/thredds/wcs/"/>
   <service name="wms" serviceType="WMS" base="/thredds/wms/"/>
-  <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/"/>
+  <service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/"/>
   <service name="cdmremote" serviceType="CdmRemote" base="/thredds/cdmremote/"/>
   <service name="iso" serviceType="ISO" base="/thredds/iso/"/>
   <service name="ncml" serviceType="NCML" base="/thredds/ncml/"/>

diff --git a/docs/devguide/src/site/pages/tds_tutorial/tds_configuration/AddingNcss.md b/docs/devguide/src/site/pages/tds_tutorial/tds_configuration/AddingNcss.md
@@ -31,21 +31,28 @@ Details on other configuration options for NCSS are available in the [`threddsCo
 
 ## Serving Datasets With NCSS
 
-In your configuration catalogs, you must define the service like this:
+In your configuration catalogs, you must define the service based on the type of data being served.
+For Feature Type `GRID`, use:
 
 ~~~xml
-<service name="subsetServer" serviceType="NetcdfSubset" base="/thredds/ncss/" />
+<service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
+~~~
+
+For Feature Types `POINT` or `STATION`, use:
+
+~~~xml
+<service name="ncssPoint" serviceType="NetcdfSubset" base="/thredds/ncss/point/" />
 ~~~
 
 Then as usual, add the service to any datasets that you want served, e.g.:
 
 ~~~xml
 <dataset name="datasetName" ID="datasetID" urlPath="/my/urlPath"> 
-   <serviceName>subsetServer</serviceName> 
+   <serviceName>ncssGrid</serviceName> 
 </dataset> 
 ~~~
 
-Note that the name of the service (`subsetServer` in this example) is arbitrary, but the `serviceType` and base must be _exactly_ as shown.
+Note that the name of the service (`ncssGrid` in this example) is arbitrary, but the `ncssGrid` and base must be _exactly_ as shown.
 
 ## Restrictions On What Files Can Be Served
 

diff --git a/.../devguide/src/site/pages/tds_tutorial/tds_configuration/AddingOgcIsoServices.md b/.../devguide/src/site/pages/tds_tutorial/tds_configuration/AddingOgcIsoServices.md
@@ -65,7 +65,7 @@ Adding them to an existing compound service would look something like this:
     <service name="odap" serviceType="OpenDAP" base="/thredds/dodsC/" />
     <service name="wcs" serviceType="WCS" base="/thredds/wcs/" />
     <service name="wms" serviceType="WMS" base="/thredds/wms/" />
-    <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/" />
+    <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
     <service name="http" serviceType="HTTPServer" base="/thredds/fileServer/" />
 </service>
 ~~~
@@ -80,7 +80,7 @@ For instance, adding to the same compound service as above:
     <service name="odap" serviceType="OpenDAP" base="/thredds/dodsC/" />
     <service name="wcs" serviceType="WCS" base="/thredds/wcs/" />
     <service name="wms" serviceType="WMS" base="/thredds/wms/" />
-    <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/" />
+    <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
     <service name="http" serviceType="HTTPServer" base="/thredds/fileServer/" />
     <service name="ncml" serviceType="NCML" base="/thredds/ncml/" />
     <service name="uddc" serviceType="UDDC" base="/thredds/uddc/" />

diff --git a/docs/devguide/src/site/pages/tds_tutorial/tds_configuration/ConfigCatalog.md b/docs/devguide/src/site/pages/tds_tutorial/tds_configuration/ConfigCatalog.md
@@ -111,13 +111,13 @@ Therefore, it is required that service base URLs must [exactly match the values
 
 * NetCDF Subset Service (Grid Data)
    ~~~xml
-   <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
+   <service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
    ~~~
 
 * NetCDF Subset Service (Point Data)
 
    ~~~xml
-   <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/point/" />
+   <service name="ncssPoint" serviceType="NetcdfSubset" base="/thredds/ncss/point/" />
    ~~~
 
 * WCS

diff --git a/docs/devguide/src/site/pages/thredds/TdsServices.md b/docs/devguide/src/site/pages/thredds/TdsServices.md
@@ -229,9 +229,17 @@ The `serviceType` and `base` values are **required** in the following examples:
 ~~~
 
 #### NetCDF Subset Service
-
+
+For Feature Type `GRID`, use:
+
+~~~xml
+<service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
+~~~
+
+For Feature Types `POINT` or `STATION`, use:
+
 ~~~xml
-  <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/"/>
+<service name="ncssPoint" serviceType="NetcdfSubset" base="/thredds/ncss/point/" />
 ~~~
 
 #### WCS
@@ -275,7 +283,7 @@ The `serviceType` and `base` values are **required** in the following examples:
 <service name="all" serviceType="Compound" base="">
   <service name="HTTPServer" serviceType="HTTPServer" base="/thredds/fileServer/"/>
   <service name="opendap" serviceType="OPENDAP" base="/thredds/dodsC/"/>
-  <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/"/>
+  <service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/"/>
   <service name="cdmremote" serviceType="CdmRemote" base="/thredds/cdmremote/"/>
 
   <service name="wcs" serviceType="WCS" base="/thredds/wcs/"/>

diff --git a/docs/devguide/src/site/pages/thredds/ViewersRef.md b/docs/devguide/src/site/pages/thredds/ViewersRef.md
@@ -119,7 +119,7 @@ Use the service type inside of curly brackets to select which access URL to use.
   <service name="http" serviceType="HTTPServer" base="/thredds/fileServer/"/>
   <service name="wcs" serviceType="WCS" base="/thredds/wcs/"/>
   <service name="wms" serviceType="WMS" base="/thredds/wms/"/>
-  <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/"/>
+  <service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/"/>
   <service name="cdmremote" serviceType="CdmRemote" base="/thredds/cdmremote/"/>
   <service name="iso" serviceType="ISO" base="/thredds/iso/"/>
   <service name="ncml" serviceType="NCML" base="/thredds/ncml/"/>

diff --git a/docs/quickstart/src/site/pages/tds_tutorial/production/Upgrade.md b/docs/quickstart/src/site/pages/tds_tutorial/production/Upgrade.md
@@ -38,7 +38,19 @@ Deprecated classes and methods have been removed, and the module structure and t
 ### Netcdf Subset Service (NCSS)
 
 NCSS queries and responses have been improved and clarified.
-Generally the previous queries are backwards compatible. See [NCSS Reference](netcdf_subset_service_ref.html) for details.
+Generally the previous queries are backwards compatible.
+See [NCSS Reference](netcdf_subset_service_ref.html) for details.
+
+Catalog (config and client) base changes:
+* NCSS service has been split and now has two different paths, depending on the feature type of data being served.
+* For `GRID`, use:
+  ~~~
+  <service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
+  ~~~
+  and for `POINT` or `STATION`, use:
+  ~~~xml
+  <service name="ncssPoint" serviceType="NetcdfSubset" base="/thredds/ncss/point/" />
+  ~~~
 
 New functionality:
 * 2D time can now be handled for gridded datasets, with addition of `runtime` and `timeOffset` parameters.

diff --git a/docs/quickstart/src/site/pages/tds_tutorial/tds_configuration/AddingNcss.md b/docs/quickstart/src/site/pages/tds_tutorial/tds_configuration/AddingNcss.md
@@ -31,21 +31,28 @@ Details on other configuration options for NCSS are available in the [`threddsCo
 
 ## Serving Datasets With NCSS
 
-In your configuration catalogs, you must define the service like this:
+In your configuration catalogs, you must define the service based on the type of data being served.
+For Feature Type `GRID`, use:
 
 ~~~xml
-<service name="subsetServer" serviceType="NetcdfSubset" base="/thredds/ncss/" />
+<service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
+~~~
+
+For Feature Types `POINT` or `STATION`, use:
+
+~~~xml
+<service name="ncssPoint" serviceType="NetcdfSubset" base="/thredds/ncss/point/" />
 ~~~
 
 Then as usual, add the service to any datasets that you want served, e.g.:
 
 ~~~xml
 <dataset name="datasetName" ID="datasetID" urlPath="/my/urlPath"> 
-   <serviceName>subsetServer</serviceName> 
+   <serviceName>ncssGrid</serviceName> 
 </dataset> 
 ~~~
 
-Note that the name of the service (`subsetServer` in this example) is arbitrary, but the `serviceType` and base must be _exactly_ as shown.
+Note that the name of the service (`ncssGrid` in this example) is arbitrary, but the `serviceType` and base must be _exactly_ as shown.
 
 ## Restrictions On What Files Can Be Served
 

diff --git a/...uickstart/src/site/pages/tds_tutorial/tds_configuration/AddingOgcIsoServices.md b/...uickstart/src/site/pages/tds_tutorial/tds_configuration/AddingOgcIsoServices.md
@@ -65,7 +65,7 @@ Adding them to an existing compound service would look something like this:
     <service name="odap" serviceType="OpenDAP" base="/thredds/dodsC/" />
     <service name="wcs" serviceType="WCS" base="/thredds/wcs/" />
     <service name="wms" serviceType="WMS" base="/thredds/wms/" />
-    <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/" />
+    <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
     <service name="http" serviceType="HTTPServer" base="/thredds/fileServer/" />
 </service>
 ~~~
@@ -80,7 +80,7 @@ For instance, adding to the same compound service as above:
     <service name="odap" serviceType="OpenDAP" base="/thredds/dodsC/" />
     <service name="wcs" serviceType="WCS" base="/thredds/wcs/" />
     <service name="wms" serviceType="WMS" base="/thredds/wms/" />
-    <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/" />
+    <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
     <service name="http" serviceType="HTTPServer" base="/thredds/fileServer/" />
     <service name="ncml" serviceType="NCML" base="/thredds/ncml/" />
     <service name="uddc" serviceType="UDDC" base="/thredds/uddc/" />

diff --git a/docs/quickstart/src/site/pages/tds_tutorial/tds_configuration/ConfigCatalog.md b/docs/quickstart/src/site/pages/tds_tutorial/tds_configuration/ConfigCatalog.md
@@ -111,13 +111,13 @@ Therefore, it is required that service base URLs must [exactly match the values
 
 * NetCDF Subset Service (Grid Data)
    ~~~xml
-   <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
+   <service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
    ~~~
 
 * NetCDF Subset Service (Point Data)
 
    ~~~xml
-   <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/point/" />
+   <service name="ncssPoint" serviceType="NetcdfSubset" base="/thredds/ncss/point/" />
    ~~~
 
 * WCS

diff --git a/docs/quickstart/src/site/pages/thredds/TdsServices.md b/docs/quickstart/src/site/pages/thredds/TdsServices.md
@@ -229,9 +229,17 @@ The `serviceType` and `base` values are **required** in the following examples:
 ~~~
 
 #### NetCDF Subset Service
-
+
+For Feature Type `GRID`, use:
+
+~~~xml
+<service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
+~~~
+
+For Feature Types `POINT` or `STATION`, use:
+
 ~~~xml
-  <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/"/>
+<service name="ncssPoint" serviceType="NetcdfSubset" base="/thredds/ncss/point/" />
 ~~~
 
 #### WCS
@@ -275,7 +283,7 @@ The `serviceType` and `base` values are **required** in the following examples:
 <service name="all" serviceType="Compound" base="">
   <service name="HTTPServer" serviceType="HTTPServer" base="/thredds/fileServer/"/>
   <service name="opendap" serviceType="OPENDAP" base="/thredds/dodsC/"/>
-  <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/"/>
+  <service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/"/>
   <service name="cdmremote" serviceType="CdmRemote" base="/thredds/cdmremote/"/>
 
   <service name="wcs" serviceType="WCS" base="/thredds/wcs/"/>

diff --git a/docs/quickstart/src/site/pages/thredds/ViewersRef.md b/docs/quickstart/src/site/pages/thredds/ViewersRef.md
@@ -119,7 +119,7 @@ Use the service type inside of curly brackets to select which access URL to use.
   <service name="http" serviceType="HTTPServer" base="/thredds/fileServer/"/>
   <service name="wcs" serviceType="WCS" base="/thredds/wcs/"/>
   <service name="wms" serviceType="WMS" base="/thredds/wms/"/>
-  <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/"/>
+  <service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/"/>
   <service name="cdmremote" serviceType="CdmRemote" base="/thredds/cdmremote/"/>
   <service name="iso" serviceType="ISO" base="/thredds/iso/"/>
   <service name="ncml" serviceType="NCML" base="/thredds/ncml/"/>

diff --git a/docs/userguide/src/site/pages/tds_tutorial/production/Upgrade.md b/docs/userguide/src/site/pages/tds_tutorial/production/Upgrade.md
@@ -37,7 +37,19 @@ Deprecated classes and methods have been removed, and the module structure and t
 ### Netcdf Subset Service (NCSS)
 
 NCSS queries and responses have been improved and clarified.
-Generally the previous queries are backwards compatible. See [NCSS Reference](netcdf_subset_service_ref.html) for details.
+Generally the previous queries are backwards compatible.
+See [NCSS Reference](netcdf_subset_service_ref.html) for details.
+
+Catalog (config and client) base changes:
+* NCSS service has been split and now has two different paths, depending on the feature type of data being served.
+* For `GRID`, use:
+  ~~~
+  <service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
+  ~~~
+  and for `POINT` or `STATION`, use:
+  ~~~xml
+  <service name="ncssPoint" serviceType="NetcdfSubset" base="/thredds/ncss/point/" />
+  ~~~
 
 New functionality:
 * 2D time can now be handled for gridded datasets, with addition of `runtime` and `timeOffset` parameters.

diff --git a/docs/userguide/src/site/pages/tds_tutorial/tds_configuration/AddingNcss.md b/docs/userguide/src/site/pages/tds_tutorial/tds_configuration/AddingNcss.md
@@ -31,21 +31,28 @@ Details on other configuration options for NCSS are available in the [`threddsCo
 
 ## Serving Datasets With NCSS
 
-In your configuration catalogs, you must define the service like this:
+In your configuration catalogs, you must define the service based on the type of data being served.
+For Feature Type `GRID`, use:
 
 ~~~xml
-<service name="subsetServer" serviceType="NetcdfSubset" base="/thredds/ncss/" />
+<service name="ncssGrid" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
+~~~
+
+For Feature Types `POINT` or `STATION`, use:
+
+~~~xml
+<service name="ncssPoint" serviceType="NetcdfSubset" base="/thredds/ncss/point/" />
 ~~~
 
 Then as usual, add the service to any datasets that you want served, e.g.:
 
 ~~~xml
 <dataset name="datasetName" ID="datasetID" urlPath="/my/urlPath"> 
-   <serviceName>subsetServer</serviceName> 
+   <serviceName>ncssGrid</serviceName> 
 </dataset> 
 ~~~
 
-Note that the name of the service (`subsetServer` in this example) is arbitrary, but the `serviceType` and base must be _exactly_ as shown.
+Note that the name of the service (`ncssGrid` in this example) is arbitrary, but the `serviceType` and base must be _exactly_ as shown.
 
 ## Restrictions On What Files Can Be Served
 

diff --git a/...userguide/src/site/pages/tds_tutorial/tds_configuration/AddingOgcIsoServices.md b/...userguide/src/site/pages/tds_tutorial/tds_configuration/AddingOgcIsoServices.md
@@ -86,7 +86,7 @@ Adding them to an existing compound service would look something like this:
     <service name="odap" serviceType="OpenDAP" base="/thredds/dodsC/" />
     <service name="wcs" serviceType="WCS" base="/thredds/wcs/" />
     <service name="wms" serviceType="WMS" base="/thredds/wms/" />
-    <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/" />
+    <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
     <service name="http" serviceType="HTTPServer" base="/thredds/fileServer/" />
 </service>
 ~~~
@@ -101,7 +101,7 @@ For instance, adding to the same compound service as above:
     <service name="odap" serviceType="OpenDAP" base="/thredds/dodsC/" />
     <service name="wcs" serviceType="WCS" base="/thredds/wcs/" />
     <service name="wms" serviceType="WMS" base="/thredds/wms/" />
-    <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/" />
+    <service name="ncss" serviceType="NetcdfSubset" base="/thredds/ncss/grid/" />
     <service name="http" serviceType="HTTPServer" base="/thredds/fileServer/" />
     <service name="ncml" serviceType="NCML" base="/thredds/ncml/" />
     <service name="uddc" serviceType="UDDC" base="/thredds/uddc/" />