From 72ec8fea43d93e9e9f76c4ab55adf11fe5afd87c Mon Sep 17 00:00:00 2001
From: Jan Zickermann <jan.zickermann@dataport.de>
Date: Wed, 23 Oct 2024 13:39:36 +0200
Subject: [PATCH] OZG-6891 KOP-2736 Explain config
---
README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 46 insertions(+), 2 deletions(-)
diff --git a/README.md b/README.md
index 14f121b..4b119ae 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,9 @@ Er wird als Maven-Artefakt `xta-client-lib` bereitgestellt und kann in Java-Anwe
## Senden einer Nachricht
Zum Senden einer Nachricht konfiguriert die Nutzer*in einen neuen XTA-Client mit einem Client-Zertifikat, welches sie für das Senden mit einer Autor-Kennung autorisiert.
-Die Nutzer*in erstellt, die zu sendende Nachricht mit entsprechender Autor- und Leser-Kennung. Mit einem Aufruf von `XtaClient::sendMessage` wird die Nachricht an den XTA-Server übermittelt. Wenn der zurückgegebene Transport-Report den Status `OPEN` meldet, steht die Nachricht dem Leser zur Abholung bereit.
+Die Nutzer*in erstellt die zu sendende Nachricht mit entsprechender Autor- und Leser-Kennung.
+Anschließend übergibt sie die Nachricht an den XTA-Server mit einem Aufruf von `XtaClient::sendMessage`.
+Wenn der zurückgegebene Transport-Report den Status `OPEN` meldet, steht die Nachricht dem Leser zur Abholung bereit.
```mermaid
%% Senden einer Nachricht
sequenceDiagram
@@ -123,11 +125,17 @@ Für eine erfolgreiche Validierung muss eine Xdomea-ZIP-Datei folgende Bedingung
<small>Hinweis: Die Xdomea-Nachricht sollte mit UTF-8 kodiert sein.</small>
## Empfangen von Nachrichten
-Zum Empfangen von Nachrichten konfiguriert die Nutzer*in einen neuen XTA-Client mit den gewünschten Leser-Kennungen. Zudem konfiguriert er das Client-Zertifikat, welches ihn zum Lesen mit den Leser-Kennungen autorisiert.
+Zum Empfangen von Nachrichten konfiguriert die Nutzer*in einen neuen XTA-Client mit den gewünschten Leser-Kennungen.
+Zudem konfiguriert er das Client-Zertifikat, welches ihn zum Lesen mit den Leser-Kennungen autorisiert.
Beim Aufruf von `fetchMessages` werden alle Nachrichten für die Leser-Kennungen abgeholt und verarbeitet.
Die Nachrichten-Verarbeitung erfolgt durch die übergebene `processMessage`-Funktion.
+Nachdem alle Nachrichten verarbeitet sind, werden die Transport-Reports zurückgegeben.
+
+Eine erfolgreich abgeholte/geschlossene Nachricht hat den Status `RED`, `YELLOW` oder `GREEN`.
+Hierbei signalisiert `RED` einen kritischen Fehler, `YELLOW` einen Warnhinweis und `GREEN` eine fehlerfreie Verarbeitung.
+
```mermaid
%% Empfangen von Nachrichten
sequenceDiagram
@@ -177,6 +185,8 @@ Die Nachrichten-Verarbeitung erfolgt durch die übergebene `processMessage`-Funk
```
<small>* Sollte `processMessage` bei der Verarbeitung eine *RuntimeException* werfen, wird `Nachrichten schließen` übersprungen.</small>
+<small>Hinweis: Nicht geschlossene Nachrichten mit Status `OPEN` werden beim nächsten Aufruf von `fetchMessages` erneut bearbeitet.</small>
+
**Beispielcode:**
```java
@@ -192,6 +202,40 @@ for (var transportReport : transportReports) {
}
```
+## Konfiguration
+
+Der XTA-Client wird mit einer `XtaClientConfig` konfiguriert:
+- XTA-Service-Port-URLs: `management`, `send` und `msgBox `
+- Client-Zertifikat der Autor-Kennung (für `sendMessage`) und der Leser-Kennungen (für `fetchMessages`)
+ - Leser-Client-Kennungen für `fetchMessages`.
+
+**Beispielcode:**
+```java
+var config = XtaClientConfig.builder()
+ .managementServiceUrl("https://my-xta-server.de/MB_XTA-WS/XTA210managementPort.svc")
+ .sendServiceUrl("https://my-xta-server.de/MB_XTA-WS/XTA210sendPort.svc")
+ .msgBoxServiceUrl("https://my-xta-server.de/MB_XTA-WS/XTA210msgBoxPort.svc")
+ .clientCertKeystore(XtaClientConfig.KeyStore.builder()
+ .content(Files.toByteArray(new File("/path/to/client-cert.p12")))
+ .type("PKCS12")
+ .password("keystore-password")
+ .bulid())
+ .clientIdentifiers(List.of(
+ XtaIdentifier.builder()
+ .category("Generischer Antragsempfänger")
+ .value("gae:test-environment@ozg-cloud.de")
+ .build(),
+ XtaIdentifier.builder()
+ .category("Generischer Antragsempfänger")
+ .value("gae:dev-environment@ozg-cloud.de")
+ .build()
+ ))
+ .build();
+var client = XtaClient.from(config);
+```
+
+<small>Hinweis: Sollte die Root-CA des XTA-Servers nicht für das Ziel-System konfiguriert sein, muss zudem ein entsprechender `XtaClientConfig::trustStore` konfiguriert werden.</small>
+
## Referenzen
- Dieser XTA-Client basiert auf dem [XTA-Client-Beispielcode für XTA 2 Version 3 vom 21.07.2021](https://www.xoev.de/sixcms/media.php/13/XTA_Client_Version_3_20210721.zip) auffindbar unter [Hilfsmittel](https://www.xoev.de/osci-xta/standard-xta-2/xta-hilfsmittel-23081).
--
GitLab