From 1946cac5685abfd1029334ff227acca33ceedccf Mon Sep 17 00:00:00 2001
From: Jan Zickermann <jan.zickermann@dataport.de>
Date: Tue, 22 Oct 2024 12:29:21 +0200
Subject: [PATCH] OZG-6891 KOP-2735 javadoc: Explain xta client
---
.../de/ozgcloud/xta/client/XtaClient.java | 44 ++++++++++++++-----
.../xta/client/config/XtaClientConfig.java | 9 ++--
.../xta/client/model/XtaMessageStatus.java | 15 +++++++
3 files changed, 52 insertions(+), 16 deletions(-)
diff --git a/src/main/java/de/ozgcloud/xta/client/XtaClient.java b/src/main/java/de/ozgcloud/xta/client/XtaClient.java
index 4e7a1b6..f6a930e 100644
--- a/src/main/java/de/ozgcloud/xta/client/XtaClient.java
+++ b/src/main/java/de/ozgcloud/xta/client/XtaClient.java
@@ -69,23 +69,24 @@ public class XtaClient {
* Fetches messages for all client identifiers.
*
* <p>
- * For each configured client identifier in {@link XtaClientConfig#getClientIdentifiers()}, checks if the client identifier is an active account,
- * then lists its pending/unread messages. Next, uses
- * the {@link XtaClientConfig#getIsMessageSupported()} predicate to decide whether to fetch a listed message. Note that if no predicate is configured,
- * all listed messages are fetched.
+ * For each configured client identifier in {@link XtaClientConfig#getClientIdentifiers() clientIdentifiers}, checks if the client identifier is
+ * an active account, then lists its pending/unread messages. Next, uses the {@link XtaClientConfig#getIsMessageSupported() isMessageSupported}
+ * predicate to decide whether to fetch a listed message. Note that if no predicate is configured, all listed messages are fetched.
* </p>
* <p>
* For each fetched message, calls the given {@code processMessage}. If {@code processMessage} does not throw a runtime exception, closes the
- * message, i.e., marks it as read. Then, fetches the transport report for the successfully or unsuccessfully processed message. Note that
- * a transport is always returned for each processed message, unless a technical problem prevents fetching the transport report.
+ * message, i.e., marks it as read. Then, fetches the transport report for the successfully or unsuccessfully processed message. Note that a
+ * transport is always returned for each processed message, unless a technical problem prevents fetching the transport report.
* </p>
* <p>
- * A listing contains a maximum of {@link XtaClientConfig#getMaxListItems()} messages. However, listing is repeated, as long as there are
- * more messages pending and some message is closed successfully during the latest listing.
+ * A listing contains a maximum of {@link XtaClientConfig#getMaxListItems() maxListItems} messages. However, listing is repeated, as long as there
+ * are more messages pending and some message is closed successfully during the latest listing.
* </p>
*
* @param processMessage The consumer to process each fetched message.
- * @return The transport reports for all fetched/processed messages.
+ * @return The transport reports for all fetched/processed messages. Messages which have not been closed have an
+ * {@link XtaMessageStatus#OPEN OPEN} status. If the message has been closed the status is {@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 {
@@ -187,15 +188,34 @@ public class XtaClient {
log.error("Processing of message '%s' failed! Not closing message.".formatted(messageId), exception);
}
- public XtaTransportReport sendMessage(@Valid XtaMessage message) throws XtaClientException {
+ /**
+ * Sends the given message.
+ *
+ * <p>
+ * Author and reader identifiers are taken from the message metadata. The message is sent to the reader.
+ * </p>
+ * <p>
+ * First, checks whether the author refers to an active account. Then, checks that the service used by the message is available for the given
+ * 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.
+ * </p>
+ *
+ * @param messageWithoutMessageId The message to send without id and size.
+ * @return The transport report for the sent message. An {@link XtaMessageStatus#OPEN} status indicates that the message was sent with no error or
+ * warning. Moreover, the report contains the message metadata, including id and size values set by the server.
+ * @throws XtaClientException If a check fails or a technical problem occurs while sending the message.
+ */
+ public XtaTransportReport sendMessage(@NotNull @Valid XtaMessage messageWithoutMessageId) throws XtaClientException {
try {
- return sendMessageRaw(message);
+ return sendMessageRaw(messageWithoutMessageId);
} catch (RuntimeException exception) {
throw exceptionHandler.deriveXtaClientException(exception);
}
}
- XtaTransportReport sendMessageRaw(@Valid XtaMessage messageWithoutMessageId) {
+ XtaTransportReport sendMessageRaw(XtaMessage messageWithoutMessageId) {
var metaData = messageWithoutMessageId.metaData();
throwExceptionIfAccountInactive(metaData.authorIdentifier());
throwExceptionIfServiceNotAvailable(metaData);
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 5d07f40..a98b2ee 100644
--- a/src/main/java/de/ozgcloud/xta/client/config/XtaClientConfig.java
+++ b/src/main/java/de/ozgcloud/xta/client/config/XtaClientConfig.java
@@ -37,7 +37,7 @@ public class XtaClientConfig {
private final List<@Valid XtaIdentifier> clientIdentifiers = emptyList();
/**
- * This predicate may be used to filter listed messages before they are fetched. If null, all messages are fetched.
+ * This predicate may be used to filter listed messages before they are fetched. If null, all listed messages are fetched.
*
* <p>
* Note that, usually, all messages for a client identifier should be read, i.e., fetched and processed. However, it may be useful to filter
@@ -86,7 +86,7 @@ public class XtaClientConfig {
* The keystore used to authenticate this client to the server.
*
* <p>
- * The keystore should contain a private key and a certificate chain which the server trusts.
+ * The keystore should contain a private key and a certificate chain which the server trusts.
* </p>
*/
@Valid
@@ -97,7 +97,8 @@ public class XtaClientConfig {
* The truststore to authenticate the server to the client.
*
* <p>
- * The truststore should contain a root certificate or a certificate chain of the server. May be null if the server certificate is trusted by the JVM.
+ * The truststore should contain a root certificate or a certificate chain of the server. May be null if the server certificate is trusted by the
+ * JVM.
* </p>
*/
@Valid
@@ -108,7 +109,7 @@ public class XtaClientConfig {
* Whether to validate the XTA SOAP schema of the messages. Default is true.
*
* <p>
- * This option is intended for testing purposes and turing it off is not recommended.
+ * This option is intended for testing purposes and turing it off is not recommended.
* </p>
*/
@Builder.Default
diff --git a/src/main/java/de/ozgcloud/xta/client/model/XtaMessageStatus.java b/src/main/java/de/ozgcloud/xta/client/model/XtaMessageStatus.java
index 4f43119..ccf1baf 100644
--- a/src/main/java/de/ozgcloud/xta/client/model/XtaMessageStatus.java
+++ b/src/main/java/de/ozgcloud/xta/client/model/XtaMessageStatus.java
@@ -3,12 +3,27 @@ package de.ozgcloud.xta.client.model;
import lombok.Getter;
import lombok.RequiredArgsConstructor;
+/**
+ * Message status of a XTA message. The status is determined by the XTA sender/receiver server.
+ */
@RequiredArgsConstructor
@Getter
public enum XtaMessageStatus {
+ /**
+ * Status for a message that is open, i.e., has not been closed.
+ */
OPEN(0),
+ /**
+ * Status for a message that has been closed and has no errors or warnings.
+ */
GREEN(1),
+ /**
+ * Status for a message that has been closed and has warnings but no errors.
+ */
YELLOW(2),
+ /**
+ * Status for a message that has been closed and has errors.
+ */
RED(3);
private final Integer code;
--
GitLab