Update documentation to follow API changes

nbbrd · Sep 6, 2024 · af44f80 · af44f80
1 parent c1e7ba6
commit af44f80
Show file tree

Hide file tree

Showing 6 changed files with 44 additions and 22 deletions.
diff --git a/docs/content/cli/configuration.md b/docs/content/cli/configuration.md
@@ -3,7 +3,7 @@ title: "Configuration"
 weight: 2
 ---
 
-**sdmx-dl CLI** is designed to work out-of-the-box but can be configured if needed by using several [properties files](#properties-files).
+**sdmx-dl CLI** is designed to work out-of-the-box but can be configured if needed by using command-line options, properties files, execution properties and environmental variables.
 
 {{< toc >}}
 
@@ -17,39 +17,45 @@ All these files are named `sdmx-dl.properties` and are located in 3 different fo
 
 Each of these scopes overwrites properties defined in the previous scope; for example, properties in execution folder overrides those in user profile folder.
 
-## Command options
-
-The default values of [command options](../options) can be overridden in two ways:
+The default values of [command-line options](../options) can be overridden in two ways:
 
 - **Widely** by targeting any command using their option names.  
     ```properties
     # enable verbose mode on all commands
     verbose=true
-    # use UNIX new-line type on all commands
-    new-line=UNIX
+    # set languages on all commands
+    languages=fr,nl,en
     ```
 - **Narrowly** by targeting a specific command using their option names prefixed by the command full path.  
     ```properties
     # enable verbose mode on status command
     sdmx-dl.check.status.verbose=true
-    # use UNIX new-line type on status command
-    sdmx-dl.check.status.new-line=UNIX
+    # set languages on status command
+    sdmx-dl.check.status.languages=fr,nl,en
     ```
 
 ## Execution properties
 
 Execution properties can be customized using [Java system property](https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html).  
 There are several types of system properties: some are defined by the platform, others by the libraries.
 
-{{< expand "sdmx-dl properties" >}}
+{{< expand "Specific sdmx-dl properties" >}}
 
-| Property                   | Description                               |
-|----------------------------|-------------------------------------------|
-| `sdmxdl.driver.dumpFolder` | Folder used to dump body of web responses |
+| Property                         | Description                      |
+|----------------------------------|----------------------------------|
+| `sdmxdl.caching.noCache`         | Disable caching                  |
+| `sdmxdl.caching.cacheFolder`     | Set cache folder                 |
+| `sdmxdl.caching.noCompression`   | Disable cache compression        |
+| `sdmxdl.caching.persistenceId`   | Set cache persistence backend    |
+| `sdmxdl.networking.autoProxy`    | Enable automatic proxy detection |
+| `sdmxdl.networking.noSystemSSL`  | Disable system truststore        |
+| `sdmxdl.networking.noDefaultSSL` | Disable default truststore       |
+| `sdmxdl.networking.urlBackend`   | Set networking URL backend       |
+| `sdmxdl.registry.sourceFile`     | Set data source definitions file |
 
 {{< /expand >}}
 
-{{< expand "Command-line properties" >}}
+{{< expand "Generic command-line properties" >}}
 
 | Property                            | Description                      |
 |-------------------------------------|----------------------------------|
@@ -58,7 +64,7 @@ There are several types of system properties: some are defined by the platform,
 
 {{< /expand >}}
 
-{{< expand "Networking properties" >}}
+{{< expand "Java networking properties" >}}
 
 | Property             | Description                                                                 |
 |----------------------|-----------------------------------------------------------------------------|
@@ -72,7 +78,7 @@ More on https://docs.oracle.com/javase/8/docs/api/java/net/doc-files/net-propert
 
 {{< /expand >}}
 
-{{< expand "Security properties" >}}
+{{< expand "Java security properties" >}}
 
 | Property                           | Description          |
 |------------------------------------|----------------------|
@@ -87,10 +93,17 @@ More on https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSS
 
 {{< /expand >}}
 
+## Environmental variables
+
+Specific sdmx-dl properties can also be set using environmental variables.
+For each property, the corresponding environmental variable is the same name but uppercase and with dots replaced with underscore.
+
+Example: `sdmxdl.caching.noCache` becomes `SDMXDL_CACHING_NOCACHE`.
+
 ## Troubleshooting
 
 Using properties files is usually error-prone.  
-Fortunately, sdmx-dl CLI includes a [command to pinpoint the problems](../usage#check-properties): `sdmx-dl check properties`
+Fortunately, sdmx-dl CLI includes a [command to pinpoint the problems](../usage#check-config): `sdmx-dl check config`
 
 Common problems:
 

diff --git a/docs/content/cli/usage.md b/docs/content/cli/usage.md
@@ -527,7 +527,8 @@ Other options:
 {{< tab "Output" >}}
 
 CSV columns:
-1. [`SupportedFeature:enum`](../datatypes#enum)
+1. [`Name:string`](../datatypes#string)
+1. [`SupportedProperties:string`](../datatypes#string)
 
 {{< /tab >}}
 {{< /tabs >}}

diff --git a/docs/tmp/usage/list-drivers-sample.md b/docs/tmp/usage/list-drivers-sample.md
@@ -1,5 +1,4 @@
-| Name       | SupportedProperties                                                                                    |
-|------------|--------------------------------------------------------------------------------------------------------|
-| ri:dotstat | connectTimeout,readTimeout,maxRedirects,preemptiveAuthentication                                       |
-| ri:nbb     | connectTimeout,readTimeout,maxRedirects,preemptiveAuthentication                                       |
-| ri:sdmx21  | connectTimeout,readTimeout,maxRedirects,preemptiveAuthentication,detailSupported,trailingSlashRequired |
+| Name         | SupportedProperties                                                                                                                                                                                                       |
+|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| RI_SDMX21    | sdmxdl.driver.connectTimeout,sdmxdl.driver.readTimeout,sdmxdl.driver.maxRedirects,sdmxdl.driver.preemptiveAuth,sdmxdl.driver.userAgent,sdmxdl.driver.dumpFolder,sdmxdl.driver.detailSupported,sdmxdl.driver.trailingSlash |
+| DIALECTS_BBK | sdmxdl.driver.connectTimeout,sdmxdl.driver.readTimeout,sdmxdl.driver.maxRedirects,sdmxdl.driver.preemptiveAuth,sdmxdl.driver.userAgent,sdmxdl.driver.dumpFolder                                                           |
diff --git a/sdmx-dl-provider-ri/src/main/java/sdmxdl/provider/ri/caching/RiCaching.java b/sdmx-dl-provider-ri/src/main/java/sdmxdl/provider/ri/caching/RiCaching.java
@@ -34,18 +34,22 @@
 @ServiceProvider(WebCaching.class)
 public final class RiCaching implements FileCaching, WebCaching {
 
+    // Disable caching
     @PropertyDefinition
     public static final BooleanProperty NO_CACHE_PROPERTY
             = BooleanProperty.of("sdmxdl.caching.noCache", false);
 
+    // Set cache folder
     @PropertyDefinition
     public static final Property<File> CACHE_FOLDER_PROPERTY
             = Property.of("sdmxdl.caching.cacheFolder", null, Parser.onFile(), Formatter.onFile());
 
+    // Disable cache compression
     @PropertyDefinition
     public static final BooleanProperty NO_COMPRESSION_PROPERTY
             = BooleanProperty.of("sdmxdl.caching.noCompression", false);
 
+    // Set cache persistence backend
     @PropertyDefinition
     public static final Property<String> PERSISTENCE_ID_PROPERTY
             = Property.of("sdmxdl.caching.persistenceId", null, Parser.onString(), Formatter.onString());

diff --git a/sdmx-dl-provider-ri/src/main/java/sdmxdl/provider/ri/networking/RiNetworking.java b/sdmx-dl-provider-ri/src/main/java/sdmxdl/provider/ri/networking/RiNetworking.java
@@ -25,18 +25,22 @@
 @ServiceProvider
 public final class RiNetworking implements Networking {
 
+    // Enable automatic proxy detection
     @PropertyDefinition
     public static final BooleanProperty AUTO_PROXY_PROPERTY
             = BooleanProperty.of("sdmxdl.networking.autoProxy", false);
 
+    // Disable system truststore
     @PropertyDefinition
     public static final BooleanProperty NO_SYSTEM_SSL_PROPERTY
             = BooleanProperty.of("sdmxdl.networking.noSystemSSL", false);
 
+    // Disable default truststore
     @PropertyDefinition
     public static final BooleanProperty NO_DEFAULT_SSL_PROPERTY
             = BooleanProperty.of("sdmxdl.networking.noDefaultSSL", false);
 
+    // Set networking URL backend
     @PropertyDefinition
     public static final Property<String> URL_BACKEND_PROPERTY
             = Property.of("sdmxdl.networking.urlBackend", RiNetwork.DEFAULT_URL_BACKEND, Parser.onString(), Formatter.onString());

diff --git a/sdmx-dl-provider-ri/src/main/java/sdmxdl/provider/ri/registry/RiRegistry.java b/sdmx-dl-provider-ri/src/main/java/sdmxdl/provider/ri/registry/RiRegistry.java
@@ -30,6 +30,7 @@ public final class RiRegistry implements Registry {
 
     public static final File NO_SOURCES_FILE = new File("");
 
+    // Set data source definitions file
     @PropertyDefinition
     public static final Property<File> SOURCES_FILE_PROPERTY =
             Property.of("sdmxdl.registry.sourcesFile", NO_SOURCES_FILE, Parser.onFile(), Formatter.onFile());