refactor: restructure samples by scope (#6)

.github/workflows/verify.yaml

@@ -34,72 +34,72 @@ jobs:
       - uses: actions/checkout@v3
       - uses: ./.github/actions/setup-build
 
-      - name: Check Sample 01
+      - name: Check Sample basic-01
         run: |
-          ./gradlew :01-basic-connector:shadowJar
-          echo "Checking Sample 01"
-          java -jar 01-basic-connector/build/libs/basic-connector.jar > log.txt &
+          ./gradlew :basic:basic-01-basic-connector:shadowJar
+          echo "Checking Sample basic-01"
+          java -jar basic/basic-01-basic-connector/build/libs/basic-connector.jar > log.txt &
           sleep 5
           grep "INFO.*edc-.*ready" log.txt
           rm log.txt
           killall java
 
 
-      - name: Check Sample 02
+      - name: Check Sample basic-02
         run: |
-          ./gradlew :02-health-endpoint:shadowJar
-          echo "Checking Sample 02"
-          java -jar 02-health-endpoint/build/libs/connector-health.jar > log.txt &
+          ./gradlew :basic:basic-02-health-endpoint:shadowJar
+          echo "Checking Sample basic-02"
+          java -jar basic/basic-02-health-endpoint/build/libs/connector-health.jar > log.txt &
           sleep 5
           grep "INFO.*edc-.*ready" log.txt
           rm log.txt
           killall java
 
-      - name: Check Sample 03
+      - name: Check Sample basic-03
         run: |
-          ./gradlew :03-configuration:shadowJar
-          echo "Checking Sample 03"
-          java -Dedc.fs.config=03-configuration/config.properties -jar 03-configuration/build/libs/filesystem-config-connector.jar > log.txt &
+          ./gradlew :basic:basic-03-configuration:shadowJar
+          echo "Checking Sample basic-03"
+          java -Dedc.fs.config=basic/basic-03-configuration/config.properties -jar basic/basic-03-configuration/build/libs/filesystem-config-connector.jar > log.txt &
           sleep 5
           grep "INFO.*edc-.*ready" log.txt
           rm log.txt
           killall java
 
-      - name: Check Sample 04.0 (Consumer)
+      - name: Check Sample transfer-01 (Consumer)
         run: |
-          ./gradlew :04.0-file-transfer:file-transfer-consumer:shadowJar
-          echo "Checking Sample 04 - Consumer"
-          java -Dedc.fs.config=04.0-file-transfer/file-transfer-consumer/config.properties -jar 04.0-file-transfer/file-transfer-consumer/build/libs/consumer.jar > log.txt &
+          ./gradlew :transfer:transfer-01-file-transfer:file-transfer-consumer:shadowJar
+          echo "Checking Sample transfer-01 - Consumer"
+          java -Dedc.fs.config=transfer/transfer-01-file-transfer/file-transfer-consumer/config.properties -jar transfer/transfer-01-file-transfer/file-transfer-consumer/build/libs/consumer.jar > log.txt &
           sleep 5
           grep "INFO.*edc-.*ready" log.txt
           rm log.txt
           killall java
 
-      - name: Check Sample 04.0 (Provider)
+      - name: Check Sample transfer-01 (Provider)
         run: |
-          echo "Checking Sample 04 - Provider"
-          ./gradlew :04.0-file-transfer:file-transfer-provider:shadowJar
-          java -Dedc.fs.config=04.0-file-transfer/file-transfer-provider/config.properties -jar 04.0-file-transfer/file-transfer-provider/build/libs/provider.jar > log.txt &
+          echo "Checking Sample transfer-01 - Provider"
+          ./gradlew :transfer:transfer-01-file-transfer:file-transfer-provider:shadowJar
+          java -Dedc.fs.config=transfer/transfer-01-file-transfer/file-transfer-provider/config.properties -jar transfer/transfer-01-file-transfer/file-transfer-provider/build/libs/provider.jar > log.txt &
           sleep 5
           grep "INFO.*edc-.*ready" log.txt
           rm log.txt
           killall java
 
-      - name: Check Sample 04.1 (Consumer)
+      - name: Check Sample transfer-02 (Consumer)
         run: |
-          echo "Checking Sample 04.1 - Consumer"
-          ./gradlew :04.1-file-transfer-listener:file-transfer-listener-consumer:shadowJar
-          java -Dedc.fs.config=04.1-file-transfer-listener/file-transfer-listener-consumer/config.properties -jar 04.1-file-transfer-listener/file-transfer-listener-consumer/build/libs/consumer.jar > log.txt &
+          echo "Checking Sample transfer-02 - Consumer"
+          ./gradlew :transfer:transfer-02-file-transfer-listener:file-transfer-listener-consumer:shadowJar
+          java -Dedc.fs.config=transfer/transfer-02-file-transfer-listener/file-transfer-listener-consumer/config.properties -jar transfer/transfer-02-file-transfer-listener/file-transfer-listener-consumer/build/libs/consumer.jar > log.txt &
           sleep 5
           grep "INFO.*edc-.*ready" log.txt
           rm log.txt
           killall java
 
-      - name: Check Sample 04.2 (Command-Q/Watchdog)
+      - name: Check Sample transfer-03 (Command-Q/Watchdog)
         run: |
-          echo "Checking Sample 04.2 - Command-Q/Watchdog"
-          ./gradlew :04.2-modify-transferprocess:modify-transferprocess-consumer:shadowJar
-          java -Dedc.fs.config=04.2-modify-transferprocess/modify-transferprocess-consumer/config.properties -jar 04.2-modify-transferprocess/modify-transferprocess-consumer/build/libs/consumer.jar > log.txt &
+          echo "Checking Sample transfer-03 - Command-Q/Watchdog"
+          ./gradlew :transfer:transfer-03-modify-transferprocess:modify-transferprocess-consumer:shadowJar
+          java -Dedc.fs.config=transfer/transfer-03-modify-transferprocess/modify-transferprocess-consumer/config.properties -jar transfer/transfer-03-modify-transferprocess/modify-transferprocess-consumer/build/libs/consumer.jar > log.txt &
           sleep 5
           grep "INFO.*edc-.*ready" log.txt
           rm log.txt

CODEOWNERS

@@ -16,14 +16,16 @@ README.md @ronjaquensel
 .github/ISSUE_TEMPLATE @ronjaquensel
 .github/workflows/ @ronjaquensel
 
-/01-basic-connector/ @paullatzelsperger
-/02-health-endpoint/ @paullatzelsperger
-/03-configuration/ @paullatzelsperger
-/04.0-file-transfer/ @ronjaquensel
-/04.1-file-transfer-listener/ @paullatzelsperger
-/04.2-modify-transferprocess/ @paullatzelsperger
-/04.3-open-telemetry/ @jimmarino
-/05-file-transfer-cloud/ @paullatzelsperger
+/basic/basic-01-basic-connector/ @paullatzelsperger
+/basic/basic-02-health-endpoint/ @paullatzelsperger
+/basic/basic-03-configuration/ @paullatzelsperger
+
+/transfer/transfer-01-file-transfer/ @ronjaquensel
+/transfer/transfer-02-file-transfer-listener/ @paullatzelsperger
+/transfer/transfer-03-modify-transferprocess/ @paullatzelsperger
+/transfer/transfer-04-open-telemetry/ @jimmarino
+/transfer/transfer-05-file-transfer-cloud/ @paullatzelsperger
+
 /other/ @paullatzelsperger
 
 /resources/ @ronjaquensel

README.md

@@ -1,59 +1,46 @@
 # EDC Samples
 
 This repository provides samples for the Eclipse Dataspace Components (EDC) project, that aim to support the
-onboarding process for new community members. The samples are incremental, so e.g. sample 3 uses code from sample 2,
-and serve as a step-by-step guide for getting familiar with the project. The code and a detailed documentation
-for each sample reside in the respective module.
+onboarding process for new community members. The samples are sorted by scope for easy navigation and serve as a
+step-by-step guide for getting familiar with the project. The code and a detailed documentation for each sample reside
+in the respective module.
 
-The samples assume a working knowledge of the EDC nomenclature. If you do not know about the EDC nomenclature we
-strongly advise reading the documentation and/or watching the introductory video.
+## Prerequisites
 
-Also, a working knowledge of Git, Gradle, Java and HTTP is presumed.
+The samples assume a working knowledge of the **EDC nomenclature**. If you do not know about the EDC nomenclature we
+strongly advise reading the [documentation](https://eclipse-edc.github.io/docs/#/) and/or watching the
+[introductory videos](https://www.youtube.com/@eclipsedataspaceconnector9622/featured).
 
-## Getting started
+Also, a working knowledge of **Git**, **Gradle**, **Java** and **HTTP** is presumed.
 
-We'll assume that you've just checked out the samples code base and have Java 11+ installed on your development machine.
-If not, please download and install JDK 11+ for your OS.
+We'll assume that you've just checked out the samples code base and have **Java 11+** installed on your development
+machine. If not, please download and install JDK 11+ for your OS.
 
 Command examples in this document will use the `bash` syntax and use Unix-style paths, but any other shell should be
 fine as well. If you're using Windows you either need to adapt the paths or use WSL2.
 
-Please simply follow the following links to the respective samples.
+## Scopes
 
-> _Please note that the entire Eclipse Dataspace Components project is under heavy development, so things are likely
-> to change significantly in the future. Be sure to check back regularly to stay updated!_
+The samples are separated by scope, where each scope has a different focus. Depending on what you want to learn more
+about, you can choose the scope to look at. More scopes may be added in the future, so be sure to check back regularly.
 
-## [Example 1: Run a simple connector](01-basic-connector/README.md)
+> **If you are new to the project, it is advisable to start with the `basic` scope. The samples in this scope teach the
+> very basics about using the EDC framework, which are presupposed in all other scopes!**
 
-> _The complete sample code can be found in `01-basic-connector`._
+### [Basic](./basic/README.md)
 
-## [Example 2: Write your first extension](02-health-endpoint/README.md)
+The samples in this scope teach you how to get started with the EDC framework. You will e.g. learn how to set up and run
+a connector and how to create your own extensions. What you learn here will be used in all other samples. Click the
+link above to learn about the basic samples in more detail.
 
-> _The complete sample code can be found in `02-health-endpoint`._
+All basic samples are located in the `basic` directory.
 
-## [Example 3: Use the file-system based configuration](03-configuration/README.md)
+### [Transfer](./transfer/README.md)
 
-> _The complete sample code can be found in `03-configuration`._
+This scope revolves around the topic of data transfer. In these samples you will learn how a data transfer works in the
+EDC and run different transfer scenarios. Click the link above to learn about the transfer samples in more detail.
 
-## [Example 4.0: Implement a simple file transfer](04.0-file-transfer/README.md)
-
-> _The complete sample code can be found in `04.0-file-transfer`._
-
-## [Example 4.1: Implement a simple file transfer listener](04.1-file-transfer-listener/README.md)
-
-> _The complete sample code can be found in `04.1-file-transfer-listener`._
-
-## [Example 4.2: Modify a TransferProcess](04.2-modify-transferprocess/README.md)
-
-> _The complete sample code can be found in `04.2-modify-transferprocess`._
-
-## [Example 4.3: Open Telemetry](04.3-open-telemetry/README.md)
-
-> _The complete sample code can be found in `04.3-open-telemetry`._
-
-## [Example 5: Improve the file transfer](05-file-transfer-cloud/README.md)
-
-> _The complete sample code can be found in `05-file-transfer-cloud`._
+All transfer samples are located in the `transfer` directory.
 
 ## Contributing
 

basic/README.md

@@ -0,0 +1,24 @@
+# Basic samples
+
+The samples in this scope teach the very basics about using the EDC framework. When new to the project, you
+should do these samples first before moving on to any of the other scopes, as all other samples build up on what you
+learn here.
+
+## Samples
+
+### [Basic sample 01](./basic-01-basic-connector/README.md): Run a simple connector
+
+In this sample you will learn what you need to run a connector. You will create a build file and run a very simple
+connector, which will serve as the basis for the following samples in this scope.
+
+### [Basic sample 02](./basic-02-health-endpoint/README.md): Write your first extension
+
+In the EDC, every feature or functionality is provided as an extension. This sample will teach you how to create your
+own extensions and use them in your connector. The extension created in this sample provides a simple, static health
+endpoint.
+
+### [Basic sample 03](./basic-03-configuration/README.md): Use the filesystem-based configuration
+
+The EDC uses many configurable values, so that we e.g. do not have to recompile the entire code just to start a 
+component on a different port. In this sample you will learn how to provide configuration values at start up by using
+a properties file as well as how to use configuration values in your own extensions.

01-basic-connector/README.md → basic/basic-01-basic-connector/README.md

@@ -5,7 +5,7 @@ A runnable connector consists of a `Runtime` and a build file, in our case this
 The first thing we need is the `Runtime` which is the main entry point to the connector application, same as with any
 other Java program. In this sample we use the
 [`BaseRuntime`](https://github.com/eclipse-edc/Connector/blob/releases/core/common/boot/src/main/java/org/eclipse/edc/boot/system/runtime/BaseRuntime.java),
-but this can be extended (take a look at the [`custom-runtime`](../other/custom-runtime) sample for more information)
+but this can be extended (take a look at the [`custom-runtime`](../../other/custom-runtime) sample for more information)
 
 The second thing we need is a [gradle build file](build.gradle.kts)
 that contains the essential dependencies. We'll need at least the following things:
@@ -21,8 +21,8 @@ dependencies {
 with that we can build and run the connector from the root directory:
 
 ```bash
-./gradlew clean 01-basic-connector:build
-java -jar 01-basic-connector/build/libs/basic-connector.jar
+./gradlew clean basic:basic-01-basic-connector:build
+java -jar basic/basic-01-basic-connector/build/libs/basic-connector.jar
 ```
 
 _Note: the above snippet assumes that you did not alter the build file, i.e. the `shadow` plugin is used and the build
@@ -59,4 +59,4 @@ scenarios.
 
 ---
 
-[Next Chapter](../02-health-endpoint/README.md)
+[Next Chapter](../basic-02-health-endpoint/README.md)

02-health-endpoint/README.md → basic/basic-02-health-endpoint/README.md

@@ -54,8 +54,8 @@ public class HealthApiController {
 Once we compile and run the application with
 
 ```bash
-./gradlew clean 02-health-endpoint:build
-java -jar 02-health-endpoint/build/libs/connector-health.jar
+./gradlew clean basic:basic-02-health-endpoint:build
+java -jar basic/basic-02-health-endpoint/build/libs/connector-health.jar
 ```
 
 we can issue a GET request to `http://localhost:8181/api/health` and receive the aforementioned string as a result.
@@ -71,4 +71,4 @@ Also, the default path is `/api/*`, which is defined in
 
 ---
 
-[Previous Chapter](../01-basic-connector/README.md) | [Next Chapter](../03-configuration/README.md)
+[Previous Chapter](../basic-01-basic-connector/README.md) | [Next Chapter](../basic-03-configuration/README.md)

03-configuration/README.md → basic/basic-03-configuration/README.md

@@ -22,8 +22,8 @@ dependencies {
 We compile and run the application with:
 
 ```bash
-./gradlew clean 03-configuration:build
-java -jar 03-configuration/build/libs/filesystem-config-connector.jar
+./gradlew clean basic:basic-03-configuration:build
+java -jar basic/basic-03-configuration/build/libs/filesystem-config-connector.jar
 ```
 
 you will notice an additional log line stating that the "configuration file does not exist":
@@ -57,7 +57,7 @@ An example file can be found [here](config.properties). Clean, rebuild and run t
 passing the path to the config file:
 
 ```bash
-java -Dedc.fs.config=/etc/eclipse/dataspaceconnector/config.properties -jar 03-configuration/build/libs/filesystem-config-connector.jar
+java -Dedc.fs.config=/etc/eclipse/dataspaceconnector/config.properties -jar basic/basic-03-configuration/build/libs/filesystem-config-connector.jar
 ```
 
 Observing the log output we now see that the connector's REST API is exposed on port `9191` instead:
@@ -81,7 +81,7 @@ Let's say we want to have a configurable log prefix in our health REST endpoint.
 Simply add a new line with an arbitrary key to your `config.properties`:
 
 ```properties
-edc.samples.03.logprefix=MyLogPrefix
+edc.samples.basic.03.logprefix=MyLogPrefix
 ```
 
 ### 2. Access the config value
@@ -96,7 +96,7 @@ public class HealthEndpointExtension implements ServiceExtension {
     @Inject
     WebService webService;
 
-    private static final String LOG_PREFIX_SETTING = "edc.samples.03.logprefix"; // this constant is new
+    private static final String LOG_PREFIX_SETTING = "edc.samples.basic.03.logprefix"; // this constant is new
 
     @Override
     public void initialize(ServiceExtensionContext context) {
@@ -176,4 +176,4 @@ connectors._
 
 ---
 
-[Previous Chapter](../02-health-endpoint/README.md) | [Next Chapter](../04.0-file-transfer/README.md)
+[Previous Chapter](../basic-02-health-endpoint/README.md) 

03-configuration/config.properties → basic/basic-03-configuration/config.properties

@@ -2,4 +2,4 @@ web.http.port=9191
 web.http.path=/api
 web.http.data.port=9192
 web.http.data.path=/api/v1/management
-edc.samples.03.logprefix=MyLogPrefix
+edc.samples.basic.03.logprefix=MyLogPrefix

03-configuration/src/main/java/org/eclipse/edc/extension/health/HealthEndpointExtension.java → basic/basic-03-configuration/src/main/java/org/eclipse/edc/extension/health/HealthEndpointExtension.java

@@ -21,7 +21,7 @@
 
 public class HealthEndpointExtension implements ServiceExtension {
 
-    private static final String LOG_PREFIX_SETTING = "edc.samples.03.logprefix";
+    private static final String LOG_PREFIX_SETTING = "edc.samples.basic.03.logprefix";
     @Inject
     WebService webService;
 

settings.gradle.kts

@@ -42,32 +42,34 @@ dependencyResolutionManagement {
     }
 }
 
-include(":01-basic-connector")
-include(":02-health-endpoint")
-include(":03-configuration")
+// basic
+include(":basic:basic-01-basic-connector")
+include(":basic:basic-02-health-endpoint")
+include(":basic:basic-03-configuration")
 
-include(":04.0-file-transfer:file-transfer-consumer")
-include(":04.0-file-transfer:file-transfer-provider")
-include(":04.0-file-transfer:file-transfer-integration-tests")
-include(":04.0-file-transfer:transfer-file-local")
-include(":04.0-file-transfer:status-checker")
+// transfer
+include(":transfer:transfer-01-file-transfer:file-transfer-consumer")
+include(":transfer:transfer-01-file-transfer:file-transfer-provider")
+include(":transfer:transfer-01-file-transfer:file-transfer-integration-tests")
+include(":transfer:transfer-01-file-transfer:transfer-file-local")
+include(":transfer:transfer-01-file-transfer:status-checker")
 
-include(":04.1-file-transfer-listener:file-transfer-listener-consumer")
-include(":04.1-file-transfer-listener:file-transfer-listener-integration-tests")
-include(":04.1-file-transfer-listener:listener")
+include(":transfer:transfer-02-file-transfer-listener:file-transfer-listener-consumer")
+include(":transfer:transfer-02-file-transfer-listener:file-transfer-listener-integration-tests")
+include(":transfer:transfer-02-file-transfer-listener:listener")
 
-include(":04.2-modify-transferprocess:api")
-include(":04.2-modify-transferprocess:modify-transferprocess-consumer")
-include(":04.2-modify-transferprocess:modify-transferprocess-integration-tests")
-include(":04.2-modify-transferprocess:simulator")
-include(":04.2-modify-transferprocess:watchdog")
+include(":transfer:transfer-03-modify-transferprocess:api")
+include(":transfer:transfer-03-modify-transferprocess:modify-transferprocess-consumer")
+include(":transfer:transfer-03-modify-transferprocess:modify-transferprocess-integration-tests")
+include(":transfer:transfer-03-modify-transferprocess:simulator")
+include(":transfer:transfer-03-modify-transferprocess:watchdog")
 
-include(":04.3-open-telemetry:open-telemetry-consumer")
-include(":04.3-open-telemetry:open-telemetry-provider")
+include(":transfer:transfer-04-open-telemetry:open-telemetry-consumer")
+include(":transfer:transfer-04-open-telemetry:open-telemetry-provider")
 
-include(":05-file-transfer-cloud:cloud-transfer-consumer")
-include(":05-file-transfer-cloud:cloud-transfer-provider")
-include(":05-file-transfer-cloud:transfer-file-cloud")
+include(":transfer:transfer-05-file-transfer-cloud:cloud-transfer-consumer")
+include(":transfer:transfer-05-file-transfer-cloud:cloud-transfer-provider")
+include(":transfer:transfer-05-file-transfer-cloud:transfer-file-cloud")
 
 // modules for code samples ------------------------------------------------------------------------
-include(":other:custom-runtime")
+include(":other:custom-runtime")