README.md

# XTA-Client

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.

## Senden einer Nachricht
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
%% Senden einer Nachricht
  sequenceDiagram
    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) Nachricht erzeugen
    Note left of A: (3) Nachricht senden
    A->>B: sendMessage
    activate A
    activate B
    B->>C: checkAccountActive
    activate C
    C-->>B: 
    deactivate C
    B->>C: lookupService
    activate C
    C-->>B:  
    deactivate C
    B->>C: createMessageID
    activate C
    C-->>B: 
    deactivate C
    B->>C: sendMessage
    activate C
    C-->>B: 
    deactivate C
    B->>C: getTransportReport
    activate C
    C-->>B: 
    deactivate C
    B-->>A: 
    deactivate B
    deactivate A
    Note left of A: (4) Nachrichtenstatus prüfen
```

<small>* Der XTA-Server wird oft als Nachrichtenbroker oder Nachrichtenvermittler bezeichnet.</small>

**Beispielcode:**

```java
// (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 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
%% Empfangen von Nachrichten
  sequenceDiagram
    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
    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) Nachrichten abholen
var transportReports = client.fetchMessages(xtaMessage -> {
    // (3) Nachricht verarbeiten
});
// (4) Nachrichtenstatus prüfen
for (var transportReport : transportReports) {
    assert transportReport.status() == XtaMessageStatus.GREEN;
}
```

## 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).
- Die [XTA 2 Version 3.1 Spezifikation](file:///home/janz/Downloads/XTA_2_Version_3.1_Spezifikation_30112021-2.pdf) ist auffindbar unter [XTA 2 Version 3.1](https://www.xoev.de/osci-xta/standard-xta-2/xta-versionsuebersicht/xta-2-version-3-23038).