Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

samples: update documentation #1224

Merged
merged 2 commits into from
Apr 28, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 8 additions & 11 deletions samples/02-health-endpoint/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,27 +10,24 @@ An _extension_ typically consists of two things:
interface's fully qualified class-name and it **must** contain the fully-qualified name of the implementing class (
=plugin class).

Therefore we require an extension class, which we'll name `HealthEndpointExtension`:
Therefore, we require an extension class, which we'll name `HealthEndpointExtension`:

```java
@Requires({ WebService.class })
public class HealthEndpointExtension implements ServiceExtension {

@Inject
WebService webService;

@Override
public void initialize(ServiceExtensionContext context) {
var webService = context.getService(WebService.class);
webService.registerController(new HealthApiController(context.getMonitor()));
webService.registerResource(new HealthApiController(context.getMonitor()));
}
}
```

The `@Requires` annotation indicates that the extension needs a service that is registered by another extension, in
The `@Inject` annotation indicates that the extension needs a service that is registered by another extension, in
this case an implementation of `WebService.class`.

The `ServiceExtensionContext` serves as registry for all resolvable services, somewhat comparable to the "module"
concept in DI frameworks like Google Guice. From it, we obtain an instance of the `WebService` interface, where we can
register our API controller class.

For that, we can use Jakarta REST annotations to implement a simple REST API:

```java
Expand Down Expand Up @@ -64,10 +61,10 @@ java -jar samples/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.

It is worth noting that by default the webserver listens on port `8181`, which is defined
in [`JettyService.java`](../../extensions/jetty/src/main/java/org/eclipse/dataspaceconnector/extension/jetty/JettyService.java)
in [`JettyService.java`](../../extensions/http/jetty/src/main/java/org/eclipse/dataspaceconnector/extension/jetty/JettyService.java)
and can be configured using the `web.http.port` property (more on that in the next chapter). You will need to configure
this whenever you have two connectors running on the same machine.

Also, the default path is `/api/*`, which is defined
in [`JerseyRestService.java`](../../extensions/jetty/src/main/java/org/eclipse/dataspaceconnector/extension/jetty/JerseyRestService.java)
in [`JerseyRestService.java`](../../extensions/http/jersey/src/main/java/org/eclipse/dataspaceconnector/extension/jersey/JerseyRestService.java)
.
Original file line number Diff line number Diff line change
Expand Up @@ -15,16 +15,17 @@
package org.eclipse.dataspaceconnector.extensions.health;

import org.eclipse.dataspaceconnector.spi.WebService;
import org.eclipse.dataspaceconnector.spi.system.Requires;
import org.eclipse.dataspaceconnector.spi.system.Inject;
import org.eclipse.dataspaceconnector.spi.system.ServiceExtension;
import org.eclipse.dataspaceconnector.spi.system.ServiceExtensionContext;

@Requires({WebService.class})
public class HealthEndpointExtension implements ServiceExtension {

@Inject
WebService webService;

@Override
public void initialize(ServiceExtensionContext context) {
var webService = context.getService(WebService.class);
webService.registerResource(new HealthApiController(context.getMonitor()));
}
}
28 changes: 13 additions & 15 deletions samples/03-configuration/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ INFO 2021-09-07T08:26:08.282159 Configuration file does not exist: dataspaceconn

By default, the `FsConfigurationExtension` expects there to be a properties file
named `dataspaceconnector-configuration.properties` located in the current directory. The name (and path) of the config
file is configurable using the `dataspaceconnector.fs.config` property, so we can customize this to our liking.
file is configurable using the `edc.fs.config` property, so we can customize this to our liking.

First, create a properties file in a location of your convenience,
e.g. `/etc/eclipse/dataspaceconnector/config.properties`.
Expand All @@ -63,14 +63,15 @@ java -Dedc.fs.config=/etc/eclipse/dataspaceconnector/config.properties -jar samp
Observing the log output we now see that the connector's REST API is exposed on port `9191` instead:

```bash
INFO 2021-09-07T08:43:04.476254 Registered Web API context at: /api/*
INFO 2021-09-07T08:43:04.503543 HTTP listening on 9191 <--this is the relevant line
INFO 2021-09-07T08:43:04.750674 Started Web extension
INFO 2022-04-27T14:09:10.547662345 HTTP context 'default' listening on port 9191 <-- this is the relevant line
DEBUG 2022-04-27T14:09:10.589738491 Port mappings: {alias='default', port=9191, path='/api'}
INFO 2022-04-27T14:09:10.589846121 Started Jetty Service

```

## Add your own configuration value

Lets say we want to have a configurable log prefix in our health REST endpoint. The way to do this involves two steps:
Let's say we want to have a configurable log prefix in our health REST endpoint. The way to do this involves two steps:

1. add the config value to the `config.properties` file
2. access and read the config value from code
Expand All @@ -91,18 +92,16 @@ of course):

```java
public class HealthEndpointExtension implements ServiceExtension {
private static final String LOG_PREFIX_SETTING = "edc.samples.03.logprefix"; // this constant is new

@Override
public Set<String> requires() {
return Set.of("edc:webservice");
}
@Inject
WebService webService;

private static final String LOG_PREFIX_SETTING = "edc.samples.03.logprefix"; // this constant is new

@Override
public void initialize(ServiceExtensionContext context) {
var logPrefix = context.getSetting(LOG_PREFIX_SETTING, "health"); //this line is new
var webService = context.getService(WebService.class);
webService.registerController(new HealthApiController(context.getMonitor(), logPrefix));
webService.registerResource(new HealthApiController(context.getMonitor(), logPrefix));
}
}
```
Expand Down Expand Up @@ -147,13 +146,12 @@ There are a few things worth mentioning here:
## Management API

Part of most connectors will be the management api defined in the
[`:extensions:api:data-management`](../../extensions/api/data-management) module. Therefor, we need to add the following
two modules to the dependency list in our `build.gradle.kts`:
[`:extensions:api:data-management`](../../extensions/api/data-management) module. Therefore, we need to add the following
module to the dependency list in our `build.gradle.kts`:

```kotlin
dependencies {
// ...
implementation(project(":extensions:api:auth-tokenbased"))
implementation(project(":extensions:api:data-management"))
// ...
}
Expand Down
1 change: 0 additions & 1 deletion samples/03-configuration/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,6 @@ dependencies {
api(project(":core"))
api(project(":extensions:http"))

implementation(project(":extensions:api:auth-tokenbased"))
implementation(project(":extensions:api:data-management"))

implementation(project(":extensions:filesystem:configuration-fs"))
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,18 +15,20 @@
package org.eclipse.dataspaceconnector.extensions.health;

import org.eclipse.dataspaceconnector.spi.WebService;
import org.eclipse.dataspaceconnector.spi.system.Requires;
import org.eclipse.dataspaceconnector.spi.system.Inject;
import org.eclipse.dataspaceconnector.spi.system.ServiceExtension;
import org.eclipse.dataspaceconnector.spi.system.ServiceExtensionContext;

@Requires({WebService.class})
public class HealthEndpointExtension implements ServiceExtension {

@Inject
WebService webService;

private static final String LOG_PREFIX_SETTING = "edc.samples.03.logprefix";

@Override
public void initialize(ServiceExtensionContext context) {
var logPrefix = context.getSetting(LOG_PREFIX_SETTING, "health");
var webService = context.getService(WebService.class);
webService.registerResource(new HealthApiController(context.getMonitor(), logPrefix));
}
}