From a87c1f6adbe1e1c6811f0f7edbd21e5c1ff98ee2 Mon Sep 17 00:00:00 2001
From: Jan Zickermann <jan.zickermann@dataport.de>
Date: Tue, 22 Oct 2024 14:04:39 +0200
Subject: [PATCH] OZG-6891 KOP-2735 xdomea-message-creator: Add javadoc
---
.../de/ozgcloud/xta/client/XtaClient.java | 9 +++--
.../xta/client/config/XtaClientConfig.java | 3 ++
.../xdomea/XdomeaXtaMessageCreator.java | 39 +++++++++++++++++++
.../extension/XtaMessageExampleLoader.java | 3 +-
.../xdomea/XdomeaXtaMessageCreatorITCase.java | 2 +-
5 files changed, 50 insertions(+), 6 deletions(-)
diff --git a/src/main/java/de/ozgcloud/xta/client/XtaClient.java b/src/main/java/de/ozgcloud/xta/client/XtaClient.java
index c5c7492..afe601d 100644
--- a/src/main/java/de/ozgcloud/xta/client/XtaClient.java
+++ b/src/main/java/de/ozgcloud/xta/client/XtaClient.java
@@ -84,9 +84,9 @@ public class XtaClient {
* </p>
*
* @param processMessage The consumer to process each fetched message.
- * @return The transport reports for all fetched/processed messages. A message which has not been closed has an
- * {@link XtaMessageStatus#OPEN OPEN} status. If a message has been closed, the status is either {@link XtaMessageStatus#GREEN GREEN},
- * {@link XtaMessageStatus#YELLOW YELLOW} or {@link XtaMessageStatus#RED RED}.
+ * @return The transport reports for all fetched/processed messages. A message which has not been closed has an {@link XtaMessageStatus#OPEN OPEN}
+ * status. If a message has been closed, the status is either {@link XtaMessageStatus#GREEN GREEN}, {@link XtaMessageStatus#YELLOW YELLOW} or
+ * {@link XtaMessageStatus#RED RED}.
* @throws XtaClientException If a technical problem occurs while fetching messages.
*/
public List<XtaTransportReport> fetchMessages(@NotNull Consumer<XtaMessage> processMessage) throws XtaClientException {
@@ -200,7 +200,8 @@ public class XtaClient {
* reader. If both checks pass, sends the message to the reader. Finally, returns the transport report for the sent message.
* </p>
* <p>
- * <b>Note:</b> message size and id are set by the server, and thus may initially be null.
+ * <b>Note:</b> message size and id are set by the server, and thus may initially be null. This applies to the message metadata as well as
+ * to the message and attachment files.
* </p>
*
* @param messageWithoutMessageId The message to send without id and size.
diff --git a/src/main/java/de/ozgcloud/xta/client/config/XtaClientConfig.java b/src/main/java/de/ozgcloud/xta/client/config/XtaClientConfig.java
index a98b2ee..ffc3e92 100644
--- a/src/main/java/de/ozgcloud/xta/client/config/XtaClientConfig.java
+++ b/src/main/java/de/ozgcloud/xta/client/config/XtaClientConfig.java
@@ -32,6 +32,9 @@ public class XtaClientConfig {
* <p>
* Usually, in order to use the client identifiers, an according client certificate needs to be configured.
* </p>
+ * <p>
+ * <b>Note:</b> The identifier type is assumed to be {@code xoev}.
+ * </p>
*/
@Builder.Default
private final List<@Valid XtaIdentifier> clientIdentifiers = emptyList();
diff --git a/src/main/java/de/ozgcloud/xta/client/xdomea/XdomeaXtaMessageCreator.java b/src/main/java/de/ozgcloud/xta/client/xdomea/XdomeaXtaMessageCreator.java
index 05c1949..17fc6b5 100644
--- a/src/main/java/de/ozgcloud/xta/client/xdomea/XdomeaXtaMessageCreator.java
+++ b/src/main/java/de/ozgcloud/xta/client/xdomea/XdomeaXtaMessageCreator.java
@@ -22,6 +22,30 @@ import de.ozgcloud.xta.client.xdomea.reader.ZipFileEntryReader;
import lombok.Builder;
import lombok.RequiredArgsConstructor;
+/**
+ * Creator of {@link XtaMessage}s for Xdomea.
+ *
+ * <p>
+ * The XdomeaXtaMessageCreator is used to create an {@link XtaMessage} for an Xdomea zip file.
+ * The resulting message may be send via the {@link de.ozgcloud.xta.client.XtaClient XtaClient}.
+ * </p>
+ *
+ *
+ * Example:
+ * <pre>
+ * var xtaMessageCreator = XdomeaXtaMessageCreator.createInstance();
+ * 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 xtaMessage = xtaMessageCreator.createMessage(xdomeaXtaFile);
+ *
+ * XtaClient.from(...).sendMessage(xtaMessage);
+ * </pre>
+ */
@Builder
@RequiredArgsConstructor
public class XdomeaXtaMessageCreator {
@@ -36,6 +60,21 @@ public class XdomeaXtaMessageCreator {
return XdomeaXtaMessageCreatorFactory.createInstance().create();
}
+ /**
+ * Creates an {@link XtaMessage} from the given xdomea zip file.
+ *
+ * <p>
+ * The zip file has to follow the XTA/Xdomea generic transport specification.
+ * According to the specification, only the Xdomea messages of type 0201, 0401 and 0402 are supported.
+ * </p>
+ *
+ * <p>
+ * <small>The XTA/Xdomea generic transport specification is unofficially available as <i>"Transportfestlegungen Generischer Antragsdienst.pdf"</i>.</small>
+ * </p>
+ * @param xdomeaZipFile the xdomea zip file
+ * @return the xta message with metadata derived from the xdomea zip file
+ * @throws XtaClientException if no valid metadata could be derived from the xdomea zip file.
+ */
public XtaMessage createMessage(XtaFile xdomeaZipFile) throws XtaClientException {
return XtaMessage.builder()
.metaData(deriveValidMetaData(xdomeaZipFile))
diff --git a/src/test/java/de/ozgcloud/xta/client/extension/XtaMessageExampleLoader.java b/src/test/java/de/ozgcloud/xta/client/extension/XtaMessageExampleLoader.java
index 8fa45ec..a4207e6 100644
--- a/src/test/java/de/ozgcloud/xta/client/extension/XtaMessageExampleLoader.java
+++ b/src/test/java/de/ozgcloud/xta/client/extension/XtaMessageExampleLoader.java
@@ -17,6 +17,7 @@ import java.util.function.Supplier;
import java.util.regex.Pattern;
import jakarta.activation.DataHandler;
+import jakarta.activation.FileDataSource;
import jakarta.annotation.Nullable;
import jakarta.mail.util.ByteArrayDataSource;
import jakarta.validation.constraints.NotBlank;
@@ -179,7 +180,7 @@ public class XtaMessageExampleLoader {
}
private static DataHandler createContentDataHandler(byte[] data) {
- return new DataHandler(new ByteArrayDataSource(data, "application/octet-stream"));
+ return new DataHandler(new FileDataSource("application/octet-stream"));
}
private static byte[] readBytesFromResource(String path) {
diff --git a/src/test/java/de/ozgcloud/xta/client/xdomea/XdomeaXtaMessageCreatorITCase.java b/src/test/java/de/ozgcloud/xta/client/xdomea/XdomeaXtaMessageCreatorITCase.java
index 7ff3ffd..84c3eea 100644
--- a/src/test/java/de/ozgcloud/xta/client/xdomea/XdomeaXtaMessageCreatorITCase.java
+++ b/src/test/java/de/ozgcloud/xta/client/xdomea/XdomeaXtaMessageCreatorITCase.java
@@ -22,7 +22,7 @@ class XdomeaXtaMessageCreatorITCase {
@BeforeEach
void setup() {
- creator = XdomeaXtaMessageCreatorFactory.createInstance().create();
+ creator = XdomeaXtaMessageCreator.createInstance();
}
@DisplayName("create message")
--
GitLab