Added a new example to the Overview section

README.md

@@ -49,14 +49,14 @@ Besides `BIN_DIR` and `LIB_DIR` above, the scripts leverage the following enviro
 
 | Variable | |
 | --- | --- |
-| `CACHE_DIR` | A persistent HTTP cache |
+| `CACHE_DIR` | A persistent HTTP cache directory |
 | `TMPDIR` | A temporary directory |
 | `LOG_FILE` | A persistent log file |
 | `LOG_LEVEL` | The global log level [0..5] |
 
 All but `LOG_LEVEL` are REQUIRED. See the following section for more info about logging.
 
-Note: Some OSes define `TMPDIR` and some do not. In any case, a temporary directory is required to use these scripts.
+Note: Some OSes define `TMPDIR` and some do not. In any case, a temporary directory by that name is required to use these scripts.
 
 ## Logging
 
@@ -82,12 +82,11 @@ The default logging level is INFO (i.e., if you do not explicitly set the option
 
 ## Overview
 
-First define a couple of HTTP resources and a cache:
+The following HTTP resources are used repeatedly in the examples below:
 
 ```Shell
 $ url1=http://md.incommon.org/InCommon/InCommon-metadata-preview.xml
 $ url2=http://md.incommon.org/InCommon/InCommon-metadata-fallback.xml
-$ export CACHE_DIR=/tmp/http_cache
 ```
 
 ### `request_http_resources.sh`
@@ -130,11 +129,9 @@ $ $BIN_DIR/request_http_resources.sh -h
 
 Bash script `cget.sh` retrieves and caches HTTP resources on disk. A previously cached resource is retrieved via HTTP Conditional GET [RFC 7232]. If the web server responds with HTTP 200 OK, the resource is cached and written to stdout. If the web server responds with 304 Not Modified, the cached resource is output instead.
 
-First define a couple of HTTP resources and a cache:
+First define a cache:
 
 ```Shell
-$ url1=http://md.incommon.org/InCommon/InCommon-metadata-preview.xml
-$ url2=http://md.incommon.org/InCommon/InCommon-metadata-fallback.xml
 $ export CACHE_DIR=/tmp/http_cache
 ```
 
@@ -228,7 +225,41 @@ $ $BIN_DIR/cget.sh -h
 
 ### `compute_md_vital_stats.sh`
 
-TBD
+Bash script `compute_md_vital_stats.sh` parses one or more previously cached SAML metadata files:
+
+```Shell
+$ $BIN_DIR/compute_md_vital_stats.sh -d /tmp/out $url1 $url2
+2017-06-11T13:09:53Z INFO compute_md_vital_stats.sh BEGIN
+2017-06-11T13:09:53Z INFO conditional_get reading cached content file: /tmp/http_cache/1e6b844a49d1850b82feded72cf83ed7_content
+2017-06-11T13:09:53Z INFO compute_md_vital_stats.sh parsing cached metadata file: http://md.incommon.org/InCommon/InCommon-metadata-preview.xml
+2017-06-11T13:09:54Z INFO conditional_get reading cached content file: /tmp/http_cache/1727196e5b7593f3b7528c539e7169d2_content
+2017-06-11T13:09:54Z INFO compute_md_vital_stats.sh parsing cached metadata file: http://md.incommon.org/InCommon/InCommon-metadata-fallback.xml
+2017-06-11T13:09:55Z INFO compute_md_vital_stats.sh writing output file: md_vital_statistics.json
+2017-06-11T13:09:55Z INFO compute_md_vital_stats.sh moving output file to dir: /tmp/out
+2017-06-11T13:09:55Z INFO compute_md_vital_stats.sh END
+```
+
+The script produces a JSON array containing objects such as the following:
+
+```JavaScript
+  {
+    "successFlag": true,
+    "message": "Metadata successfully parsed",
+    "metadataLocation": "http://md.incommon.org/InCommon/InCommon-metadata-preview.xml",
+    "currentTime": "2017-06-11T13:09:54Z",
+    "validUntil": "2017-06-23T18:56:31Z",
+    "creationInstant": "2017-06-09T18:56:31Z",
+    "validityInterval": "P14DT0H0M0S",
+    "untilInvalid": "P12DT5H46M37S",
+    "sinceCreation": "P1DT18H13M23S"
+  }
+```
+
+Note that this script depends on cached metadata. It will not fetch a metadata file from the server. See the inline help file for details:
+
+```Shell
+$ $BIN_DIR/compute_md_vital_stats.sh -h
+```
 
 ### `test_compressed_resources.sh`