docs: annotate properly settings and refer to autodoc from the README…

… files (#4084)

* docs: annotate properly settings and refer to autodoc from the README files (#3986)

* avoid outdatedness of the documentation of config params in README files

* docs: simplify description of setting

Co-authored-by: Jim Marino <jim.marino@gmail.com>

* fix: avoid string to int conversion in config parameters

* docs: annotate properly the settings and unify their usage

* chore: update DEPENDENCIES file

* chore: remove unneeded sections from README

---------

Co-authored-by: Jim Marino <jim.marino@gmail.com>

core/common/connector-core/README.md

@@ -1,18 +1,3 @@
 # Connector-core
 
 Extension that registers default and core services as default implementations, http client, in memory stores and so on.
-
-## Configuration settings
-
-| Parameter name                           | Description                                                          | Mandatory | Default value |
-|------------------------------------------|----------------------------------------------------------------------|-----------|---------------|
-| `edc.hostname`                           | Connector hostname, which e.g. is used in referer urls               | false     | localhost     |
-| `edc.http.enforce-https`                 | If true, enable HTTPS call enforcement.                              | false     | false         |
-| `edc.core.retry.retries.max`             | Maximum retries for the retry policy before a failure is propagated. | false     | 5             |
-| `edc.core.retry.backoff.min`             | Minimum number of milliseconds for exponential backoff.              | false     | 500           |
-| `edc.core.retry.backoff.max`             | Maximum number of milliseconds for exponential backoff.              | false     | 10000         |
-| `edc.core.retry.log.on.retry`            | Log Failsafe onRetry events.                                         | false     | false         |
-| `edc.core.retry.log.on.retry.scheduled`  | Log Failsafe onRetryScheduled events.                                | false     | false         |
-| `edc.core.retry.log.on.retries.exceeded` | Log Failsafe onRetriesExceeded events.                               | false     | false         |
-| `edc.core.retry.log.on.failed.attempt`   | Log Failsafe onFailedAttempt events.                                 | false     | false         |
-| `edc.core.retry.log.on.abort`            | Log Failsafe onAbort events.                                         | false     | false         |

core/common/connector-core/src/main/java/org/eclipse/edc/connector/core/CoreDefaultServicesExtension.java

@@ -39,8 +39,6 @@
 
 import java.util.concurrent.Executors;
 
-import static java.lang.Integer.parseInt;
-
 /**
  * Provides default service implementations for fallback
  * Omitted {@link Extension} since this module contains the extension {@link CoreServicesExtension}
@@ -49,39 +47,46 @@ public class CoreDefaultServicesExtension implements ServiceExtension {
 
     public static final String NAME = "Core Default Services";
 
-    private static final String RETRY_POLICY_DEFAULT_RETRIES = "5";
-    private static final String RETRY_POLICY_DEFAULT_MIN_BACKOFF = "500";
-    private static final String RETRY_POLICY_DEFAULT_MAX_BACKOFF = "10000";
-    private static final String RETRY_POLICY_DEFAULT_LOG = "false";
-    @Setting(value = "RetryPolicy: Maximum retries before a failure is propagated", defaultValue = RETRY_POLICY_DEFAULT_RETRIES)
+    private static final int DEFAULT_RETRY_POLICY_MAX_RETRIES = 5;
+    private static final int DEFAULT_RETRY_POLICY_BACKOFF_MIN_MILLIS = 500;
+    private static final int DEFAULT_RETRY_POLICY_BACKOFF_MAX_MILLIS = 10000;
+    private static final boolean DEFAULT_RETRY_POLICY_LOG_ON_RETRY = false;
+    private static final boolean DEFAULT_RETRY_POLICY_LOG_ON_RETRY_SCHEDULED = false;
+    private static final boolean DEFAULT_RETRY_POLICY_LOG_ON_RETRIES_EXCEEDED = false;
+    private static final boolean DEFAULT_RETRY_POLICY_LOG_ON_FAILED_ATTEMPT = false;
+    private static final boolean DEFAULT_RETRY_POLICY_LOG_ON_ABORT = false;
+    private static final int DEFAULT_OK_HTTP_CLIENT_TIMEOUT_CONNECT = 30;
+    private static final int DEFAULT_OK_HTTP_CLIENT_TIMEOUT_READ = 30;
+    private static final boolean DEFAULT_OK_HTTP_CLIENT_HTTPS_ENFORCE = false;
+    private static final int DEFAULT_OK_HTTP_CLIENT_SEND_BUFFER_SIZE = 0;
+    private static final int DEFAULT_OK_HTTP_CLIENT_RECEIVE_BUFFER_SIZE = 0;
+
+    @Setting(value = "RetryPolicy: Maximum retries before a failure is propagated", defaultValue = DEFAULT_RETRY_POLICY_MAX_RETRIES + "", type = "int")
     private static final String RETRY_POLICY_MAX_RETRIES = "edc.core.retry.retries.max";
-    @Setting(value = "RetryPolicy: Minimum number of milliseconds for exponential backoff", defaultValue = RETRY_POLICY_DEFAULT_MIN_BACKOFF)
+    @Setting(value = "RetryPolicy: Minimum number of milliseconds for exponential backoff", defaultValue = DEFAULT_RETRY_POLICY_BACKOFF_MIN_MILLIS + "", type = "int")
     private static final String RETRY_POLICY_BACKOFF_MIN_MILLIS = "edc.core.retry.backoff.min";
-    @Setting(value = "RetryPolicy: Maximum number of milliseconds for exponential backoff.", defaultValue = RETRY_POLICY_DEFAULT_MAX_BACKOFF)
+    @Setting(value = "RetryPolicy: Maximum number of milliseconds for exponential backoff", defaultValue = DEFAULT_RETRY_POLICY_BACKOFF_MAX_MILLIS + "", type = "int")
     private static final String RETRY_POLICY_BACKOFF_MAX_MILLIS = "edc.core.retry.backoff.max";
-    @Setting(value = "RetryPolicy: Log onRetry events", defaultValue = RETRY_POLICY_DEFAULT_LOG)
-    static final String RETRY_POLICY_LOG_ON_RETRY = "edc.core.retry.log.on.retry";
-    @Setting(value = "RetryPolicy: Log onRetryScheduled events", defaultValue = RETRY_POLICY_DEFAULT_LOG)
-    static final String RETRY_POLICY_LOG_ON_RETRY_SCHEDULED = "edc.core.retry.log.on.retry.scheduled";
-    @Setting(value = "RetryPolicy: Log onRetriesExceeded events", defaultValue = RETRY_POLICY_DEFAULT_LOG)
-    static final String RETRY_POLICY_LOG_ON_RETRIES_EXCEEDED = "edc.core.retry.log.on.retries.exceeded";
-    @Setting(value = "RetryPolicy: Log onFailedAttempt events", defaultValue = RETRY_POLICY_DEFAULT_LOG)
-    static final String RETRY_POLICY_LOG_ON_FAILED_ATTEMPT = "edc.core.retry.log.on.failed.attempt";
-    @Setting(value = "RetryPolicy: Log onAbort events", defaultValue = RETRY_POLICY_DEFAULT_LOG)
-    static final String RETRY_POLICY_LOG_ON_ABORT = "edc.core.retry.log.on.abort";
-
-    private static final String OK_HTTP_CLIENT_DEFAULT_TIMEOUT = "30";
-    private static final String OK_HTTP_CLIENT_DEFAULT_HTTPS_ENFORCE = "false";
-    @Setting(value = "OkHttpClient: If true, enable HTTPS call enforcement.", defaultValue = OK_HTTP_CLIENT_DEFAULT_HTTPS_ENFORCE, type = "boolean")
-    public static final String OK_HTTP_CLIENT_HTTPS_ENFORCE = "edc.http.client.https.enforce";
-    @Setting(value = "OkHttpClient: connect timeout, in seconds", defaultValue = OK_HTTP_CLIENT_DEFAULT_TIMEOUT, type = "int")
-    public static final String OK_HTTP_CLIENT_TIMEOUT_CONNECT = "edc.http.client.timeout.connect";
-    @Setting(value = "OkHttpClient: read timeout, in seconds", defaultValue = OK_HTTP_CLIENT_DEFAULT_TIMEOUT, type = "int")
-    public static final String OK_HTTP_CLIENT_TIMEOUT_READ = "edc.http.client.timeout.read";
-    @Setting(value = "OkHttpClient: send buffer size, in bytes", type = "int", min = 1)
-    public static final String OK_HTTP_CLIENT_SEND_BUFFER_SIZE = "edc.http.client.send.buffer.size";
-    @Setting(value = "OkHttpClient: receive buffer size, in bytes", type = "int", min = 1)
-    public static final String OK_HTTP_CLIENT_RECEIVE_BUFFER_SIZE = "edc.http.client.receive.buffer.size";
+    @Setting(value = "RetryPolicy: Log onRetry events", defaultValue = DEFAULT_RETRY_POLICY_LOG_ON_RETRY + "", type = "boolean")
+    private static final String RETRY_POLICY_LOG_ON_RETRY = "edc.core.retry.log.on.retry";
+    @Setting(value = "RetryPolicy: Log onRetryScheduled events", defaultValue = DEFAULT_RETRY_POLICY_LOG_ON_RETRY_SCHEDULED + "", type = "boolean")
+    private static final String RETRY_POLICY_LOG_ON_RETRY_SCHEDULED = "edc.core.retry.log.on.retry.scheduled";
+    @Setting(value = "RetryPolicy: Log onRetriesExceeded events", defaultValue = DEFAULT_RETRY_POLICY_LOG_ON_RETRIES_EXCEEDED + "", type = "boolean")
+    private static final String RETRY_POLICY_LOG_ON_RETRIES_EXCEEDED = "edc.core.retry.log.on.retries.exceeded";
+    @Setting(value = "RetryPolicy: Log onFailedAttempt events", defaultValue = DEFAULT_RETRY_POLICY_LOG_ON_FAILED_ATTEMPT + "", type = "boolean")
+    private static final String RETRY_POLICY_LOG_ON_FAILED_ATTEMPT = "edc.core.retry.log.on.failed.attempt";
+    @Setting(value = "RetryPolicy: Log onAbort events", defaultValue = DEFAULT_RETRY_POLICY_LOG_ON_ABORT + "", type = "boolean")
+    private static final String RETRY_POLICY_LOG_ON_ABORT = "edc.core.retry.log.on.abort";
+    @Setting(value = "OkHttpClient: If true, enable HTTPS call enforcement", defaultValue = DEFAULT_OK_HTTP_CLIENT_HTTPS_ENFORCE + "", type = "boolean")
+    private static final String OK_HTTP_CLIENT_HTTPS_ENFORCE = "edc.http.client.https.enforce";
+    @Setting(value = "OkHttpClient: connect timeout, in seconds", defaultValue = DEFAULT_OK_HTTP_CLIENT_TIMEOUT_CONNECT + "", type = "int")
+    private static final String OK_HTTP_CLIENT_TIMEOUT_CONNECT = "edc.http.client.timeout.connect";
+    @Setting(value = "OkHttpClient: read timeout, in seconds", defaultValue = DEFAULT_OK_HTTP_CLIENT_TIMEOUT_READ + "", type = "int")
+    private static final String OK_HTTP_CLIENT_TIMEOUT_READ = "edc.http.client.timeout.read";
+    @Setting(value = "OkHttpClient: send buffer size, in bytes", defaultValue = DEFAULT_OK_HTTP_CLIENT_SEND_BUFFER_SIZE + "", type = "int", min = 1)
+    private static final String OK_HTTP_CLIENT_SEND_BUFFER_SIZE = "edc.http.client.send.buffer.size";
+    @Setting(value = "OkHttpClient: receive buffer size, in bytes", defaultValue = DEFAULT_OK_HTTP_CLIENT_RECEIVE_BUFFER_SIZE + "", type = "int", min = 1)
+    private static final String OK_HTTP_CLIENT_RECEIVE_BUFFER_SIZE = "edc.http.client.receive.buffer.size";
 
     /**
      * An optional OkHttp {@link EventListener} that can be used to instrument OkHttp client for collecting metrics.
@@ -123,11 +128,11 @@ public EdcHttpClient edcHttpClient(ServiceExtensionContext context) {
     @Provider
     public OkHttpClient okHttpClient(ServiceExtensionContext context) {
         var configuration = OkHttpClientConfiguration.Builder.newInstance()
-                .enforceHttps(context.getSetting(OK_HTTP_CLIENT_HTTPS_ENFORCE, Boolean.parseBoolean(OK_HTTP_CLIENT_DEFAULT_HTTPS_ENFORCE)))
-                .connectTimeout(context.getSetting(OK_HTTP_CLIENT_TIMEOUT_CONNECT, parseInt(OK_HTTP_CLIENT_DEFAULT_TIMEOUT)))
-                .readTimeout(context.getSetting(OK_HTTP_CLIENT_TIMEOUT_READ, parseInt(OK_HTTP_CLIENT_DEFAULT_TIMEOUT)))
-                .sendBufferSize(context.getSetting(OK_HTTP_CLIENT_SEND_BUFFER_SIZE, 0))
-                .receiveBufferSize(context.getSetting(OK_HTTP_CLIENT_RECEIVE_BUFFER_SIZE, 0))
+                .enforceHttps(context.getSetting(OK_HTTP_CLIENT_HTTPS_ENFORCE, DEFAULT_OK_HTTP_CLIENT_HTTPS_ENFORCE))
+                .connectTimeout(context.getSetting(OK_HTTP_CLIENT_TIMEOUT_CONNECT, DEFAULT_OK_HTTP_CLIENT_TIMEOUT_CONNECT))
+                .readTimeout(context.getSetting(OK_HTTP_CLIENT_TIMEOUT_READ, DEFAULT_OK_HTTP_CLIENT_TIMEOUT_READ))
+                .sendBufferSize(context.getSetting(OK_HTTP_CLIENT_SEND_BUFFER_SIZE, DEFAULT_OK_HTTP_CLIENT_SEND_BUFFER_SIZE))
+                .receiveBufferSize(context.getSetting(OK_HTTP_CLIENT_RECEIVE_BUFFER_SIZE, DEFAULT_OK_HTTP_CLIENT_RECEIVE_BUFFER_SIZE))
                 .build();
 
         return OkHttpClientFactory.create(configuration, okHttpEventListener, context.getMonitor());
@@ -136,14 +141,14 @@ public OkHttpClient okHttpClient(ServiceExtensionContext context) {
     @Provider
     public <T> RetryPolicy<T> retryPolicy(ServiceExtensionContext context) {
         var configuration = RetryPolicyConfiguration.Builder.newInstance()
-                .maxRetries(context.getSetting(RETRY_POLICY_MAX_RETRIES, parseInt(RETRY_POLICY_DEFAULT_RETRIES)))
-                .minBackoff(context.getSetting(RETRY_POLICY_BACKOFF_MIN_MILLIS, parseInt(RETRY_POLICY_DEFAULT_MIN_BACKOFF)))
-                .maxBackoff(context.getSetting(RETRY_POLICY_BACKOFF_MAX_MILLIS, parseInt(RETRY_POLICY_DEFAULT_MAX_BACKOFF)))
-                .logOnRetry(context.getSetting(RETRY_POLICY_LOG_ON_RETRY, false))
-                .logOnRetryScheduled(context.getSetting(RETRY_POLICY_LOG_ON_RETRY_SCHEDULED, false))
-                .logOnRetriesExceeded(context.getSetting(RETRY_POLICY_LOG_ON_RETRIES_EXCEEDED, false))
-                .logOnFailedAttempt(context.getSetting(RETRY_POLICY_LOG_ON_FAILED_ATTEMPT, false))
-                .logOnAbort(context.getSetting(RETRY_POLICY_LOG_ON_ABORT, false))
+                .maxRetries(context.getSetting(RETRY_POLICY_MAX_RETRIES, DEFAULT_RETRY_POLICY_MAX_RETRIES))
+                .minBackoff(context.getSetting(RETRY_POLICY_BACKOFF_MIN_MILLIS, DEFAULT_RETRY_POLICY_BACKOFF_MIN_MILLIS))
+                .maxBackoff(context.getSetting(RETRY_POLICY_BACKOFF_MAX_MILLIS, DEFAULT_RETRY_POLICY_BACKOFF_MAX_MILLIS))
+                .logOnRetry(context.getSetting(RETRY_POLICY_LOG_ON_RETRY, DEFAULT_RETRY_POLICY_LOG_ON_RETRY))
+                .logOnRetryScheduled(context.getSetting(RETRY_POLICY_LOG_ON_RETRY_SCHEDULED, DEFAULT_RETRY_POLICY_LOG_ON_RETRY_SCHEDULED))
+                .logOnRetriesExceeded(context.getSetting(RETRY_POLICY_LOG_ON_RETRIES_EXCEEDED, DEFAULT_RETRY_POLICY_LOG_ON_RETRIES_EXCEEDED))
+                .logOnFailedAttempt(context.getSetting(RETRY_POLICY_LOG_ON_FAILED_ATTEMPT, DEFAULT_RETRY_POLICY_LOG_ON_FAILED_ATTEMPT))
+                .logOnAbort(context.getSetting(RETRY_POLICY_LOG_ON_ABORT, DEFAULT_RETRY_POLICY_LOG_ON_ABORT))
                 .build();
 
         return RetryPolicyFactory.create(configuration, context.getMonitor());

core/common/connector-core/src/main/java/org/eclipse/edc/connector/core/CoreServicesExtension.java

@@ -53,17 +53,14 @@
 @Extension(value = CoreServicesExtension.NAME)
 public class CoreServicesExtension implements ServiceExtension {
 
-    @Setting
-    public static final String HOSTNAME_SETTING = "edc.hostname";
+    public static final String NAME = "Core Services";
 
-    /**
-     * The name of the claim key used to determine the participant identity.
-     */
-    @Setting
-    public static final String IDENTITY_KEY = "edc.agent.identity.key";
+    private static final String DEFAULT_EDC_HOSTNAME = "localhost";
 
-    public static final String NAME = "Core Services";
-    private static final String DEFAULT_HOSTNAME = "localhost";
+    @Setting(value = "Connector hostname, which e.g. is used in referer urls", defaultValue = DEFAULT_EDC_HOSTNAME)
+    public static final String EDC_HOSTNAME = "edc.hostname";
+    @Setting(value = "The name of the claim key used to determine the participant identity", defaultValue = DEFAULT_IDENTITY_CLAIM_KEY)
+    public static final String EDC_AGENT_IDENTITY_KEY = "edc.agent.identity.key";
 
     @Inject
     private EventExecutorServiceContainer eventExecutorServiceContainer;
@@ -103,9 +100,9 @@ public TypeManager typeManager() {
 
     @Provider
     public Hostname hostname(ServiceExtensionContext context) {
-        var hostname = context.getSetting(HOSTNAME_SETTING, DEFAULT_HOSTNAME);
-        if (DEFAULT_HOSTNAME.equals(hostname)) {
-            context.getMonitor().warning(String.format("Settings: No setting found for key '%s'. Using default value '%s'", HOSTNAME_SETTING, DEFAULT_HOSTNAME));
+        var hostname = context.getSetting(EDC_HOSTNAME, DEFAULT_EDC_HOSTNAME);
+        if (DEFAULT_EDC_HOSTNAME.equals(hostname)) {
+            context.getMonitor().warning(String.format("Settings: No setting found for key '%s'. Using default value '%s'", EDC_HOSTNAME, DEFAULT_EDC_HOSTNAME));
         }
         return () -> hostname;
     }
@@ -122,7 +119,7 @@ public CommandHandlerRegistry commandHandlerRegistry() {
 
     @Provider
     public ParticipantAgentService participantAgentService(ServiceExtensionContext context) {
-        var identityKey = context.getSetting(IDENTITY_KEY, DEFAULT_IDENTITY_CLAIM_KEY);
+        var identityKey = context.getSetting(EDC_AGENT_IDENTITY_KEY, DEFAULT_IDENTITY_CLAIM_KEY);
         return new ParticipantAgentServiceImpl(identityKey);
     }
 

core/common/connector-core/src/test/java/org/eclipse/edc/connector/core/CoreServicesExtensionIntegrationTest.java

@@ -23,14 +23,14 @@
 import java.util.Map;
 
 import static org.assertj.core.api.Assertions.assertThat;
-import static org.eclipse.edc.connector.core.CoreServicesExtension.HOSTNAME_SETTING;
+import static org.eclipse.edc.connector.core.CoreServicesExtension.EDC_HOSTNAME;
 
 @ExtendWith(EdcExtension.class)
 class CoreServicesExtensionIntegrationTest {
 
     @BeforeEach
     void setUp(EdcExtension extension) {
-        extension.setConfiguration(Map.of(HOSTNAME_SETTING, "hostname"));
+        extension.setConfiguration(Map.of(EDC_HOSTNAME, "hostname"));
     }
 
     @Test

extensions/control-plane/transfer/transfer-data-plane/README.md

@@ -41,12 +41,3 @@ put these data into its Azure Blob Storage.
 
 This extension introduces a Control Plane endpoint used by the Data Plane for validating the access token received in input
 of its public API. OpenApi documentation can be found [here](../../../../resources/openapi/yaml/transfer-data-plane.yaml).
-
-### Configurations
-
-| Parameter name                                      | Description                                                                                    | Mandatory | Default value         |
-|:----------------------------------------------------|:-----------------------------------------------------------------------------------------------|:----------|:----------------------|
-| `edc.transfer.proxy.token.validity.seconds`         | Validity (in seconds) of tokens generated by the extension for accessing Data Plane public API | false     | 600                   | 
-| `edc.transfer.client.selector.strategy`             | Strategy for Data Plane instance selection                                                     | false     | random                |
-| `edc.transfer.proxy.token.signer.privatekey.alias`  | Alias of private key used for signing tokens                                                   | false     | Random EC public key  |
-| `edc.transfer.proxy.token.verifier.publickey.alias` | Alias of public key used for verifying the tokens                                              | false     | Random EC private key |

extensions/data-plane/data-plane-control-api/README.md

@@ -48,12 +48,6 @@ _Provide some information about dependencies, e.g., used extensions._
 |:--------|:---------------------------------------------|
 | web-spi | Essentially for the Controllers registration |
 
-### Configurations
-
-| Parameter name                                      | Description                                                                                       | Mandatory | Default value                          |
-|:----------------------------------------------------|:--------------------------------------------------------------------------------------------------|:----------|:---------------------------------------|
-| `edc.dataplane.token.validation.endpoint`  | Endpoint of the token validation server that will be hit when targeting the Data Plane public API | true      |                                        |
-
 ## Design Principles
 
 Both public and control APIs rely on the `DataPlaneManager` for executing the actual data transfer, see [Data Plane Framework](../../../core/data-plane/data-plane-framework/README.md) for more details.

extensions/data-plane/data-plane-http/README.md

@@ -21,14 +21,6 @@ Typically, this extension is used to fetch or post data from/to a REST endpoint.
 |:-------------------------------------|:----------------------|
 | extensions:data-plane:data-plane-spi | SPI of the data plane |
 
-### Configurations
-
-The setting parameters of this extension are listed below:
-
-| Parameter name                           | Description                                                          | Mandatory | Default value |
-|:-----------------------------------------|:---------------------------------------------------------------------|:----------|:--------------|
-| `edc.dataplane.http.sink.partition.size` | Number of partitions for parallel message push in the `HttpDataSink` | false     | 5             |
-
 ### Provided Services
 
 #### `HttpRequestParamsProvider`