Newer
Older
# 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 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.
%% Senden einer Nachricht
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
deactivate C
B->>C: createMessageID
activate C
C-->>B:
deactivate C
B->>C: sendMessage
activate C
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:010200100000")
.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;
Da eine Xdomea-Nachricht die Leser- und Autor-Kennung bereits enthält, ist es möglich aus der Xdomea-ZIP-Datei die Metadaten der XTA-Nachricht abzuleiten:
```java
// ...
// (2) Nachricht erzeugen
// ...
var message = XdomeaXtaMessageCreator.createInstance().createMessage(xdomeaXtaFile);
// (3) Nachricht senden
var transportReport = client.sendMessage(message);
// ...
```
Hierbei wird die Xta-Autor-Kennung aus dem *Xdomea-Absender-Kennung/Behoerdenschluessel* gelesen und die Xta-Leser-Kennung aus dem *Xdomea-Empfaenger-Kennung/Behoerdenschluessel*.
### Validierung der Xdomea-ZIP-Datei
Wenn eine `XtaMessage` für eine Xdomea-ZIP-Datei mit `XdomeaXtaMessageCreator::createMessage` erstellt wird, wird zudem geprüft, ob die Nachricht die ["Transportfestlegungen Generischer Antragsdienst"](Transportfestlegungen%20Generischer%20Antragsdienst.pdf) einhält.
Für eine erfolgreiche Validierung muss eine Xdomea-ZIP-Datei folgende Bedingungen erfüllen:
- Der ZIP-Dateiname ist `<ProzessID>_<Nachrichtentyp>.zip` (z.B. `00000000-0000-0000-0000-_Geschaeftsgang.Geschaeftsgang.0201.zip`)
- Die ProzessID in der Xdomea-Nachricht entspricht der ProzessID im Dateinamen
- Die Xdomea-Nachricht `<ProzessID>_<Nachrichtentyp>.xml` in der ZIP-Datei ist schema-konform.
- Der Xdomea-Nachrichten-Typ ist zulässig:
- `Geschaeftsgang.Geschaeftsgang.0201` mit Xdomea 2.4.0
- `Abgabe.Abgabe.0401` mit Xdomea 3.0.0
- `Abgabe.ImportBestaetigen.0402` mit Xdomea 3.0.0
- Alle Dateien, die die Xdomea-Nachricht referenziert, sind in der ZIP-Datei enthalten.
- Eine Absender-Kennung ist vorhanden mit dem Präfix `gad`
- Eine Empfänger-Kennung ist vorhanden mit dem Präfix `gae`
<small>Hinweis: Die Xdomea-Nachricht sollte mit UTF-8 kodiert sein.</small>
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.
%% Empfangen von Nachrichten
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
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
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
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;
}
- 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).
