OZG-6891 Add javadoc for fetch messages

src/main/java/de/ozgcloud/xta/client/XtaClient.java

@@ -27,6 +27,22 @@ import lombok.Builder;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.log4j.Log4j2;
 
+/**
+ * A client for sending and receiving messages via the XTA protocol.
+ *
+ * <p>
+ * The client may be initialized for a {@link XtaClientConfig} configuration by {@link #from(XtaClientConfig)}.
+ * </p>
+ *
+ * Example:
+ * <pre>
+ * var client = XtaClient.from(config);
+ * var transportReport = client.sendMessage(message);
+ * var transportReports = client.fetchMessages(message -> {
+ *   // process message
+ * });
+ * </pre>
+ */
 @RequiredArgsConstructor(access = AccessLevel.MODULE)
 @Builder(access = AccessLevel.MODULE)
 @Log4j2
@@ -38,10 +54,40 @@ public class XtaClient {
 
 	static final String NO_MESSAGE_CLOSED_WARNING = "No message has been closed although more are pending. Try increasing max list items.";
 
+	/**
+	 * Initialize a new {@link XtaClient} instance from the given configuration.
+	 *
+	 * @param config The configuration for the client.
+	 * @return The initialized client.
+	 * @throws XtaClientInitializationException If the configuration is invalid or a configured keystore failed to initialize.
+	 */
 	public static XtaClient from(XtaClientConfig config) throws XtaClientInitializationException {
 		return XtaClientFactory.from(config).create();
 	}
 
+	/**
+	 * 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.
+	 * </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.
+	 * </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.
+	 * </p>
+	 *
+	 * @param processMessage The consumer to process each fetched message.
+	 * @return The transport reports for all fetched/processed messages.
+	 * @throws XtaClientException If a technical problem occurs while fetching messages.
+	 */
 	public List<XtaTransportReport> fetchMessages(@NotNull Consumer<XtaMessage> processMessage) throws XtaClientException {
 		try {
 			return fetchMessagesRaw(processMessage);

src/main/java/de/ozgcloud/xta/client/config/XtaClientConfig.java

@@ -17,6 +17,9 @@ import lombok.Getter;
 import lombok.RequiredArgsConstructor;
 import lombok.ToString;
 
+/**
+ * Configuration for creating an instance of {@link de.ozgcloud.xta.client.XtaClient}.
+ */
 @RequiredArgsConstructor
 @Getter
 @Builder
@@ -26,6 +29,9 @@ public class XtaClientConfig {
 	@Builder.Default
 	private final List<@Valid XtaIdentifier> clientIdentifiers = emptyList();
 
+	/**
+	 * avoid downloading unsupported messages
+	 */
 	@Builder.Default
 	private final Predicate<XtaMessageMetaData> isMessageSupported = null;