You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by ol...@apache.org on 2021/07/26 07:21:15 UTC
[sling-org-apache-sling-commons-messaging-mail] 20/23: [checkstyle]
(javadoc) MissingJavadocMethod
This is an automated email from the ASF dual-hosted git repository.
olli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-commons-messaging-mail.git
commit 4e6acb63cfeba9399004b44baddd953cd5f2f016
Author: Oliver Lietz <ol...@apache.org>
AuthorDate: Sun Jul 25 18:07:14 2021 +0200
[checkstyle] (javadoc) MissingJavadocMethod
---
checkstyle-suppressions.xml | 1 +
.../sling/commons/messaging/mail/MailService.java | 11 +
.../commons/messaging/mail/MessageBuilder.java | 342 +++++++++++++++++++++
.../commons/messaging/mail/MessageIdProvider.java | 8 +
4 files changed, 362 insertions(+)
diff --git a/checkstyle-suppressions.xml b/checkstyle-suppressions.xml
index 295d2af..76f9991 100644
--- a/checkstyle-suppressions.xml
+++ b/checkstyle-suppressions.xml
@@ -20,6 +20,7 @@
<!DOCTYPE suppressions PUBLIC "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN" "https://checkstyle.org/dtds/suppressions_1_2.dtd">
<suppressions>
<suppress checks="MissingJavadocType" files=".*\/internal\/.*\.java"/>
+ <suppress checks="MissingJavadocMethod" files=".*\/internal\/.*\.java"/>
<suppress checks="ClassFanOutComplexity" files=".*\/SimpleMailService\.java"/>
<suppress checks="ClassFanOutComplexity" files=".*\/SimpleMessageBuilder\.java"/>
<suppress checks="ClassDataAbstractionCoupling" files=".*\/SimpleMessageBuilder\.java"/>
diff --git a/src/main/java/org/apache/sling/commons/messaging/mail/MailService.java b/src/main/java/org/apache/sling/commons/messaging/mail/MailService.java
index e1d176f..35fe782 100644
--- a/src/main/java/org/apache/sling/commons/messaging/mail/MailService.java
+++ b/src/main/java/org/apache/sling/commons/messaging/mail/MailService.java
@@ -34,8 +34,19 @@ import org.osgi.annotation.versioning.ProviderType;
@ProviderType
public interface MailService extends MessageService<MimeMessage, Void> {
+ /**
+ * Provides the message builder for this service.
+ *
+ * @return the message builder for this service
+ */
public abstract @NotNull MessageBuilder getMessageBuilder();
+ /**
+ * Sends the given MIME message.
+ *
+ * @param message the MIME message to send
+ * @return {@link java.util.concurrent.CompletableFuture} for signaling completion
+ */
public abstract @NotNull CompletableFuture<Void> sendMessage(@NotNull MimeMessage message);
}
diff --git a/src/main/java/org/apache/sling/commons/messaging/mail/MessageBuilder.java b/src/main/java/org/apache/sling/commons/messaging/mail/MessageBuilder.java
index 3534491..eeeef5c 100644
--- a/src/main/java/org/apache/sling/commons/messaging/mail/MessageBuilder.java
+++ b/src/main/java/org/apache/sling/commons/messaging/mail/MessageBuilder.java
@@ -20,10 +20,15 @@ package org.apache.sling.commons.messaging.mail;
import java.util.Collection;
+import jakarta.mail.Address;
import jakarta.mail.Header;
+import jakarta.mail.Message.RecipientType;
import jakarta.mail.MessagingException;
+import jakarta.mail.Part;
import jakarta.mail.internet.AddressException;
import jakarta.mail.internet.InternetAddress;
+import jakarta.mail.internet.InternetHeaders;
+import jakarta.mail.internet.MimeBodyPart;
import jakarta.mail.internet.MimeMessage;
import org.jetbrains.annotations.NotNull;
@@ -38,78 +43,415 @@ import org.osgi.annotation.versioning.ProviderType;
@ProviderType
public interface MessageBuilder {
+ // header(s)
+
+ /**
+ * Creates a new header from given name and value and adds it to the list of headers.
+ *
+ * @param name the name of the header
+ * @param value the value of the header
+ * @return the message builder
+ * @see Header
+ * @see InternetHeaders
+ */
public abstract @NotNull MessageBuilder header(@NotNull final String name, @Nullable final String value);
+ /**
+ * Adds the given headers to the list of headers.
+ *
+ * @param headers the headers to add
+ * @return the message builder
+ * @see Header
+ * @see InternetHeaders
+ */
public abstract @NotNull MessageBuilder headers(@NotNull final Collection<Header> headers);
+ // from
+
+ /**
+ * Sets the given address for the RFC 822 <code>From</code> header field.
+ *
+ * @param from the address
+ * @return the message builder
+ * @see MimeMessage#setFrom(Address)
+ */
public abstract @NotNull MessageBuilder from(@NotNull final InternetAddress from);
+ /**
+ * Creates a new <code>InternetAddress</code> from given address and sets it for the RFC 822 <code>From</code> header field.
+ *
+ * @param address the address
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address string fails
+ * @see MimeMessage#setFrom(Address)
+ */
public abstract @NotNull MessageBuilder from(@NotNull final String address) throws AddressException;
+ /**
+ * Creates a new <code>InternetAddress</code> from given address and name and sets it for the RFC 822 <code>From</code> header field.
+ *
+ * @param address the address
+ * @param name the (personal) name
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address string fails
+ * @see MimeMessage#setFrom(Address)
+ */
public abstract @NotNull MessageBuilder from(@NotNull final String address, @NotNull final String name) throws AddressException;
+ // to
+
+ /**
+ * Adds the given address to the list of primary (<code>to</code>) recipients.
+ *
+ * @param to the address
+ * @return the message builder
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#TO
+ */
public abstract @NotNull MessageBuilder to(@NotNull final InternetAddress to);
+ /**
+ * Creates a new <code>InternetAddress</code> from given address and adds it to the list of primary (<code>to</code>) recipients.
+ *
+ * @param address the address
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address string fails
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#TO
+ */
public abstract @NotNull MessageBuilder to(@NotNull final String address) throws AddressException;
+ /**
+ * Creates a new <code>InternetAddress</code> from given address and name and adds it to the list of primary (<code>to</code>) recipients.
+ *
+ * @param address the address
+ * @param name the (personal) name
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address string fails
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#TO
+ */
public abstract @NotNull MessageBuilder to(@NotNull final String address, @NotNull final String name) throws AddressException;
+ /**
+ * Adds the given addresses to the list of primary (<code>to</code>) recipients.
+ *
+ * @param addresses the addresses
+ * @return the message builder
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#TO
+ */
public abstract @NotNull MessageBuilder to(@NotNull final InternetAddress[] addresses);
+ /**
+ * Creates new <code>InternetAddress</code>es from given addresses and adds them to the list of primary (<code>to</code>) recipients.
+ *
+ * @param addresses the addresses
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address strings fails
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#TO
+ */
public abstract @NotNull MessageBuilder to(@NotNull final String[] addresses) throws AddressException;
+ /**
+ * Creates new <code>InternetAddress</code>es from given addresses and adds them to the list of primary (<code>to</code>) recipients.
+ *
+ * @param addresses the addresses
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address strings fails
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#TO
+ */
public abstract @NotNull MessageBuilder to(@NotNull final Collection<String> addresses) throws AddressException;
+ // cc
+
+ /**
+ * Adds the given address to the list of carbon copy (<code>cc</code>) recipients.
+ *
+ * @param cc the address
+ * @return the message builder
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#CC
+ */
public abstract @NotNull MessageBuilder cc(@NotNull final InternetAddress cc);
+ /**
+ * Creates a new <code>InternetAddress</code> from given address and adds it to the list of carbon copy (<code>cc</code>) recipients.
+ *
+ * @param address the address
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address string fails
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#CC
+ */
public abstract @NotNull MessageBuilder cc(@NotNull final String address) throws AddressException;
+ /**
+ * Creates a new <code>InternetAddress</code> from given address and name and adds it to the list of carbon copy (<code>cc</code>) recipients.
+ *
+ * @param address the address
+ * @param name the (personal) name
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address string fails
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#CC
+ */
public abstract @NotNull MessageBuilder cc(@NotNull final String address, @NotNull final String name) throws AddressException;
+ /**
+ * Adds the given addresses to the list of carbon copy (<code>cc</code>) recipients.
+ *
+ * @param addresses the addresses
+ * @return the message builder
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#CC
+ */
public abstract @NotNull MessageBuilder cc(@NotNull final InternetAddress[] addresses);
+ /**
+ * Creates new <code>InternetAddress</code>es from given addresses and adds them to the list of carbon copy (<code>cc</code>) recipients.
+ *
+ * @param addresses the addresses
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address strings fails
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#CC
+ */
public abstract @NotNull MessageBuilder cc(@NotNull final String[] addresses) throws AddressException;
+ /**
+ * Creates new <code>InternetAddress</code>es from given addresses and adds them to the list of carbon copy (<code>cc</code>) recipients.
+ *
+ * @param addresses the addresses
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address strings fails
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#CC
+ */
public abstract @NotNull MessageBuilder cc(@NotNull final Collection<String> addresses) throws AddressException;
+ // bcc
+
+ /**
+ * Adds the given address to the list of blind carbon copy (<code>bcc</code>) recipients.
+ *
+ * @param bcc the address
+ * @return the message builder
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#BCC
+ */
public abstract @NotNull MessageBuilder bcc(@NotNull final InternetAddress bcc);
+ /**
+ * Creates a new <code>InternetAddress</code> from given address and adds it to the list of blind carbon copy (<code>bcc</code>) recipients.
+ *
+ * @param address the address
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address string fails
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#BCC
+ */
public abstract @NotNull MessageBuilder bcc(@NotNull final String address) throws AddressException;
+ /**
+ * Creates a new <code>InternetAddress</code> from given address and name and adds it to the list of blind carbon copy (<code>bcc</code>) recipients.
+ *
+ * @param address the address
+ * @param name the (personal) name
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address string fails
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#BCC
+ */
public abstract @NotNull MessageBuilder bcc(@NotNull final String address, final String name) throws AddressException;
+ /**
+ * Adds the given addresses to the list of blind carbon copy (<code>bcc</code>) recipients.
+ *
+ * @param addresses the addresses
+ * @return the message builder
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#BCC
+ */
public abstract @NotNull MessageBuilder bcc(@NotNull final InternetAddress[] addresses);
+ /**
+ * Creates new <code>InternetAddress</code>es from given addresses and adds them to the list of blind carbon copy (<code>bcc</code>) recipients.
+ *
+ * @param addresses the addresses
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address strings fails
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#BCC
+ */
public abstract @NotNull MessageBuilder bcc(@NotNull final String[] addresses) throws AddressException;
+ /**
+ * Creates new <code>InternetAddress</code>es from given addresses and adds them to the list of blind carbon copy (<code>bcc</code>) recipients.
+ *
+ * @param addresses the addresses
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address strings fails
+ * @see MimeMessage#setRecipients(RecipientType, Address[])
+ * @see RecipientType#BCC
+ */
public abstract @NotNull MessageBuilder bcc(@NotNull final Collection<String> addresses) throws AddressException;
+ // replyTo
+
+ /**
+ * Adds the given address to the list of addresses for the RFC 822 <code>Reply-To</code> header field.
+ *
+ * @param replyTo the address
+ * @return the message builder
+ * @see MimeMessage#setReplyTo(Address[])
+ */
public abstract @NotNull MessageBuilder replyTo(@NotNull final InternetAddress replyTo);
+ /**
+ * Creates a new <code>InternetAddress</code> from given address and adds it to the list of addresses for the RFC 822 <code>Reply-To</code> header field.
+ *
+ * @param address the address
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address string fails
+ * @see MimeMessage#setReplyTo(Address[])
+ */
public abstract @NotNull MessageBuilder replyTo(@NotNull final String address) throws AddressException;
+ /**
+ * Creates a new <code>InternetAddress</code> from given address and name and adds it to the list of addresses for the RFC 822 <code>Reply-To</code> header field.
+ *
+ * @param address the address
+ * @param name the (personal) name
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address string fails
+ * @see MimeMessage#setReplyTo(Address[])
+ */
public abstract @NotNull MessageBuilder replyTo(@NotNull final String address, final String name) throws AddressException;
+ /**
+ * Adds the given addresses to the list of addresses for the RFC 822 <code>Reply-To</code> header field.
+ *
+ * @param addresses the addresses
+ * @return the message builder
+ * @see MimeMessage#setReplyTo(Address[])
+ */
public abstract @NotNull MessageBuilder replyTo(@NotNull final InternetAddress[] addresses);
+ /**
+ * Creates new <code>InternetAddress</code>es from given addresses and adds them to the list of addresses for the RFC 822 <code>Reply-To</code> header field.
+ *
+ * @param addresses the addresses
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address strings fails
+ * @see MimeMessage#setReplyTo(Address[])
+ */
public abstract @NotNull MessageBuilder replyTo(@NotNull final String[] addresses) throws AddressException;
+ /**
+ * Creates new <code>InternetAddress</code>es from given addresses and adds them to the list of addresses for the RFC 822 <code>Reply-To</code> header field.
+ *
+ * @param addresses the addresses
+ * @return the message builder
+ * @throws AddressException if creating an <code>InternetAddress</code> from given address strings fails
+ * @see MimeMessage#setReplyTo(Address[])
+ */
public abstract @NotNull MessageBuilder replyTo(@NotNull final Collection<String> addresses) throws AddressException;
+ // subject
+
+ /**
+ * Sets the given subject into the <code>Subject</code> header field.
+ *
+ * @param subject the subject of the message
+ * @return the message builder
+ * @see MimeMessage#setSubject(String)
+ */
public abstract @NotNull MessageBuilder subject(@NotNull final String subject);
+ // text
+
+ /**
+ * Sets the plain text content.
+ *
+ * @param text the plain text content
+ * @return the message builder
+ * @see MimeMessage#setText(String, String)
+ * @see MimeBodyPart#setContent(Object, String)
+ */
public abstract @NotNull MessageBuilder text(@NotNull final String text);
+ // html
+
+ /**
+ * Sets the HTML content.
+ *
+ * @param html the HTML content
+ * @return the message builder
+ * @see MimeBodyPart#setContent(Object, String)
+ */
public abstract @NotNull MessageBuilder html(@NotNull final String html);
+ // attachment
+
+ /**
+ * Attaches the given content to the message.
+ *
+ * @param content the content to attach
+ * @param type the type of the content (content/media/MIME type)
+ * @param filename the filename of the attachment
+ * @return the message builder
+ * @see Part#ATTACHMENT
+ */
public abstract @NotNull MessageBuilder attachment(final byte @NotNull [] content, @NotNull final String type, @NotNull final String filename);
+ /**
+ * Attaches the given content with headers to the message.
+ *
+ * @param content the content to attach
+ * @param type the type of the content (content/media/MIME type)
+ * @param filename the filename of the attachment
+ * @param headers the headers for the content
+ * @return the message builder
+ * @see Part#ATTACHMENT
+ */
public abstract @NotNull MessageBuilder attachment(final byte @NotNull [] content, @NotNull final String type, @NotNull final String filename, @Nullable final Collection<Header> headers);
+ // inline
+
+ /**
+ * Inlines the given content into the message.
+ *
+ * @param content the content to inline
+ * @param type the type of the content (content/media/MIME type)
+ * @param cid the content identifier (<code>Content-ID</code>)
+ * @return the message builder
+ * @see Part#INLINE
+ */
public abstract @NotNull MessageBuilder inline(final byte @NotNull [] content, @NotNull final String type, @NotNull final String cid);
+ /**
+ * Inlines the given content with headers into the message.
+ *
+ * @param content the content to inline
+ * @param type the type of the content (content/media/MIME type)
+ * @param cid the content identifier (<code>Content-ID</code>)
+ * @param headers the headers for the content
+ * @return the message builder
+ * @see Part#INLINE
+ */
public abstract @NotNull MessageBuilder inline(final byte @NotNull [] content, @NotNull final String type, @NotNull final String cid, @Nullable final Collection<Header> headers);
+ // build
+
+ /**
+ * Builds the MIME message with the given input.
+ *
+ * @return the built message
+ * @throws MessagingException if building message fails
+ */
public abstract @NotNull MimeMessage build() throws MessagingException;
}
diff --git a/src/main/java/org/apache/sling/commons/messaging/mail/MessageIdProvider.java b/src/main/java/org/apache/sling/commons/messaging/mail/MessageIdProvider.java
index 1948677..6113263 100644
--- a/src/main/java/org/apache/sling/commons/messaging/mail/MessageIdProvider.java
+++ b/src/main/java/org/apache/sling/commons/messaging/mail/MessageIdProvider.java
@@ -32,6 +32,14 @@ import org.osgi.annotation.versioning.ProviderType;
@ProviderType
public interface MessageIdProvider {
+ /**
+ * Provides an identifier for given message.
+ *
+ * @param message the message to provide an identifier for
+ * @return the message identifier
+ * @throws MessagingException if providing an identifier fails
+ * @see MimeMessage#getMessageID()
+ */
public abstract @NotNull String getMessageId(@NotNull final MimeMessage message) throws MessagingException;
}