You are viewing a plain text version of this content. The canonical link for it is here.
Posted to mailet-api@james.apache.org by rd...@apache.org on 2009/08/03 13:29:26 UTC
svn commit: r800311 - in
/james/mailet/api/trunk/src/main/java/org/apache/mailet: HostAddress.java
Mail.java MailAddress.java Mailet.java MailetConfig.java MailetContext.java
MailetException.java Matcher.java MatcherConfig.java package.html
Author: rdonkin
Date: Mon Aug 3 11:29:26 2009
New Revision: 800311
URL: http://svn.apache.org/viewvc?rev=800311&view=rev
Log:
MAILET-26 Javadoc improvements https://issues.apache.org/jira/browse/MAILET-26
Modified:
james/mailet/api/trunk/src/main/java/org/apache/mailet/HostAddress.java
james/mailet/api/trunk/src/main/java/org/apache/mailet/Mail.java
james/mailet/api/trunk/src/main/java/org/apache/mailet/MailAddress.java
james/mailet/api/trunk/src/main/java/org/apache/mailet/Mailet.java
james/mailet/api/trunk/src/main/java/org/apache/mailet/MailetConfig.java
james/mailet/api/trunk/src/main/java/org/apache/mailet/MailetContext.java
james/mailet/api/trunk/src/main/java/org/apache/mailet/MailetException.java
james/mailet/api/trunk/src/main/java/org/apache/mailet/Matcher.java
james/mailet/api/trunk/src/main/java/org/apache/mailet/MatcherConfig.java
james/mailet/api/trunk/src/main/java/org/apache/mailet/package.html
Modified: james/mailet/api/trunk/src/main/java/org/apache/mailet/HostAddress.java
URL: http://svn.apache.org/viewvc/james/mailet/api/trunk/src/main/java/org/apache/mailet/HostAddress.java?rev=800311&r1=800310&r2=800311&view=diff
==============================================================================
--- james/mailet/api/trunk/src/main/java/org/apache/mailet/HostAddress.java (original)
+++ james/mailet/api/trunk/src/main/java/org/apache/mailet/HostAddress.java Mon Aug 3 11:29:26 2009
@@ -21,46 +21,32 @@
package org.apache.mailet;
/**
- * A specialized subclass of javax.mail.URLName, which provides location
- * information for servers.
+ * A specialized subclass of javax.mail.URLName, which provides
+ * the name of a URL as well as its corresponding host name.
*
- * @since Mailet API v2.2.0a16-unstable
+ * @since Mailet API v2.3
*/
-public class HostAddress extends javax.mail.URLName
-{
+public class HostAddress extends javax.mail.URLName {
private String hostname;
- public HostAddress(String hostname, String url)
- {
+ /**
+ * Constructs a new host address with the given details.
+ *
+ * @param hostname the hostname corresponding to the url
+ * @param url the url name
+ */
+ public HostAddress(String hostname, String url) {
super(url);
this.hostname = hostname;
}
- public String getHostName()
- {
+ /**
+ * Returns the host name corresponding to the url
+ *
+ * @return the host name
+ */
+ public String getHostName() {
return hostname;
}
-/*
- public static void main(String[] args) throws Exception
- {
- HostAddress url;
- try
- {
- url = new HostAddress("mail.devtech.com", "smtp://" + "66.112.202.2" + ":25");
- System.out.println("Hostname: " + url.getHostName());
- System.out.println("The protocol is: " + url.getProtocol());
- System.out.println("The host is: " + url.getHost());
- System.out.println("The port is: " + url.getPort());
- System.out.println("The user is: " + url.getUsername());
- System.out.println("The password is: " + url.getPassword());
- System.out.println("The file is: " + url.getFile());
- System.out.println("The ref is: " + url.getRef());
- }
- catch (Exception e)
- {
- System.err.println(e);
- };
- }
-*/
}
Modified: james/mailet/api/trunk/src/main/java/org/apache/mailet/Mail.java
URL: http://svn.apache.org/viewvc/james/mailet/api/trunk/src/main/java/org/apache/mailet/Mail.java?rev=800311&r1=800310&r2=800311&view=diff
==============================================================================
--- james/mailet/api/trunk/src/main/java/org/apache/mailet/Mail.java (original)
+++ james/mailet/api/trunk/src/main/java/org/apache/mailet/Mail.java Mon Aug 3 11:29:26 2009
@@ -27,13 +27,43 @@
import java.util.Iterator;
/**
- * Wrap a MimeMessage with routing information (from SMTP) such
- * as SMTP specified recipients, sender, and ip address and hostname
- * of sending server. It also contains its state which represents
- * which processor in the mailet container it is currently running.
- * Special processor names are "root" and "error".
- *
- * @version CVS $Revision$ $Date$
+ * <p>Wraps a MimeMessage with additional routing and processing information.
+ * <p>This includes
+ * <ul>
+ * <li>a unique name</li>
+ * <li>envelope properties such the SMTP-specified sender ("MAIL FROM") and recipients ("RCPT TO")</li>
+ * <li>the IP address and hostname of the sending server</li>
+ * <li>the processing state, which also represents the processor in
+ * the mailet container which is currently processing the message</li>
+ * <li>the time at which the Mail was last updated</li>
+ * <li>additional processing attributes (see below)</li>
+ * </ul>
+ * <p>
+ * The Mail interface also defines constants for special processor names,
+ * such as "root" and "error".
+ * <p>
+ * <b>Mail Attributes</b>
+ * <p>
+ * While processing a Mail instance, a Mailet can associate additional
+ * information with it by using mail attributes. These attributes can
+ * then be queried by the same mailet or other mailets later on.
+ * <p>
+ * Some containers may also use attributes to provide envelope information.
+ * <p>
+ * Every attribute consists of a name and a value.
+ * 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>.
+ * <p>
+ * Attribute values can be arbitrary objects, but since Mail is
+ * Serializable, the attribute value must be Serializable as well.
+ * <p>
+ * The list of attributes which are currently associated with a Mail
+ * instance can be retrieved using the {@link #getAttributeNames}
+ * method, and given its name, the value of an attribute can be
+ * retrieved using the {@link #getAttribute} method. It is also
+ * possible to remove {@link #removeAttribute one} attribute or
+ * {@link #removeAllAttributes() all} attributes of a Mail instance.
*/
public interface Mail extends Serializable, Cloneable {
String GHOST = "ghost";
@@ -41,165 +71,194 @@
String ERROR = "error";
String TRANSPORT = "transport";
/**
- * Returns the message name of this message
+ * Returns the name of this message.
*
* @return the message name
* @since Mailet API v2.3
*/
String getName();
+
/**
- * Set the message name of this message
+ * Set the name of this message.
*
- * @param newName new name
+ * @param newName the new message name
* @since Mailet API v2.3
*/
void setName(String newName);
+
/**
- * Returns the MimeMessage stored in this message
+ * Returns the MimeMessage stored in this message.
*
* @return the MimeMessage that this Mail object wraps
- * @throws MessagingException - an error occured while loading this object
+ * @throws MessagingException when an error occurs while retrieving the message
*/
MimeMessage getMessage() throws MessagingException;
+
/**
- * Returns a Collection of MailAddress objects that are recipients of this message
+ * Returns the message recipients as a Collection of MailAddress objects,
+ * as specified by the SMTP "RCPT TO" command, or internally defined.
*
* @return a Collection of MailAddress objects that are recipients of this message
*/
Collection getRecipients();
+
/**
- * Method setRecipients.
- * @param recipients a Collection of MailAddress Objects representing the recipients of this message
- * @since Mailet API v3.0-unstable
+ * Sets the message recipients as a Collection of MailAddress objects.
+ *
+ * @param recipients the message recipients as a Collection of MailAddress Objects
+ * @since Mailet API v2.4
*/
void setRecipients(Collection recipients);
+
/**
- * The sender of the message, as specified by the MAIL FROM header, or internally defined
+ * Returns the sender of the message, as specified by the SMTP "MAIL FROM" command,
+ * or internally defined.
*
- * @return a MailAddress of the sender of this message
+ * @return the sender of this message
*/
MailAddress getSender();
+
/**
- * The current state of the message, such as GHOST, ERROR, or DEFAULT
+ * Returns the current state of the message, such as GHOST, ERROR or DEFAULT.
*
* @return the state of this message
*/
String getState();
+
/**
- * The remote hostname of the server that connected to send this message
+ * Returns the host name of the remote server that sent this message.
*
- * @return a String of the hostname of the server that connected to send this message
+ * @return the host name of the remote server that sent this message
*/
String getRemoteHost();
+
/**
- * The remote ip address of the server that connected to send this message
+ * Returns the IP address of the remote server that sent this message.
*
- * @return a String of the ip address of the server that connected to send this message
+ * @return the IP address of the remote server that sent this message
*/
String getRemoteAddr();
+
/**
- * The error message, if any, associated with this message. Not sure why this is needed.
+ * The error message, if any, associated with this message.
*
- * @return a String of a descriptive error message
+ * @return the error message associated with this message, or null
*/
String getErrorMessage();
+
/**
- * Sets the error message associated with this message. Not sure why this is needed.
+ * Sets the error message associated with this message.
*
- * @param msg - a descriptive error message
+ * @param msg the error message
*/
void setErrorMessage(String msg);
+
/**
- * Sets the MimeMessage associated with this message via the object.
+ * Sets the MimeMessage wrapped by this Mail instance.
*
- * @param message - the new MimeMessage that this Mail object will wrap
+ * @param message the new message that this Mail instance will wrap
*/
void setMessage(MimeMessage message);
+
/**
* Sets the state of this message.
*
- * @param state - the new state of this message
+ * @param state the new state of this message
*/
void setState(String state);
+
/**
- * Returns the Mail session attribute with the given name, or null
- * if there is no attribute by that name.
- * An attribute allows a mailet to give this Mail instance additional information
- * not already provided by this interface.<p>
- * A list of currently set attributes can be retrieved using getAttributeNames.
- * <p>
- * The attribute is returned as a java.lang.Object or some subclass. 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 - a String specifying the name of the attribute
- * @return an Object containing the value of the attribute, or null if no attribute
- * exists matching the given name
+ * Returns the value of the named Mail instance attribute,
+ * or null if the attribute does not exist.
+ *
+ * @param name the attribute name
+ * @return the attribute value, or null if the attribute does not exist
* @since Mailet API v2.1
*/
Serializable getAttribute(String name);
+
/**
- * Returns an Iterator containing the attribute names currently available within
- * this Mail instance. Use the getAttribute(java.lang.String) method with an
- * attribute name to get the value of an attribute.
+ * Returns an Iterator over the names of all attributes which are set
+ * in this Mail instance.
+ * <p>
+ * The {@link #getAttribute} method can be called to
+ * retrieve an attribute's value given its name.
*
- * @return an Iterator of attribute names
+ * @return an Iterator (of Strings) over all attribute names
* @since Mailet API v2.1
*/
Iterator getAttributeNames();
+
/**
- * @return true if this Mail instance has any attributes set.
+ * Returns whether this Mail instance has any attributes set.
+ *
+ * @return true if this Mail instance has any attributes set, false if not
* @since Mailet API v2.1
- **/
+ */
boolean hasAttributes();
+
/**
- * Removes the attribute with the given name from this Mail instance. After
- * removal, subsequent calls to getAttribute(java.lang.String) to retrieve
- * the attribute's value will return null.
- *
- * @param name - a String specifying the name of the attribute to be removed
- * @return previous attribute value associated with specified name, or null
- * if there was no mapping for name (null can also mean that null
- * was bound to the name)
+ * Removes the attribute with the given name from this Mail instance.
+ *
+ * @param name the name of the attribute to be removed
+ * @return the value of the removed attribute, or null
+ * if there was no such attribute (or if the attribute existed
+ * and its value was null)
* @since Mailet API v2.1
*/
Serializable removeAttribute(String name);
+
/**
- * Removes all the attributes associated with this Mail instance.
+ * Removes all attributes associated with this Mail instance.
* @since Mailet API v2.1
**/
void removeAllAttributes();
+
/**
- * Binds an object to a given attribute name in this Mail instance. 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.
- * As instances of Mail is Serializable, it is necessary that the attributes being
- * Serializable as well
+ * Associates an attribute with the given name and value with this Mail instance.
+ * If an attribute with the given name already exists, it is replaced, and the
+ * previous value is returned.
* <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 - a String specifying the name of the attribute
- * @param object - a Serializable Object representing the attribute to be bound
- * @return the object previously bound to the name, null if the name was
- * not bound (null can also mean that null was bound to the name)
+ * Conventionally, attribute names should follow the namespacing guidelines
+ * for Java packages.
+ * The Mailet API specification reserves names matching
+ * <i>org.apache.james.*</i> and <i>org.apache.mailet.*</i>.
+ *
+ * @param name the attribute name
+ * @param object the attribute value
+ * @return the value of the previously existing attribute with the same name,
+ * or null if there was no such attribute (or if the attribute existed
+ * and its value was null)
* @since Mailet API v2.1
*/
Serializable setAttribute(String name, Serializable object);
+
/**
- * @return message size
+ * Returns the message size (including headers).
+ * <p>
+ * This is intended as a guide suitable for processing heuristics, and not
+ * a precise indication of the number of outgoing bytes that would be produced
+ * were the email to be encoded for transport.
+ * In cases where an exact value is not readily available or is difficult to
+ * determine (for example, when the fully transfer encoded message is not available)
+ * a suitable estimate may be returned.
+ *
+ * @return the message size
+ * @throws MessagingException when the size cannot be retrieved
* @since Mailet API v2.3
*/
long getMessageSize() throws MessagingException;
+
/**
- * @return the last update date
+ * 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
*/
Date getLastUpdated();
+
/**
- * @param lastUpdated the new last updated date
+ * 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
*/
void setLastUpdated(Date lastUpdated);
Modified: james/mailet/api/trunk/src/main/java/org/apache/mailet/MailAddress.java
URL: http://svn.apache.org/viewvc/james/mailet/api/trunk/src/main/java/org/apache/mailet/MailAddress.java?rev=800311&r1=800310&r2=800311&view=diff
==============================================================================
--- james/mailet/api/trunk/src/main/java/org/apache/mailet/MailAddress.java (original)
+++ james/mailet/api/trunk/src/main/java/org/apache/mailet/MailAddress.java Mon Aug 3 11:29:26 2009
@@ -26,7 +26,8 @@
/**
* A representation of an email address.
- * <p>This class encapsulates functionalities to access to different
+ *
+ * <p>This class encapsulates functionality to access different
* parts of an email address without dealing with its parsing.</p>
*
* <p>A MailAddress is an address specified in the MAIL FROM and
@@ -40,17 +41,17 @@
* <p>MailAddress parses an email address as defined in RFC 821
* (SMTP) p. 30 and 31 where addresses are defined in BNF convention.
* As the mailet API does not support the aged "SMTP-relayed mail"
- * addressing protocol, this leaves all addresses to be a <mailbox>,
+ * addressing protocol, this leaves all addresses to be a {@code <mailbox>},
* as per the spec.
*
* <p>This class is a good way to validate email addresses as there are
* some valid addresses which would fail with a simpler approach
- * to parsing address. It also removes parsing burden from
+ * to parsing address. It also removes the parsing burden from
* mailets and matchers that might not realize the flexibility of an
- * SMTP address. For instance, "serge@home"@lokitech.com is a valid
+ * SMTP address. For instance, "serge@home"@lokitech.com is a valid
* SMTP address (the quoted text serge@home is the local-part and
- * lokitech.com is the domain). This means all current parsing to date
- * is incorrect as we just find the first @ and use that to separate
+ * lokitech.com is the domain). This means all current parsing to date
+ * is incorrect as we just find the first '@' and use that to separate
* local-part from domain.</p>
*
* <p>This parses an address as per the BNF specification for <mailbox>
@@ -62,7 +63,9 @@
public class MailAddress implements java.io.Serializable {
/**
* We hardcode the serialVersionUID
- * This version (2779163542539434916L) retains compatibility back to Mailet version 1.2 (James 1.2) so that MailAddress will be deserializable and mail doesn't get lost after an upgrade.
+ * This version (2779163542539434916L) retains compatibility back to
+ * Mailet version 1.2 (James 1.2) so that MailAddress will be
+ * deserializable and mail doesn't get lost after an upgrade.
*/
public static final long serialVersionUID = 2779163542539434916L;
@@ -75,14 +78,16 @@
private int pos = 0;
/**
- * strip source routing, according to RFC-2821 it is an allowed approach to handle mails
- * contaning RFC-821 source-route information
+ * Strips source routing. According to RFC-2821 it is a valid approach
+ * to handle mails containing RFC-821 source-route information.
+ *
+ * @param address the address to strip
*/
private void stripSourceRoute(String address) {
if (pos < address.length()) {
- if(address.charAt(pos)=='@') {
+ if (address.charAt(pos)=='@') {
int i = address.indexOf(':');
- if(i != -1) {
+ if (i != -1) {
pos = i+1;
}
}
@@ -90,12 +95,10 @@
}
/**
- * <p>Construct a MailAddress parsing the provided <code>String</code> object.</p>
- *
- * <p>The <code>personal</code> variable is left empty.</p>
+ * Constructs a MailAddress by parsing the provided address.
*
- * @param address the email address compliant to the RFC2822 3.4.1. Addr-spec specification
- * @throws AddressException if the parse failed
+ * @param address the email address, compliant to the RFC2822 3.4.1. addr-spec specification
+ * @throws AddressException if the parse failed
*/
public MailAddress(String address) throws AddressException {
address = address.trim();
@@ -164,73 +167,77 @@
}
/**
- * Construct a MailAddress with the provided personal name and email
- * address.
+ * Constructs a MailAddress with the provided local part and domain.
*
- * @param localPart The local-part portion is a domain dependent string. In addresses, it is simply interpreted on the particular host as a name of a particular mailbox. per RFC2822 3.4.1. Addr-spec specification
- * @param domain The domain portion identifies the point to which the mail is delivered per RFC2822 3.4.1. Addr-spec specification
- * @throws AddressException if the parse failed
+ * @param localPart the local-part portion. This is a domain dependent string.
+ * In addresses, it is simply interpreted on the particular host as a
+ * name of a particular mailbox. per RFC2822 3.4.1. addr-spec specification
+ * @param domain the domain portion. This identifies the point to which the mail
+ * is delivered per RFC2822 3.4.1. addr-spec specification
+ * @throws AddressException if the parse failed
*/
public MailAddress(String localPart, String domain) throws AddressException {
this(new InternetAddress(localPart+"@"+domain));
}
/**
- * Constructs a MailAddress from a JavaMail InternetAddress, using only the
- * email address portion, discarding the personal name. (an "addr-spec" not a "name-addr" as defined in RFC2822 3.4. Address Specification
- * @param address
- * @throws AddressException
+ * Constructs a MailAddress from an InternetAddress, using only the
+ * email address portion (an "addr-spec", not "name-addr", as
+ * defined in the RFC2822 3.4. Address Specification)
+ *
+ * @param address the address
+ * @throws AddressException if the parse failed
*/
public MailAddress(InternetAddress address) throws AddressException {
this(address.getAddress());
}
/**
- * Return the host part.
+ * Returns the host part.
*
- * @return a <code>String</code> object representing the host part
- * of this email address. If the host is of the dotNum form
- * (e.g. [yyy.yyy.yyy.yyy]) then strip the braces first.
- * @deprecated use getDomain() - name change to align with RFC2822 3.4.1. Addr-spec specification
+ * @return the host part of this email address. If the host is of the
+ * dotNum form (e.g. [yyy.yyy.yyy.yyy]), then strip the braces first.
+ * @deprecated use {@link #getDomain()}, whose name was changed to
+ * align with RFC2822 3.4.1. addr-spec specification
*/
public String getHost() {
return getDomain();
}
/**
- * Return the domain part per RFC2822 3.4.1. Addr-spec specification
+ * Returns the domain part per RFC2822 3.4.1. addr-spec specification.
*
- * @return a <code>String</code> object representing the domain part
- * of this email address. If the domain is of the domain-literal form (e.g. [yyy.yyy.yyy.yyy]) the braces will have been stripped returning the raw IP address.
+ * @return the domain part of this email address. If the domain is of
+ * the domain-literal form (e.g. [yyy.yyy.yyy.yyy]), the braces will
+ * have been stripped returning the raw IP address.
*/
public String getDomain() {
if (!(domain.startsWith("[") && domain.endsWith("]"))) {
return domain;
}
- return domain.substring(1, domain.length() -1);
-
+ return domain.substring(1, domain.length() -1);
}
/**
- * Return the user part.
+ * Returns the user part.
*
- * @return a <code>String</code> object representing the user part
- * of this email address.
- * @throws AddressException if the parse failed
- * @deprecated use getLocalPart() - name change to align with RFC2822 3.4.1. Addr-spec specification
+ * @return the user part of this email address
+ * @deprecated use {@link #getLocalPart()}, whose name was changed to
+ * align with the RFC2822 3.4.1. addr-spec specification
*/
public String getUser() {
return getLocalPart();
}
/**
- * Return the local-part per RFC2822 3.4.1. Addr-spec specification
+ * Returns the local-part per RFC2822 3.4.1. addr-spec specification.
*
- * @return a <code>String</code> object representing the local-part
- * of this email address as defined by RFC2822 3.4.1. Addr-spec specification.
- * The local-part portion is a domain dependent string. In addresses, it is simply interpreted on the particular host as a name of a particular mailbox.
- * It is the part before the "@"
- * @throws AddressException if the parse failed
+ * @return the local-part of this email address as defined by the
+ * RFC2822 3.4.1. addr-spec specification.
+ * The local-part portion is a domain dependent string.
+ * In addresses, it is simply interpreted on the particular
+ * host as a name of a particular mailbox
+ * (the part before the "@" character)
*/
public String getLocalPart() {
return localPart;
@@ -244,10 +251,10 @@
.append(domain);
return addressBuffer.toString();
}
-
/**
- * Return MailAddress as InternetAddress
+ * Returns an InternetAddress representing the same address
+ * as this MailAddress.
*
* @return the address
*/
@@ -260,6 +267,16 @@
}
}
+ /**
+ * Indicates whether some other object is "equal to" this one.
+ *
+ * Note that this implementation breaks the general contract of the
+ * <code>equals</code> method by allowing an instance to equal to a
+ * <code>String</code>. It is recommended that implementations avoid
+ * relying on this design which may be removed in a future release.
+ *
+ * @returns true if the given object is equal to this one, false otherwise
+ */
public boolean equals(Object obj) {
if (obj == null) {
return false;
@@ -274,11 +291,11 @@
}
/**
- * Return a hashCode for this object which should be identical for addresses
- * which are equivalent. This is implemented by obtaining the default
- * hashcode of the String representation of the MailAddress. Without this
- * explicit definition, the default hashCode will create different hashcodes
- * for separate object instances.
+ * Returns a hash code value for this object.
+ * <p>
+ * This method is implemented by returning the hash code of the canonical
+ * string representation of this address, so that all instances representing
+ * the same address will return an identical hash code.
*
* @return the hashcode.
*/
Modified: james/mailet/api/trunk/src/main/java/org/apache/mailet/Mailet.java
URL: http://svn.apache.org/viewvc/james/mailet/api/trunk/src/main/java/org/apache/mailet/Mailet.java?rev=800311&r1=800310&r2=800311&view=diff
==============================================================================
--- james/mailet/api/trunk/src/main/java/org/apache/mailet/Mailet.java (original)
+++ james/mailet/api/trunk/src/main/java/org/apache/mailet/Mailet.java Mon Aug 3 11:29:26 2009
@@ -20,103 +20,112 @@
package org.apache.mailet;
+import javax.mail.MessagingException;
+
/**
- * Draft of a Mailet inteface. The <code>service</code> perform all needed work
- * on the Mail object. Whatever remains at the end of the service is considered
- * to need futher processing and will go to the next Mailet if there is one
- * configured or will go to the error processor if not.
- * Setting a Mail state (setState(String)) to Mail.GHOST or cleaning its recipient
- * list has the same meaning that s no more processing is needed.
- * Instead of creating new messages, the mailet can put a message with new recipients
- * at the top of the mail queue, or insert them immediately after it's execution
- * through the API are provided by the MailetContext interface.
+ * A Mailet processes mail messages.
* <p>
- * This interface defines methods to initialize a mailet, to service messages, and to
- * remove a mailet from the server. These are known as life-cycle methods and are called
- * in the following sequence:
+ * The Mailet life cycle is controlled by the mailet container,
+ * which invokes the Mailet methods in the following order:
* <ol>
- * <li>The mailet is constructed, then initialized with the init method. </li>
- * <li>Any messages for the service method are handled.</li>
- * <li>The mailet is taken out of service, then destroyed with the destroy method,
- * then garbage collected and finalized.</li>
+ * <li>The mailet is constructed.
+ * <li>The {@link #init} method is invoked once to initialize the mailet.
+ * <li>The {@link #service} method is invoked to process mail messages.
+ * This can occur an unlimited number of times, even concurrently.
+ * <li>At some point, such as when the mailet container is shut down,
+ * the mailet is taken out of service and then destroyed by invoking
+ * the {@link #destroy} method once.
* </ol>
- * In addition to the life-cycle methods, this interface provides the getMailetConfig
- * method, which the mailet can use to get any startup information, and the
- * getMailetInfo method, which allows the mailet to return basic information about itself,
- * such as author, version, and copyright.
- *
- * @version 1.0.0, 24/04/1999
+ * <p>
+ * In addition to the life-cycle methods, this interface provides the
+ * {@link #getMailetConfig} method, which provides the Mailet with
+ * its initialization parameters and a {@link MailetContext} through which
+ * it can interact with the mailet container, and the {@link #getMailetInfo}
+ * method, which provides basic information about the Mailet.
+ * <p>
+ * Mailets are grouped by the mailet container's configuration into processors.
+ * Each processor is comprised of an ordered sequence of Mailets, each with a
+ * corresponding {@link Matcher}. A Mail message is processed by each
+ * Matcher-Mailet pair in order: If the mail is matched by the Matcher, it is
+ * passed to the Mailet's {@code service} method for processing, and if it is
+ * not matched, the Mailet is skipped and the mail moves on to the next
+ * Matcher-Mailet pair.
+ * <p>
+ * The {@code service} method performs all needed processing on the Mail,
+ * and may modify the message content, recipients, attributes, state, etc.
+ * When the method returns, the mail is passed on to the next Matcher-Mailer
+ * pair in the processor. If there are no subsequent mailets in the processor,
+ * it is moved to the error processor.
+ * Setting the Mail {@link Mail#setState state} to {@link Mail#GHOST}, or clearing its
+ * recipient list, both mean that no further processing is needed, which will
+ * cause the Mail to be dropped without ever reaching subsequent Mailets.
+ * <p>
+ * Instead of creating new messages, the mailet can put a message with new recipients
+ * at the top of the mail queue, or insert them immediately after it's execution
+ * through the API are provided by the MailetContext interface.
*/
public interface Mailet {
-
+
/**
- * Called by the mailet container to indicate to a mailet that the
- * mailet is being taken out of service. This method is only called once
- * all threads within the mailet's service method have exited or after a
- * timeout period has passed. After the mailet container calls this method,
- * it will not call the service method again on this mailet.
+ * Initializes this Mailet.
* <p>
- * This method gives the mailet an opportunity to clean up any resources that
- * are being held (for example, memory, file handles, threads) and make sure
- * that any persistent state is synchronized with the mailet's current state in memory.
+ * This method is called only once, and must complete successfully
+ * before the {@link #service} method can be invoked.
+ *
+ * @param config a MailetConfig containing the mailet's configuration
+ * and initialization parameters
+ * @throws MessagingException if an error occurs
*/
- void destroy();
+ void init(MailetConfig config) throws MessagingException;
/**
- * Returns information about the mailet, such as author, version, and
- * copyright.
+ * Services a mail message.
* <p>
- * The string that this method returns should be plain text and not markup
- * of any kind (such as HTML, XML, etc.).
+ * Mailets typically run inside multithreaded mailet containers that can handle
+ * multiple requests concurrently. Developers must be aware to synchronize access
+ * to any shared resources such as files and network connections, as well as the
+ * mailet's fields. More information on multithreaded programming in Java is
+ * available at <a href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html">the
+ * Java tutorial on multi-threaded programming</a>.
*
- * @return a String containing servlet information
+ * @param mail the Mail to process
+ * @throws MessagingException if any error occurs which prevents the Mail
+ * processing from completing successfully
*/
- String getMailetInfo();
+ void service(Mail mail) throws MessagingException;
/**
- * Returns a MailetConfig object, which contains initialization and
- * startup parameters for this mailet.
+ * Destroys this Mailet.
* <p>
- * Implementations of this interface are responsible for storing the MailetConfig
- * object so that this method can return it. The GenericMailet class, which implements
- * this interface, already does this.
- *
- * @return the MailetConfig object that initializes this mailet
+ * This method is called only once, after all {@link #service} invocations
+ * have completed (or a timeout period has elapsed). After this method
+ * returns, this Mailet will no longer be used.
+ * <p>
+ * Implementations should use this method to release any resources that
+ * are being held (such as memory, file handles or threads) and make sure
+ * that any persistent information is properly stored.
*/
- MailetConfig getMailetConfig();
+ void destroy();
/**
- * Called by the mailet container to indicate to a mailet that the
- * mailet is being placed into service.
- * <p>
- * The mailet container calls the init method exactly once after
- * instantiating the mailet. The init method must complete successfully
- * before the mailet can receive any requests.
+ * Returns a MailetConfig object, which provides initialization parameters
+ * and a {@link MailetContext} through which it can interact with the
+ * mailet container.
+ * <p>
+ * Implementations of this interface are responsible for storing the
+ * MailetConfig which they receive in the {@link #init} method so
+ * that this method can return it.
*
- * @param config - a MailetConfig object containing the mailet's configuration
- * and initialization parameters
- * @throws javax.mail.MessagingException - if an exception has occurred that interferes with
- * the mailet's normal operation
+ * @return the MailetConfig that this mailet was initialized with
*/
- void init(MailetConfig config) throws javax.mail.MessagingException;
-
+ MailetConfig getMailetConfig();
+
/**
- * Called by the mailet container to allow the mailet to process to
- * a message.
- * <p>
- * This method is only called after the mailet's init() method has completed
- * successfully.
- * <p>
- * Mailets typically run inside multithreaded mailet containers that can handle
- * multiple requests concurrently. Developers must be aware to synchronize access
- * to any shared resources such as files, network connections, as well as the
- * mailet's class and instance variables. More information on multithreaded
- * programming in Java is available in <a href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html">the
- * Java tutorial on multi-threaded programming</a>.
+ * Returns information about the mailet, such as author, version and
+ * copyright.
*
- * @param mail - the Mail object that contains the message and routing information
- * @throws javax.mail.MessagingException - if a message or address parsing exception occurs or
- * an exception that interferes with the mailet's normal operation
+ * @return the Mailet information (as a plain text string)
*/
- void service(Mail mail) throws javax.mail.MessagingException;
+ String getMailetInfo();
+
}
Modified: james/mailet/api/trunk/src/main/java/org/apache/mailet/MailetConfig.java
URL: http://svn.apache.org/viewvc/james/mailet/api/trunk/src/main/java/org/apache/mailet/MailetConfig.java?rev=800311&r1=800310&r2=800311&view=diff
==============================================================================
--- james/mailet/api/trunk/src/main/java/org/apache/mailet/MailetConfig.java (original)
+++ james/mailet/api/trunk/src/main/java/org/apache/mailet/MailetConfig.java Mon Aug 3 11:29:26 2009
@@ -23,23 +23,22 @@
import java.util.Iterator;
/**
- * A mailet configuration object used by a mailet container to pass information
- * to a mailet during initialization.
+ * A mailet configuration object used by the mailet container to pass
+ * information to a mailet during initialization.
* <p>
- * The configuration information contains initialization parameters, which are a set
- * of name/value pairs, and a MailetContext object, which gives the mailet information
- * about the server.
+ * 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.
*
- * @version 1.0.0, 24/04/1999
*/
public interface MailetConfig {
/**
- * Returns a String containing the value of the named initialization
- * parameter, or null if the parameter does not exist.
+ * Returns the value of the named initialization parameter,
+ * or null if the parameter does not exist.
*
- * @param name - a String specifying the name of the initialization parameter
- * @return a String containing the value of the initialization parameter
+ * @param name the name of the initialization parameter
+ * @return the value of the initialization parameter, or null
*/
String getInitParameter(String name);
@@ -48,8 +47,8 @@
* Iterator of String objects, or an empty Iterator if the mailet has
* no initialization parameters.
*
- * @return an Iterator of String objects containing the names of the mailet's
- * initialization parameters
+ * @return an Iterator of String objects containing the names of the
+ * mailet's initialization parameters
*/
Iterator getInitParameterNames();
@@ -57,16 +56,16 @@
* Returns a reference to the MailetContext in which the mailet is
* executing.
*
- * @return a MailetContext object, used by the mailet to interact with its
- * mailet container
+ * @return a MailetContext object which can be used by the mailet
+ * to interact with the mailet container
*/
MailetContext getMailetContext();
/**
* Returns the name of this mailet instance. The name may be provided via
* server administration, assigned in the application deployment descriptor,
- * or for an unregistered (and thus unnamed) mailet instance it will be the
- * mailet's class name.
+ * or, for an unregistered (and thus unnamed) mailet instance, it will be
+ * the mailet's class name.
*
* @return the name of the mailet instance
*/
Modified: james/mailet/api/trunk/src/main/java/org/apache/mailet/MailetContext.java
URL: http://svn.apache.org/viewvc/james/mailet/api/trunk/src/main/java/org/apache/mailet/MailetContext.java?rev=800311&r1=800310&r2=800311&view=diff
==============================================================================
--- james/mailet/api/trunk/src/main/java/org/apache/mailet/MailetContext.java (original)
+++ james/mailet/api/trunk/src/main/java/org/apache/mailet/MailetContext.java Mon Aug 3 11:29:26 2009
@@ -27,237 +27,283 @@
import javax.mail.internet.MimeMessage;
/**
- * Defines a set of methods that a mailet or matcher uses to communicate
- * with its mailet container, for example, to send a new message, to
- * deliver a message locally, or write to a log file.
+ * Defines a set of methods that can be used to interact with the mailet
+ * container. For example, it can be used to send a new message, to deliver
+ * a message locally, or to write to a log file.
+ * <p>
+ * Mailets and Matchers can retrieve a MailetContext through their
+ * respective MailetConfig and MatcherConfig objects, which are provided
+ * to them by the mailet container when they are initialized.
+ * <p>
+ * <b>Mailet Context Attributes</b>
+ * <p>
+ * The Mailet Context can provide additional configuration or other
+ * information not defined in this interface to Mailets and Matchers
+ * by using attributes. See your server documentation for information
+ * on the attributes it provides.
+ * <p>
+ * Every attribute consists of a name and a value.
+ * 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>.
+ * Attribute values can be arbitrary objects.
+ * <p>
+ * The list of attributes which are currently associated with a mailet
+ * context can be retrieved using the {@link #getAttributeNames}
+ * method, and given its name, the value of an attribute can be
+ * retrieved using the {@link #getAttribute} method.
*
- * The MailetContext object is contained within the MailetConfig and
- * MatcherConfig objects, which the mailet container provides to the
- * mailets and matchers when they are initialized.
- *
- * @version 1.0.0, 24/04/1999
*/
public interface MailetContext {
-
+
/**
- * Bounces the message using a standard format with the given message.
- * The message will be sent back to the sender from the postmaster as specified for
- * this mailet context, adding message to top of mail server queue using
- * sendMail().
+ * Returns the major version number of the Mailet API that this mailet
+ * container supports. For example, if the mailet container supports
+ * version 1.2 of the Mailet API, this method returns 1.
*
- * @param mail - the message that is to be bounced and sender to whom to return the message
- * @param message - a descriptive message as to why the message bounced
+ * @return the major version number of the supported Mailet API
*/
- void bounce(Mail mail, String message) throws MessagingException;
+ int getMajorVersion();
/**
- * Bounces the email message using the provided email address as the
- * sender of the bounce.
+ * Returns the minor version number of the Mailet API that this mailet
+ * container supports. For example, if the mailet container supports
+ * version 1.2 of the Mailet API, this method returns 2.
*
- * @param mail - the message that is to be bounced and sender to whom to return the message
- * @param message - a descriptive message as to why the message bounced
- * @param bouncer - the address to give as the sender of the bounced message
+ * @return the minor version number of the supported Mailet API
*/
- void bounce(Mail mail, String message, MailAddress bouncer) throws MessagingException;
+ int getMinorVersion();
/**
- * Returns a Collection of Strings of hostnames or ip addresses that
- * are specified as mail server listeners for the given hostname.
- * This is done using MX records, and the hostnames or ip addresses
- * are returned sorted by MX priority.
+ * Returns the name and version of the mailet container on which
+ * the mailet is running.
+ * <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"}
+ * or {@code "JAMES/1.2 (JDK 1.3.0; Windows NT 4.0 x86)"}.
*
- * <p>TODO: This needs to be made a more specific ordered subtype of Collection.</p>
- *
- * @param host - the domain name for which to find mail servers
- * @return a Collection of Strings of hostnames, sorted by priority
+ * @return the server information string
*/
- Collection getMailServers(String host);
+ String getServerInfo();
/**
- * Returns the postmaster's address for this mailet context.
+ * Returns an Iterator over the names of all attributes which are set
+ * in this mailet context.
+ * <p>
+ * The {@link #getAttribute} method can be called to
+ * retrieve an attribute's value given its name.
*
- * @return a MailAddress of the Postmaster's address
+ * @return an Iterator (of Strings) over all attribute names
*/
- MailAddress getPostmaster();
-
+ Iterator getAttributeNames();
+
/**
- * Returns the mailet container attribute with the given name, or null
- * if there is no attribute by that name. An attribute allows a mailet container
- * to give the mailet additional information not already provided by this interface.
- * See your server documentation for information about its attributes. A list of
- * supported attributes can be retrieved using getAttributeNames.
- * <p>
- * The attribute is returned as a java.lang.Object or some subclass. Attribute
- * names should follow the same convention as package names. The Java Mailet API
- * specification reserves names matching java.*, javax.*, and sun.*
+ * Returns the value of the named mailet context attribute,
+ * or null if the attribute does not exist.
*
- * @param name - a String specifying the name of the attribute
- * @return an Object containing the value of the attribute, or null if no attribute
- * exists matching the given name
+ * @param name the attribute name
+ * @return the attribute value, or null if the attribute does not exist
*/
Object getAttribute(String name);
-
+
/**
- * Returns an Iterator containing the attribute names available within
- * this mailet context. Use the getAttribute(java.lang.String) method with an
- * attribute name to get the value of an attribute.
+ * 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.*.
*
- * @return an Iterator of attribute names
+ * @param name - a String specifying the name of the attribute
+ * @param object - an Object representing the attribute to be bound
*/
- Iterator getAttributeNames();
-
+
/**
- * Returns the major version of the Mailet API that this mailet
- * container supports. All implementations that comply with Version 1.2 must have
- * this method return the integer 1.
+ * Associates an attribute with the given name and value with this mailet context.
+ * <p>
+ * If an attribute with the given name already exists, it is replaced, and the
+ * previous value is returned.
+ * <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>.
*
- * @return 1
+ * @param name the attribute name
+ * @param value the attribute value
*/
- int getMajorVersion();
-
+ void setAttribute(String name, Object value);
+
/**
- * Returns the minor version of the Mailet API that this mailet
- * container supports. All implementations that comply with Version 1.2 must have
- * this method return the integer 2.
+ * Removes the attribute with the given name from this Mail instance.
*
- * @return 2
+ * @param name the name of the attribute to be removed
+ * @since Mailet API v2.1
*/
- int getMinorVersion();
+ void removeAttribute(String name);
/**
- * Returns the name and version of the mailet container on which
- * the mailet is running.
- * <p>
- * The form of the returned string is servername/versionnumber. For example,
- * JAMES may return the string JAMES/1.2.
- * <p>
- * The mailet container may return other optional information after the primary
- * string in parentheses, for example, JAMES/1.2 (JDK 1.3.0; Windows NT 4.0 x86).
+ * Writes the specified message to a mailet log. The name and type of
+ * the mailet log is specific to the mailet container.
*
- * @return a String containing at least the mailet container name and version number
+ * @param message the message to be written to the log
*/
- String getServerInfo();
+ void log(String message);
/**
- * Checks if a server is serviced by mail context
+ * Writes the specified message to a mailet log, along with the stack
+ * trace of the given Throwable. The name and type of the mailet log
+ * is specific to the mailet container.
*
- * @param serverName - name of server.
- * @return true if server is local, i.e. serviced by this mail context
+ * @param message the message to be written to the log
+ * @param t the Throwable whose stack trace is to be written to the log
*/
- boolean isLocalServer(String serverName);
-
+ void log(String message, Throwable t);
+
/**
- * Checks if a user account is exists in the mail context.
+ * Returns the Postmaster address for this mailet context.
*
- * @param userAccount - user identifier.
- * @return true if the account is a local account
- *
- * @deprecated use isLocalEmail(MailAddress) instead
- *
- * @since James 2.4.0 this method expect to receive also the domain
- * name within the userAccount string (user\@domain).
- * By default it will use \@localhost when no domain is passed.
+ * @return the Postmaster address
*/
- boolean isLocalUser(String userAccount);
+ MailAddress getPostmaster();
/**
- * Checks if a user account is exists in the mail context.
+ * Checks if a host name is local, i.e. this server is the
+ * final delivery destination for messages sent to this host.
*
- * @param mailAddress - address of the account to be checked.
- * @return true if the account is a local account
- *
- * @since James 2.4.0
+ * @param hostname the host name to check
+ * @return true if server is local, false otherwise
*/
- boolean isLocalEmail(MailAddress mailAddress);
+ boolean isLocalServer(String hostname);
/**
- * Writes the specified message to a mailet log file, usually an event
- * log. The name and type of the mailet log file is specific to the mailet
- * container.
- *
- * @param message - a String specifying the message to be written to the log file
+ * 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>
+ * 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.
+ *
+ * @param userAccount the full address of the account to be checked
+ * @return true if the account is a local account, false otherwise
+ * @deprecated use {@link #isLocalEmail(MailAddress)} instead
*/
- void log(String message);
-
+ boolean isLocalUser(String userAccount);
+
/**
- * Writes an explanatory message and a stack trace for a given Throwable
- * exception to the mailet log file.
- *
- * @param message - a String that describes the error or exception
- * @param t - the Throwable error or exception
+ * Checks if an address is local, i.e. its account exists locally
+ * and this server is the final delivery destination for messages
+ * sent to this address.
+ *
+ * @param mailAddress the full address of the account to be checked
+ * @return true if the account is a local account, false otherwise
+ * @since Mailet API 2.4
*/
- void log(String message, Throwable t);
-
+ boolean isLocalEmail(MailAddress mailAddress);
+
/**
- * Removes the attribute with the given name from the mailet context. After
- * removal, subsequent calls to getAttribute(java.lang.String) to retrieve
- * the attribute's value will return null.
- *
- * @param name - a String specifying the name of the attribute to be removed
+ * Returns the hostnames that are specified as mail handlers for
+ * the given domain name. The host names are determined using DNS
+ * lookup of MX records and are returned sorted by priority
+ * (as detailed in the SMTP RFC).
+ *
+ * @param domain the domain name whose mail handling hosts are requested
+ * @return the sorted mail-handling hostnames for the domain
*/
- void removeAttribute(String name);
-
+ Collection getMailServers(String domain);
+
/**
- * Send an outgoing message to the top of this mailet container's root queue.
- * This is the equivalent of opening an SMTP session to localhost.
- * This uses sender and recipients as specified in the message itself.
+ * Returns the SMTP host addresses specified as mail handlers for
+ * the given domain name. This is equivalent to calling the
+ * {@link #getMailServers} method and then performing address
+ * resolution lookups on all returned host names in order.
+ * The results are returned as instances of {@link HostAddress}
+ * containing the host and address information.
+ *
+ * @since Mailet API v2.3
+ * @param domain the domain whose mail handling SMTP host addresses are requested
+ * @return an Iterator over HostAddress, in proper order of priority, or
+ * an empty iterator if no hosts are found
+ */
+ Iterator getSMTPHostAddresses(String domain);
+
+ /**
+ * Sends an outgoing message to the top of this mailet container's root queue.
+ * This is functionally equivalent to having opened an SMTP session to the local
+ * host and delivering the message using the sender and recipients from within
+ * the message itself.
*
- * @param msg - the MimeMessage of the headers and body content of the outgoing message
- * @throws MessagingException - if the message fails to parse
+ * @param message the message to send
+ * @throws MessagingException if an error occurs accessing or sending the message
*/
- void sendMail(MimeMessage msg)
+ void sendMail(MimeMessage message)
throws MessagingException;
/**
- * Send an outgoing message to the top of this mailet container's root queue.
- * This is the equivalent of opening an SMTP session to localhost.
- *
- * @param sender - the sender of the message
- * @param recipients - a Collection of MailAddress objects of recipients
- * @param msg - the MimeMessage of the headers and body content of the outgoing message
- * @throws MessagingException - if the message fails to parse
+ * Sends an outgoing message to the top of this mailet container's root queue.
+ * 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 recipients the message recipients as a Collection of MailAddress objects
+ * @param message the message to send
+ * @throws MessagingException if an error occurs accessing or sending the message
*/
- void sendMail(MailAddress sender, Collection recipients, MimeMessage msg)
+ void sendMail(MailAddress sender, Collection recipients, MimeMessage message)
throws MessagingException;
/**
- * Send an outgoing message to the top of this mailet container queue for the
- * appropriate processor that is specified.
+ * Sends an outgoing message to the top of this mailet container's queue for the
+ * specified processor.
*
- * @param sender - the sender of the message
- * @param recipients - a Collection of MailAddress objects of recipients
- * @param msg - the MimeMessage of the headers and body content of the outgoing message
- * @param state - the state of the message, indicates which processor to use
- * This is a String that names a processor for which the message will be queued
- * @throws MessagingException - if the message fails to parse
+ * @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
+ * @throws MessagingException if an error occurs accessing or sending the message
*/
- void sendMail(MailAddress sender, Collection recipients, MimeMessage msg, String state)
+ void sendMail(MailAddress sender, Collection recipients, MimeMessage message, String state)
throws MessagingException;
/**
- * Send an outgoing message to the top of this mailet container's root queue.
+ * 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
*
* @param mail - the message that is to sent
- * @throws MessagingException - if the message fails to spool
+ * @throws MessagingException if an error occurs accessing or sending the message
*/
void sendMail(Mail mail)
throws MessagingException;
+
+ /**
+ * Bounces the message using a standard format with the given message.
+ * <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 message a descriptive message explaining why the message bounced
+ * @throws MessagingException if an error occurs accessing or sending the message
+ */
+ void bounce(Mail mail, String message) throws MessagingException;
/**
- * 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.
+ * Bounces the message using a standard format with the given message.
* <p>
- * Attribute names should follow the same convention as package names. The Java
- * Mailet API specification reserves names matching java.*, javax.*, and sun.*.
+ * 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 name - a String specifying the name of the attribute
- * @param object - an Object representing the attribute to be bound
+ * @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
*/
- void setAttribute(String name, Object object);
-
+ void bounce(Mail mail, String message, MailAddress bouncer) throws MessagingException;
+
/**
* Stores the message is in the local repository associated with
* recipient for later retrieval, e.g., by a POP3 or IMAP service.
@@ -266,24 +312,10 @@
* resource acquired via JNDI.
* @param sender - the sender of the incoming message
* @param recipient - the user who is receiving this message (as a complete email address)
- * @param msg - the MimeMessage to store in a local mailbox
+ * @param message - the MimeMessage to store in a local mailbox
* @throws MessagingException - if the message fails to parse
*/
- void storeMail(MailAddress sender, MailAddress recipient, MimeMessage msg)
+ void storeMail(MailAddress sender, MailAddress recipient, MimeMessage message)
throws MessagingException;
- /**
- * Returns an Iterator over HostAddress, a specialized subclass of
- * javax.mail.URLName, which provides location information for
- * servers that are specified as mail handlers for the given
- * hostname. This is done using MX records, and the HostAddress
- * instances are returned sorted by MX priority. If no host is
- * found for domainName, the Iterator returned will be empty and the
- * first call to hasNext() will return false.
- *
- * @since Mailet API v2.2.0a16-unstable
- * @param domainName - the domain for which to find mail servers
- * @return an Iterator over HostAddress instances, sorted by priority
- */
- Iterator getSMTPHostAddresses(String domainName);
}
Modified: james/mailet/api/trunk/src/main/java/org/apache/mailet/MailetException.java
URL: http://svn.apache.org/viewvc/james/mailet/api/trunk/src/main/java/org/apache/mailet/MailetException.java?rev=800311&r1=800310&r2=800311&view=diff
==============================================================================
--- james/mailet/api/trunk/src/main/java/org/apache/mailet/MailetException.java (original)
+++ james/mailet/api/trunk/src/main/java/org/apache/mailet/MailetException.java Mon Aug 3 11:29:26 2009
@@ -24,8 +24,6 @@
/**
* Defines a general exception a mailet can throw when it encounters difficulty.
- *
- * @version 1.0.0, 24/04/1999
*/
public class MailetException extends MessagingException {
@@ -44,10 +42,8 @@
}
/**
- * Constructs a new mailet exception when the mailet needs to throw
- * an exception and include a message about the "root cause" exception
- * that interfered with its normal operation, including a description
- * message.
+ * Constructs a new mailet exception with the specified message
+ * and an exception which is the "root cause" of the exception.
*/
public MailetException(String message, Exception e) {
super(message, e);
Modified: james/mailet/api/trunk/src/main/java/org/apache/mailet/Matcher.java
URL: http://svn.apache.org/viewvc/james/mailet/api/trunk/src/main/java/org/apache/mailet/Matcher.java?rev=800311&r1=800310&r2=800311&view=diff
==============================================================================
--- james/mailet/api/trunk/src/main/java/org/apache/mailet/Matcher.java (original)
+++ james/mailet/api/trunk/src/main/java/org/apache/mailet/Matcher.java Mon Aug 3 11:29:26 2009
@@ -21,120 +21,107 @@
package org.apache.mailet;
import java.util.Collection;
+import javax.mail.MessagingException;
/**
- * This interface define the behaviour of the message "routing" inside
- * the mailet container. The match(Mail) method returns a Collection of
- * recipients that meet this class's criteria.
+ * This interface defines the behaviour of the message "routing" inside
+ * the mailet container. At its heart is the {@link #match(Mail)} method,
+ * which inspects a Mail and returns a subset of its recipients which meet
+ * this Matcher's criteria.
* <p>
* An important feature of the mailet container is the ability to fork
- * processing of messages. When a message first arrives at the server,
- * it might have multiple recipients specified. As a message is passed
- * to a matcher, the matcher might only "match" one of the listed
- * recipients. It would then return only the matching recipient in
- * the Collection. The mailet container should then duplicate the
- * message splitting the recipient list across the two messages as per
- * what the matcher returned.
+ * processing of messages. When a message first arrives at the server,
+ * it might have multiple recipients specified. When a message is passed
+ * to a matcher, the matcher might only match some of the listed recipients.
+ * The mailet container should then duplicate the message, splitting the
+ * recipient list across the two messages as per the match result, and
+ * proceed to process them separately.
* <p>
- * <b>[THIS PARAGRAPH NOT YET IMPLEMENTED]</b>
- * <i>The matcher can extend this forking to further separation by returning
- * a Collection of Collection objects. This allows a matcher to fork
- * multiple processes if there are multiple recipients that require
- * separate processing. For example, we could write a ListservMatcher
- * that handles multiple listservs. When someone cross-posts across
- * multiple listservs that this matcher handles, it could put each
- * listserv address (recipient) that it handles in a separate Collection
- * object. By returning each of these Collections within a container
- * Collection object, it could indicate to the mailet container how
- * many forks to spawn.</i>
- * <p>
- * This interface defines methods to initialize a matcher, to match
- * messages, and to remove a matcher from the server. These are known
- * as life-cycle methods and are called in the following sequence:
+ * The Matcher life cycle is controlled by the mailet container,
+ * which invokes the Matcher methods in the following order:
* <ol>
- * <li>The matcher is constructed, then initialized with the init method.</li>
- * <li>Any calls from clients to the match method are handled.</li>
- * <li>The matcher is taken out of service, then destroyed with the
- * destroy method, then garbage collected and finalized.</li>
+ * <li>The matcher is constructed.
+ * <li>The {@link #init} method is invoked once to initialize the matcher.
+ * <li>The {@link #match} method is invoked to match mail messages.
+ * This can occur an unlimited number of times, even concurrently.
+ * <li>At some point, such as when the mailet container is shut down,
+ * the matcher is taken out of service and then destroyed by invoking
+ * the {@link #destroy} method once.
* </ol>
+ * <p>
* In addition to the life-cycle methods, this interface provides the
- * getMatcherConfig method, which the matcher can use to get any startup
- * information, and the getMatcherInfo method, which allows the matcher
- * to return basic information about itself, such as author, version,
- * and copyright.
+ * {@link #getMatcherConfig} method, which provides the Matcher with
+ * 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.
*
- * @version 1.0.0, 24/04/1999
*/
public interface Matcher {
/**
- * Called by the mailet container to indicate to a matcher that the matcher
- * is being taken out of service. This method is only called once all threads
- * within the matcher's service method have exited or after a timeout period
- * has passed. After the mailet container calls this method, it will not call
- * the match method again on this matcher.
- * <p>
- * This method gives the matcher an opportunity to clean up any resources that
- * are being held (for example, memory, file handles, threads) and make sure
- * that any persistent state is synchronized with the matcher's current state in memory.
+ * Initializes this Matcher.
+ * <p>
+ * This method is called only once, and must complete successfully
+ * before the {@link #match} method can be invoked.
+ *
+ * @param config a MatcherConfig containing the matcher's configuration
+ * and initialization parameters
+ * @throws MessagingException if an error occurs
*/
- void destroy();
+ void init(MatcherConfig config) throws MessagingException;
/**
- * Returns a MatcherConfig object, which contains initialization and
- * startup parameters for this matcher.
+ * Takes a Mail message, looks at any pertinent information, and returns
+ * a subset of recipients that meet the match conditions.
* <p>
- * Implementations of this interface are responsible for storing the
- * MatcherConfig object so that this method can return it. The GenericMatcher
- * class, which implements this interface, already does this.
+ * Matchers typically run inside multithreaded mailet containers that can handle
+ * multiple requests concurrently. Developers must be aware to synchronize access
+ * to any shared resources such as files, network connections, and as well as the
+ * matcher's fields. More information on multithreaded programming in Java is
+ * available at <a href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html">the
+ * Java tutorial on multi-threaded programming</a>.
*
- * @return the MatcherConfig object that initializes this matcher
+ * @param mail the Mail to match
+ * @return the recipients that meet the match criteria as a Collection of String objects
+ * @throws MessagingException if any error occurs which prevents the Mail
+ * matching from completing successfully
*/
- MatcherConfig getMatcherConfig();
-
+ Collection match(Mail mail) throws MessagingException;
+
/**
- * Returns information about the matcher, such as author, version, and copyright.
+ * Destroys this Matcher.
* <p>
- * The string that this method returns should be plain text and not markup
- * of any kind (such as HTML, XML, etc.).
- *
- * @return a String containing matcher information
+ * This method is called only once, after all {@link #match} invocations
+ * have completed (or a timeout period has elapsed). After this method
+ * returns, this Matcher will no longer be used.
+ * <p>
+ * Implementations should use this method to release any resources that
+ * are being held (such as memory, file handles or threads) and make sure
+ * that any persistent information is properly stored.
+ * <p>
+ * Note that containers <code>SHOULD NOT</code> invoke this method before
+ * {@link #init(MatcherConfig)} has been successfully completed.
*/
- String getMatcherInfo();
-
+ void destroy();
+
/**
- * Called by the mailet container to indicate to a matcher that the
- * matcher is being placed into service.
+ * Returns a MatcherConfig object, which provides initialization parameters
+ * and a {@link MailetContext} through which it can interact with the
+ * mailet container.
* <p>
- * The mailet container calls the init method exactly once after instantiating
- * the matcher. The init method must complete successfully before the matcher
- * can receive any messages.
+ * Implementations of this interface are responsible for storing the
+ * MatcherConfig which they receive in the {@link #init} method so
+ * that this method can return it.
*
- * @param config - a MatcherConfig object containing the matcher's configuration
- * and initialization parameters
- * @throws javax.mail.MessagingException - if an exception has occurred that
- * interferes with the matcher's normal operation
+ * @return the MatcherConfig that this matcher was initialized with
*/
- void init( MatcherConfig config ) throws javax.mail.MessagingException;
+ MatcherConfig getMatcherConfig();
/**
- * Takes a Mail message, looks at any pertinent information, and then returns a subset
- * of recipients that meet the "match" conditions.
- * <p>
- * This method is only called after the matcher's init() method has completed
- * successfully.
- * <p>
- * Matchers typically run inside multithreaded mailet containers that can handle
- * multiple requests concurrently. Developers must be aware to synchronize access
- * to any shared resources such as files, network connections, and as well as the
- * matcher's class and instance variables. More information on multithreaded
- * programming in Java is available in <a href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html">the
- * Java tutorial on multi-threaded programming</a>.
+ * Returns information about the matcher, such as author, version and
+ * copyright.
*
- * @param mail - the Mail object that contains the message and routing information
- * @return a Collection of String objects (recipients) that meet the match criteria
- * @throws javax.mail.MessagingException - if an message or address parsing exception occurs or
- * an exception that interferes with the matcher's normal operation
+ * @return the Mailet information (as a plain text string)
*/
- Collection match( Mail mail ) throws javax.mail.MessagingException;
+ String getMatcherInfo();
}
Modified: james/mailet/api/trunk/src/main/java/org/apache/mailet/MatcherConfig.java
URL: http://svn.apache.org/viewvc/james/mailet/api/trunk/src/main/java/org/apache/mailet/MatcherConfig.java?rev=800311&r1=800310&r2=800311&view=diff
==============================================================================
--- james/mailet/api/trunk/src/main/java/org/apache/mailet/MatcherConfig.java (original)
+++ james/mailet/api/trunk/src/main/java/org/apache/mailet/MatcherConfig.java Mon Aug 3 11:29:26 2009
@@ -21,20 +21,21 @@
package org.apache.mailet;
/**
- * A matcher configuration object used by a mailet container used to pass information
- * to a matcher during initialization.
+ * A matcher configuration object used by the mailet container to pass
+ * information to a matcher during initialization.
* <p>
- * The configuration information contains an initialization parameter,
- * which is set as a condition String, and a MailetContext object,
- * which gives the mailet information about the mailet container.
- *
- * @version 1.0.0, 24/04/1999
+ * The configuration information consists of the matcher's condition string,
+ * and a MailetContext object which allows the matcher to interact with the
+ * mailet container.
*/
public interface MatcherConfig {
/**
- * The simple condition defined for this matcher, e.g., for
- * SenderIs=admin@localhost, this would return admin@localhost.
+ * The condition defined for this matcher.
+ * <p>
+ * For example, the SenderIs matcher might be configured as
+ * "SenderIs=admin@localhost", in which case the condition would be
+ * "admin@localhost".
*
* @return a String containing the value of the initialization parameter
*/
@@ -43,15 +44,15 @@
/**
* Returns a reference to the MailetContext in which the matcher is executing
*
- * @return a MailetContext object, used by the matcher to interact with its
- * mailet container
+ * @return a MailetContext object which can be used by the matcher
+ * to interact with the mailet container
*/
MailetContext getMailetContext();
/**
* Returns the name of this matcher instance. The name may be provided via server
- * administration, assigned in the application deployment descriptor, or for
- * an unregistered (and thus unnamed) matcher instance it will be the matcher's
+ * administration, assigned in the application deployment descriptor, or, for
+ * an unregistered (and thus unnamed) matcher instance, it will be the matcher's
* class name.
*
* @return the name of the matcher instance
Modified: james/mailet/api/trunk/src/main/java/org/apache/mailet/package.html
URL: http://svn.apache.org/viewvc/james/mailet/api/trunk/src/main/java/org/apache/mailet/package.html?rev=800311&r1=800310&r2=800311&view=diff
==============================================================================
--- james/mailet/api/trunk/src/main/java/org/apache/mailet/package.html (original)
+++ james/mailet/api/trunk/src/main/java/org/apache/mailet/package.html Mon Aug 3 11:29:26 2009
@@ -17,5 +17,6 @@
under the License.
-->
<body>
-<p>The classes that constitute the Mailet API.</p>
+<p>This package constitutes the Mailet API.</p>
+<p>To understand the API, start by reviewing the Matcher and Mailet interfaces.</p>
</body>