You are viewing a plain text version of this content. The canonical link for it is here.
Posted to site-dev@james.apache.org by rd...@apache.org on 2009/08/03 14:19:07 UTC
svn commit: r800330 [3/22] - in /james/site/trunk/www/mailet: ./ api/
api/apidocs/ api/apidocs/org/apache/mailet/
api/apidocs/org/apache/mailet/class-use/ api/stylesheets/ api/testapidocs/
api/testapidocs/org/apache/mailet/ api/testapidocs/org/apache/m...
Modified: james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/Mailet.html
URL: http://svn.apache.org/viewvc/james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/Mailet.html?rev=800330&r1=800329&r2=800330&view=diff
==============================================================================
--- james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/Mailet.html (original)
+++ james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/Mailet.html Mon Aug 3 12:18:51 2009
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_18) on Thu May 28 11:11:01 BST 2009 -->
+<!-- Generated by javadoc (build 1.5.0_18) on Mon Aug 03 13:36:26 BST 2009 -->
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>
Mailet (Apache Mailet API 2.5-SNAPSHOT API)
@@ -94,36 +94,49 @@
</PRE>
<P>
-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 <A HREF="../../../org/apache/mailet/Mailet.html#init(org.apache.mailet.MailetConfig)"><CODE>init(org.apache.mailet.MailetConfig)</CODE></A> method is invoked once to initialize the mailet.
+ <li>The <A HREF="../../../org/apache/mailet/Mailet.html#service(org.apache.mailet.Mail)"><CODE>service(org.apache.mailet.Mail)</CODE></A> 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 <A HREF="../../../org/apache/mailet/Mailet.html#destroy()"><CODE>destroy()</CODE></A> 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.
+ <p>
+ In addition to the life-cycle methods, this interface provides the
+ <A HREF="../../../org/apache/mailet/Mailet.html#getMailetConfig()"><CODE>getMailetConfig()</CODE></A> method, which provides the Mailet with
+ its initialization parameters and a <A HREF="../../../org/apache/mailet/MailetContext.html" title="interface in org.apache.mailet"><CODE>MailetContext</CODE></A> through which
+ it can interact with the mailet container, and the <A HREF="../../../org/apache/mailet/Mailet.html#getMailetInfo()"><CODE>getMailetInfo()</CODE></A>
+ 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 <A HREF="../../../org/apache/mailet/Matcher.html" title="interface in org.apache.mailet"><CODE>Matcher</CODE></A>. 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</code> 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</code> 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 <A HREF="../../../org/apache/mailet/Mail.html#setState(java.lang.String)"><CODE>state</CODE></A> to <A HREF="../../../org/apache/mailet/Mail.html#GHOST"><CODE>Mail.GHOST</CODE></A>, 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.
<P>
<P>
-<DL>
-<DT><B>Version:</B></DT>
- <DD>1.0.0, 24/04/1999</DD>
-</DL>
<HR>
<P>
@@ -142,8 +155,7 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/Mailet.html#destroy()">destroy</A></B>()</CODE>
<BR>
- Called by the mailet container to indicate to a mailet that the
- mailet is being taken out of service.</TD>
+ Destroys this Mailet.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -151,8 +163,9 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/Mailet.html#getMailetConfig()">getMailetConfig</A></B>()</CODE>
<BR>
- Returns a MailetConfig object, which contains initialization and
- startup parameters for this mailet.</TD>
+ Returns a MailetConfig object, which provides initialization parameters
+ and a <A HREF="../../../org/apache/mailet/MailetContext.html" title="interface in org.apache.mailet"><CODE>MailetContext</CODE></A> through which it can interact with the
+ mailet container.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -160,7 +173,7 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/Mailet.html#getMailetInfo()">getMailetInfo</A></B>()</CODE>
<BR>
- Returns information about the mailet, such as author, version, and
+ Returns information about the mailet, such as author, version and
copyright.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
@@ -169,8 +182,7 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/Mailet.html#init(org.apache.mailet.MailetConfig)">init</A></B>(<A HREF="../../../org/apache/mailet/MailetConfig.html" title="interface in org.apache.mailet">MailetConfig</A> config)</CODE>
<BR>
- Called by the mailet container to indicate to a mailet that the
- mailet is being placed into service.</TD>
+ Initializes this Mailet.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -178,8 +190,7 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/Mailet.html#service(org.apache.mailet.Mail)">service</A></B>(<A HREF="../../../org/apache/mailet/Mail.html" title="interface in org.apache.mailet">Mail</A> mail)</CODE>
<BR>
- Called by the mailet container to allow the mailet to process to
- a message.</TD>
+ Services a mail message.</TD>
</TR>
</TABLE>
@@ -195,111 +206,102 @@
</TR>
</TABLE>
-<A NAME="destroy()"><!-- --></A><H3>
-destroy</H3>
+<A NAME="init(org.apache.mailet.MailetConfig)"><!-- --></A><H3>
+init</H3>
<PRE>
-void <B>destroy</B>()</PRE>
+void <B>init</B>(<A HREF="../../../org/apache/mailet/MailetConfig.html" title="interface in org.apache.mailet">MailetConfig</A> config)
+ throws javax.mail.MessagingException</PRE>
<DL>
-<DD>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.
+<DD>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 <A HREF="../../../org/apache/mailet/Mailet.html#service(org.apache.mailet.Mail)"><CODE>service(org.apache.mailet.Mail)</CODE></A> method can be invoked.
<P>
<DD><DL>
-</DL>
+<DT><B>Parameters:</B><DD><CODE>config</CODE> - a MailetConfig containing the mailet's configuration
+ and initialization parameters
+<DT><B>Throws:</B>
+<DD><CODE>javax.mail.MessagingException</CODE> - if an error occurs</DL>
</DD>
</DL>
<HR>
-<A NAME="getMailetInfo()"><!-- --></A><H3>
-getMailetInfo</H3>
+<A NAME="service(org.apache.mailet.Mail)"><!-- --></A><H3>
+service</H3>
<PRE>
-java.lang.String <B>getMailetInfo</B>()</PRE>
+void <B>service</B>(<A HREF="../../../org/apache/mailet/Mail.html" title="interface in org.apache.mailet">Mail</A> mail)
+ throws javax.mail.MessagingException</PRE>
<DL>
-<DD>Returns information about the mailet, such as author, version, and
- copyright.
+<DD>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>.
<P>
<DD><DL>
-
-<DT><B>Returns:</B><DD>a String containing servlet information</DL>
+<DT><B>Parameters:</B><DD><CODE>mail</CODE> - the Mail to process
+<DT><B>Throws:</B>
+<DD><CODE>javax.mail.MessagingException</CODE> - if any error occurs which prevents the Mail
+ processing from completing successfully</DL>
</DD>
</DL>
<HR>
-<A NAME="getMailetConfig()"><!-- --></A><H3>
-getMailetConfig</H3>
+<A NAME="destroy()"><!-- --></A><H3>
+destroy</H3>
<PRE>
-<A HREF="../../../org/apache/mailet/MailetConfig.html" title="interface in org.apache.mailet">MailetConfig</A> <B>getMailetConfig</B>()</PRE>
+void <B>destroy</B>()</PRE>
<DL>
-<DD>Returns a MailetConfig object, which contains initialization and
- startup parameters for this mailet.
+<DD>Destroys this Mailet.
+ <p>
+ This method is called only once, after all <A HREF="../../../org/apache/mailet/Mailet.html#service(org.apache.mailet.Mail)"><CODE>service(org.apache.mailet.Mail)</CODE></A> invocations
+ have completed (or a timeout period has elapsed). After this method
+ returns, this Mailet will no longer be used.
<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.
+ 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>
<DD><DL>
-
-<DT><B>Returns:</B><DD>the MailetConfig object that initializes this mailet</DL>
+</DL>
</DD>
</DL>
<HR>
-<A NAME="init(org.apache.mailet.MailetConfig)"><!-- --></A><H3>
-init</H3>
+<A NAME="getMailetConfig()"><!-- --></A><H3>
+getMailetConfig</H3>
<PRE>
-void <B>init</B>(<A HREF="../../../org/apache/mailet/MailetConfig.html" title="interface in org.apache.mailet">MailetConfig</A> config)
- throws javax.mail.MessagingException</PRE>
+<A HREF="../../../org/apache/mailet/MailetConfig.html" title="interface in org.apache.mailet">MailetConfig</A> <B>getMailetConfig</B>()</PRE>
<DL>
-<DD>Called by the mailet container to indicate to a mailet that the
- mailet is being placed into service.
+<DD>Returns a MailetConfig object, which provides initialization parameters
+ and a <A HREF="../../../org/apache/mailet/MailetContext.html" title="interface in org.apache.mailet"><CODE>MailetContext</CODE></A> through which it can interact with the
+ mailet container.
<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.
+ Implementations of this interface are responsible for storing the
+ MailetConfig which they receive in the <A HREF="../../../org/apache/mailet/Mailet.html#init(org.apache.mailet.MailetConfig)"><CODE>init(org.apache.mailet.MailetConfig)</CODE></A> method so
+ that this method can return it.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>config</CODE> - - a MailetConfig object containing the mailet's configuration
- and initialization parameters
-<DT><B>Throws:</B>
-<DD><CODE>javax.mail.MessagingException</CODE> - - if an exception has occurred that interferes with
- the mailet's normal operation</DL>
+
+<DT><B>Returns:</B><DD>the MailetConfig that this mailet was initialized with</DL>
</DD>
</DL>
<HR>
-<A NAME="service(org.apache.mailet.Mail)"><!-- --></A><H3>
-service</H3>
+<A NAME="getMailetInfo()"><!-- --></A><H3>
+getMailetInfo</H3>
<PRE>
-void <B>service</B>(<A HREF="../../../org/apache/mailet/Mail.html" title="interface in org.apache.mailet">Mail</A> mail)
- throws javax.mail.MessagingException</PRE>
+java.lang.String <B>getMailetInfo</B>()</PRE>
<DL>
-<DD>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>.
+<DD>Returns information about the mailet, such as author, version and
+ copyright.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>mail</CODE> - - the Mail object that contains the message and routing information
-<DT><B>Throws:</B>
-<DD><CODE>javax.mail.MessagingException</CODE> - - if a message or address parsing exception occurs or
- an exception that interferes with the mailet's normal operation</DL>
+
+<DT><B>Returns:</B><DD>the Mailet information (as a plain text string)</DL>
</DD>
</DL>
<!-- ========= END OF CLASS DATA ========= -->
Modified: james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/MailetConfig.html
URL: http://svn.apache.org/viewvc/james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/MailetConfig.html?rev=800330&r1=800329&r2=800330&view=diff
==============================================================================
--- james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/MailetConfig.html (original)
+++ james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/MailetConfig.html Mon Aug 3 12:18:51 2009
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_18) on Thu May 28 11:11:01 BST 2009 -->
+<!-- Generated by javadoc (build 1.5.0_18) on Mon Aug 03 13:36:26 BST 2009 -->
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>
MailetConfig (Apache Mailet API 2.5-SNAPSHOT API)
@@ -94,19 +94,15 @@
</PRE>
<P>
-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.
<P>
<P>
-<DL>
-<DT><B>Version:</B></DT>
- <DD>1.0.0, 24/04/1999</DD>
-</DL>
<HR>
<P>
@@ -125,8 +121,8 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetConfig.html#getInitParameter(java.lang.String)">getInitParameter</A></B>(java.lang.String name)</CODE>
<BR>
- Returns a String containing the value of the named initialization
- parameter, or null if the parameter does not exist.</TD>
+ Returns the value of the named initialization parameter,
+ or null if the parameter does not exist.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -174,12 +170,12 @@
<PRE>
java.lang.String <B>getInitParameter</B>(java.lang.String name)</PRE>
<DL>
-<DD>Returns a String containing the value of the named initialization
- parameter, or null if the parameter does not exist.
+<DD>Returns the value of the named initialization parameter,
+ or null if the parameter does not exist.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>name</CODE> - - a String specifying the name of the initialization parameter
-<DT><B>Returns:</B><DD>a String containing the value of the initialization parameter</DL>
+<DT><B>Parameters:</B><DD><CODE>name</CODE> - the name of the initialization parameter
+<DT><B>Returns:</B><DD>the value of the initialization parameter, or null</DL>
</DD>
</DL>
<HR>
@@ -195,8 +191,8 @@
<P>
<DD><DL>
-<DT><B>Returns:</B><DD>an Iterator of String objects containing the names of the mailet's
- initialization parameters</DL>
+<DT><B>Returns:</B><DD>an Iterator of String objects containing the names of the
+ mailet's initialization parameters</DL>
</DD>
</DL>
<HR>
@@ -211,8 +207,8 @@
<P>
<DD><DL>
-<DT><B>Returns:</B><DD>a MailetContext object, used by the mailet to interact with its
- mailet container</DL>
+<DT><B>Returns:</B><DD>a MailetContext object which can be used by the mailet
+ to interact with the mailet container</DL>
</DD>
</DL>
<HR>
@@ -224,8 +220,8 @@
<DL>
<DD>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.
<P>
<DD><DL>
Modified: james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/MailetContext.html
URL: http://svn.apache.org/viewvc/james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/MailetContext.html?rev=800330&r1=800329&r2=800330&view=diff
==============================================================================
--- james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/MailetContext.html (original)
+++ james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/MailetContext.html Mon Aug 3 12:18:51 2009
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_18) on Thu May 28 11:11:01 BST 2009 -->
+<!-- Generated by javadoc (build 1.5.0_18) on Mon Aug 03 13:36:26 BST 2009 -->
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>
MailetContext (Apache Mailet API 2.5-SNAPSHOT API)
@@ -94,20 +94,34 @@
</PRE>
<P>
-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.
-
- 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.
+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 <A HREF="../../../org/apache/mailet/MailetContext.html#getAttributeNames()"><CODE>getAttributeNames()</CODE></A>
+ method, and given its name, the value of an attribute can be
+ retrieved using the <A HREF="../../../org/apache/mailet/MailetContext.html#getAttribute(java.lang.String)"><CODE>getAttribute(java.lang.String)</CODE></A> method.
<P>
<P>
-<DL>
-<DT><B>Version:</B></DT>
- <DD>1.0.0, 24/04/1999</DD>
-</DL>
<HR>
<P>
@@ -137,8 +151,7 @@
<A HREF="../../../org/apache/mailet/MailAddress.html" title="class in org.apache.mailet">MailAddress</A> bouncer)</CODE>
<BR>
- Bounces the email message using the provided email address as the
- sender of the bounce.</TD>
+ Bounces the message using a standard format with the given message.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -146,8 +159,8 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#getAttribute(java.lang.String)">getAttribute</A></B>(java.lang.String name)</CODE>
<BR>
- Returns the mailet container attribute with the given name, or null
- if there is no attribute by that name.</TD>
+ Returns the value of the named mailet context attribute,
+ or null if the attribute does not exist.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -155,17 +168,17 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#getAttributeNames()">getAttributeNames</A></B>()</CODE>
<BR>
- Returns an Iterator containing the attribute names available within
- this mailet context.</TD>
+ Returns an Iterator over the names of all attributes which are set
+ in this mailet context.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE> java.util.Collection</CODE></FONT></TD>
-<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#getMailServers(java.lang.String)">getMailServers</A></B>(java.lang.String host)</CODE>
+<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#getMailServers(java.lang.String)">getMailServers</A></B>(java.lang.String domain)</CODE>
<BR>
- Returns a Collection of Strings of hostnames or ip addresses that
- are specified as mail server listeners for the given hostname.</TD>
+ Returns the hostnames that are specified as mail handlers for
+ the given domain name.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -173,7 +186,7 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#getMajorVersion()">getMajorVersion</A></B>()</CODE>
<BR>
- Returns the major version of the Mailet API that this mailet
+ Returns the major version number of the Mailet API that this mailet
container supports.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
@@ -182,7 +195,7 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#getMinorVersion()">getMinorVersion</A></B>()</CODE>
<BR>
- Returns the minor version of the Mailet API that this mailet
+ Returns the minor version number of the Mailet API that this mailet
container supports.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
@@ -191,7 +204,7 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#getPostmaster()">getPostmaster</A></B>()</CODE>
<BR>
- Returns the postmaster's address for this mailet context.</TD>
+ Returns the Postmaster address for this mailet context.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -205,13 +218,11 @@
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE> java.util.Iterator</CODE></FONT></TD>
-<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#getSMTPHostAddresses(java.lang.String)">getSMTPHostAddresses</A></B>(java.lang.String domainName)</CODE>
+<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#getSMTPHostAddresses(java.lang.String)">getSMTPHostAddresses</A></B>(java.lang.String domain)</CODE>
<BR>
- 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.</TD>
+ Returns the SMTP host addresses specified as mail handlers for
+ the given domain name.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -219,15 +230,15 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#isLocalEmail(org.apache.mailet.MailAddress)">isLocalEmail</A></B>(<A HREF="../../../org/apache/mailet/MailAddress.html" title="class in org.apache.mailet">MailAddress</A> mailAddress)</CODE>
<BR>
- Checks if a user account is exists in the mail context.</TD>
+ Checks if an address is local, i.e.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE> boolean</CODE></FONT></TD>
-<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#isLocalServer(java.lang.String)">isLocalServer</A></B>(java.lang.String serverName)</CODE>
+<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#isLocalServer(java.lang.String)">isLocalServer</A></B>(java.lang.String hostname)</CODE>
<BR>
- Checks if a server is serviced by mail context</TD>
+ Checks if a host name is local, i.e.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -235,7 +246,7 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#isLocalUser(java.lang.String)">isLocalUser</A></B>(java.lang.String userAccount)</CODE>
<BR>
- <B>Deprecated.</B> <I>use isLocalEmail(MailAddress) instead</I></TD>
+ <B>Deprecated.</B> <I>use <A HREF="../../../org/apache/mailet/MailetContext.html#isLocalEmail(org.apache.mailet.MailAddress)"><CODE>isLocalEmail(MailAddress)</CODE></A> instead</I></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -243,8 +254,7 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#log(java.lang.String)">log</A></B>(java.lang.String message)</CODE>
<BR>
- Writes the specified message to a mailet log file, usually an event
- log.</TD>
+ Writes the specified message to a mailet log.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -253,8 +263,8 @@
java.lang.Throwable t)</CODE>
<BR>
- Writes an explanatory message and a stack trace for a given Throwable
- exception to the mailet log file.</TD>
+ Writes the specified message to a mailet log, along with the stack
+ trace of the given Throwable.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -262,7 +272,7 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#removeAttribute(java.lang.String)">removeAttribute</A></B>(java.lang.String name)</CODE>
<BR>
- Removes the attribute with the given name from the mailet context.</TD>
+ Removes the attribute with the given name from this Mail instance.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -270,53 +280,53 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#sendMail(org.apache.mailet.Mail)">sendMail</A></B>(<A HREF="../../../org/apache/mailet/Mail.html" title="interface in org.apache.mailet">Mail</A> mail)</CODE>
<BR>
- Send an outgoing message to the top of this mailet container's root queue.</TD>
+ Sends an outgoing message to the top of this mailet container's root queue.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE> void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#sendMail(org.apache.mailet.MailAddress, java.util.Collection, javax.mail.internet.MimeMessage)">sendMail</A></B>(<A HREF="../../../org/apache/mailet/MailAddress.html" title="class in org.apache.mailet">MailAddress</A> sender,
java.util.Collection recipients,
- javax.mail.internet.MimeMessage msg)</CODE>
+ javax.mail.internet.MimeMessage message)</CODE>
<BR>
- Send an outgoing message to the top of this mailet container's root queue.</TD>
+ Sends an outgoing message to the top of this mailet container's root queue.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE> void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#sendMail(org.apache.mailet.MailAddress, java.util.Collection, javax.mail.internet.MimeMessage, java.lang.String)">sendMail</A></B>(<A HREF="../../../org/apache/mailet/MailAddress.html" title="class in org.apache.mailet">MailAddress</A> sender,
java.util.Collection recipients,
- javax.mail.internet.MimeMessage msg,
+ javax.mail.internet.MimeMessage message,
java.lang.String state)</CODE>
<BR>
- Send an outgoing message to the top of this mailet container queue for the
- appropriate processor that is specified.</TD>
+ Sends an outgoing message to the top of this mailet container's queue for the
+ specified processor.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE> void</CODE></FONT></TD>
-<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#sendMail(javax.mail.internet.MimeMessage)">sendMail</A></B>(javax.mail.internet.MimeMessage msg)</CODE>
+<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#sendMail(javax.mail.internet.MimeMessage)">sendMail</A></B>(javax.mail.internet.MimeMessage message)</CODE>
<BR>
- Send an outgoing message to the top of this mailet container's root queue.</TD>
+ Sends an outgoing message to the top of this mailet container's root queue.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE> void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#setAttribute(java.lang.String, java.lang.Object)">setAttribute</A></B>(java.lang.String name,
- java.lang.Object object)</CODE>
+ java.lang.Object value)</CODE>
<BR>
- Binds an object to a given attribute name in this mailet context.</TD>
+ Associates an attribute with the given name and value with this mailet context.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE> void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../org/apache/mailet/MailetContext.html#storeMail(org.apache.mailet.MailAddress, org.apache.mailet.MailAddress, javax.mail.internet.MimeMessage)">storeMail</A></B>(<A HREF="../../../org/apache/mailet/MailAddress.html" title="class in org.apache.mailet">MailAddress</A> sender,
<A HREF="../../../org/apache/mailet/MailAddress.html" title="class in org.apache.mailet">MailAddress</A> recipient,
- javax.mail.internet.MimeMessage msg)</CODE>
+ javax.mail.internet.MimeMessage message)</CODE>
<BR>
<B>Deprecated.</B> <I>- use sparingly. Service will be replaced with
@@ -336,74 +346,72 @@
</TR>
</TABLE>
-<A NAME="bounce(org.apache.mailet.Mail, java.lang.String)"><!-- --></A><H3>
-bounce</H3>
+<A NAME="getMajorVersion()"><!-- --></A><H3>
+getMajorVersion</H3>
<PRE>
-void <B>bounce</B>(<A HREF="../../../org/apache/mailet/Mail.html" title="interface in org.apache.mailet">Mail</A> mail,
- java.lang.String message)
- throws javax.mail.MessagingException</PRE>
+int <B>getMajorVersion</B>()</PRE>
<DL>
-<DD>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().
+<DD>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.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>mail</CODE> - - the message that is to be bounced and sender to whom to return the message<DD><CODE>message</CODE> - - a descriptive message as to why the message bounced
-<DT><B>Throws:</B>
-<DD><CODE>javax.mail.MessagingException</CODE></DL>
+
+<DT><B>Returns:</B><DD>the major version number of the supported Mailet API</DL>
</DD>
</DL>
<HR>
-<A NAME="bounce(org.apache.mailet.Mail, java.lang.String, org.apache.mailet.MailAddress)"><!-- --></A><H3>
-bounce</H3>
+<A NAME="getMinorVersion()"><!-- --></A><H3>
+getMinorVersion</H3>
<PRE>
-void <B>bounce</B>(<A HREF="../../../org/apache/mailet/Mail.html" title="interface in org.apache.mailet">Mail</A> mail,
- java.lang.String message,
- <A HREF="../../../org/apache/mailet/MailAddress.html" title="class in org.apache.mailet">MailAddress</A> bouncer)
- throws javax.mail.MessagingException</PRE>
+int <B>getMinorVersion</B>()</PRE>
<DL>
-<DD>Bounces the email message using the provided email address as the
- sender of the bounce.
+<DD>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.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>mail</CODE> - - the message that is to be bounced and sender to whom to return the message<DD><CODE>message</CODE> - - a descriptive message as to why the message bounced<DD><CODE>bouncer</CODE> - - the address to give as the sender of the bounced message
-<DT><B>Throws:</B>
-<DD><CODE>javax.mail.MessagingException</CODE></DL>
+
+<DT><B>Returns:</B><DD>the minor version number of the supported Mailet API</DL>
</DD>
</DL>
<HR>
-<A NAME="getMailServers(java.lang.String)"><!-- --></A><H3>
-getMailServers</H3>
+<A NAME="getServerInfo()"><!-- --></A><H3>
+getServerInfo</H3>
<PRE>
-java.util.Collection <B>getMailServers</B>(java.lang.String host)</PRE>
+java.lang.String <B>getServerInfo</B>()</PRE>
<DL>
-<DD>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.
-
- <p>TODO: This needs to be made a more specific ordered subtype of Collection.</p>
+<DD>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></code>,
+ optionally followed by additional information in parentheses. For example,
+ the JAMES mailet container may return the string <code>"JAMES/1.2"</code>
+ or <code>"JAMES/1.2 (JDK 1.3.0; Windows NT 4.0 x86)"</code>.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>host</CODE> - - the domain name for which to find mail servers
-<DT><B>Returns:</B><DD>a Collection of Strings of hostnames, sorted by priority</DL>
+
+<DT><B>Returns:</B><DD>the server information string</DL>
</DD>
</DL>
<HR>
-<A NAME="getPostmaster()"><!-- --></A><H3>
-getPostmaster</H3>
+<A NAME="getAttributeNames()"><!-- --></A><H3>
+getAttributeNames</H3>
<PRE>
-<A HREF="../../../org/apache/mailet/MailAddress.html" title="class in org.apache.mailet">MailAddress</A> <B>getPostmaster</B>()</PRE>
+java.util.Iterator <B>getAttributeNames</B>()</PRE>
<DL>
-<DD>Returns the postmaster's address for this mailet context.
+<DD>Returns an Iterator over the names of all attributes which are set
+ in this mailet context.
+ <p>
+ The <A HREF="../../../org/apache/mailet/MailetContext.html#getAttribute(java.lang.String)"><CODE>getAttribute(java.lang.String)</CODE></A> method can be called to
+ retrieve an attribute's value given its name.
<P>
<DD><DL>
-<DT><B>Returns:</B><DD>a MailAddress of the Postmaster's address</DL>
+<DT><B>Returns:</B><DD>an Iterator (of Strings) over all attribute names</DL>
</DD>
</DL>
<HR>
@@ -413,89 +421,92 @@
<PRE>
java.lang.Object <B>getAttribute</B>(java.lang.String name)</PRE>
<DL>
-<DD>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.*
+<DD>Returns the value of the named mailet context attribute,
+ or null if the attribute does not exist.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>name</CODE> - - a String specifying the name of the attribute
-<DT><B>Returns:</B><DD>an Object containing the value of the attribute, or null if no attribute
- exists matching the given name</DL>
+<DT><B>Parameters:</B><DD><CODE>name</CODE> - the attribute name
+<DT><B>Returns:</B><DD>the attribute value, or null if the attribute does not exist</DL>
</DD>
</DL>
<HR>
-<A NAME="getAttributeNames()"><!-- --></A><H3>
-getAttributeNames</H3>
+<A NAME="setAttribute(java.lang.String, java.lang.Object)"><!-- --></A><H3>
+setAttribute</H3>
<PRE>
-java.util.Iterator <B>getAttributeNames</B>()</PRE>
+void <B>setAttribute</B>(java.lang.String name,
+ java.lang.Object value)</PRE>
<DL>
-<DD>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.
+<DD>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>.
<P>
<DD><DL>
-
-<DT><B>Returns:</B><DD>an Iterator of attribute names</DL>
+<DT><B>Parameters:</B><DD><CODE>name</CODE> - the attribute name<DD><CODE>value</CODE> - the attribute value</DL>
</DD>
</DL>
<HR>
-<A NAME="getMajorVersion()"><!-- --></A><H3>
-getMajorVersion</H3>
+<A NAME="removeAttribute(java.lang.String)"><!-- --></A><H3>
+removeAttribute</H3>
<PRE>
-int <B>getMajorVersion</B>()</PRE>
+void <B>removeAttribute</B>(java.lang.String name)</PRE>
<DL>
-<DD>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.
+<DD>Removes the attribute with the given name from this Mail instance.
<P>
<DD><DL>
-
-<DT><B>Returns:</B><DD>1</DL>
+<DT><B>Parameters:</B><DD><CODE>name</CODE> - the name of the attribute to be removed<DT><B>Since:</B></DT>
+ <DD>Mailet API v2.1</DD>
+</DL>
</DD>
</DL>
<HR>
-<A NAME="getMinorVersion()"><!-- --></A><H3>
-getMinorVersion</H3>
+<A NAME="log(java.lang.String)"><!-- --></A><H3>
+log</H3>
<PRE>
-int <B>getMinorVersion</B>()</PRE>
+void <B>log</B>(java.lang.String message)</PRE>
<DL>
-<DD>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.
+<DD>Writes the specified message to a mailet log. The name and type of
+ the mailet log is specific to the mailet container.
<P>
<DD><DL>
+<DT><B>Parameters:</B><DD><CODE>message</CODE> - the message to be written to the log</DL>
+</DD>
+</DL>
+<HR>
-<DT><B>Returns:</B><DD>2</DL>
+<A NAME="log(java.lang.String, java.lang.Throwable)"><!-- --></A><H3>
+log</H3>
+<PRE>
+void <B>log</B>(java.lang.String message,
+ java.lang.Throwable t)</PRE>
+<DL>
+<DD>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.
+<P>
+<DD><DL>
+<DT><B>Parameters:</B><DD><CODE>message</CODE> - the message to be written to the log<DD><CODE>t</CODE> - the Throwable whose stack trace is to be written to the log</DL>
</DD>
</DL>
<HR>
-<A NAME="getServerInfo()"><!-- --></A><H3>
-getServerInfo</H3>
+<A NAME="getPostmaster()"><!-- --></A><H3>
+getPostmaster</H3>
<PRE>
-java.lang.String <B>getServerInfo</B>()</PRE>
+<A HREF="../../../org/apache/mailet/MailAddress.html" title="class in org.apache.mailet">MailAddress</A> <B>getPostmaster</B>()</PRE>
<DL>
-<DD>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).
+<DD>Returns the Postmaster address for this mailet context.
<P>
<DD><DL>
-<DT><B>Returns:</B><DD>a String containing at least the mailet container name and version number</DL>
+<DT><B>Returns:</B><DD>the Postmaster address</DL>
</DD>
</DL>
<HR>
@@ -503,13 +514,14 @@
<A NAME="isLocalServer(java.lang.String)"><!-- --></A><H3>
isLocalServer</H3>
<PRE>
-boolean <B>isLocalServer</B>(java.lang.String serverName)</PRE>
+boolean <B>isLocalServer</B>(java.lang.String hostname)</PRE>
<DL>
-<DD>Checks if a server is serviced by mail context
+<DD>Checks if a host name is local, i.e. this server is the
+ final delivery destination for messages sent to this host.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>serverName</CODE> - - name of server.
-<DT><B>Returns:</B><DD>true if server is local, i.e. serviced by this mail context</DL>
+<DT><B>Parameters:</B><DD><CODE>hostname</CODE> - the host name to check
+<DT><B>Returns:</B><DD>true if server is local, false otherwise</DL>
</DD>
</DL>
<HR>
@@ -519,17 +531,19 @@
<PRE>
boolean <B>isLocalUser</B>(java.lang.String userAccount)</PRE>
<DL>
-<DD><B>Deprecated.</B> <I>use isLocalEmail(MailAddress) instead</I>
+<DD><B>Deprecated.</B> <I>use <A HREF="../../../org/apache/mailet/MailetContext.html#isLocalEmail(org.apache.mailet.MailAddress)"><CODE>isLocalEmail(MailAddress)</CODE></A> instead</I>
<P>
-<DD>Checks if a user account is exists in the mail context.
+<DD>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.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>userAccount</CODE> - - user identifier.
-<DT><B>Returns:</B><DD>true if the account is a local account<DT><B>Since:</B></DT>
- <DD>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.</DD>
-</DL>
+<DT><B>Parameters:</B><DD><CODE>userAccount</CODE> - the full address of the account to be checked
+<DT><B>Returns:</B><DD>true if the account is a local account, false otherwise</DL>
</DD>
</DL>
<HR>
@@ -539,58 +553,54 @@
<PRE>
boolean <B>isLocalEmail</B>(<A HREF="../../../org/apache/mailet/MailAddress.html" title="class in org.apache.mailet">MailAddress</A> mailAddress)</PRE>
<DL>
-<DD>Checks if a user account is exists in the mail context.
+<DD>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.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>mailAddress</CODE> - - address of the account to be checked.
-<DT><B>Returns:</B><DD>true if the account is a local account<DT><B>Since:</B></DT>
- <DD>James 2.4.0</DD>
+<DT><B>Parameters:</B><DD><CODE>mailAddress</CODE> - the full address of the account to be checked
+<DT><B>Returns:</B><DD>true if the account is a local account, false otherwise<DT><B>Since:</B></DT>
+ <DD>Mailet API 2.4</DD>
</DL>
</DD>
</DL>
<HR>
-<A NAME="log(java.lang.String)"><!-- --></A><H3>
-log</H3>
+<A NAME="getMailServers(java.lang.String)"><!-- --></A><H3>
+getMailServers</H3>
<PRE>
-void <B>log</B>(java.lang.String message)</PRE>
+java.util.Collection <B>getMailServers</B>(java.lang.String domain)</PRE>
<DL>
-<DD>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.
+<DD>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).
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>message</CODE> - - a String specifying the message to be written to the log file</DL>
+<DT><B>Parameters:</B><DD><CODE>domain</CODE> - the domain name whose mail handling hosts are requested
+<DT><B>Returns:</B><DD>the sorted mail-handling hostnames for the domain</DL>
</DD>
</DL>
<HR>
-<A NAME="log(java.lang.String, java.lang.Throwable)"><!-- --></A><H3>
-log</H3>
+<A NAME="getSMTPHostAddresses(java.lang.String)"><!-- --></A><H3>
+getSMTPHostAddresses</H3>
<PRE>
-void <B>log</B>(java.lang.String message,
- java.lang.Throwable t)</PRE>
+java.util.Iterator <B>getSMTPHostAddresses</B>(java.lang.String domain)</PRE>
<DL>
-<DD>Writes an explanatory message and a stack trace for a given Throwable
- exception to the mailet log file.
+<DD>Returns the SMTP host addresses specified as mail handlers for
+ the given domain name. This is equivalent to calling the
+ <A HREF="../../../org/apache/mailet/MailetContext.html#getMailServers(java.lang.String)"><CODE>getMailServers(java.lang.String)</CODE></A> method and then performing address
+ resolution lookups on all returned host names in order.
+ The results are returned as instances of <A HREF="../../../org/apache/mailet/HostAddress.html" title="class in org.apache.mailet"><CODE>HostAddress</CODE></A>
+ containing the host and address information.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>message</CODE> - - a String that describes the error or exception<DD><CODE>t</CODE> - - the Throwable error or exception</DL>
-</DD>
+<DT><B>Parameters:</B><DD><CODE>domain</CODE> - the domain whose mail handling SMTP host addresses are requested
+<DT><B>Returns:</B><DD>an Iterator over HostAddress, in proper order of priority, or
+ an empty iterator if no hosts are found<DT><B>Since:</B></DT>
+ <DD>Mailet API v2.3</DD>
</DL>
-<HR>
-
-<A NAME="removeAttribute(java.lang.String)"><!-- --></A><H3>
-removeAttribute</H3>
-<PRE>
-void <B>removeAttribute</B>(java.lang.String name)</PRE>
-<DL>
-<DD>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.
-<P>
-<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>name</CODE> - - a String specifying the name of the attribute to be removed</DL>
</DD>
</DL>
<HR>
@@ -598,17 +608,18 @@
<A NAME="sendMail(javax.mail.internet.MimeMessage)"><!-- --></A><H3>
sendMail</H3>
<PRE>
-void <B>sendMail</B>(javax.mail.internet.MimeMessage msg)
+void <B>sendMail</B>(javax.mail.internet.MimeMessage message)
throws javax.mail.MessagingException</PRE>
<DL>
-<DD>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.
+<DD>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.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>msg</CODE> - - the MimeMessage of the headers and body content of the outgoing message
+<DT><B>Parameters:</B><DD><CODE>message</CODE> - the message to send
<DT><B>Throws:</B>
-<DD><CODE>javax.mail.MessagingException</CODE> - - if the message fails to parse</DL>
+<DD><CODE>javax.mail.MessagingException</CODE> - if an error occurs accessing or sending the message</DL>
</DD>
</DL>
<HR>
@@ -618,16 +629,17 @@
<PRE>
void <B>sendMail</B>(<A HREF="../../../org/apache/mailet/MailAddress.html" title="class in org.apache.mailet">MailAddress</A> sender,
java.util.Collection recipients,
- javax.mail.internet.MimeMessage msg)
+ javax.mail.internet.MimeMessage message)
throws javax.mail.MessagingException</PRE>
<DL>
-<DD>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.
+<DD>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.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>sender</CODE> - - the sender of the message<DD><CODE>recipients</CODE> - - a Collection of MailAddress objects of recipients<DD><CODE>msg</CODE> - - the MimeMessage of the headers and body content of the outgoing message
+<DT><B>Parameters:</B><DD><CODE>sender</CODE> - the message sender<DD><CODE>recipients</CODE> - the message recipients as a Collection of MailAddress objects<DD><CODE>message</CODE> - the message to send
<DT><B>Throws:</B>
-<DD><CODE>javax.mail.MessagingException</CODE> - - if the message fails to parse</DL>
+<DD><CODE>javax.mail.MessagingException</CODE> - if an error occurs accessing or sending the message</DL>
</DD>
</DL>
<HR>
@@ -637,18 +649,18 @@
<PRE>
void <B>sendMail</B>(<A HREF="../../../org/apache/mailet/MailAddress.html" title="class in org.apache.mailet">MailAddress</A> sender,
java.util.Collection recipients,
- javax.mail.internet.MimeMessage msg,
+ javax.mail.internet.MimeMessage message,
java.lang.String state)
throws javax.mail.MessagingException</PRE>
<DL>
-<DD>Send an outgoing message to the top of this mailet container queue for the
- appropriate processor that is specified.
+<DD>Sends an outgoing message to the top of this mailet container's queue for the
+ specified processor.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>sender</CODE> - - the sender of the message<DD><CODE>recipients</CODE> - - a Collection of MailAddress objects of recipients<DD><CODE>msg</CODE> - - the MimeMessage of the headers and body content of the outgoing message<DD><CODE>state</CODE> - - 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
+<DT><B>Parameters:</B><DD><CODE>sender</CODE> - the message sender<DD><CODE>recipients</CODE> - the message recipients as a Collection of MailAddress objects<DD><CODE>message</CODE> - the message to send<DD><CODE>state</CODE> - the state of the message, indicating the name of the processor for
+ which the message will be queued
<DT><B>Throws:</B>
-<DD><CODE>javax.mail.MessagingException</CODE> - - if the message fails to parse</DL>
+<DD><CODE>javax.mail.MessagingException</CODE> - if an error occurs accessing or sending the message</DL>
</DD>
</DL>
<HR>
@@ -659,33 +671,56 @@
void <B>sendMail</B>(<A HREF="../../../org/apache/mailet/Mail.html" title="interface in org.apache.mailet">Mail</A> mail)
throws javax.mail.MessagingException</PRE>
<DL>
-<DD>Send an outgoing message to the top of this mailet container's root queue.
+<DD>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
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>mail</CODE> - - the message that is to sent
<DT><B>Throws:</B>
-<DD><CODE>javax.mail.MessagingException</CODE> - - if the message fails to spool</DL>
+<DD><CODE>javax.mail.MessagingException</CODE> - if an error occurs accessing or sending the message</DL>
</DD>
</DL>
<HR>
-<A NAME="setAttribute(java.lang.String, java.lang.Object)"><!-- --></A><H3>
-setAttribute</H3>
+<A NAME="bounce(org.apache.mailet.Mail, java.lang.String)"><!-- --></A><H3>
+bounce</H3>
<PRE>
-void <B>setAttribute</B>(java.lang.String name,
- java.lang.Object object)</PRE>
+void <B>bounce</B>(<A HREF="../../../org/apache/mailet/Mail.html" title="interface in org.apache.mailet">Mail</A> mail,
+ java.lang.String message)
+ throws javax.mail.MessagingException</PRE>
<DL>
-<DD>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.
+<DD>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 postmaster address
+ as configured in this mailet context, adding the message to top of mail
+ server queue using <code>sendMail</code>.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>name</CODE> - - a String specifying the name of the attribute<DD><CODE>object</CODE> - - an Object representing the attribute to be bound</DL>
+<DT><B>Parameters:</B><DD><CODE>mail</CODE> - the message to bounce, with the original sender<DD><CODE>message</CODE> - a descriptive message explaining why the message bounced
+<DT><B>Throws:</B>
+<DD><CODE>javax.mail.MessagingException</CODE> - if an error occurs accessing or sending the message</DL>
+</DD>
+</DL>
+<HR>
+
+<A NAME="bounce(org.apache.mailet.Mail, java.lang.String, org.apache.mailet.MailAddress)"><!-- --></A><H3>
+bounce</H3>
+<PRE>
+void <B>bounce</B>(<A HREF="../../../org/apache/mailet/Mail.html" title="interface in org.apache.mailet">Mail</A> mail,
+ java.lang.String message,
+ <A HREF="../../../org/apache/mailet/MailAddress.html" title="class in org.apache.mailet">MailAddress</A> bouncer)
+ throws javax.mail.MessagingException</PRE>
+<DL>
+<DD>Bounces the message using a standard format with the given message.
+ <p>
+ 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</code>.
+<P>
+<DD><DL>
+<DT><B>Parameters:</B><DD><CODE>mail</CODE> - the message to bounce, with the original sender<DD><CODE>message</CODE> - a descriptive message explaining why the message bounced<DD><CODE>bouncer</CODE> - the address used as the sender of the bounce message
+<DT><B>Throws:</B>
+<DD><CODE>javax.mail.MessagingException</CODE> - if an error occurs accessing or sending the message</DL>
</DD>
</DL>
<HR>
@@ -695,7 +730,7 @@
<PRE>
void <B>storeMail</B>(<A HREF="../../../org/apache/mailet/MailAddress.html" title="class in org.apache.mailet">MailAddress</A> sender,
<A HREF="../../../org/apache/mailet/MailAddress.html" title="class in org.apache.mailet">MailAddress</A> recipient,
- javax.mail.internet.MimeMessage msg)
+ javax.mail.internet.MimeMessage message)
throws javax.mail.MessagingException</PRE>
<DL>
<DD><B>Deprecated.</B> <I>- use sparingly. Service will be replaced with
@@ -705,33 +740,11 @@
recipient for later retrieval, e.g., by a POP3 or IMAP service.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>sender</CODE> - - the sender of the incoming message<DD><CODE>recipient</CODE> - - the user who is receiving this message (as a complete email address)<DD><CODE>msg</CODE> - - the MimeMessage to store in a local mailbox
+<DT><B>Parameters:</B><DD><CODE>sender</CODE> - - the sender of the incoming message<DD><CODE>recipient</CODE> - - the user who is receiving this message (as a complete email address)<DD><CODE>message</CODE> - - the MimeMessage to store in a local mailbox
<DT><B>Throws:</B>
<DD><CODE>javax.mail.MessagingException</CODE> - - if the message fails to parse</DL>
</DD>
</DL>
-<HR>
-
-<A NAME="getSMTPHostAddresses(java.lang.String)"><!-- --></A><H3>
-getSMTPHostAddresses</H3>
-<PRE>
-java.util.Iterator <B>getSMTPHostAddresses</B>(java.lang.String domainName)</PRE>
-<DL>
-<DD>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.
-<P>
-<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>domainName</CODE> - - the domain for which to find mail servers
-<DT><B>Returns:</B><DD>an Iterator over HostAddress instances, sorted by priority<DT><B>Since:</B></DT>
- <DD>Mailet API v2.2.0a16-unstable</DD>
-</DL>
-</DD>
-</DL>
<!-- ========= END OF CLASS DATA ========= -->
<HR>
Modified: james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/MailetException.html
URL: http://svn.apache.org/viewvc/james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/MailetException.html?rev=800330&r1=800329&r2=800330&view=diff
==============================================================================
--- james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/MailetException.html (original)
+++ james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/MailetException.html Mon Aug 3 12:18:51 2009
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_18) on Thu May 28 11:11:01 BST 2009 -->
+<!-- Generated by javadoc (build 1.5.0_18) on Mon Aug 03 13:36:26 BST 2009 -->
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>
MailetException (Apache Mailet API 2.5-SNAPSHOT API)
@@ -109,8 +109,6 @@
<P>
<DL>
-<DT><B>Version:</B></DT>
- <DD>1.0.0, 24/04/1999</DD>
<DT><B>See Also:</B><DD><A HREF="../../../serialized-form.html#org.apache.mailet.MailetException">Serialized Form</A></DL>
<HR>
@@ -141,10 +139,8 @@
java.lang.Exception e)</CODE>
<BR>
- 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.</TD>
+ Constructs a new mailet exception with the specified message
+ and an exception which is the "root cause" of the exception.</TD>
</TR>
</TABLE>
@@ -223,10 +219,8 @@
public <B>MailetException</B>(java.lang.String message,
java.lang.Exception e)</PRE>
<DL>
-<DD>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.
+<DD>Constructs a new mailet exception with the specified message
+ and an exception which is the "root cause" of the exception.
<P>
</DL>
<!-- ========= END OF CLASS DATA ========= -->
Modified: james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/Matcher.html
URL: http://svn.apache.org/viewvc/james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/Matcher.html?rev=800330&r1=800329&r2=800330&view=diff
==============================================================================
--- james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/Matcher.html (original)
+++ james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/Matcher.html Mon Aug 3 12:18:51 2009
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_18) on Thu May 28 11:11:02 BST 2009 -->
+<!-- Generated by javadoc (build 1.5.0_18) on Mon Aug 03 13:36:26 BST 2009 -->
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>
Matcher (Apache Mailet API 2.5-SNAPSHOT API)
@@ -94,52 +94,39 @@
</PRE>
<P>
-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 <A HREF="../../../org/apache/mailet/Matcher.html#match(org.apache.mailet.Mail)"><CODE>match(Mail)</CODE></A> 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 <A HREF="../../../org/apache/mailet/Matcher.html#init(org.apache.mailet.MatcherConfig)"><CODE>init(org.apache.mailet.MatcherConfig)</CODE></A> method is invoked once to initialize the matcher.
+ <li>The <A HREF="../../../org/apache/mailet/Matcher.html#match(org.apache.mailet.Mail)"><CODE>match(org.apache.mailet.Mail)</CODE></A> 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 <A HREF="../../../org/apache/mailet/Matcher.html#destroy()"><CODE>destroy()</CODE></A> 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.
+ <A HREF="../../../org/apache/mailet/Matcher.html#getMatcherConfig()"><CODE>getMatcherConfig()</CODE></A> method, which provides the Matcher with
+ its configuration information and a <A HREF="../../../org/apache/mailet/MailetContext.html" title="interface in org.apache.mailet"><CODE>MailetContext</CODE></A> through which
+ it can interact with the mailet container, and the <A HREF="../../../org/apache/mailet/Matcher.html#getMatcherInfo()"><CODE>getMatcherInfo()</CODE></A>
+ method, which provides basic information about the Matcher.
<P>
<P>
-<DL>
-<DT><B>Version:</B></DT>
- <DD>1.0.0, 24/04/1999</DD>
-</DL>
<HR>
<P>
@@ -158,8 +145,7 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/Matcher.html#destroy()">destroy</A></B>()</CODE>
<BR>
- Called by the mailet container to indicate to a matcher that the matcher
- is being taken out of service.</TD>
+ Destroys this Matcher.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -167,8 +153,9 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/Matcher.html#getMatcherConfig()">getMatcherConfig</A></B>()</CODE>
<BR>
- Returns a MatcherConfig object, which contains initialization and
- startup parameters for this matcher.</TD>
+ Returns a MatcherConfig object, which provides initialization parameters
+ and a <A HREF="../../../org/apache/mailet/MailetContext.html" title="interface in org.apache.mailet"><CODE>MailetContext</CODE></A> through which it can interact with the
+ mailet container.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -176,7 +163,8 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/Matcher.html#getMatcherInfo()">getMatcherInfo</A></B>()</CODE>
<BR>
- Returns information about the matcher, such as author, version, and copyright.</TD>
+ Returns information about the matcher, such as author, version and
+ copyright.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -184,8 +172,7 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/Matcher.html#init(org.apache.mailet.MatcherConfig)">init</A></B>(<A HREF="../../../org/apache/mailet/MatcherConfig.html" title="interface in org.apache.mailet">MatcherConfig</A> config)</CODE>
<BR>
- Called by the mailet container to indicate to a matcher that the
- matcher is being placed into service.</TD>
+ Initializes this Matcher.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -193,8 +180,8 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/Matcher.html#match(org.apache.mailet.Mail)">match</A></B>(<A HREF="../../../org/apache/mailet/Mail.html" title="interface in org.apache.mailet">Mail</A> mail)</CODE>
<BR>
- Takes a Mail message, looks at any pertinent information, and then returns a subset
- of recipients that meet the "match" conditions.</TD>
+ Takes a Mail message, looks at any pertinent information, and returns
+ a subset of recipients that meet the match conditions.</TD>
</TR>
</TABLE>
@@ -210,111 +197,107 @@
</TR>
</TABLE>
-<A NAME="destroy()"><!-- --></A><H3>
-destroy</H3>
+<A NAME="init(org.apache.mailet.MatcherConfig)"><!-- --></A><H3>
+init</H3>
<PRE>
-void <B>destroy</B>()</PRE>
+void <B>init</B>(<A HREF="../../../org/apache/mailet/MatcherConfig.html" title="interface in org.apache.mailet">MatcherConfig</A> config)
+ throws javax.mail.MessagingException</PRE>
<DL>
-<DD>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.
+<DD>Initializes 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.
+ This method is called only once, and must complete successfully
+ before the <A HREF="../../../org/apache/mailet/Matcher.html#match(org.apache.mailet.Mail)"><CODE>match(org.apache.mailet.Mail)</CODE></A> method can be invoked.
<P>
<DD><DL>
-</DL>
+<DT><B>Parameters:</B><DD><CODE>config</CODE> - a MatcherConfig containing the matcher's configuration
+ and initialization parameters
+<DT><B>Throws:</B>
+<DD><CODE>javax.mail.MessagingException</CODE> - if an error occurs</DL>
</DD>
</DL>
<HR>
-<A NAME="getMatcherConfig()"><!-- --></A><H3>
-getMatcherConfig</H3>
+<A NAME="match(org.apache.mailet.Mail)"><!-- --></A><H3>
+match</H3>
<PRE>
-<A HREF="../../../org/apache/mailet/MatcherConfig.html" title="interface in org.apache.mailet">MatcherConfig</A> <B>getMatcherConfig</B>()</PRE>
+java.util.Collection <B>match</B>(<A HREF="../../../org/apache/mailet/Mail.html" title="interface in org.apache.mailet">Mail</A> mail)
+ throws javax.mail.MessagingException</PRE>
<DL>
-<DD>Returns a MatcherConfig object, which contains initialization and
- startup parameters for this matcher.
+<DD>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>.
<P>
<DD><DL>
-
-<DT><B>Returns:</B><DD>the MatcherConfig object that initializes this matcher</DL>
+<DT><B>Parameters:</B><DD><CODE>mail</CODE> - the Mail to match
+<DT><B>Returns:</B><DD>the recipients that meet the match criteria as a Collection of String objects
+<DT><B>Throws:</B>
+<DD><CODE>javax.mail.MessagingException</CODE> - if any error occurs which prevents the Mail
+ matching from completing successfully</DL>
</DD>
</DL>
<HR>
-<A NAME="getMatcherInfo()"><!-- --></A><H3>
-getMatcherInfo</H3>
+<A NAME="destroy()"><!-- --></A><H3>
+destroy</H3>
<PRE>
-java.lang.String <B>getMatcherInfo</B>()</PRE>
+void <B>destroy</B>()</PRE>
<DL>
-<DD>Returns information about the matcher, such as author, version, and copyright.
+<DD>Destroys this Matcher.
+ <p>
+ This method is called only once, after all <A HREF="../../../org/apache/mailet/Matcher.html#match(org.apache.mailet.Mail)"><CODE>match(org.apache.mailet.Mail)</CODE></A> 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>
- The string that this method returns should be plain text and not markup
- of any kind (such as HTML, XML, etc.).
+ Note that containers <code>SHOULD NOT</code> invoke this method before
+ <A HREF="../../../org/apache/mailet/Matcher.html#init(org.apache.mailet.MatcherConfig)"><CODE>init(MatcherConfig)</CODE></A> has been successfully completed.
<P>
<DD><DL>
-
-<DT><B>Returns:</B><DD>a String containing matcher information</DL>
+</DL>
</DD>
</DL>
<HR>
-<A NAME="init(org.apache.mailet.MatcherConfig)"><!-- --></A><H3>
-init</H3>
+<A NAME="getMatcherConfig()"><!-- --></A><H3>
+getMatcherConfig</H3>
<PRE>
-void <B>init</B>(<A HREF="../../../org/apache/mailet/MatcherConfig.html" title="interface in org.apache.mailet">MatcherConfig</A> config)
- throws javax.mail.MessagingException</PRE>
+<A HREF="../../../org/apache/mailet/MatcherConfig.html" title="interface in org.apache.mailet">MatcherConfig</A> <B>getMatcherConfig</B>()</PRE>
<DL>
-<DD>Called by the mailet container to indicate to a matcher that the
- matcher is being placed into service.
+<DD>Returns a MatcherConfig object, which provides initialization parameters
+ and a <A HREF="../../../org/apache/mailet/MailetContext.html" title="interface in org.apache.mailet"><CODE>MailetContext</CODE></A> 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 <A HREF="../../../org/apache/mailet/Matcher.html#init(org.apache.mailet.MatcherConfig)"><CODE>init(org.apache.mailet.MatcherConfig)</CODE></A> method so
+ that this method can return it.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>config</CODE> - - a MatcherConfig object containing the matcher's configuration
- and initialization parameters
-<DT><B>Throws:</B>
-<DD><CODE>javax.mail.MessagingException</CODE> - - if an exception has occurred that
- interferes with the matcher's normal operation</DL>
+
+<DT><B>Returns:</B><DD>the MatcherConfig that this matcher was initialized with</DL>
</DD>
</DL>
<HR>
-<A NAME="match(org.apache.mailet.Mail)"><!-- --></A><H3>
-match</H3>
+<A NAME="getMatcherInfo()"><!-- --></A><H3>
+getMatcherInfo</H3>
<PRE>
-java.util.Collection <B>match</B>(<A HREF="../../../org/apache/mailet/Mail.html" title="interface in org.apache.mailet">Mail</A> mail)
- throws javax.mail.MessagingException</PRE>
+java.lang.String <B>getMatcherInfo</B>()</PRE>
<DL>
-<DD>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>.
+<DD>Returns information about the matcher, such as author, version and
+ copyright.
<P>
<DD><DL>
-<DT><B>Parameters:</B><DD><CODE>mail</CODE> - - the Mail object that contains the message and routing information
-<DT><B>Returns:</B><DD>a Collection of String objects (recipients) that meet the match criteria
-<DT><B>Throws:</B>
-<DD><CODE>javax.mail.MessagingException</CODE> - - if an message or address parsing exception occurs or
- an exception that interferes with the matcher's normal operation</DL>
+
+<DT><B>Returns:</B><DD>the Mailet information (as a plain text string)</DL>
</DD>
</DL>
<!-- ========= END OF CLASS DATA ========= -->
Modified: james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/MatcherConfig.html
URL: http://svn.apache.org/viewvc/james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/MatcherConfig.html?rev=800330&r1=800329&r2=800330&view=diff
==============================================================================
--- james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/MatcherConfig.html (original)
+++ james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/MatcherConfig.html Mon Aug 3 12:18:51 2009
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_18) on Thu May 28 11:11:02 BST 2009 -->
+<!-- Generated by javadoc (build 1.5.0_18) on Mon Aug 03 13:36:26 BST 2009 -->
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>
MatcherConfig (Apache Mailet API 2.5-SNAPSHOT API)
@@ -94,19 +94,15 @@
</PRE>
<P>
-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.
+ The configuration information consists of the matcher's condition string,
+ and a MailetContext object which allows the matcher to interact with the
+ mailet container.
<P>
<P>
-<DL>
-<DT><B>Version:</B></DT>
- <DD>1.0.0, 24/04/1999</DD>
-</DL>
<HR>
<P>
@@ -125,8 +121,7 @@
<TD><CODE><B><A HREF="../../../org/apache/mailet/MatcherConfig.html#getCondition()">getCondition</A></B>()</CODE>
<BR>
- The simple condition defined for this matcher, e.g., for
- SenderIs=admin@localhost, this would return admin@localhost.</TD>
+ The condition defined for this matcher.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -163,8 +158,11 @@
<PRE>
java.lang.String <B>getCondition</B>()</PRE>
<DL>
-<DD>The simple condition defined for this matcher, e.g., for
- SenderIs=admin@localhost, this would return admin@localhost.
+<DD>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".
<P>
<DD><DL>
@@ -182,8 +180,8 @@
<P>
<DD><DL>
-<DT><B>Returns:</B><DD>a MailetContext object, used by the matcher to interact with its
- mailet container</DL>
+<DT><B>Returns:</B><DD>a MailetContext object which can be used by the matcher
+ to interact with the mailet container</DL>
</DD>
</DL>
<HR>
@@ -194,8 +192,8 @@
java.lang.String <B>getMatcherName</B>()</PRE>
<DL>
<DD>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.
<P>
<DD><DL>
Modified: james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/class-use/HostAddress.html
URL: http://svn.apache.org/viewvc/james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/class-use/HostAddress.html?rev=800330&r1=800329&r2=800330&view=diff
==============================================================================
--- james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/class-use/HostAddress.html (original)
+++ james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/class-use/HostAddress.html Mon Aug 3 12:18:51 2009
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_18) on Thu May 28 11:11:02 BST 2009 -->
+<!-- Generated by javadoc (build 1.5.0_18) on Mon Aug 03 13:36:26 BST 2009 -->
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>
Uses of Class org.apache.mailet.HostAddress (Apache Mailet API 2.5-SNAPSHOT API)
Modified: james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/class-use/Mail.html
URL: http://svn.apache.org/viewvc/james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/class-use/Mail.html?rev=800330&r1=800329&r2=800330&view=diff
==============================================================================
--- james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/class-use/Mail.html (original)
+++ james/site/trunk/www/mailet/api/apidocs/org/apache/mailet/class-use/Mail.html Mon Aug 3 12:18:51 2009
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_18) on Thu May 28 11:11:02 BST 2009 -->
+<!-- Generated by javadoc (build 1.5.0_18) on Mon Aug 03 13:36:26 BST 2009 -->
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>
Uses of Interface org.apache.mailet.Mail (Apache Mailet API 2.5-SNAPSHOT API)
@@ -110,8 +110,7 @@
<A HREF="../../../../org/apache/mailet/MailAddress.html" title="class in org.apache.mailet">MailAddress</A> bouncer)</CODE>
<BR>
- Bounces the email message using the provided email address as the
- sender of the bounce.</TD>
+ Bounces the message using a standard format with the given message.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -119,8 +118,8 @@
<TD><CODE><B>Matcher.</B><B><A HREF="../../../../org/apache/mailet/Matcher.html#match(org.apache.mailet.Mail)">match</A></B>(<A HREF="../../../../org/apache/mailet/Mail.html" title="interface in org.apache.mailet">Mail</A> mail)</CODE>
<BR>
- Takes a Mail message, looks at any pertinent information, and then returns a subset
- of recipients that meet the "match" conditions.</TD>
+ Takes a Mail message, looks at any pertinent information, and returns
+ a subset of recipients that meet the match conditions.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -128,7 +127,7 @@
<TD><CODE><B>MailetContext.</B><B><A HREF="../../../../org/apache/mailet/MailetContext.html#sendMail(org.apache.mailet.Mail)">sendMail</A></B>(<A HREF="../../../../org/apache/mailet/Mail.html" title="interface in org.apache.mailet">Mail</A> mail)</CODE>
<BR>
- Send an outgoing message to the top of this mailet container's root queue.</TD>
+ Sends an outgoing message to the top of this mailet container's root queue.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
@@ -136,8 +135,7 @@
<TD><CODE><B>Mailet.</B><B><A HREF="../../../../org/apache/mailet/Mailet.html#service(org.apache.mailet.Mail)">service</A></B>(<A HREF="../../../../org/apache/mailet/Mail.html" title="interface in org.apache.mailet">Mail</A> mail)</CODE>
<BR>
- Called by the mailet container to allow the mailet to process to
- a message.</TD>
+ Services a mail message.</TD>
</TR>
</TABLE>