You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2023/12/14 15:06:38 UTC
(commons-email) 03/04: Javadoc
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 fe226ee9ca3ff88d1a992d5d5dad48c4fdfb6523
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Thu Dec 14 09:55:48 2023 -0500
Javadoc
- Better variable names
- Better parameter names
- Format tweaks
---
.../org/apache/commons/mail/EmailException.java | 2 +-
.../java/org/apache/commons/mail/EmailUtils.java | 2 +-
.../java/org/apache/commons/mail/HtmlEmail.java | 5 ++-
.../org/apache/commons/mail/MultiPartEmail.java | 46 ++++++++--------------
.../java/org/apache/commons/mail/SimpleEmail.java | 4 +-
.../mail/resolver/DataSourceBaseResolver.java | 5 ++-
.../mail/resolver/DataSourceCompositeResolver.java | 4 +-
.../mail/resolver/DataSourceFileResolver.java | 6 +--
.../mail/resolver/DataSourceUrlResolver.java | 4 +-
.../mail/util/IDNEmailAddressConverter.java | 26 ++++++------
10 files changed, 48 insertions(+), 56 deletions(-)
diff --git a/src/main/java/org/apache/commons/mail/EmailException.java b/src/main/java/org/apache/commons/mail/EmailException.java
index f166f8e..e9148d9 100644
--- a/src/main/java/org/apache/commons/mail/EmailException.java
+++ b/src/main/java/org/apache/commons/mail/EmailException.java
@@ -32,6 +32,7 @@ import java.nio.charset.Charset;
* @since 1.0
*/
public class EmailException extends Exception {
+
/** Serializable version identifier. */
private static final long serialVersionUID = 5550674499282474616L;
@@ -87,7 +88,6 @@ public class EmailException extends Exception {
synchronized (out) {
final PrintWriter pw = new PrintWriter(new OutputStreamWriter(out, Charset.defaultCharset()), false);
printStackTrace(pw);
-
// Flush the PrintWriter before it's GC'ed.
pw.flush();
}
diff --git a/src/main/java/org/apache/commons/mail/EmailUtils.java b/src/main/java/org/apache/commons/mail/EmailUtils.java
index e6dbb6d..9a9f813 100644
--- a/src/main/java/org/apache/commons/mail/EmailUtils.java
+++ b/src/main/java/org/apache/commons/mail/EmailUtils.java
@@ -44,6 +44,7 @@ import org.apache.commons.mail.util.MimeMessageUtils;
* @since 1.0
*/
final class EmailUtils {
+
/**
* Random object used by random method. This has to be not local to the random method so as to not return the same value in the same millisecond.
*/
@@ -104,7 +105,6 @@ final class EmailUtils {
if (input == null) {
return null;
}
-
final StringBuilder builder = new StringBuilder();
for (final byte c : input.getBytes(StandardCharsets.US_ASCII)) {
final int b = c & 0xff;
diff --git a/src/main/java/org/apache/commons/mail/HtmlEmail.java b/src/main/java/org/apache/commons/mail/HtmlEmail.java
index 45a30b3..4596597 100644
--- a/src/main/java/org/apache/commons/mail/HtmlEmail.java
+++ b/src/main/java/org/apache/commons/mail/HtmlEmail.java
@@ -88,8 +88,10 @@ public class HtmlEmail extends MultiPartEmail {
/** Content id. */
private final String cid;
+
/** {@code DataSource} for the content. */
private final DataSource dataSource;
+
/** the {@code MimeBodyPart} that contains the encoded data. */
private final MimeBodyPart mbp;
@@ -345,8 +347,7 @@ public class HtmlEmail extends MultiPartEmail {
mbp.setFileName(name);
mbp.setDisposition(EmailAttachment.INLINE);
mbp.setContentID("<" + encodedCid + ">");
- final InlineImage inlineImage = new InlineImage(encodedCid, dataSource, mbp);
- this.inlineEmbeds.put(name, inlineImage);
+ this.inlineEmbeds.put(name, new InlineImage(encodedCid, dataSource, mbp));
return encodedCid;
} catch (final MessagingException uee) {
throw new EmailException(uee);
diff --git a/src/main/java/org/apache/commons/mail/MultiPartEmail.java b/src/main/java/org/apache/commons/mail/MultiPartEmail.java
index 1445d1f..c7a7a42 100644
--- a/src/main/java/org/apache/commons/mail/MultiPartEmail.java
+++ b/src/main/java/org/apache/commons/mail/MultiPartEmail.java
@@ -58,7 +58,7 @@ public class MultiPartEmail extends Email {
private boolean initialized;
/** Indicates if attachments have been added to the message. */
- private boolean boolHasAttachments;
+ private boolean hasAttachments;
/**
* Add a new part to the email.
@@ -121,26 +121,26 @@ public class MultiPartEmail extends Email {
/**
* Attach a file specified as a DataSource interface.
*
- * @param ds A DataSource interface for the file.
+ * @param dataSource A DataSource interface for the file.
* @param name The name field for the attachment.
* @param description A description for the attachment.
* @return A MultiPartEmail.
* @throws EmailException see javax.mail.internet.MimeBodyPart for definitions
* @since 1.0
*/
- public MultiPartEmail attach(final DataSource ds, final String name, final String description) throws EmailException {
- if (ds == null) {
+ public MultiPartEmail attach(final DataSource dataSource, final String name, final String description) throws EmailException {
+ if (dataSource == null) {
throw new EmailException("Invalid Datasource");
}
// verify that the DataSource is valid
- try (InputStream is = ds.getInputStream()) {
- if (is == null) {
+ try (InputStream inputStream = dataSource.getInputStream()) {
+ if (inputStream == null) {
throw new EmailException("Invalid Datasource");
}
} catch (final IOException e) {
throw new EmailException("Invalid Datasource", e);
}
- return attach(ds, name, description, EmailAttachment.ATTACHMENT);
+ return attach(dataSource, name, description, EmailAttachment.ATTACHMENT);
}
/**
@@ -158,20 +158,18 @@ public class MultiPartEmail extends Email {
if (EmailUtils.isEmpty(name)) {
name = ds.getName();
}
- final BodyPart bodyPart = createBodyPart();
try {
+ final BodyPart bodyPart = createBodyPart();
bodyPart.setDisposition(disposition);
bodyPart.setFileName(MimeUtility.encodeText(name));
bodyPart.setDescription(description);
bodyPart.setDataHandler(new DataHandler(ds));
-
getContainer().addBodyPart(bodyPart);
} catch (final UnsupportedEncodingException | MessagingException me) {
// in case the file name could not be encoded
throw new EmailException(me);
}
setBoolHasAttachments(true);
-
return this;
}
@@ -221,15 +219,11 @@ public class MultiPartEmail extends Email {
*/
public MultiPartEmail attach(final File file) throws EmailException {
final String fileName = file.getAbsolutePath();
-
try {
if (!file.exists()) {
throw new IOException("\"" + fileName + "\" does not exist");
}
-
- final FileDataSource fds = new FileDataSource(file);
-
- return attach(fds, file.getName(), null, EmailAttachment.ATTACHMENT);
+ return attach(new FileDataSource(file), file.getName(), null, EmailAttachment.ATTACHMENT);
} catch (final IOException e) {
throw new EmailException("Cannot attach file \"" + fileName + "\"", e);
}
@@ -267,7 +261,6 @@ public class MultiPartEmail extends Email {
} catch (final IOException e) {
throw new EmailException("Invalid URL set:" + url, e);
}
-
return attach(new URLDataSource(url), name, description, disposition);
}
@@ -286,7 +279,7 @@ public class MultiPartEmail extends Email {
// the content for the main body part was actually set. If not,
// an IOException will be thrown during super.send().
- final BodyPart body = this.getPrimaryBodyPart();
+ final BodyPart body = getPrimaryBodyPart();
try {
body.getContent();
} catch (final IOException e) // NOPMD
@@ -350,13 +343,11 @@ public class MultiPartEmail extends Email {
if (!initialized) {
init();
}
-
// Add the first body part to the message. The fist body part must be
if (this.primaryBodyPart == null) {
primaryBodyPart = createBodyPart();
getContainer().addBodyPart(primaryBodyPart, 0);
}
-
return primaryBodyPart;
}
@@ -379,10 +370,8 @@ public class MultiPartEmail extends Email {
if (initialized) {
throw new IllegalStateException("Already initialized");
}
-
container = createMimeMultipart();
super.setContent(container);
-
initialized = true;
}
@@ -393,7 +382,7 @@ public class MultiPartEmail extends Email {
* @since 1.0
*/
public boolean isBoolHasAttachments() {
- return boolHasAttachments;
+ return hasAttachments;
}
/**
@@ -408,20 +397,20 @@ public class MultiPartEmail extends Email {
/**
* Sets whether there are attachments.
*
- * @param b the attachments flag
+ * @param hasAttachments the attachments flag
* @since 1.0
*/
- public void setBoolHasAttachments(final boolean b) {
- boolHasAttachments = b;
+ public void setBoolHasAttachments(final boolean hasAttachments) {
+ this.hasAttachments = hasAttachments;
}
/**
* Sets the initialized status of this object.
*
- * @param b the initialized status flag
+ * @param initialized the initialized status flag
*/
- protected void setInitialized(final boolean b) {
- initialized = b;
+ protected void setInitialized(final boolean initialized) {
+ this.initialized = initialized;
}
/**
@@ -440,7 +429,6 @@ public class MultiPartEmail extends Email {
}
try {
final BodyPart primary = getPrimaryBodyPart();
-
if (primary instanceof MimePart && EmailUtils.isNotEmpty(charset)) {
((MimePart) primary).setText(msg, charset);
} else {
diff --git a/src/main/java/org/apache/commons/mail/SimpleEmail.java b/src/main/java/org/apache/commons/mail/SimpleEmail.java
index f605191..bfe6087 100644
--- a/src/main/java/org/apache/commons/mail/SimpleEmail.java
+++ b/src/main/java/org/apache/commons/mail/SimpleEmail.java
@@ -17,11 +17,12 @@
package org.apache.commons.mail;
/**
- * This class is used to send simple internet email messages without attachments.
+ * This class is used to send simple Internet email messages without attachments.
*
* @since 1.0
*/
public class SimpleEmail extends Email {
+
/**
* Sets the content of the mail.
*
@@ -35,7 +36,6 @@ public class SimpleEmail extends Email {
if (EmailUtils.isEmpty(msg)) {
throw new EmailException("Invalid message supplied");
}
-
setContent(msg, EmailConstants.TEXT_PLAIN);
return this;
}
diff --git a/src/main/java/org/apache/commons/mail/resolver/DataSourceBaseResolver.java b/src/main/java/org/apache/commons/mail/resolver/DataSourceBaseResolver.java
index e3c8525..ae11d0f 100644
--- a/src/main/java/org/apache/commons/mail/resolver/DataSourceBaseResolver.java
+++ b/src/main/java/org/apache/commons/mail/resolver/DataSourceBaseResolver.java
@@ -24,18 +24,19 @@ import org.apache.commons.mail.DataSourceResolver;
* @since 1.3
*/
public abstract class DataSourceBaseResolver implements DataSourceResolver {
+
/** shall we ignore resources not found or complain with an exception */
private final boolean lenient;
/**
- * Constructor.
+ * Constructs a new instance.
*/
public DataSourceBaseResolver() {
this.lenient = false;
}
/**
- * Constructor.
+ * Constructs a new instance.
*
* @param lenient shall we ignore resources not found or throw an exception?
*/
diff --git a/src/main/java/org/apache/commons/mail/resolver/DataSourceCompositeResolver.java b/src/main/java/org/apache/commons/mail/resolver/DataSourceCompositeResolver.java
index 92fdd23..22a1466 100644
--- a/src/main/java/org/apache/commons/mail/resolver/DataSourceCompositeResolver.java
+++ b/src/main/java/org/apache/commons/mail/resolver/DataSourceCompositeResolver.java
@@ -32,7 +32,7 @@ public class DataSourceCompositeResolver extends DataSourceBaseResolver {
private final DataSourceResolver[] dataSourceResolvers;
/**
- * Constructor.
+ * Constructs a new instance.
*
* @param dataSourceResolvers a list of resolvers being used
*/
@@ -41,7 +41,7 @@ public class DataSourceCompositeResolver extends DataSourceBaseResolver {
}
/**
- * Constructor.
+ * Constructs a new instance.
*
* @param dataSourceResolvers a list of resolvers being used
* @param isLenient shall we ignore resources not found or throw an exception?
diff --git a/src/main/java/org/apache/commons/mail/resolver/DataSourceFileResolver.java b/src/main/java/org/apache/commons/mail/resolver/DataSourceFileResolver.java
index 321a55d..9c1f0d8 100644
--- a/src/main/java/org/apache/commons/mail/resolver/DataSourceFileResolver.java
+++ b/src/main/java/org/apache/commons/mail/resolver/DataSourceFileResolver.java
@@ -32,14 +32,14 @@ public class DataSourceFileResolver extends DataSourceBaseResolver {
private final File baseDir;
/**
- * Constructor.
+ * Constructs a new instance.
*/
public DataSourceFileResolver() {
baseDir = new File(".");
}
/**
- * Constructor.
+ * Constructs a new instance.
*
* @param baseDir the base directory of the resource when resolving relative paths
*/
@@ -48,7 +48,7 @@ public class DataSourceFileResolver extends DataSourceBaseResolver {
}
/**
- * Constructor.
+ * Constructs a new instance.
*
* @param baseDir the base directory of the resource when resolving relative paths
* @param lenient shall we ignore resources not found or complain with an exception
diff --git a/src/main/java/org/apache/commons/mail/resolver/DataSourceUrlResolver.java b/src/main/java/org/apache/commons/mail/resolver/DataSourceUrlResolver.java
index 2d8573c..924456a 100644
--- a/src/main/java/org/apache/commons/mail/resolver/DataSourceUrlResolver.java
+++ b/src/main/java/org/apache/commons/mail/resolver/DataSourceUrlResolver.java
@@ -33,7 +33,7 @@ public class DataSourceUrlResolver extends DataSourceBaseResolver {
private final URL baseUrl;
/**
- * Constructor.
+ * Constructs a new instance.
*
* @param baseUrl the base URL used for resolving relative resource locations
*/
@@ -42,7 +42,7 @@ public class DataSourceUrlResolver extends DataSourceBaseResolver {
}
/**
- * Constructor.
+ * Constructs a new instance.
*
* @param baseUrl the base URL used for resolving relative resource locations
* @param lenient shall we ignore resources not found or complain with an exception
diff --git a/src/main/java/org/apache/commons/mail/util/IDNEmailAddressConverter.java b/src/main/java/org/apache/commons/mail/util/IDNEmailAddressConverter.java
index 25af2d0..b8d0a73 100644
--- a/src/main/java/org/apache/commons/mail/util/IDNEmailAddressConverter.java
+++ b/src/main/java/org/apache/commons/mail/util/IDNEmailAddressConverter.java
@@ -17,6 +17,7 @@
package org.apache.commons.mail.util;
import java.net.IDN;
+import java.util.function.Function;
import javax.mail.internet.InternetAddress;
@@ -31,6 +32,7 @@ import javax.mail.internet.InternetAddress;
* @since 1.5
*/
public class IDNEmailAddressConverter {
+
/**
* Null-safe wrapper for {@link String#indexOf} to find the '@' character.
*
@@ -38,11 +40,7 @@ public class IDNEmailAddressConverter {
* @return index of first '@' character or {@code -1}
*/
private int findAtSymbolIndex(final String value) {
- if (value == null) {
- return -1;
- }
-
- return value.indexOf('@');
+ return value == null ? -1 : value.indexOf('@');
}
/**
@@ -68,23 +66,21 @@ public class IDNEmailAddressConverter {
}
/**
- * Convert an email address to its ASCII representation using "Punycode".
+ * Converts an email address to its ASCII representation using "Punycode".
*
* @param email email address.
* @return The ASCII representation
*/
public String toASCII(final String email) {
final int idx = findAtSymbolIndex(email);
-
if (idx < 0) {
return email;
}
-
return getLocalPart(email, idx) + '@' + IDN.toASCII(getDomainPart(email, idx));
}
/**
- * Convert the address part of an InternetAddress to its Unicode representation.
+ * Converts the address part of an InternetAddress to its Unicode representation.
*
* @param address email address.
* @return The Unicode representation
@@ -94,18 +90,24 @@ public class IDNEmailAddressConverter {
}
/**
- * Convert an "Punycode" email address to its Unicode representation.
+ * Converts an "Punycode" email address to its Unicode representation.
*
* @param email email address.
* @return The Unicode representation
*/
String toUnicode(final String email) {
final int idx = findAtSymbolIndex(email);
-
if (idx < 0) {
return email;
}
-
return getLocalPart(email, idx) + '@' + IDN.toUnicode(getDomainPart(email, idx));
}
+
+ private String toString(final String email, Function<String, String> converter) {
+ final int idx = findAtSymbolIndex(email);
+ if (idx < 0) {
+ return email;
+ }
+ return getLocalPart(email, idx) + '@' + converter.apply((getDomainPart(email, idx)));
+ }
}