OZG-6891 KOP-2735 javadoc: Explain xta client

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);

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
@@ -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

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;