You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by ie...@apache.org on 2020/06/17 20:29:02 UTC
[james-project] branch master updated: Mailed Javadoc contribution
from github @amichair
This is an automated email from the ASF dual-hosted git repository.
ieugen pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
The following commit(s) were added to refs/heads/master by this push:
new 97c391d Mailed Javadoc contribution from github @amichair
97c391d is described below
commit 97c391d8e0dae062d440280300c400f6a5753cda
Author: Eugen Stan <ie...@apache.org>
AuthorDate: Wed Jun 17 23:28:13 2020 +0300
Mailed Javadoc contribution from github @amichair
* Merged contribution from https://github.com/amichair
* Changes where part of https://github.com/apache/james-project/pull/153
* I fixed the conflict and merged them here.
---
.../src/main/java/org/apache/mailet/Attribute.java | 2 +-
.../java/org/apache/mailet/LookupException.java | 2 +
.../api/src/main/java/org/apache/mailet/Mail.java | 28 ++++--
.../main/java/org/apache/mailet/MailetConfig.java | 2 +-
.../main/java/org/apache/mailet/MailetContext.java | 110 +++++++++------------
.../java/org/apache/mailet/MailetException.java | 5 +
.../src/main/java/org/apache/mailet/Matcher.java | 2 +-
.../main/java/org/apache/mailet/Serializer.java | 2 +-
.../apache/mailet/TemporaryLookupException.java | 2 +
.../java/org/apache/mailet/base/GenericMailet.java | 14 +--
.../org/apache/mailet/base/GenericMatcher.java | 2 +-
11 files changed, 90 insertions(+), 81 deletions(-)
diff --git a/mailet/api/src/main/java/org/apache/mailet/Attribute.java b/mailet/api/src/main/java/org/apache/mailet/Attribute.java
index 92c6164..53b1546 100644
--- a/mailet/api/src/main/java/org/apache/mailet/Attribute.java
+++ b/mailet/api/src/main/java/org/apache/mailet/Attribute.java
@@ -25,7 +25,7 @@ import com.google.common.base.MoreObjects;
import com.google.common.base.Preconditions;
/**
- * Attribute attached to an email
+ * Attribute attached to an email.
*
* Attributes hold information to be shared during Mail processing, across mailets.
*
diff --git a/mailet/api/src/main/java/org/apache/mailet/LookupException.java b/mailet/api/src/main/java/org/apache/mailet/LookupException.java
index fd3432a..35abe27 100644
--- a/mailet/api/src/main/java/org/apache/mailet/LookupException.java
+++ b/mailet/api/src/main/java/org/apache/mailet/LookupException.java
@@ -38,6 +38,8 @@ public class LookupException extends IOException {
/**
* Constructs a new lookup exception with the specified message.
+ *
+ * @param message the exception message
*/
public LookupException(String message) {
super(message);
diff --git a/mailet/api/src/main/java/org/apache/mailet/Mail.java b/mailet/api/src/main/java/org/apache/mailet/Mail.java
index 637edea..2ab5499 100644
--- a/mailet/api/src/main/java/org/apache/mailet/Mail.java
+++ b/mailet/api/src/main/java/org/apache/mailet/Mail.java
@@ -140,12 +140,12 @@ public interface Mail extends Serializable, Cloneable {
* Returns the sender of the message, as specified by the SMTP "MAIL FROM" command,
* or internally defined.
*
- * @deprecated @see {@link #getMaybeSender()} and {@link MaybeSender}
- *
- * Note that SMTP null sender ( "<>" ) needs to be implicitly handled by the caller under the form of 'null' or
- * {@link MailAddress#nullSender()}. Replacement method adds type safety on this operation.
+ * Note that SMTP null sender ( "<>" ) needs to be implicitly handled by the caller
+ * in the form of 'null' or {@link MailAddress#nullSender()}.
+ * Replacement method adds type safety on this operation.
*
* @return the sender of this message
+ * @deprecated see {@link #getMaybeSender()}
*/
@Deprecated
MailAddress getSender();
@@ -175,8 +175,11 @@ public interface Mail extends Serializable, Cloneable {
}
/**
+ * Returns a duplicate copy of this email.
+ * Implementation can affect a variation of the initial mail name property.
+ *
* @since Mailet API v3.2.0
- * @return A copy of this email. Implementation can affect a variation of the initial mail name property.
+ * @return A copy of this email
*/
Mail duplicate() throws MessagingException;
@@ -354,18 +357,23 @@ public interface Mail extends Serializable, Cloneable {
Optional<Attribute> setAttribute(Attribute attribute);
/**
- * Store a header (and its specific values) for a recipient
- * This header will be stored only for this recipient at delivery time
- *
+ * Adds a header (and its specific values) for a recipient.
+ * This header will be stored only for this recipient at delivery time.
+ * <p>
* Note that the headers must contain only US-ASCII characters, so a header that
* contains non US-ASCII characters must have been encoded by the
* caller as per the rules of RFC 2047.
+ *
+ * @param header the header to add
+ * @param recipient the recipient for which the header is added
*/
void addSpecificHeaderForRecipient(Header header, MailAddress recipient);
/**
* Get the currently stored association between recipients and
- * specific headers
+ * specific headers.
+ *
+ * @return the recipient-specific headers
*/
PerRecipientHeaders getPerRecipientSpecificHeaders();
@@ -387,6 +395,7 @@ public interface Mail extends Serializable, Cloneable {
/**
* Returns the time at which this Mail was last updated.
+ *
* @return the time at which this Mail was last updated
* @since Mailet API v2.3
*/
@@ -394,6 +403,7 @@ public interface Mail extends Serializable, Cloneable {
/**
* Sets the time at which this Mail was last updated.
+ *
* @param lastUpdated the time at which this Mail was last modified
* @since Mailet API v2.3
*/
diff --git a/mailet/api/src/main/java/org/apache/mailet/MailetConfig.java b/mailet/api/src/main/java/org/apache/mailet/MailetConfig.java
index 6922292..9688c2a 100644
--- a/mailet/api/src/main/java/org/apache/mailet/MailetConfig.java
+++ b/mailet/api/src/main/java/org/apache/mailet/MailetConfig.java
@@ -29,13 +29,13 @@ import java.util.Iterator;
* The configuration information consists of mailet-specific initialization
* parameters in a set of name/value pairs, and a MailetContext object
* which allows the mailet to interact with the mailet container.
- *
*/
public interface MailetConfig {
/**
* Returns the value of the named initialization parameter,
* or null if the parameter does not exist.
+ * Multi-valued parameters are returned as a comma-delineated string.
*
* @param name the name of the initialization parameter
* @return the value of the initialization parameter, or null
diff --git a/mailet/api/src/main/java/org/apache/mailet/MailetContext.java b/mailet/api/src/main/java/org/apache/mailet/MailetContext.java
index 459dac0..1afd9c5 100644
--- a/mailet/api/src/main/java/org/apache/mailet/MailetContext.java
+++ b/mailet/api/src/main/java/org/apache/mailet/MailetContext.java
@@ -107,7 +107,7 @@ public interface MailetContext {
/**
* Returns the name and version of the mailet container on which
* the mailet is running.
- * <p/>
+ * <p>
* The returned string is of the form {@code <servername>/<versionnumber>},
* optionally followed by additional information in parentheses. For example,
* the JAMES mailet container may return the string {@code "JAMES/1.2"}
@@ -120,7 +120,7 @@ public interface MailetContext {
/**
* Returns an Iterator over the names of all attributes which are set
* in this mailet context.
- * <p/>
+ * <p>
* The {@link #getAttribute} method can be called to
* retrieve an attribute's value given its name.
*
@@ -140,28 +140,16 @@ public interface MailetContext {
Object getAttribute(String name);
/**
- * Binds an object to a given attribute name in this mailet context. If the name
- * specified is already used for an attribute, this method will remove the old
- * attribute and bind the name to the new attribute.
- * <p>
- * Attribute names should follow the same convention as package names. The Java
- * Mailet API specification reserves names matching java.*, javax.*, and sun.*.
- *
- * @param name - a String specifying the name of the attribute
- * @param object - an Object representing the attribute to be bound
- */
-
- /**
* Associates an attribute with the given name and value with this mailet context.
- * <p/>
+ * <p>
* If an attribute with the given name already exists, it is replaced, and the
* previous value is returned.
- * <p/>
+ * <p>
* Attribute names should follow the same convention as package names.
* The Mailet API specification reserves names matching
* <i>org.apache.james.*</i> and <i>org.apache.mailet.*</i>.
*
- * @param name the attribute name
+ * @param name the attribute name
* @param value the attribute value
*/
@Deprecated
@@ -192,7 +180,7 @@ public interface MailetContext {
* is specific to the mailet container.
*
* @param message the message to be written to the log
- * @param t the Throwable whose stack trace is to be written to the log
+ * @param t the Throwable whose stack trace is to be written to the log
* @deprecated Prefer using SLF4J LoggingFactory to get a Logger in each class
*/
@Deprecated
@@ -203,7 +191,7 @@ public interface MailetContext {
* Writes the specified message to a mailet log. The name and type of
* the mailet log is specific to the mailet container.
*
- * @param level {@link LogLevel} to use
+ * @param level the {@link LogLevel} to use
* @param message the message to be written to the log
* @since 2.5
* @deprecated Prefer using SLF4J LoggingFactory to get a Logger in each class
@@ -217,8 +205,8 @@ public interface MailetContext {
* is specific to the mailet container.
*
* @param message the message to be written to the log
- * @param t the Throwable whose stack trace is to be written to the log
- * @param level {@link LogLevel} to use
+ * @param t the Throwable whose stack trace is to be written to the log
+ * @param level {@link LogLevel} to use
* @since 2.5
* @deprecated Prefer using SLF4J LoggingFactory to get a Logger in each class
*/
@@ -245,7 +233,7 @@ public interface MailetContext {
* Checks if a user account is local, i.e. the account exists locally
* and this server is the final delivery destination for messages
* sent to this address.
- * <p/>
+ * <p>
* This given user account string should contain the full
* user address, i.e. user@domain. If the domain part is
* missing, "localhost" will be used as the domain name.
@@ -319,9 +307,9 @@ public interface MailetContext {
* This is functionally equivalent to having opened an SMTP session to the local
* host and delivering the message using the given sender and recipients.
*
- * @param sender the message sender
+ * @param sender the message sender
* @param recipients the message recipients as a Collection of MailAddress objects
- * @param message the message to send
+ * @param message the message to send
* @throws MessagingException if an error occurs accessing or sending the message
*/
void sendMail(MailAddress sender, Collection<MailAddress> recipients, MimeMessage message)
@@ -331,11 +319,11 @@ public interface MailetContext {
* Sends an outgoing message to the top of this mailet container's queue for the
* specified processor.
*
- * @param sender the message sender
+ * @param sender the message sender
* @param recipients the message recipients as a Collection of MailAddress objects
- * @param message the message to send
- * @param state the state of the message, indicating the name of the processor for
- * which the message will be queued
+ * @param message the message to send
+ * @param state the state of the message, indicating the name of the processor for
+ * which the message will be queued
* @throws MessagingException if an error occurs accessing or sending the message
*/
void sendMail(MailAddress sender, Collection<MailAddress> recipients, MimeMessage message, String state)
@@ -344,42 +332,40 @@ public interface MailetContext {
/**
* Sends an outgoing message to the top of this mailet container's root queue.
* This is the equivalent of opening an SMTP session to localhost.
- * The Mail object provides all envelope and content information
+ * The Mail object provides all envelope and content information.
*
- * @param mail - the message that is to sent
+ * @param mail the message that is to sent
* @throws MessagingException if an error occurs accessing or sending the message
*/
- void sendMail(Mail mail)
- throws MessagingException;
+ void sendMail(Mail mail) throws MessagingException;
/**
* Sends an outgoing message to the top of this mailet container's root queue.
* This is the equivalent of opening an SMTP session to localhost.
- * The Mail object provides all envelope and content information
- *
+ * The Mail object provides all envelope and content information.
+ * <p>
* The given delay and unit are used to calculate the time when
- * the Mail will be available for deQueue
+ * the Mail will be available for deQueue.
*
- * @param mail - the message that is to sent
- * @param delay - the delay value for deQueue
- * @param unit - the delay unit for deQueue
+ * @param mail the message that is to sent
+ * @param delay the delay value for deQueue
+ * @param unit the delay unit for deQueue
* @throws MessagingException if an error occurs accessing or sending the message
*/
- void sendMail(Mail mail, long delay, TimeUnit unit)
- throws MessagingException;
+ void sendMail(Mail mail, long delay, TimeUnit unit) throws MessagingException;
/**
* Sends an outgoing message to the top of this mailet container's root queue,
* targeting a specific processing state.
- *
+ * <p>
* This functionally allows mail treatment done out of the MailetProcessor to be sent
* to a specific processor inside the MailetContainer. This is for instance useful for bouncing mail
- * being remote delivered (asynchronously to original mail treatment)
+ * being remote delivered (asynchronously to original mail treatment).
*
- * @param message The message to send
- * @param state The state of the message, indicating the name of the processor for
- * which the message will be queued
+ * @param mail The message to send
+ * @param state The state of the message, indicating the name of the processor for
+ * which the message will be queued
* @throws MessagingException if an error occurs accessing or sending the message
*/
void sendMail(Mail mail, String state) throws MessagingException;
@@ -387,31 +373,31 @@ public interface MailetContext {
/**
* Sends an outgoing message to the top of this mailet container's root queue,
* targeting a specific processing state.
- *
+ * <p>
* This functionally allows mail treatment done out of the MailetProcessor to be sent
* to a specific processor inside the MailetContainer. This is for instance useful for bouncing mail
- * being remote delivered (asynchronously to original mail treatment)
- *
+ * being remote delivered (asynchronously to original mail treatment).
+ * <p>
* The given delay and unit are used to calculate the time when
- * the Mail will be available for deQueue
+ * the Mail will be available for deQueue.
*
- * @param message The message to send
- * @param state The state of the message, indicating the name of the processor for
- * which the message will be queued
- * @param delay The delay value for deQueue
- * @param unit The delay unit for deQueue
+ * @param mail The message to send
+ * @param state The state of the message, indicating the name of the processor for
+ * which the message will be queued
+ * @param delay The delay value for deQueue
+ * @param unit The delay unit for deQueue
* @throws MessagingException if an error occurs accessing or sending the message
*/
void sendMail(Mail mail, String state, long delay, TimeUnit unit) throws MessagingException;
/**
* Bounces the message using a standard format with the given message.
- * <p/>
+ * <p>
* The message will be sent to the original sender from the postmaster address
* as configured in this mailet context, adding the message to top of mail
* server queue using {@code sendMail}.
*
- * @param mail the message to bounce, with the original sender
+ * @param mail the message to bounce, with the original sender
* @param message a descriptive message explaining why the message bounced
* @throws MessagingException if an error occurs accessing or sending the message
*/
@@ -423,7 +409,7 @@ public interface MailetContext {
* The message will be sent to the original sender from the given address,
* adding the message to top of mail server queue using {@code sendMail}.
*
- * @param mail the message to bounce, with the original sender
+ * @param mail the message to bounce, with the original sender
* @param message a descriptive message explaining why the message bounced
* @param bouncer the address used as the sender of the bounce message
* @throws MessagingException if an error occurs accessing or sending the message
@@ -432,14 +418,16 @@ public interface MailetContext {
/**
- * Lookups the DNS system for a given record type.
- * In case of MX records the returned List will be sorted using the priority score, ascending.
+ * Looks up the given record type in the DNS system.
+ * <p>
+ * In the case of MX records the returned List will be sorted using the priority score, ascending.
*
* @param name the host/domain name to lookup
* @param type the "IN" record type to lookup
- * @return a String list with result records with at least 1 element.
+ * @return a String list with result records with at least 1 element
* @throws TemporaryLookupException on timeout or servfail
- * @throws LookupException on host not found, record type not found, name syntax issues and other permanent exceptions.
+ * @throws LookupException on host not found, record type not found,
+ * name syntax issues and other permanent exceptions
* @since Mailet API v2.5
*/
List<String> dnsLookup(String name, RecordType type) throws TemporaryLookupException, LookupException;
diff --git a/mailet/api/src/main/java/org/apache/mailet/MailetException.java b/mailet/api/src/main/java/org/apache/mailet/MailetException.java
index 425247d..4bd87c9 100644
--- a/mailet/api/src/main/java/org/apache/mailet/MailetException.java
+++ b/mailet/api/src/main/java/org/apache/mailet/MailetException.java
@@ -41,6 +41,8 @@ public class MailetException extends MessagingException {
/**
* Constructs a new mailet exception with the specified message.
+ *
+ * @param message the exception message
*/
public MailetException(String message) {
super(message);
@@ -49,6 +51,9 @@ public class MailetException extends MessagingException {
/**
* Constructs a new mailet exception with the specified message
* and an exception which is the "root cause" of the exception.
+ *
+ * @param message the exception message
+ * @param e the root cause exception
*/
public MailetException(String message, Exception e) {
super(message, e);
diff --git a/mailet/api/src/main/java/org/apache/mailet/Matcher.java b/mailet/api/src/main/java/org/apache/mailet/Matcher.java
index ad4b529..b711cf1 100644
--- a/mailet/api/src/main/java/org/apache/mailet/Matcher.java
+++ b/mailet/api/src/main/java/org/apache/mailet/Matcher.java
@@ -57,7 +57,6 @@ import org.apache.james.core.MailAddress;
* its configuration information and a {@link MailetContext} through which
* it can interact with the mailet container, and the {@link #getMatcherInfo}
* method, which provides basic information about the Matcher.
- *
*/
public interface Matcher {
@@ -86,6 +85,7 @@ public interface Matcher {
*
* @param mail the Mail to match
* @return the recipients that meet the match criteria as a Collection of String objects
+ * (may be null if there are no matched recipients)
* @throws MessagingException if any error occurs which prevents the Mail
* matching from completing successfully
*/
diff --git a/mailet/api/src/main/java/org/apache/mailet/Serializer.java b/mailet/api/src/main/java/org/apache/mailet/Serializer.java
index cc3f787..f03abf7 100644
--- a/mailet/api/src/main/java/org/apache/mailet/Serializer.java
+++ b/mailet/api/src/main/java/org/apache/mailet/Serializer.java
@@ -55,7 +55,7 @@ import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
/**
- * Controlled Json serialization/deserialization
+ * Controlled Json serialization/deserialization.
*
* @since Mailet API v3.2
*/
diff --git a/mailet/api/src/main/java/org/apache/mailet/TemporaryLookupException.java b/mailet/api/src/main/java/org/apache/mailet/TemporaryLookupException.java
index f462481..66025ba 100644
--- a/mailet/api/src/main/java/org/apache/mailet/TemporaryLookupException.java
+++ b/mailet/api/src/main/java/org/apache/mailet/TemporaryLookupException.java
@@ -37,6 +37,8 @@ public class TemporaryLookupException extends LookupException {
/**
* Constructs a new lookup exception with the specified message.
+ *
+ * @param message the exception message
*/
public TemporaryLookupException(String message) {
super(message);
diff --git a/mailet/base/src/main/java/org/apache/mailet/base/GenericMailet.java b/mailet/base/src/main/java/org/apache/mailet/base/GenericMailet.java
index dbc167e..6eb481d 100644
--- a/mailet/base/src/main/java/org/apache/mailet/base/GenericMailet.java
+++ b/mailet/base/src/main/java/org/apache/mailet/base/GenericMailet.java
@@ -76,6 +76,7 @@ public abstract class GenericMailet implements Mailet, MailetConfig {
* <p>Gets a boolean valued init parameter.</p>
* <p>A convenience method. The result is parsed
* from the value of the named parameter in the {@link MailetConfig}.</p>
+ *
* @param name name of the init parameter to be queried
* @param defaultValue this value will be substituted when the named value
* cannot be parse or when the init parameter is absent
@@ -123,7 +124,7 @@ public abstract class GenericMailet implements Mailet, MailetConfig {
* named parameter from the mailet's MailetConfig object.
*
* @param name - a String specifying the name of the initialization parameter
- * @return a String containing the value of the initalization parameter
+ * @return a String containing the value of the initialization parameter
*/
@Override
public String getInitParameter(String name) {
@@ -141,7 +142,7 @@ public abstract class GenericMailet implements Mailet, MailetConfig {
* @param name - a String specifying the name of the initialization parameter
* @param defValue - a String specifying the default value when the parameter
* is not present
- * @return a String containing the value of the initalization parameter
+ * @return a String containing the value of the initialization parameter
*/
public String getInitParameter(String name, String defValue) {
Preconditions.checkState(config != null, CONFIG_IS_NULL_ERROR_MESSAGE);
@@ -224,7 +225,7 @@ public abstract class GenericMailet implements Mailet, MailetConfig {
* method, call super.init(config).</p>
*
* @param newConfig - the MailetConfig object that contains
- * configutation information for this mailet
+ * configuration information for this mailet
* @throws MessagingException
* if an exception occurs that interrupts the mailet's normal operation
*/
@@ -246,7 +247,7 @@ public abstract class GenericMailet implements Mailet, MailetConfig {
* if an exception occurs that interrupts the mailet's normal operation
*/
public void init() throws MessagingException {
- //Do nothing... can be overriden
+ //Do nothing... can be overridden
}
/**
@@ -289,9 +290,10 @@ public abstract class GenericMailet implements Mailet, MailetConfig {
/**
- * Utility method: Checks if there are unallowed init parameters specified in the
+ * Utility method: Checks if there are disallowed init parameters specified in the
* configuration file against the allowedInitParameters.
- * @param allowed List of strings containing the allowed parameter names
+ *
+ * @param allowed Set of strings containing the allowed parameter names
* @throws MessagingException if an unknown parameter name is found
*/
protected final void checkInitParameters(Set<String> allowed) throws MessagingException {
diff --git a/mailet/base/src/main/java/org/apache/mailet/base/GenericMatcher.java b/mailet/base/src/main/java/org/apache/mailet/base/GenericMatcher.java
index 3c997ab..d36044e 100644
--- a/mailet/base/src/main/java/org/apache/mailet/base/GenericMatcher.java
+++ b/mailet/base/src/main/java/org/apache/mailet/base/GenericMatcher.java
@@ -63,7 +63,7 @@ public abstract class GenericMatcher implements Matcher, MatcherConfig {
* <p>This method is supplied for convenience. It gets the value of the
* named parameter from the matcher's MatcherConfig object.</p>
*
- * @return String a String containing the value of the initalization parameter
+ * @return String a String containing the value of the initialization parameter
*/
@Override
public String getCondition() {
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org