upd: rename sendmail to sendMail

[gigi.git] / tests / org / cacert / gigi / testUtils / TestEmailReceiver.java

diff --git a/tests/org/cacert/gigi/testUtils/TestEmailReceiver.java b/tests/org/cacert/gigi/testUtils/TestEmailReceiver.java
index 789d6bc3fcc4682504603c37105fbcbe903fa935..27b166f9667c35109839d9a4fccd404f117831fb 100644 (file)
--- a/tests/org/cacert/gigi/testUtils/TestEmailReceiver.java
+++ b/tests/org/cacert/gigi/testUtils/TestEmailReceiver.java
@@ -13,10 +13,20 @@ import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
 import org.cacert.gigi.email.EmailProvider;
+import org.cacert.gigi.email.TestEmailProvider;
 
-public final class TestEmailReceiver extends EmailProvider implements Runnable {
+/**
+ * This class reveives emails from the current system under test. It is the
+ * counterpart to the {@link TestEmailProvider} who is loaded into the system to
+ * intercept the emails. This class resides in the VM that executes the
+ * testcases and supplies the intercepted emails to the current test case.
+ */
+public final class TestEmailReceiver extends EmailProvider implements Runnable, MailReceiver {
 
-    public class TestMail {
+    /**
+     * An email that has been intercepted.
+     */
+    public static class TestMail {
 
         String to;
 
@@ -64,7 +74,8 @@ public final class TestEmailReceiver extends EmailProvider implements Runnable {
         }
 
         public void verify() throws IOException {
-            String[] parts = extractLink().split("\\?");
+            String link = extractLink();
+            String[] parts = link.split("\\?");
             URL u = new URL("https://" + ManagedTest.getServerName() + "/verify?" + parts[1]);
 
             URLConnection csrfConn = u.openConnection();
@@ -87,6 +98,16 @@ public final class TestEmailReceiver extends EmailProvider implements Runnable {
 
     private DataOutputStream dos;
 
+    /**
+     * Creates a new TestEmailReceiver based on the address where the
+     * {@link TestEmailProvider} is listening. This class is only ready after
+     * {@link #start()} has been called.
+     * 
+     * @param target
+     *            the address where the {@link TestEmailProvider} is listening.
+     * @throws IOException
+     *             if the connection cannot be opened
+     */
     public TestEmailReceiver(SocketAddress target) throws IOException {
         s = new Socket();
         s.connect(target);
@@ -97,11 +118,16 @@ public final class TestEmailReceiver extends EmailProvider implements Runnable {
         setInstance(this);
     }
 
+    /**
+     * Spawns a new {@link Thread} that reads incoming {@link TestMail}s.
+     * 
+     * @see #destroy()
+     */
     public void start() {
-        new Thread(this, "Mail reciever").start();
+        new Thread(this, "Mail receiver").start();
     }
 
-    LinkedBlockingQueue<TestMail> mails = new LinkedBlockingQueue<TestEmailReceiver.TestMail>();
+    private LinkedBlockingQueue<TestMail> mails = new LinkedBlockingQueue<TestEmailReceiver.TestMail>();
 
     /**
      * Retrieves an outgoing mail from the system. The method will return a
@@ -110,6 +136,7 @@ public final class TestEmailReceiver extends EmailProvider implements Runnable {
      * @return The intercepted {@link TestMail}
      * @see #poll()
      */
+    @Override
     public TestMail receive() {
         TestMail poll;
 
@@ -117,10 +144,10 @@ public final class TestEmailReceiver extends EmailProvider implements Runnable {
             poll = mails.poll(60, TimeUnit.SECONDS);
 
         } catch (InterruptedException e) {
-            throw new AssertionError("Interrupted while recieving mails");
+            throw new AssertionError("Interrupted while receiving mails");
         }
         if (poll == null) {
-            throw new AssertionError("Mail recieving timed out");
+            throw new AssertionError("Mail receiving timed out");
         }
 
         return poll;
@@ -135,12 +162,7 @@ public final class TestEmailReceiver extends EmailProvider implements Runnable {
      * @see #receive()
      */
     public TestMail poll() {
-        try {
-            return mails.poll(60, TimeUnit.SECONDS);
-
-        } catch (InterruptedException e) {
-            throw new AssertionError("Interrupted while recieving mails");
-        }
+        return mails.poll();
     }
 
     @Override
@@ -182,28 +204,60 @@ public final class TestEmailReceiver extends EmailProvider implements Runnable {
 
     String error = "FAIL";
 
+    /**
+     * Sets the error that will be sent back to incoming "fast mail checks" that
+     * only check for the availability of a mailbox.
+     * 
+     * @param error
+     *            the error Massage to return in
+     *            {@link EmailProvider#checkEmailServer(int, String)}
+     */
     public void setEmailCheckError(String error) {
         this.error = error;
     }
 
-    Pattern approveRegex = Pattern.compile(".*");
+    private Pattern approveRegex = Pattern.compile(".*");
 
+    /**
+     * Specifies a pattern that will be used for incoming
+     * {@link EmailProvider#checkEmailServer(int, String)} calls to determine
+     * whether the mailbox should exist.
+     * 
+     * @param approveRegex
+     *            the regex that will perform the check
+     */
     public void setApproveRegex(Pattern approveRegex) {
         this.approveRegex = approveRegex;
     }
 
+    /**
+     * Removes all queued mails.
+     */
+    @Override
     public void clearMails() {
         mails.clear();
     }
 
+    /**
+     * Resets this class to its initial state
+     * 
+     * @see #clearMails()
+     * @see #setApproveRegex(Pattern)
+     * @see #setEmailCheckError(String)
+     */
     public void reset() {
         clearMails();
         error = "FAIL";
         approveRegex = Pattern.compile(".*");
     }
 
-    boolean closed = false;
+    private boolean closed = false;
 
+    /**
+     * stops reading for incoming messages
+     * 
+     * @see #start()
+     */
     public void destroy() {
         try {
             closed = true;
@@ -219,7 +273,7 @@ public final class TestEmailReceiver extends EmailProvider implements Runnable {
     }
 
     @Override
-    public void sendmail(String to, String subject, String message, String from, String replyto, String toname, String fromname, String errorsto, boolean extra) throws IOException {
+    public void sendMail(String to, String subject, String message, String from, String replyto, String toname, String fromname, String errorsto, boolean extra) throws IOException {
         mails.add(new TestMail(to, subject, message, from, replyto));
     }