OZG-6891 KOP-2736 Improve Readme sequence diagrams

README.md

@@ -8,11 +8,13 @@ Der Client verwendet *XTA 2 Version 3.1* mit [XTA-Modul-Webservice-Version](http
 Er wird als Maven-Artefakt `xta-client-lib` bereitgestellt und kann in Java-Anwendungen eingebunden werden.
 
 ## Senden einer Nachricht
-Zum Senden einer Nachricht konfiguriert der Nutzer einen neuen XTA-Client.
+Zum Senden einer Nachricht konfiguriert die Nutzer*in einen neuen XTA-Client mit einem Client-Zertifikat, welches ihn für das Senden mit einer Autor-Kennung autorisiert.
+
+Beim Aufruf von `sendMessage` wird die Nachricht an den XTA-Server übergeben und der Transport-Report zurückgegeben.
 ```mermaid
-%% Versand einer Nachricht
+%% Senden einer Nachricht
   sequenceDiagram
-    participant A as Nutzer
+    participant A as Nutzer*in
     participant B as XTA-Client
     participant C as XTA-Server
     Note left of A: (1) XTA-Client erzeugen
@@ -27,7 +29,7 @@ Zum Senden einer Nachricht konfiguriert der Nutzer einen neuen XTA-Client.
     deactivate C
     B->>C: lookupService
     activate C
-    C-->>B: 
+    C-->>B:  
     deactivate C
     B->>C: createMessageID
     activate C
@@ -35,18 +37,19 @@ Zum Senden einer Nachricht konfiguriert der Nutzer einen neuen XTA-Client.
     deactivate C
     B->>C: sendMessage
     activate C
+    C-->>B: 
     deactivate C
     B->>C: getTransportReport
     activate C
     C-->>B: 
     deactivate C
-    Note left of A: (4) Nachrichtenstatus prüfen
     B-->>A: 
-	deactivate B
-	deactivate A
+    deactivate B
+    deactivate A
+    Note left of A: (4) Nachrichtenstatus prüfen
 ```
 
-<small>* XTA-Server wird auch oft als Nachrichtenbroker oder Nachrichtenvermittler bezeichnet.</small>
+<small>* Der XTA-Server wird oft als Nachrichtenbroker oder Nachrichtenvermittler bezeichnet.</small>
 
 **Beispielcode:**
 
@@ -54,70 +57,109 @@ Zum Senden einer Nachricht konfiguriert der Nutzer einen neuen XTA-Client.
 // (1) XTA-Client erzeugen
 var client = XtaClient.from(config);
 // (2) Nachricht erzeugen
-...
+var zipFileName = "d5be7468-e620-4126-a40e-61a7f9b46345_Geschaeftsgang.Geschaeftsgang.0201.zip";
+var zipFileContentDataHandler = new DataHandler(new FileDataSource("/path/to/" + zipFileName));
+var xdomeaXtaFile = XtaFile.builder()
+        .name(zipFileName)
+        .content(zipFileContentDataHandler)
+        .contentType("application/zip")
+        .build();
+
+var message = XtaMessage.builder()
+        .metaData(XtaMessageMetaData.builder()
+                .service("urn:xoev-de:xdomea:schema:2.4.0/xdomea240Antrag.wsdl")
+                .businessScenarioCode("XDOMEAGAD_DATA")
+                .businessScenarioListUri("urn:de:dataport:codeliste:business.scenario")
+                .businessScenarioListVersionId("1.0")
+                .messageTypeCode("Geschaeftsgang.Geschaeftsgang.0201")
+                .messageTypePayloadSchema("urn:xoev-de:xdomea:schema:2.4.0")
+                .authorIdentifier(XtaIdentifier.builder()
+                        .category("Generischer Antragsdienst")
+                        .value("gad:010103000000")
+                        .build())
+                .readerIdentifier(XtaIdentifier.builder()
+                        .category("Generischer Antragsempfänger")
+                        .value("gae:test-environment@ozg-cloud.de")
+                        .build())
+                .build())
+        .messageFile(xdomeaXtaFile)
+        .attachmentFiles(emptyList())
+        .build();
+// (3) Nachricht senden
+var transportReport = client.sendMessage(message);
+// (4) Nachrichtenstatus prüfen
+assert transportReport.status() == XtaMessageStatus.OPEN;
 ```
 
 
 ## Empfangen von Nachrichten
-Zum Empfangen von Nachrichten konfiguriert der Nutzer einen neuen XTA-Client mit allen seinen Leser-Kennungen.
+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.
 
 ```mermaid
-%% Abfrage einer Nachricht
+%% Empfangen von Nachrichten
   sequenceDiagram
-    participant A as Nutzer
-    participant D as Verarbeiter
+    participant A as Nutzer*in
     participant B as XTA-Client
     participant C as XTA-Server
     Note left of A: (1) XTA-Client erzeugen
     Note left of A: (2) Nachrichten abholen
     A->>B: fetchMessages
-
     activate A
     activate B
-    B->>C: getStatusList
-    activate C
-    C-->>B: 
-    deactivate C
-    B->>C: getTransportReport
-    activate C
-    C-->>B: 
-    deactivate C
-    B->>A: 
-	deactivate B
-	Note left of B: (4) Nachricht abholen
-    A->>B: getMessage
-    activate B
-    B->>C: getMessage
-    activate C
-    C-->>B: 
-    deactivate C
-    B->>C: getTransportReport
-    activate C
-    C-->>B: 
-    deactivate C
-    B->>A: 
-	deactivate B
-	Note left of D: ...Nachricht verarbeiten...
-	Note left of B: (5) Nachricht schließen
-    A->>B: close
-    activate B
-    B->>C: close
-    activate C
-    C-->>B: 
-    deactivate C
-    B->>A: 
+    loop Für jede Leser-Kennung
+        B->>C: checkAccountActive 
+        activate C
+        C-->>B: 
+        deactivate C
+        B->>C: getStatusList
+        activate C
+        C-->>B: 
+        deactivate C
+        loop Für jede ungelesene Nachricht
+            B->>C: getMessage
+            activate C
+            Note left of B: Nachricht abholen
+            C-->>B: 
+            deactivate C
+            B->>A: processMessage
+	        deactivate B
+            Note left of A: (3) Nachricht verarbeiten
+            A-->>B: 
+            activate B
+            B->>C: close
+            activate C
+            Note left of B: Nachricht schließen
+            C-->>B: 
+            deactivate C
+            B->>C: getTransportReport
+            activate C
+            C-->>B: 
+            deactivate C
+            B->>A: 
+        end
+	end
 	deactivate B
 	deactivate A
+    Note left of A: (4) Nachrichtenstatus prüfen
 ```
-
+<small>* Sollte `processMessage` bei der Verarbeitung eine *RuntimeException* werfen, wird `Nachrichten schließen` übersprungen.</small>
 
 **Beispielcode:**
 
 ```java
 // (1) XTA-Client erzeugen
 var client = XtaClient.from(config);
-// (2) Nachricht erzeugen
-...
+// (2) Nachrichten abholen
+var transportReports = client.fetchMessages(xtaMessage -> {
+    // (3) Nachricht verarbeiten
+});
+// (4) Nachrichtenstatus prüfen
+for (var transportReport : transportReports) {
+    assert transportReport.status() == XtaMessageStatus.GREEN;
+}
 ```
 
 ## Referenzen

src/main/java/de/ozgcloud/xta/client/model/XtaMessage.java

@@ -8,7 +8,7 @@ import jakarta.validation.constraints.NotNull;
 import lombok.Builder;
 
 /**
- * A xta message consisting of meta data, a message file and optional attachment files.
+ * An XTA message consisting of metadata, a message file and optional attachment files.
  *
  * @param metaData Metadata of the message <p>This field is required.</p>
  * @param messageFile Main message of the message <p>This field is required.</p>