diff --git a/README.md b/README.md index a08a5ccfcc5c9ce42d415ab99e8e9882d0bec457..8d4cffef6b8cadf5814e43ed93a7c149a62f95d8 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,53 @@ Ein Client zum Senden und Empfangen von XTA Nachrichten. Der Client verwendet *XTA 2 Version 3.1* mit [XTA-Modul-Webservice-Version](https://www.xoev.de/osci-xta/standard-xta-2/xta-versionsuebersicht-23036) `2.1.1`. Er wird als Maven-Artefakt `xta-client-lib` bereitgestellt und kann in Java-Anwendungen eingebunden werden. +1. [Konfiguration](#Konfiguration) + 1. [Filterung von Nachrichten vor der Abholung](#Filterung-von-Nachrichten-vor-der-Abholung) +2. [Senden einer Nachricht](#Senden-einer-Nachricht) + 1. [Validierung der Xdomea-ZIP-Datei](#Validierung-der-Xdomea-ZIP-Datei) +3. [Empfangen von Nachrichten](#Empfangen-von-Nachrichten) +4. [Referenzen](#Referenzen) + +## 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`. +- ... siehe [XtaClientConfig](src/main/java/de/ozgcloud/xta/client/config/XtaClientConfig.java) + +**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> + +### Filterung von Nachrichten vor der Abholung +Um Nachrichten vor dem Abholen basierend auf `XtaMessageMetadata` zu filtern, sollte das optionale `Predicate<XtaMessageMetadata>` für `XtaClientConfig::isMessageSupported` konfiguriert werden. +Zum Beispiel kann auf diese Weise verhindert werden, dass nicht unterstützte Nachrichten, die unausweichlich zu einem Verarbeitungsfehler führen, vollständig heruntergeladen werden müssen. + + ## 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. @@ -126,7 +173,7 @@ Für eine erfolgreiche Validierung muss eine Xdomea-ZIP-Datei folgende Bedingung ## 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. +Zudem konfiguriert sie das Client-Zertifikat, welches sie 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. @@ -201,44 +248,6 @@ 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`. -- ... siehe [XtaClientConfig](src/main/java/de/ozgcloud/xta/client/config/XtaClientConfig.java) - -**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> - -### Filterung von Nachrichten vor der Abholung -Um Nachrichten vor dem Abholen basierend auf `XtaMessageMetadata` zu filtern, sollte das optionale `Predicate<XtaMessageMetadata>` für `XtaClientConfig::isMessageSupported` konfiguriert werden. -Zum Beispiel kann auf diese Weise verhindert werden, dass nicht unterstützte Nachrichten, die unausweichlich zu einem Verarbeitungsfehler führen, vollständig heruntergeladen werden müssen. ## Referenzen