OZG-6891 KOP-2736 Explain config

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).