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
commit f3fb8a1b97d0cd61090f453fe08b25660cb98674
Author: Gary Gregory <garydgreg...@gmail.com>
AuthorDate: Wed Dec 13 16:33:40 2023 -0500
Javadoc
- Format tweaks
- Inline single use local variable
- Better internal names
- Internal refactoring
---
.../apache/commons/mail/ByteArrayDataSource.java | 1 +
.../apache/commons/mail/DataSourceResolver.java | 1 +
.../apache/commons/mail/DefaultAuthenticator.java | 1 +
src/main/java/org/apache/commons/mail/Email.java | 40 ++++-------
.../java/org/apache/commons/mail/HtmlEmail.java | 77 +++++++++-------------
5 files changed, 47 insertions(+), 73 deletions(-)
diff --git a/src/main/java/org/apache/commons/mail/ByteArrayDataSource.java
b/src/main/java/org/apache/commons/mail/ByteArrayDataSource.java
index b471ee1..70da146 100644
--- a/src/main/java/org/apache/commons/mail/ByteArrayDataSource.java
+++ b/src/main/java/org/apache/commons/mail/ByteArrayDataSource.java
@@ -43,6 +43,7 @@ import javax.activation.DataSource;
*/
@Deprecated
public class ByteArrayDataSource implements DataSource {
+
/** Define the buffer size. */
public static final int BUFFER_SIZE = 512;
diff --git a/src/main/java/org/apache/commons/mail/DataSourceResolver.java
b/src/main/java/org/apache/commons/mail/DataSourceResolver.java
index dbb6753..7158f4d 100644
--- a/src/main/java/org/apache/commons/mail/DataSourceResolver.java
+++ b/src/main/java/org/apache/commons/mail/DataSourceResolver.java
@@ -26,6 +26,7 @@ import javax.activation.DataSource;
* @since 1.3
*/
public interface DataSourceResolver {
+
/**
* Resolves the given resource location to a {@code DataSource}.
*
diff --git a/src/main/java/org/apache/commons/mail/DefaultAuthenticator.java
b/src/main/java/org/apache/commons/mail/DefaultAuthenticator.java
index 8ff56e8..8861e4c 100644
--- a/src/main/java/org/apache/commons/mail/DefaultAuthenticator.java
+++ b/src/main/java/org/apache/commons/mail/DefaultAuthenticator.java
@@ -25,6 +25,7 @@ import javax.mail.PasswordAuthentication;
* @since 1.0
*/
public class DefaultAuthenticator extends Authenticator {
+
/** Stores the login information for authentication. */
private final PasswordAuthentication authentication;
diff --git a/src/main/java/org/apache/commons/mail/Email.java
b/src/main/java/org/apache/commons/mail/Email.java
index 596ef28..035a66d 100644
--- a/src/main/java/org/apache/commons/mail/Email.java
+++ b/src/main/java/org/apache/commons/mail/Email.java
@@ -52,6 +52,7 @@ import org.apache.commons.mail.util.IDNEmailAddressConverter;
* @since 1.0
*/
public abstract class Email {
+
private static final InternetAddress[] EMPTY_INTERNET_ADDRESS_ARRAY = {};
/** @deprecated since 1.3, use {@link EmailConstants#SENDER_EMAIL} instead
*/
@@ -170,6 +171,10 @@ public abstract class Email {
@Deprecated
public static final String MAIL_SMTP_TIMEOUT =
EmailConstants.MAIL_SMTP_TIMEOUT;
+ private static boolean isEmpty(final Collection<?> collection) {
+ return collection == null || collection.isEmpty();
+ }
+
/** The email message to send. */
protected MimeMessage message;
@@ -403,11 +408,9 @@ public abstract class Email {
if (isEmpty(emails)) {
throw new EmailException("Address List provided was invalid");
}
-
for (final String email : emails) {
addCc(email, null);
}
-
return this;
}
@@ -456,7 +459,6 @@ public abstract class Email {
if (EmailUtils.isEmpty(value)) {
throw new IllegalArgumentException("value can not be null or
empty");
}
-
this.headers.put(name, value);
}
@@ -532,11 +534,9 @@ public abstract class Email {
if (isEmpty(emails)) {
throw new EmailException("Address List provided was invalid");
}
-
for (final String email : emails) {
addTo(email, null);
}
-
return this;
}
@@ -690,7 +690,6 @@ public abstract class Email {
if (EmailUtils.isEmpty(value)) {
throw new IllegalArgumentException("value can not be null or
empty");
}
-
try {
return MimeUtility.fold(name.length() + 2,
MimeUtility.encodeText(value, this.charset, null));
} catch (final UnsupportedEncodingException e) {
@@ -709,10 +708,8 @@ public abstract class Email {
*/
private InternetAddress createInternetAddress(final String email, final
String name, final String charsetName) throws EmailException {
InternetAddress address;
-
try {
address = new InternetAddress(new
IDNEmailAddressConverter().toASCII(email));
-
// check name input
if (EmailUtils.isNotEmpty(name)) {
// check charset input.
@@ -725,7 +722,6 @@ public abstract class Email {
address.setPersonal(name, set.name());
}
}
-
// run sanity check on new InternetAddress object; if this fails
// it will throw AddressException.
address.validate();
@@ -1079,16 +1075,12 @@ public abstract class Email {
* @throws EmailException the sending failed
*/
public String sendMimeMessage() throws EmailException {
- final Object object = this.message;
- Objects.requireNonNull(object, "MimeMessage has not been created yet");
-
+ Objects.requireNonNull(message, "MimeMessage has not been created
yet");
try {
- Transport.send(this.message);
+ Transport.send(message);
return this.message.getMessageID();
} catch (final Throwable t) {
- final String msg = "Sending the email to the following server
failed : " + this.getHostName() + ":" + this.getSmtpPort();
-
- throw new EmailException(msg, t);
+ throw new EmailException("Sending the email to the following
server failed : " + this.getHostName() + ":" + this.getSmtpPort(), t);
}
}
@@ -1130,10 +1122,9 @@ public abstract class Email {
* @since 1.0
*/
public Email setBcc(final Collection<InternetAddress> aCollection) throws
EmailException {
- if (aCollection == null || aCollection.isEmpty()) {
+ if (isEmpty(aCollection)) {
throw new EmailException("Address List provided was invalid");
}
-
this.bccList = new ArrayList<>(aCollection);
return this;
}
@@ -1149,7 +1140,6 @@ public abstract class Email {
*/
public Email setBounceAddress(final String email) {
checkSessionAlreadyInitialized();
-
if (email != null && !email.isEmpty()) {
try {
this.bounceAddress = createInternetAddress(email, null,
this.charset).getAddress();
@@ -1174,10 +1164,9 @@ public abstract class Email {
* @since 1.0
*/
public Email setCc(final Collection<InternetAddress> aCollection) throws
EmailException {
- if (aCollection == null || aCollection.isEmpty()) {
+ if (isEmpty(aCollection)) {
throw new EmailException("Address List provided was invalid");
}
-
this.ccList = new ArrayList<>(aCollection);
return this;
}
@@ -1282,7 +1271,6 @@ public abstract class Email {
*/
public void setHeaders(final Map<String, String> map) {
this.headers.clear();
-
for (final Map.Entry<String, String> entry : map.entrySet()) {
addHeader(entry.getKey(), entry.getValue());
}
@@ -1394,10 +1382,9 @@ public abstract class Email {
* @since 1.1
*/
public Email setReplyTo(final Collection<InternetAddress> aCollection)
throws EmailException {
- if (aCollection == null || aCollection.isEmpty()) {
+ if (isEmpty(aCollection)) {
throw new EmailException("Address List provided was invalid");
}
-
this.replyList = new ArrayList<>(aCollection);
return this;
}
@@ -1444,11 +1431,9 @@ public abstract class Email {
*/
public void setSmtpPort(final int aPortNumber) {
checkSessionAlreadyInitialized();
-
if (aPortNumber < 1) {
throw new IllegalArgumentException("Cannot connect to a port
number that is less than 1 ( " + aPortNumber + " )");
}
-
this.smtpPort = Integer.toString(aPortNumber);
}
@@ -1596,10 +1581,9 @@ public abstract class Email {
* @since 1.0
*/
public Email setTo(final Collection<InternetAddress> aCollection) throws
EmailException {
- if (aCollection == null || aCollection.isEmpty()) {
+ if (isEmpty(aCollection)) {
throw new EmailException("Address List provided was invalid");
}
-
this.toList = new ArrayList<>(aCollection);
return this;
}
diff --git a/src/main/java/org/apache/commons/mail/HtmlEmail.java
b/src/main/java/org/apache/commons/mail/HtmlEmail.java
index d4415dd..828b60a 100644
--- a/src/main/java/org/apache/commons/mail/HtmlEmail.java
+++ b/src/main/java/org/apache/commons/mail/HtmlEmail.java
@@ -40,23 +40,23 @@ import javax.mail.internet.MimeMultipart;
*
* <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>
* <p>
* This class also inherits from {@link MultiPartEmail}, so it is easy to add
attachments to the email.
- *
+ * </p>
* <p>
* To send an email in HTML, one should create a {@code HtmlEmail}, then use
the {@link #setFrom(String)}, {@link #addTo(String)} etc. methods. The HTML
content
* can be set with the {@link #setHtmlMsg(String)} method. The alternative
text content can be set with {@link #setTextMsg(String)}.
- *
+ * </p>
* <p>
* Either the text or HTML can be omitted, in which case the "main" part of
the multipart becomes whichever is supplied rather than a
* {@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");
@@ -69,22 +69,24 @@ import javax.mail.internet.MimeMultipart;
* he.setHtmlMsg(msg.toString());
* // code to set the other email fields (not shown)
* </pre>
- *
* <p>
* Embedded entities are tracked by their name, which for {@code File}s is the
file name itself and for {@code URL}s is the canonical path. It is an error to
* bind the same name to more than one entity, and this class will attempt to
validate that for {@code File}s and {@code URL}s. When embedding a
* {@code DataSource}, the code uses the {@code equals()} method defined on
the {@code DataSource}s to make the determination.
+ * </p>
*
* @since 1.0
*/
public class HtmlEmail extends MultiPartEmail {
+
/**
* Private bean class that encapsulates data about URL contents that are
embedded in the final email.
*
* @since 1.1
*/
private static final class InlineImage {
- /** content id. */
+
+ /** Content id. */
private final String cid;
/** {@code DataSource} for the content. */
private final DataSource dataSource;
@@ -119,10 +121,7 @@ public class HtmlEmail extends MultiPartEmail {
if (!(obj instanceof InlineImage)) {
return false;
}
-
- final InlineImage that = (InlineImage) obj;
-
- return this.cid.equals(that.cid);
+ return this.cid.equals(((InlineImage) obj).cid);
}
/**
@@ -165,6 +164,7 @@ public class HtmlEmail extends MultiPartEmail {
/** Definition of the length of generated CID's. */
public static final int CID_LENGTH = 10;
+
/** prefix for default HTML mail. */
private static final String HTML_MESSAGE_START = "<html><body><pre>";
@@ -308,15 +308,15 @@ public class HtmlEmail extends MultiPartEmail {
public String embed(final DataSource dataSource, final String name) throws
EmailException {
// check if the DataSource has already been attached;
// if so, return the cached CID value.
- final InlineImage ii = inlineEmbeds.get(name);
- if (ii != null) {
+ final InlineImage inlineImage = inlineEmbeds.get(name);
+ if (inlineImage != null) {
// make sure the supplied URL points to the same thing
// as the one already associated with this name.
- if (dataSource.equals(ii.getDataSource())) {
- return ii.getCid();
+ if (dataSource.equals(inlineImage.getDataSource())) {
+ return inlineImage.getCid();
}
- throw new EmailException(
- "embedded DataSource '" + name + "' is already bound to
name " + ii.getDataSource().toString() + "; existing names cannot be rebound");
+ throw new EmailException("embedded DataSource '" + name + "' is
already bound to name " + inlineImage.getDataSource().toString()
+ + "; existing names cannot be rebound");
}
final String cid =
EmailUtils.randomAlphabetic(HtmlEmail.CID_LENGTH).toLowerCase();
@@ -337,21 +337,16 @@ public class HtmlEmail extends MultiPartEmail {
if (EmailUtils.isEmpty(name)) {
throw new EmailException("name cannot be null or empty");
}
-
final MimeBodyPart mbp = new MimeBodyPart();
-
try {
// URL encode the cid according to RFC 2392
final String encodedCid = EmailUtils.encodeUrl(cid);
-
mbp.setDataHandler(new DataHandler(dataSource));
mbp.setFileName(name);
mbp.setDisposition(EmailAttachment.INLINE);
mbp.setContentID("<" + encodedCid + ">");
-
- final InlineImage ii = new InlineImage(encodedCid, dataSource,
mbp);
- this.inlineEmbeds.put(name, ii);
-
+ final InlineImage inlineImage = new InlineImage(encodedCid,
dataSource, mbp);
+ this.inlineEmbeds.put(name, inlineImage);
return encodedCid;
} catch (final MessagingException uee) {
throw new EmailException(uee);
@@ -369,8 +364,7 @@ public class HtmlEmail extends MultiPartEmail {
* @since 1.1
*/
public String embed(final File file) throws EmailException {
- final String cid =
EmailUtils.randomAlphabetic(HtmlEmail.CID_LENGTH).toLowerCase(Locale.ENGLISH);
- return embed(file, cid);
+ return embed(file,
EmailUtils.randomAlphabetic(HtmlEmail.CID_LENGTH).toLowerCase(Locale.ENGLISH));
}
/**
@@ -408,9 +402,9 @@ public class HtmlEmail extends MultiPartEmail {
// check if a FileDataSource for this name has already been attached;
// if so, return the cached CID value.
- final InlineImage ii = inlineEmbeds.get(file.getName());
- if (ii != null) {
- final FileDataSource fileDataSource = (FileDataSource)
ii.getDataSource();
+ final InlineImage inlineImage = inlineEmbeds.get(file.getName());
+ if (inlineImage != null) {
+ final FileDataSource fileDataSource = (FileDataSource)
inlineImage.getDataSource();
// make sure the supplied file has the same canonical path
// as the one already associated with this name.
String existingFilePath = null;
@@ -420,7 +414,7 @@ public class HtmlEmail extends MultiPartEmail {
throw new EmailException("couldn't get canonical path for file
" + fileDataSource.getFile().getName() + "which has already been embedded",
ioe);
}
if (filePath.equals(existingFilePath)) {
- return ii.getCid();
+ return inlineImage.getCid();
}
throw new EmailException(
"embedded name '" + file.getName() + "' is already bound
to file " + existingFilePath + "; existing names cannot be rebound");
@@ -492,30 +486,30 @@ public class HtmlEmail extends MultiPartEmail {
// check if a URLDataSource for this name has already been attached;
// if so, return the cached CID value.
- final InlineImage ii = inlineEmbeds.get(name);
- if (ii != null) {
- final URLDataSource urlDataSource = (URLDataSource)
ii.getDataSource();
+ final InlineImage inlineImage = inlineEmbeds.get(name);
+ if (inlineImage != null) {
+ final URLDataSource urlDataSource = (URLDataSource)
inlineImage.getDataSource();
// make sure the supplied URL points to the same thing
// as the one already associated with this name.
// NOTE: Comparing URLs with URL.equals() is a blocking operation
// in the case of a network failure therefore we use
// url.toExternalForm().equals() here.
if
(url.toExternalForm().equals(urlDataSource.getURL().toExternalForm())) {
- return ii.getCid();
+ return inlineImage.getCid();
}
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 is = null;
+ InputStream inputStream = null;
try {
- is = url.openStream();
+ inputStream = url.openStream();
} catch (final IOException e) {
throw new EmailException("Invalid URL", e);
} finally {
try {
- if (is != null) {
- is.close();
+ if (inputStream != null) {
+ inputStream.close();
}
} catch (final IOException ioe) // NOPMD
{
@@ -537,7 +531,6 @@ public class HtmlEmail extends MultiPartEmail {
if (EmailUtils.isEmpty(aHtml)) {
throw new EmailException("Invalid message supplied");
}
-
this.html = aHtml;
return this;
}
@@ -559,15 +552,10 @@ public class HtmlEmail extends MultiPartEmail {
if (EmailUtils.isEmpty(msg)) {
throw new EmailException("Invalid message supplied");
}
-
setTextMsg(msg);
-
final StringBuilder htmlMsgBuf = new StringBuilder(msg.length() +
HTML_MESSAGE_START.length() + HTML_MESSAGE_END.length());
-
htmlMsgBuf.append(HTML_MESSAGE_START).append(msg).append(HTML_MESSAGE_END);
-
setHtmlMsg(htmlMsgBuf.toString());
-
return this;
}
@@ -583,7 +571,6 @@ public class HtmlEmail extends MultiPartEmail {
if (EmailUtils.isEmpty(aText)) {
throw new EmailException("Invalid message supplied");
}
-
this.text = aText;
return this;
}
