pgoldstein 2002/08/17 11:43:56
Modified: src/java/org/apache/james/transport LinearProcessor.java
MailetLoader.java MatchLoader.java Resources.java
src/java/org/apache/james/transport/mailets Null.java
Added: src/java/org/apache/james/transport package.html
src/java/org/apache/james/transport/mailets package.html
src/java/org/apache/james/transport/mailets/debug
package.html
src/java/org/apache/james/transport/matchers package.html
Log:
Added extensive comments.
Revision Changes Path
1.8 +57 -24
jakarta-james/src/java/org/apache/james/transport/LinearProcessor.java
Index: LinearProcessor.java
===================================================================
RCS file:
/home/cvs/jakarta-james/src/java/org/apache/james/transport/LinearProcessor.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- LinearProcessor.java 10 Aug 2002 23:13:12 -0000 1.7
+++ LinearProcessor.java 17 Aug 2002 18:43:55 -0000 1.8
@@ -26,6 +26,9 @@
import java.util.Iterator;
/**
+ * Implements a processor for mails, directing the mail down
+ * the chain of matchers/mailets.
+ *
* @author Serge Knystautas <[EMAIL PROTECTED]>
* @author Federico Barbieri <[EMAIL PROTECTED]>
* @author Steve Short <[EMAIL PROTECTED]>
@@ -77,7 +80,7 @@
*
* @param spool the spool to be used by this processor
*
- * @exception IllegalArgumentException thrown when the spool passed in is null
+ * @throws IllegalArgumentException when the spool passed in is null
*/
public void setSpool(SpoolRepository spool) {
if (spool == null) {
@@ -86,12 +89,28 @@
this.spool = spool;
}
+ /**
+ * Initialize the component. Initialization includes
+ * allocating any resources required throughout the
+ * components lifecycle.
+ *
+ * @throws Exception if an error occurs
+ */
public void initialize() {
matchers = new ArrayList();
mailets = new ArrayList();
}
- // Shutdown mailets
+ /**
+ * <p>The dispose operation is called at the end of a components lifecycle.
+ * Instances of this class use this method to release and destroy any
+ * resources that they own.</p>
+ *
+ * <p>This implementation disposes of all the mailet instances added to the
+ * processor</p>
+ *
+ * @throws Exception if an error is encountered during shutdown
+ */
public void dispose() {
Iterator it = mailets.iterator();
boolean debugEnabled = getLogger().isDebugEnabled();
@@ -105,24 +124,27 @@
}
/**
- * Adds a new <code>Matcher</code> / <code>Mailet</code> pair
+ * <p>Adds a new <code>Matcher</code> / <code>Mailet</code> pair
* to the processor. Checks to ensure that the matcher and
* mailet passed in are not null. Synchronized to ensure that
- * the matchers and mailets are kept in sync.
+ * the matchers and mailets are kept in sync.</p>
*
- * It is an essential part of the contract of the LinearProcessor
+ * <p>It is an essential part of the contract of the LinearProcessor
* that a particular matcher/mailet combination be used to
* terminate the processor chain. This is done by calling the
- * closeProcessorList method.
+ * closeProcessorList method.</p>
+ *
+ * <p>Once the closeProcessorList has been called any subsequent
+ * call to the add method will result in an IllegalStateException.</p>
*
- * Once the closeProcessorList has been called any subsequent
- * call to the add method will result in an IllegalStateException.
+ * <p>This method is synchronized to protect against corruption of
+ * matcher/mailets lists</p>
*
* @param matcher the new matcher being added
* @param mailet the new mailet being added
*
- * @exception IllegalArgumentException thrown when the matcher or mailet passed
in is null
- * @exception IllegalStateException thrown when this method is called after the
processor lists have been closed
+ * @throws IllegalArgumentException when the matcher or mailet passed in is null
+ * @throws IllegalStateException when this method is called after the processor
lists have been closed
*/
public synchronized void add(Matcher matcher, Mailet mailet) {
if (matcher == null) {
@@ -139,9 +161,12 @@
}
/**
- * Closes the processor matcher/mailet list.
+ * <p>Closes the processor matcher/mailet list.</p>
+ *
+ * <p>This method is synchronized to protect against corruption of
+ * matcher/mailets lists</p>
*
- * @exception IllegalStateException thrown when this method is called after the
processor lists have been closed
+ * @throws IllegalStateException when this method is called after the processor
lists have been closed
*/
public synchronized void closeProcessorLists() {
if (listsClosed) {
@@ -176,21 +201,21 @@
}
/**
- * Processes a single mail message through the chain of matchers and mailets.
+ * <p>Processes a single mail message through the chain of matchers and
mailets.</p>
*
- * Calls to this method before setSpool has been called with a non-null argument
- * will result in an <code>IllegalStateException<\code>.
+ * <p>Calls to this method before setSpool has been called with a non-null
argument
+ * will result in an <code>IllegalStateException</code>.</p>
*
- * If the matcher/mailet lists have not been closed by a call to the
closeProcessorLists
- * method then a call to this method will result in an
<code>IllegalStateException<\code>.
+ * <p>If the matcher/mailet lists have not been closed by a call to the
closeProcessorLists
+ * method then a call to this method will result in an
<code>IllegalStateException</code>.
* The end of the matcher/mailet chain must be a matcher that matches all mails
and
* a mailet that sets every mail to GHOST status. This is necessary to ensure
that
* mails are removed from the spool in an orderly fashion. The
closeProcessorLists method
- * ensures this.
+ * ensures this.</p>
*
* @param mail the new mail to be processed
*
- * @exception IllegalStateException thrown when this method is called before
the processor lists have been closed
+ * @throws IllegalStateException when this method is called before the
processor lists have been closed
* or the spool has been initialized
*/
public void service(MailImpl mail) throws MessagingException {
@@ -357,23 +382,27 @@
}
/**
- * Create a unique new primary key name
+ * Create a unique new primary key name.
+ *
+ * @param mail the mail to use as the basis for the new mail name
+ *
+ * @return a new name
*/
private String newName(MailImpl mail) {
StringBuffer nameBuffer =
new StringBuffer(64)
.append(mail.getName())
.append("-!")
- .append(Math.abs(random.nextInt()));
+ .append(random.nextInt(1048576));
return nameBuffer.toString();
}
/**
- * Checks that all objects in this class are of the form MailAddress
+ * Checks that all objects in this class are of the form MailAddress.
*
- * @exception MessagingException thrown when the <code>Collection</code>
contains objects that are not <code>MailAddress</code> objects
+ * @throws MessagingException when the <code>Collection</code> contains objects
that are not <code>MailAddress</code> objects
*/
private void verifyMailAddresses(Collection col) throws MessagingException {
MailAddress addresses[] = (MailAddress[])col.toArray(new MailAddress[0]);
@@ -386,7 +415,11 @@
* This is a helper method that updates the state of the mail object to
* Mail.ERROR as well as recording the exception to the log
*
- * @exception MessagingException thrown always, rethrowing the passed in
exception
+ * @param me the exception to be handled
+ * @param mail the mail being processed when the exception was generated
+ * @param offendersName the matcher or mailet than generated the exception
+ *
+ * @throws MessagingException thrown always, rethrowing the passed in exception
*/
private void handleException(MessagingException me, Mail mail, String
offendersName) throws MessagingException {
System.err.println("exception! " + me);
1.4 +20 -1
jakarta-james/src/java/org/apache/james/transport/MailetLoader.java
Index: MailetLoader.java
===================================================================
RCS file:
/home/cvs/jakarta-james/src/java/org/apache/james/transport/MailetLoader.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- MailetLoader.java 7 Aug 2002 23:44:55 -0000 1.3
+++ MailetLoader.java 17 Aug 2002 18:43:55 -0000 1.4
@@ -20,14 +20,24 @@
import java.util.Vector;
/**
+ * Loads Mailets for use inside James.
+ *
* @author Serge Knystautas <[EMAIL PROTECTED]>
* @author Federico Barbieri <[EMAIL PROTECTED]>
*/
public class MailetLoader implements Component, Configurable {
- private Configuration conf;
+ /**
+ * The list of packages that may contain Mailets
+ */
private Vector mailetPackages;
+ /**
+ * Pass the <code>Configuration</code> to the instance.
+ *
+ * @param configuration the class configurations.
+ * @throws ConfigurationException if an error occurs
+ */
public void configure(Configuration conf) throws ConfigurationException {
mailetPackages = new Vector();
mailetPackages.addElement("");
@@ -43,6 +53,15 @@
}
}
+ /**
+ * Get a new Mailet with the specified name acting
+ * in the specified context.
+ *
+ * @param matchName the name of the mailet to be loaded
+ * @param context the MailetContext to be passed to the new
+ * mailet
+ * @throws MessagingException if an error occurs
+ */
public Mailet getMailet(String mailetName, MailetContext context, Configuration
configuration)
throws MessagingException {
try {
1.5 +20 -1
jakarta-james/src/java/org/apache/james/transport/MatchLoader.java
Index: MatchLoader.java
===================================================================
RCS file:
/home/cvs/jakarta-james/src/java/org/apache/james/transport/MatchLoader.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- MatchLoader.java 7 Aug 2002 23:44:55 -0000 1.4
+++ MatchLoader.java 17 Aug 2002 18:43:55 -0000 1.5
@@ -20,14 +20,24 @@
import java.util.Vector;
/**
+ * Loads Matchers for use inside James.
+ *
* @author Serge Knystautas <[EMAIL PROTECTED]>
* @author Federico Barbieri <[EMAIL PROTECTED]>
*/
public class MatchLoader implements Component, Configurable {
- private Configuration conf;
+ /**
+ * The list of packages that may contain Mailets
+ */
private Vector matcherPackages;
+ /**
+ * Pass the <code>Configuration</code> to the instance.
+ *
+ * @param configuration the class configurations.
+ * @throws ConfigurationException if an error occurs
+ */
public void configure(Configuration conf) throws ConfigurationException {
matcherPackages = new Vector();
matcherPackages.addElement("");
@@ -43,6 +53,15 @@
}
}
+ /**
+ * Get a new Matcher with the specified name acting
+ * in the specified context.
+ *
+ * @param matchName the name of the matcher to be loaded
+ * @param context the MailetContext to be passed to the new
+ * matcher
+ * @throws MessagingException if an error occurs
+ */
public Matcher getMatcher(String matchName, MailetContext context)
throws MessagingException {
try {
1.2 +33 -0 jakarta-james/src/java/org/apache/james/transport/Resources.java
Index: Resources.java
===================================================================
RCS file:
/home/cvs/jakarta-james/src/java/org/apache/james/transport/Resources.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Resources.java 11 May 2001 10:36:19 -0000 1.1
+++ Resources.java 17 Aug 2002 18:43:55 -0000 1.2
@@ -8,6 +8,8 @@
package org.apache.james.transport;
/**
+ * A set of constants used inside the James transport.
+ *
* @version 1.0.0, 24/04/1999
* @author Federico Barbieri <[EMAIL PROTECTED]>
*/
@@ -16,18 +18,49 @@
//Already defined in Constants
//public static final String SERVER_NAMES = "SERVER_NAMES";
+ /**
+ * Don't know what this is supposed to be.
+ *
+ * @deprecated this is unused
+ */
public static final String USERS_MANAGER = "USERS_MANAGER";
//Already defined in Constants
//public static final String POSTMASTER = "POSTMASTER";
+ /**
+ * Don't know what this is supposed to be.
+ *
+ * @deprecated this is unused
+ */
public static final String MAIL_SERVER = "MAIL_SERVER";
+ /**
+ * Don't know what this is supposed to be.
+ *
+ * @deprecated this is unused
+ */
public static final String TRANSPORT = "TRANSPORT";
+ /**
+ * Don't know what this is supposed to be.
+ *
+ * @deprecated this is unused
+ */
public static final String TMP_REPOSITORY = "TMP_REPOSITORY";
+ /**
+ * Key for looking up the MailetLoader
+ */
public static final String MAILET_LOADER = "MAILET_LOADER";
+ /**
+ * Key for looking up the MatchLoader
+ */
public static final String MATCH_LOADER = "MATCH_LOADER";
+
+ /**
+ * Private constructor to prevent instantiation of the class
+ */
+ private Resources() {}
}
1.1 jakarta-james/src/java/org/apache/james/transport/package.html
Index: package.html
===================================================================
<body>
<p>Classes that implement the matcher/mailet processing chain.</p>
</body>
1.4 +1 -1
jakarta-james/src/java/org/apache/james/transport/mailets/Null.java
Index: Null.java
===================================================================
RCS file:
/home/cvs/jakarta-james/src/java/org/apache/james/transport/mailets/Null.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Null.java 9 Aug 2002 06:04:22 -0000 1.3
+++ Null.java 17 Aug 2002 18:43:55 -0000 1.4
@@ -18,7 +18,7 @@
public class Null extends GenericMailet {
public void service(Mail mail) {
- mail.setState(mail.GHOST);
+ mail.setState(Mail.GHOST);
}
public String getMailetInfo() {
1.1
jakarta-james/src/java/org/apache/james/transport/mailets/package.html
Index: package.html
===================================================================
<body>
<p>Core mailets for use with the Mailet API.</p>
</body>
1.1
jakarta-james/src/java/org/apache/james/transport/mailets/debug/package.html
Index: package.html
===================================================================
<body>
<p>Debugging mailets for use with the Mailet API.</p>
</body>
1.1
jakarta-james/src/java/org/apache/james/transport/matchers/package.html
Index: package.html
===================================================================
<body>
<p>Core matchers for use with the Mailet API.</p>
</body>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
