This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-email.git
The following commit(s) were added to refs/heads/master by this push:
new cbdfc08 Javadoc
cbdfc08 is described below
commit cbdfc08ff0ec73e5e19784c88db78a021a31ab29
Author: Gary Gregory <garydgreg...@gmail.com>
AuthorDate: Fri Dec 15 10:37:05 2023 -0500
Javadoc
- Better parameter names
- Better instance variable names
- Better private method name
- Close HTML tags
---
.../org/apache/commons/mail/EmailAttachment.java | 3 ++-
.../java/org/apache/commons/mail/EmailConstants.java | 1 +
.../java/org/apache/commons/mail/EmailException.java | 4 +++-
.../java/org/apache/commons/mail/EmailUtils.java | 9 ++-------
src/main/java/org/apache/commons/mail/HtmlEmail.java | 20 +++++++++-----------
5 files changed, 17 insertions(+), 20 deletions(-)
diff --git a/src/main/java/org/apache/commons/mail/EmailAttachment.java
b/src/main/java/org/apache/commons/mail/EmailAttachment.java
index bfe2044..d6caa1c 100644
--- a/src/main/java/org/apache/commons/mail/EmailAttachment.java
+++ b/src/main/java/org/apache/commons/mail/EmailAttachment.java
@@ -19,11 +19,12 @@ package org.apache.commons.mail;
import java.net.URL;
/**
- * This class models an email attachment. Used by MultiPartEmail.
+ * This class models an email attachment. Used by {@link MultiPartEmail}.
*
* @since 1.0
*/
public class EmailAttachment {
+
/** Definition of the part being an attachment. */
public static final String ATTACHMENT = javax.mail.Part.ATTACHMENT;
diff --git a/src/main/java/org/apache/commons/mail/EmailConstants.java
b/src/main/java/org/apache/commons/mail/EmailConstants.java
index 50729b1..fb7a660 100644
--- a/src/main/java/org/apache/commons/mail/EmailConstants.java
+++ b/src/main/java/org/apache/commons/mail/EmailConstants.java
@@ -25,6 +25,7 @@ package org.apache.commons.mail;
* @since 1.3
*/
public final class EmailConstants {
+
/** @deprecated since 1.3, not in use since 1.0 */
@Deprecated
public static final String SENDER_EMAIL = "sender.email";
diff --git a/src/main/java/org/apache/commons/mail/EmailException.java
b/src/main/java/org/apache/commons/mail/EmailException.java
index e9148d9..0009227 100644
--- a/src/main/java/org/apache/commons/mail/EmailException.java
+++ b/src/main/java/org/apache/commons/mail/EmailException.java
@@ -26,8 +26,10 @@ import java.nio.charset.Charset;
* Exception thrown when a checked error occurs in commons-email.
* <p>
* Adapted from FunctorException in Commons Collections.
+ * </p>
* <p>
- * Emulation support for nested exceptions has been removed in {@code Email
1.3}, supported by JDK ≥ 1.4.
+ * Emulation support for nested exceptions has been removed in {@code Email
1.3}, supported by JDK 1.4 and above.
+ * </p>
*
* @since 1.0
*/
diff --git a/src/main/java/org/apache/commons/mail/EmailUtils.java
b/src/main/java/org/apache/commons/mail/EmailUtils.java
index 9a9f813..aa82316 100644
--- a/src/main/java/org/apache/commons/mail/EmailUtils.java
+++ b/src/main/java/org/apache/commons/mail/EmailUtils.java
@@ -32,11 +32,9 @@ import org.apache.commons.mail.util.MimeMessageUtils;
/**
* Utility methods used by commons-email.
- *
* <p>
* These methods are copied from other commons components (commons-lang) to
avoid creating a dependency for such a small component.
* </p>
- *
* <p>
* This is a package scoped class, and should not be used directly by users.
* </p>
@@ -137,7 +135,7 @@ final class EmailUtils {
* Checks if a String is empty ("") or null.
* <p>
* Copied from Commons Lang v2.1, svn 240418
- * <p>
+ * </p>
*
* @param str the String to check, may be null
* @return {@code true} if the String is empty or null
@@ -150,7 +148,7 @@ final class EmailUtils {
* Checks if a String is not empty ("") and not null.
* <p>
* Copied from Commons Lang v2.1, svn 240418
- * <p>
+ * </p>
*
* @param str the String to check, may be null
* @return {@code true} if the String is not empty and not null
@@ -161,16 +159,13 @@ final class EmailUtils {
/**
* Creates a random string based on a variety of options, using supplied
source of randomness.
- *
* <p>
* If start and end are both {@code 0}, start and end are set to {@code '
'} and {@code 'z'}, the ASCII printable characters, will be used, unless letters
* and numbers are both {@code false}, in which case, start and end are
set to {@code 0} and {@code Integer.MAX_VALUE}.
* </p>
- *
* <p>
* If set is not {@code null}, characters between start and end are chosen.
* </p>
- *
* <p>
* This method accepts a user-supplied {@link Random} instance to use as a
source of randomness. By seeding a single {@link Random} instance with a fixed
* seed and using it for each call, the same random sequence of strings
can be generated repeatedly and predictably.
diff --git a/src/main/java/org/apache/commons/mail/HtmlEmail.java
b/src/main/java/org/apache/commons/mail/HtmlEmail.java
index 9c21b45..4e79683 100644
--- a/src/main/java/org/apache/commons/mail/HtmlEmail.java
+++ b/src/main/java/org/apache/commons/mail/HtmlEmail.java
@@ -37,7 +37,6 @@ import javax.mail.internet.MimeMultipart;
/**
* An HTML multipart email.
- *
* <p>
* This class is used to send HTML formatted email. A text message can also be
set for HTML unaware email clients, such as text-based email clients.
* </p>
@@ -53,10 +52,10 @@ import javax.mail.internet.MimeMultipart;
* {@code multipart/alternative}.
* </p>
* <h2>Embedding Images and Media</h2>
- *
* <p>
* It is also possible to embed URLs, files, or arbitrary {@code DataSource}s
directly into the body of the mail:
* </p>
+ *
* <pre>
* HtmlEmail he = new HtmlEmail();
* File img = new File("my/image.gif");
@@ -178,7 +177,7 @@ public class HtmlEmail extends MultiPartEmail {
*/
protected String text;
- /** Html part of the message. */
+ /** HTML part of the message. */
protected String html;
/**
@@ -281,8 +280,8 @@ public class HtmlEmail extends MultiPartEmail {
}
/**
- * Does the work of actually building the MimeMessage. Please note that a
user rarely calls this method directly and only if he/she is interested in the
- * sending the underlying MimeMessage without commons-email.
+ * Builds the MimeMessage. Please note that a user rarely calls this
method directly and only if he/she is interested in the sending the underlying
+ * MimeMessage without commons-email.
*
* @throws EmailException if there was an error.
* @since 1.0
@@ -436,7 +435,7 @@ public class HtmlEmail extends MultiPartEmail {
}
/**
- * Attempts to parse the specified {@code String} as a URL that will then
be embedded in the message.
+ * Parses the specified {@code String} as a URL that will then be embedded
in the message.
*
* @param urlString String representation of the URL.
* @param name The name that will be set in the file name header
field.
@@ -462,16 +461,17 @@ public class HtmlEmail extends MultiPartEmail {
* This method embeds a file located by an URL into the mail body. It
allows, for instance, to add inline images to the email. Inline files may be
* referenced with a {@code cid:xxxxxx} URL, where xxxxxx is the
Content-ID returned by the embed function. It is an error to bind the same name
to more
* than one URL; if the same URL is embedded multiple times, the same
Content-ID is guaranteed to be returned.
- *
+ * </p>
* <p>
* While functionally the same as passing {@code URLDataSource} to {@link
#embed(DataSource, String, String)}, this method attempts to validate the URL
* before embedding it in the message and will throw {@code
EmailException} if the validation fails. In this case, the {@code HtmlEmail}
object will not be
* changed.
- *
+ * </p>
* <p>
* NOTE: Clients should take care to ensure that different URLs are bound
to different names. This implementation tries to detect this and throw
* {@code EmailException}. However, it is not guaranteed to catch all
cases, especially when the URL refers to a remote HTTP host that may be part of
a
* virtual host cluster.
+ * </p>
*
* @param url The URL of the file.
* @param name The name that will be set in the file name header field.
@@ -484,7 +484,6 @@ public class HtmlEmail extends MultiPartEmail {
if (EmailUtils.isEmpty(name)) {
throw new EmailException("name cannot be null or empty");
}
-
// check if a URLDataSource for this name has already been attached;
// if so, return the cached CID value.
final InlineImage inlineImage = inlineEmbeds.get(name);
@@ -500,7 +499,6 @@ public class HtmlEmail extends MultiPartEmail {
}
throw new EmailException("embedded name '" + name + "' is already
bound to URL " + urlDataSource.getURL() + "; existing names cannot be rebound");
}
-
// verify that the URL is valid
InputStream inputStream = null;
try {
@@ -516,7 +514,6 @@ public class HtmlEmail extends MultiPartEmail {
{
/* sigh */ }
}
-
return embed(new URLDataSource(url), name);
}
@@ -542,6 +539,7 @@ public class HtmlEmail extends MultiPartEmail {
* <p>
* This method overrides {@link MultiPartEmail#setMsg(String)} in order to
send an HTML message instead of a plain text message in the mail body. The
* message is formatted in HTML for the HTML part of the message; it is
left as is in the alternate text part.
+ * </p>
*
* @param msg the message text to use
* @return this {@code HtmlEmail}
