edited javadocs only

git-svn-id: https://svn.apache.org/repos/asf/james/postage/trunk@451263 13f79535-47bb-0310-9956-ffa450edef68

src/main/config/postage.xml

@@ -86,7 +86,7 @@
         -->
         <smtp-forwarding port="2525" latecomer-wait-seconds="45"/>
         <!-- James' SMTP listening port. -->
-        <smtp-inbound port="25" />
+        <smtp-inbound port="2524" />
         <!-- James' POP3 listening port. 
              count-per-min: how often per minute another random internal user account is accessed and all test email there is 
              downloaded -->
@@ -126,18 +126,18 @@
         </users>
         <profiles>
             <profile name="ext-int" source="extern" target="intern">
-               <send count-per-min="10" subject="ext2int" text-size-min="10" text-size-max="1000" binary-size-min="1" binary-size-max="1000" />
+               <send count-per-min="1" subject="ext2int" text-size-min="10" text-size-max="1000" binary-size-min="1" binary-size-max="1000" />
             </profile>
             <profile name="int-ext" source="intern" target="extern">
-               <send count-per-min="10" subject="int2ext" text-size-min="10" text-size-max="1000" binary-size-min="1" binary-size-max="1000"  />
+               <send count-per-min="1" subject="int2ext" text-size-min="10" text-size-max="1000" binary-size-min="1" binary-size-max="1000"  />
             </profile>
             <profile name="int-int" source="intern" target="intern">
-               <send count-per-min="10" subject="int2int" text-size-min="10" text-size-max="1000" binary-size-min="1" binary-size-max="1000"  />
+               <send count-per-min="1" subject="int2int" text-size-min="10" text-size-max="1000" binary-size-min="1" binary-size-max="1000"  />
             </profile>
         </profiles>
         <testserver host="localhost">
-          <smtp-forwarding port="2525" latecomer-wait-seconds="120"/>
-          <smtp-inbound port="25" />
+          <smtp-forwarding port="2525" latecomer-wait-seconds="10"/>
+          <smtp-inbound port="2524" />
           <pop3 port="110" count-per-min="10" />
           <remotemanager port="4555" name="root" password="root" />
           <spam-account name="spam-sink" password="spam-sink" />

src/main/java/org/apache/james/postage/PostageRunner.java

@@ -42,7 +42,7 @@
 import java.io.File;
 
 /**
- * central controlling class for the testing process. starts all workers, collects data and stops when time is out.
+ * central controlling class for the testing process. starts all workers, collects data and stops when time is out.<br/>
  * relates to one and only one Scenario section from the configuration file.
  */
 public class PostageRunner implements Runnable {

src/main/java/org/apache/james/postage/PostageRuntimeException.java

@@ -19,7 +19,7 @@
 package org.apache.james.postage;
 
 /**
- * base exception for Postage
+ * base unchecked exception for Postage
  */
 public class PostageRuntimeException extends RuntimeException {
     public PostageRuntimeException() {

src/main/java/org/apache/james/postage/SamplingException.java

@@ -21,7 +21,7 @@
 package org.apache.james.postage;
 
 /**
- * base exception for all the recording-data-stuff
+ * base exception for all the data recording stuff
  */
 public class SamplingException extends PostageException {
     public SamplingException() {

src/main/java/org/apache/james/postage/classloading/CachedInstanceFactory.java

@@ -24,6 +24,9 @@
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 
+/**
+ * generic object factory, caching the class object for reuse
+ */
 public class CachedInstanceFactory {
 
     private static Log log = LogFactory.getLog(CachedInstanceFactory.class);

src/main/java/org/apache/james/postage/client/POP3Client.java

@@ -33,6 +33,10 @@
 import org.apache.james.postage.result.PostageRunnerResult;
 import org.apache.james.postage.user.UserList;
 
+/**
+ * acts like a MUA using POP3 protocol.<br/>
+ * fetches all mails for one (all) users and initiates adding to results
+ */
 public class POP3Client implements Sampler {
 
     private static Log log = LogFactory.getLog(POP3Client.class);
@@ -49,6 +53,9 @@ public POP3Client(String host, int port, UserList internalUsers, PostageRunnerRe
         m_results = results;
     }
 
+    /**
+     * checks, if the configured POP3 services is accessable
+     */
     public boolean checkAvailability() throws StartupException {
         try {
             org.apache.commons.net.pop3.POP3Client pop3Client = openConnection(m_internalUsers.getRandomUsername());
@@ -79,6 +86,9 @@ private org.apache.commons.net.pop3.POP3Client openConnection(String username) t
         return pop3Client;
     }
 
+    /**
+     * take one POP3 sample for a random user
+     */
     public void doSample() throws SamplingException {
         String username = m_internalUsers.getRandomUsername();
 
@@ -90,6 +100,10 @@ public void doSample() throws SamplingException {
         }
     }
 
+    /**
+     * used after completing with regular test scenario. tries to collect all mails, which are left 
+     * unprocessed by the random access. this is done by iterating over all user accounts, looking for mail
+     */
     public void doMatchMailForAllUsers() {
         Iterator usernames = m_internalUsers.getUsernames();
         while (usernames.hasNext()) {
@@ -102,6 +116,11 @@ public void doMatchMailForAllUsers() {
         }
     }
 
+    /**
+     * for the specified user, fetches all mail and invokes the matching process
+     * @param username
+     * @throws SamplingException
+     */
     private void findAllMatchingTestMail(String username) throws SamplingException {
         try {
             org.apache.commons.net.pop3.POP3Client pop3Client = openConnection(username);

src/main/java/org/apache/james/postage/client/RemoteManagerClient.java

@@ -31,6 +31,10 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Apache James Server specific client to access its Remote Manager.<br/>
+ * This is used for creating user accounts.
+ */
 public class RemoteManagerClient {
 
     private String  m_host = null;

src/main/java/org/apache/james/postage/client/SMTPClient.java

@@ -37,8 +37,8 @@
 import java.util.Properties;
 
 /**
- * connects as a SMTP client and handles all mail according to its configuration.
- * it is threadsafe and reentrant and thus can be reused over multiple parallel client session
+ * connects as a SMTP client and handles all mail according to its configuration.<br/>
+ * it is threadsafe and reentrant and thus can be reused over multiple parallel client session<br/>
  */
 public class SMTPClient implements Sampler {
 

src/main/java/org/apache/james/postage/configuration/MailSender.java

@@ -29,7 +29,12 @@
 import javax.mail.Session;
 import javax.mail.Message;
 
-// TODO init increaseSendPerMinute & maxSendPerMinute from config
+/**
+ * specifies, how mail is to be generated and sent, as coming from the configuration (<send> element)<br/>
+ * the source and target are specified by the parent SendProfile instance<br/>
+ * <br/>
+ * TODO init increaseSendPerMinute & maxSendPerMinute from config
+ */
 public class MailSender {
 
     private static Log log = LogFactory.getLog(MailSender.class);

src/main/java/org/apache/james/postage/configuration/SendProfile.java

@@ -24,6 +24,9 @@
 import java.util.List;
 import java.util.Iterator;
 
+/**
+ * specifies for the contained MailSenders, what are source and target of each mail they generate
+ */
 public class SendProfile {
     private String m_profileName;
     private boolean m_sourceInternal = true;

src/main/java/org/apache/james/postage/execution/Sampler.java

@@ -22,6 +22,10 @@
 
 import org.apache.james.postage.SamplingException;
 
+/**
+ * every unit-of-work concerning issueing and retrieving test data must implement this interface
+ * as invoked by @see SampleController
+ */
 public interface Sampler {
     void doSample() throws SamplingException;
 }

src/main/java/org/apache/james/postage/jmx/JVMResourceSampler.java

@@ -28,10 +28,10 @@
 import java.lang.reflect.Method;
 
 /**
- * wraps JVMResourceSamplerWorker to allow J2SE 1.4 compatibility
- * does not access this class through direct reference, only through reflection
- * in the case this compatibility is removed, simply inline the Worker class
- *
+ * wraps JVMResourceSamplerWorker to allow J2SE 1.4 compatibility<br/>
+ * does not access this class through direct reference, only through reflection<br/>
+ * in the case this compatibility is removed, simply inline the Worker class<br/>
+ * <br/>
  * @see org.apache.james.postage.jmx.JVMResourceSamplerWorker for how to configure James to be JVM-JMX agnostic
  */
 public class JVMResourceSampler implements Sampler {

src/main/java/org/apache/james/postage/jmx/JVMResourceSamplerWorker.java

@@ -39,14 +39,17 @@
 /**
  * the peek into the James JVM is done using the build-in management (JMX) of J2SE 5 (and probably later)
  * you must start James under a J2SE 5 compatible JVM and
- * add some system properties to the phoenix.[sh|bat] file (all on one line):
+ * add some system properties to the phoenix.[sh|bat] file (all on one line):<br/>
+ * <br/>
+ * <code>
  * JVM_OPTS="-Djava.ext.dirs=$JVM_EXT_DIRS
  *           -Dcom.sun.management.jmxremote
  *           -Dcom.sun.management.jmxremote.ssl=false
  *           -Dcom.sun.management.jmxremote.authenticate=false
  *           -Dcom.sun.management.jmxremote.port=10201 "
- *
- * this class does not even compile on Java versions before JSE 5.
+ * </code>
+ * <br/>
+ * this class does not even compile on Java versions before JSE 5.<br/>
  */
 public class JVMResourceSamplerWorker implements Sampler {
 

src/main/java/org/apache/james/postage/mail/AbstractMailFactory.java

@@ -28,6 +28,11 @@
 import org.apache.james.postage.configuration.MailSender;
 import org.apache.james.postage.result.MailProcessingRecord;
 
+/**
+ * prototype of a mail factory, only missing the use case specific data. <br/>
+ * it prepares the message with all Postage specific headers.<br/>
+ * @see DefaultMailFactory as a template implementation  
+ */
 public abstract class AbstractMailFactory {
 
     private static Log log = LogFactory.getLog(DefaultMailFactory.class);

src/main/java/org/apache/james/postage/mail/DefaultMailFactory.java

@@ -31,6 +31,9 @@
 import javax.mail.internet.MimeMultipart;
 import javax.mail.util.ByteArrayDataSource;
 
+/**
+ * mail factory used, when no other is specified
+ */
 public class DefaultMailFactory extends AbstractMailFactory implements MailFactory {
 
     protected void populateMessage(MimeMessage message, MailSender mailSender, MailProcessingRecord mailProcessingRecord) throws MessagingException {

src/main/java/org/apache/james/postage/mail/DefaultMailValidator.java

@@ -26,6 +26,9 @@
 import org.apache.commons.logging.LogFactory;
 import org.apache.james.postage.result.MailProcessingRecord;
 
+/**
+ * this validator is used together with DefaultMailFactory
+ */
 public class DefaultMailValidator implements MailValidator {
 
     private static Log log = LogFactory.getLog(DefaultMailValidator.class);

src/main/java/org/apache/james/postage/mail/MailAnalyzeStrategy.java

@@ -26,7 +26,8 @@
 import org.apache.james.postage.result.PostageRunnerResult;
 
 /**
- * handles the process of retrieving, analyzing and finally (optionally) dismissing the 
+ * handles the process of retrieving, analyzing, matching and finally (optionally) dismissing one
+ * received message.
  */
 public abstract class MailAnalyzeStrategy {
 

src/main/java/org/apache/james/postage/result/PostageRunnerResult.java

@@ -22,6 +22,9 @@
 
 import java.util.Map;
 
+/**
+ * collects and writes all result data for one scenario
+ */
 public interface PostageRunnerResult {
 
     void setEnvironmentDescription(Map descriptionItems);

src/main/java/org/apache/james/postage/smtpserver/AvalonToPostageLogger.java

@@ -23,6 +23,9 @@
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 
+/**
+ * adapter to redirect log avalon messages to commons-logging 
+ */
 public class AvalonToPostageLogger implements org.apache.avalon.framework.logger.Logger {
 
     private static Log log = LogFactory.getLog(AvalonToPostageLogger.class);

src/main/java/org/apache/james/postage/smtpserver/SMTPMailSink.java

@@ -39,7 +39,7 @@
 import org.apache.james.util.connection.SimpleConnectionManager;
 
 /**
- * puts up a gateway SMTP server acting as a mail sink for the external mail sent out by James.
+ * puts up a gateway SMTP server acting as a mail sink for the external mail sent out by James.<br/>
  * mails are catched, test mails are identified and tracked
  */
 public class SMTPMailSink implements Sampler, SocketManager, ThreadManager {

src/main/java/org/apache/james/postage/smtpserver/SimpleMailServer.java

@@ -44,7 +44,7 @@
 
 
 /**
- * a quite simple (only receiving) SMTP server which reads mails and tries to match them with sent test mails.
+ * a quite simple (only receiving) SMTP server which reads mails and tries to match them with sent test mails.<br/>
  * reuses James' own SMTP server components
  */
 public class SimpleMailServer implements MailServer {