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 <ieu...@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-unsubscr...@james.apache.org For additional commands, e-mail: server-dev-h...@james.apache.org