Completed javadoc for test framework.

git-svn-id: https://svn.apache.org/repos/asf/incubator/qpid/branches/M2@556024 13f79535-47bb-0310-9956-ffa450edef68

13 files changed, 133 insertions, 42 deletions

diff --git a/java/systests/src/main/java/org/apache/qpid/server/exchange/ImmediateMessageTest.java b/java/systests/src/main/java/org/apache/qpid/server/exchange/ImmediateMessageTest.java
index 7d6e7d044c..c2b7a2094f 100644
--- a/java/systests/src/main/java/org/apache/qpid/server/exchange/ImmediateMessageTest.java
+++ b/java/systests/src/main/java/org/apache/qpid/server/exchange/ImmediateMessageTest.java
@@ -39,14 +39,24 @@ import uk.co.thebadgerset.junit.extensions.util.TestContextProperties;
  * <tr><th> Responsibilities <th> Collaborations

  * <tr><td> Check that an immediate message is sent succesfully not using transactions when a consumer is connected.

  * <tr><td> Check that an immediate message is committed succesfully in a transaction when a consumer is connected.

- * <tr><td> Check that an immediate message results in no consumers code, not using transactions, when no consumer is

+ * <tr><td> Check that an immediate message results in no consumers code, not using transactions, when a consumer is

+ *          disconnected.

+ * <tr><td> Check that an immediate message results in no consumers code, in a transaction, when a consumer is

+ *          disconnected.

+ * <tr><td> Check that an immediate message results in no route code, not using transactions, when no outgoing route is

  *          connected.

- * <tr><td> Check that an immediate message results in no consumers code, upon transaction commit, when a consumer is

+ * <tr><td> Check that an immediate message results in no route code, upon transaction commit, when no outgoing route is

  *          connected.

+ * <tr><td> Check that an immediate message is sent succesfully not using transactions when a consumer is connected.

+ * <tr><td> Check that an immediate message is committed succesfully in a transaction when a consumer is connected.

  * <tr><td> Check that an immediate message results in no consumers code, not using transactions, when a consumer is

  *          disconnected.

- * <tr><dt> Check that an immediate message results in no consumers code, in a transaction, when a consumer is

+ * <tr><td> Check that an immediate message results in no consumers code, in a transaction, when a consumer is

  *          disconnected.

+ * <tr><td> Check that an immediate message results in no route code, not using transactions, when no outgoing route is

+ *          connected.

+ * <tr><td> Check that an immediate message results in no route code, upon transaction commit, when no outgoing route is

+ *          connected.

  * </table>

  *

  * @todo All of these test cases will be generated by a test generator that thoroughly tests all combinations of test

@@ -115,7 +125,7 @@ public class ImmediateMessageTest extends FrameworkBaseCase
         assertNoFailures(testCircuit.test(1, assertionList(testCircuit.getPublisher().noConsumersAssertion())));

     }

 

-    /** Check that an immediate message results in no consumers code, not using transactions, when no consumer is connected. */

+    /** Check that an immediate message results in no route code, not using transactions, when no outgoing route is connected. */

     public void test_QPID_517_ImmediateFailsNoRouteNoTxP2P()

     {

         // Ensure transactional sessions are off.

@@ -128,11 +138,11 @@ public class ImmediateMessageTest extends FrameworkBaseCase
 

         Circuit testCircuit = CircuitImpl.createCircuit(testProps);

 

-        // Send one message and get a linked no consumers exception.

+        // Send one message and get a linked no route exception.

         assertNoFailures(testCircuit.test(1, assertionList(testCircuit.getPublisher().noRouteAssertion())));

     }

 

-    /** Check that an immediate message results in no consumers code, upon transaction commit, when a consumer is connected. */

+    /** Check that an immediate message results in no route code, upon transaction commit, when no outgoing route is connected. */

     public void test_QPID_517_ImmediateFailsNoRouteTxP2P()

     {

         // Ensure transactional sessions are on.

@@ -213,7 +223,7 @@ public class ImmediateMessageTest extends FrameworkBaseCase
         assertNoFailures(testCircuit.test(1, assertionList(testCircuit.getPublisher().noConsumersAssertion())));

     }

 

-    /** Check that an immediate message results in no consumers code, not using transactions, when no consumer is connected. */

+    /** Check that an immediate message results in no route code, not using transactions, when no outgoing route is connected. */

     public void test_QPID_517_ImmediateFailsNoRouteNoTxPubSub()

     {

         // Ensure transactional sessions are off.

@@ -226,11 +236,11 @@ public class ImmediateMessageTest extends FrameworkBaseCase
 

         Circuit testCircuit = CircuitImpl.createCircuit(testProps);

 

-        // Send one message and get a linked no consumers exception.

+        // Send one message and get a linked no route exception.

         assertNoFailures(testCircuit.test(1, assertionList(testCircuit.getPublisher().noRouteAssertion())));

     }

 

-    /** Check that an immediate message results in no consumers code, upon transaction commit, when a consumer is connected. */

+    /** Check that an immediate message results in no route code, upon transaction commit, when no outgoing route is connected. */

     public void test_QPID_517_ImmediateFailsNoRouteTxPubSub()

     {

         // Ensure transactional sessions are on.

@@ -243,7 +253,7 @@ public class ImmediateMessageTest extends FrameworkBaseCase
 

         Circuit testCircuit = CircuitImpl.createCircuit(testProps);

 

-        // Send one message and get a linked no consumers exception.

+        // Send one message and get a linked no route exception.

         assertNoFailures(testCircuit.test(1, assertionList(testCircuit.getPublisher().noRouteAssertion())));

     }

 

diff --git a/java/systests/src/main/java/org/apache/qpid/server/exchange/MandatoryMessageTest.java b/java/systests/src/main/java/org/apache/qpid/server/exchange/MandatoryMessageTest.java
index 75257cc508..1bfc97838c 100644
--- a/java/systests/src/main/java/org/apache/qpid/server/exchange/MandatoryMessageTest.java
+++ b/java/systests/src/main/java/org/apache/qpid/server/exchange/MandatoryMessageTest.java
@@ -37,16 +37,26 @@ import uk.co.thebadgerset.junit.extensions.util.TestContextProperties;
  *

  * <p><table id="crc"><caption>CRC Card</caption>

  * <tr><th> Responsibilities <th> Collaborations

- * <tr><td> Check that a mandatory message is sent succesfully not using transactions when a consumer is connected.

- * <tr><td> Check that a mandatory message is committed succesfully in a transaction when a consumer is connected.

- * <tr><td> Check that a mandatory message results in no route code, not using transactions, when no consumer is

+ * <tr><td> Check that an mandatory message is sent succesfully not using transactions when a consumer is connected.

+ * <tr><td> Check that an mandatory message is committed succesfully in a transaction when a consumer is connected.

+ * <tr><td> Check that a mandatory message is sent succesfully, not using transactions, when a consumer is disconnected

+ *          but the route exists.

+ * <tr><td> Check that a mandatory message is sent succesfully, in a transaction, when a consumer is disconnected but

+ *          the route exists.

+ * <tr><td> Check that an mandatory message results in no route code, not using transactions, when no consumer is

  *          connected.

- * <tr><td> Check that a mandatory message results in no route code, upon transaction commit, when a consumer is

+ * <tr><td> Check that an mandatory message results in no route code, upon transaction commit, when a consumer is

+ *          connected.

+ * <tr><td> Check that an mandatory message is sent succesfully not using transactions when a consumer is connected.

+ * <tr><td> Check that an mandatory message is committed succesfully in a transaction when a consumer is connected.

+ * <tr><td> Check that a mandatory message is sent succesfully, not using transactions, when a consumer is disconnected

+ *          but the route exists.

+ * <tr><td> Check that a mandatory message is sent succesfully, in a transaction, when a consumer is disconnected but

+ *          the route exists.

+ * <tr><td> Check that an mandatory message results in no route code, not using transactions, when no consumer is

+ *          connected.

+ * <tr><td> Check that an mandatory message results in no route code, upon transaction commit, when a consumer is

  *          connected.

- * <tr><td> Check that a mandatory message is sent succesfully, not using transactions, when a consumer is

- *          disconnected but the route exists.

- * <tr><dt> Check that a mandatory message is send successfully, in a transactions, when a consumer is

- *          disconnected but when the route exists.

  * </table>

  *

  * @todo All of these test cases will be generated by a test generator that thoroughly tests all combinations of test

diff --git a/java/systests/src/main/java/org/apache/qpid/test/framework/AssertionBase.java b/java/systests/src/main/java/org/apache/qpid/test/framework/AssertionBase.java
index e939b66c31..3d83224513 100644
--- a/java/systests/src/main/java/org/apache/qpid/test/framework/AssertionBase.java
+++ b/java/systests/src/main/java/org/apache/qpid/test/framework/AssertionBase.java
@@ -29,7 +29,7 @@ import java.util.List;
  *

  * <p/><table id="crc"><caption>CRC Card</caption>

  * <tr><th> Responsibilities <th> Collaborations

- * <tr><td>

+ * <tr><td> Collect error messages.

  * </table>

  */

 public abstract class AssertionBase implements Assertion

diff --git a/java/systests/src/main/java/org/apache/qpid/test/framework/Circuit.java b/java/systests/src/main/java/org/apache/qpid/test/framework/Circuit.java
index 83a6d7279b..74c14ee6c5 100644
--- a/java/systests/src/main/java/org/apache/qpid/test/framework/Circuit.java
+++ b/java/systests/src/main/java/org/apache/qpid/test/framework/Circuit.java
@@ -20,8 +20,6 @@
  */

 package org.apache.qpid.test.framework;

 

-import uk.co.thebadgerset.junit.extensions.util.ParsedProperties;

-

 import java.util.List;

 

 /**

diff --git a/java/systests/src/main/java/org/apache/qpid/test/framework/CircuitImpl.java b/java/systests/src/main/java/org/apache/qpid/test/framework/CircuitImpl.java
index 936ac57a4b..70bd16353c 100644
--- a/java/systests/src/main/java/org/apache/qpid/test/framework/CircuitImpl.java
+++ b/java/systests/src/main/java/org/apache/qpid/test/framework/CircuitImpl.java
@@ -34,15 +34,20 @@ import java.util.List;
 import java.util.concurrent.atomic.AtomicLong;

 

 /**

+ * CircuitImpl provides an implementation of the test circuit. This is a first prototype implementation and only supports

+ * a single producer/consumer on each end of the circuit, with both ends of the circuit on the same JVM.

+ *

  * <p/><table id="crc"><caption>CRC Card</caption>

  * <tr><th> Responsibilities <th> Collaborations

  * <tr><td> Supply the publishing and receiving ends of a test messaging circuit.

+ *     <td> {@link PublisherImpl}, {@link ReceiverImpl}

  * <tr><td> Start the circuit running.

  * <tr><td> Close the circuit down.

  * <tr><td> Take a reading of the circuits state.

- * <tr><td> Apply assertions against the circuits state.

+ * <tr><td> Apply assertions against the circuits state. <td> {@link Assertion}

  * <tr><td> Send test messages over the circuit.

- * <tr><td> Perform the default test procedue on the circuit.

+ * <tr><td> Perform the default test procedure on the circuit.

+ * <tr><td> Provide access to connection and session exception monitors <td> {@link ExceptionMonitor}

  * </table>

  */

 public class CircuitImpl implements Circuit

@@ -246,7 +251,17 @@ public class CircuitImpl implements Circuit
      */

     public List<Assertion> applyAssertions(List<Assertion> assertions)

     {

-        return null;

+        List<Assertion> failures = new LinkedList<Assertion>();

+

+        for (Assertion assertion : assertions)

+        {

+            if (!assertion.apply())

+            {

+                failures.add(assertion);

+            }

+        }

+

+        return failures;

     }

 

     /**

@@ -331,15 +346,7 @@ public class CircuitImpl implements Circuit
         check();

 

         // Apply all of the requested assertions, keeping record of any that fail.

-        List<Assertion> failures = new LinkedList<Assertion>();

-

-        for (Assertion assertion : assertions)

-        {

-            if (!assertion.apply())

-            {

-                failures.add(assertion);

-            }

-        }

+        List<Assertion> failures = applyAssertions(assertions);

 

         // Clean up the publisher/receiver/session/connections.

         close();

diff --git a/java/systests/src/main/java/org/apache/qpid/test/framework/ExceptionMonitor.java b/java/systests/src/main/java/org/apache/qpid/test/framework/ExceptionMonitor.java
index 9f4e8b2142..606f2eabda 100644
--- a/java/systests/src/main/java/org/apache/qpid/test/framework/ExceptionMonitor.java
+++ b/java/systests/src/main/java/org/apache/qpid/test/framework/ExceptionMonitor.java
@@ -29,30 +29,55 @@ import java.util.ArrayList;
 import java.util.List;

 

 /**

+ * An exception monitor, listens for JMS exception on a connection or consumer. It record all exceptions that it receives

+ * and provides methods to test the number and type of exceptions received.

+ *

  * <p/><table id="crc"><caption>CRC Card</caption>

-* <tr><th> Responsibilities <th> Collaborations

-* <tr><td>

-* </table>

-*/

+ * <tr><th> Responsibilities <th> Collaborations

+ * <tr><td> Record all exceptions received. <td> {@link ExceptionListener}

+ * </table>

+ */

 public class ExceptionMonitor implements ExceptionListener

 {

+    /** Holds the received exceptions. */

     List<JMSException> exceptions = new ArrayList<JMSException>();

 

+    /**

+     * Receives incoming exceptions.

+     *

+     * @param e The exception to record.

+     */

     public void onException(JMSException e)

     {

         exceptions.add(e);

     }

 

+    /**

+     * Checks that no exceptions have been received.

+     *

+     * @return <tt>true</tt> if no exceptions have been received, <tt>false</tt> otherwise.

+     */

     public boolean assertNoExceptions()

     {

         return exceptions.isEmpty();

     }

 

+    /**

+     * Checks that exactly one exception has been received.

+     *

+     * @return <tt>true</tt> if exactly one exception been received, <tt>false</tt> otherwise.

+     */

     public boolean assertOneJMSException()

     {

         return exceptions.size() == 1;

     }

 

+    /**

+     * Checks that exactly one exception, with a linked cause of the specified type, has been received.

+     *

+     * @return <tt>true</tt> if exactly one exception, with a linked cause of the specified type, been received,

+     *         <tt>false</tt> otherwise.

+     */

     public boolean assertOneJMSExceptionWithLinkedCause(Class aClass)

     {

         if (exceptions.size() == 1)

@@ -80,6 +105,9 @@ public class ExceptionMonitor implements ExceptionListener
         return exceptions.size();

     }

 

+    /**

+     * Clears the record of received exceptions.

+     */

     public void reset()

     {

         exceptions = new ArrayList();

diff --git a/java/systests/src/main/java/org/apache/qpid/test/framework/MessageMonitor.java b/java/systests/src/main/java/org/apache/qpid/test/framework/MessageMonitor.java
index 63ff99826b..873f876012 100644
--- a/java/systests/src/main/java/org/apache/qpid/test/framework/MessageMonitor.java
+++ b/java/systests/src/main/java/org/apache/qpid/test/framework/MessageMonitor.java
@@ -24,13 +24,23 @@ import javax.jms.Message;
 import javax.jms.MessageListener;

 

 /**

+ * MessageMonitor is used to record information about messages received. This will provide methods to check various

+ * properties, such as the type, number and content of messages received in order to verify the correct behaviour of

+ * tests.

+ *

+ * <p/>At the moment this monitor does not do anything.

+ *

  * <p/><table id="crc"><caption>CRC Card</caption>

  * <tr><th> Responsibilities <th> Collaborations

- * <tr><td>

  * </table>

  */

 public class MessageMonitor implements MessageListener

 {

+    /**

+     * Handles received messages. Does Nothing.

+     *

+     * @param message The message. Ignored.

+     */

     public void onMessage(Message message)

     { }

 }

diff --git a/java/systests/src/main/java/org/apache/qpid/test/framework/MultiProducerConsumerPairImpl.java b/java/systests/src/main/java/org/apache/qpid/test/framework/MultiProducerConsumerPairImpl.java
index 55bf141f93..88617555d3 100644
--- a/java/systests/src/main/java/org/apache/qpid/test/framework/MultiProducerConsumerPairImpl.java
+++ b/java/systests/src/main/java/org/apache/qpid/test/framework/MultiProducerConsumerPairImpl.java
@@ -28,7 +28,6 @@ import javax.jms.*;
  */

 public class MultiProducerConsumerPairImpl implements CircuitEnd

 {

-

     /**

      * Gets the message producer at this circuit end point.

      *

diff --git a/java/systests/src/main/java/org/apache/qpid/test/framework/Publisher.java b/java/systests/src/main/java/org/apache/qpid/test/framework/Publisher.java
index eed2edfb5e..59aa9065dd 100644
--- a/java/systests/src/main/java/org/apache/qpid/test/framework/Publisher.java
+++ b/java/systests/src/main/java/org/apache/qpid/test/framework/Publisher.java
@@ -23,6 +23,13 @@ package org.apache.qpid.test.framework;
 /**

  * A Publisher is a {@link CircuitEnd} that represents one end of a test circuit. Its main purpose is to

  * provide assertions that can be applied to test the behaviour of the publisher.

+ *

+ * <p/><table id="crc"><caption>CRC Card</caption>

+ * <tr><th> Responsibilities

+ * <tr><td> Provide assertion that the publisher received no exceptions.

+ * <tr><td> Provide assertion that the publisher received a no consumers error code.

+ * <tr><td> Provide assertion that the publisher received a no route error code.

+ * </table>

  */

 public interface Publisher extends CircuitEnd

 {

diff --git a/java/systests/src/main/java/org/apache/qpid/test/framework/PublisherImpl.java b/java/systests/src/main/java/org/apache/qpid/test/framework/PublisherImpl.java
index 46427ce89f..48bb9187fb 100644
--- a/java/systests/src/main/java/org/apache/qpid/test/framework/PublisherImpl.java
+++ b/java/systests/src/main/java/org/apache/qpid/test/framework/PublisherImpl.java
@@ -28,9 +28,16 @@ import javax.jms.MessageProducer;
 import javax.jms.Session;

 

 /**

+ * Provides an implementation of the {@link Publisher} interface that wraps a single message producer and consumer on

+ * a single session.

+ *

  * <p/><table id="crc"><caption>CRC Card</caption>

  * <tr><th> Responsibilities <th> Collaborations

- * <tr><td>

+ * <tr><td> Provide a message producer for sending messages.

+ * <tr><td> Provide a message consumer for receiving messages.

+ * <tr><td> Provide assertion that the publisher received no exceptions.

+ * <tr><td> Provide assertion that the publisher received a no consumers error code.

+ * <tr><td> Provide assertion that the publisher received a no route error code.

  * </table>

  */

 public class PublisherImpl extends CircuitEndBase implements Publisher

diff --git a/java/systests/src/main/java/org/apache/qpid/test/framework/Receiver.java b/java/systests/src/main/java/org/apache/qpid/test/framework/Receiver.java
index 526537349a..a79e29ef67 100644
--- a/java/systests/src/main/java/org/apache/qpid/test/framework/Receiver.java
+++ b/java/systests/src/main/java/org/apache/qpid/test/framework/Receiver.java
@@ -23,6 +23,12 @@ package org.apache.qpid.test.framework;
 /**

  * A Receiver is a {@link CircuitEnd} that represents one end of a test circuit. Its main purpose is to

  * provide assertions that can be applied to test the behaviour of the receiver.

+ *

+ * <p/><table id="crc"><caption>CRC Card</caption>

+ * <tr><th> Responsibilities

+ * <tr><td> Provide assertion that the receiver received no exceptions.

+ * <tr><td> Provide assertion that the receiver received all test messages sent to it.

+ * </table>

  */

 public interface Receiver extends CircuitEnd

 {

diff --git a/java/systests/src/main/java/org/apache/qpid/test/framework/ReceiverImpl.java b/java/systests/src/main/java/org/apache/qpid/test/framework/ReceiverImpl.java
index 5f0cb83e63..06ca8e8cc3 100644
--- a/java/systests/src/main/java/org/apache/qpid/test/framework/ReceiverImpl.java
+++ b/java/systests/src/main/java/org/apache/qpid/test/framework/ReceiverImpl.java
@@ -25,9 +25,15 @@ import javax.jms.MessageProducer;
 import javax.jms.Session;

 

 /**

+ * Provides an implementation of the {@link Receiver} interface that wraps a single message producer and consumer on

+ * a single session.

+ *

  * <p/><table id="crc"><caption>CRC Card</caption>

  * <tr><th> Responsibilities <th> Collaborations

- * <tr><td>

+ * <tr><td> Provide a message producer for sending messages.

+ * <tr><td> Provide a message consumer for receiving messages.

+ * <tr><td> Provide assertion that the receiver received no exceptions.

+ * <tr><td> Provide assertion that the receiver received all test messages sent to it.

  * </table>

  */

 public class ReceiverImpl extends CircuitEndBase implements Receiver

diff --git a/java/systests/src/main/java/org/apache/qpid/test/framework/TestUtils.java b/java/systests/src/main/java/org/apache/qpid/test/framework/TestUtils.java
index 60dd4b0f5b..c3d68ce66c 100644
--- a/java/systests/src/main/java/org/apache/qpid/test/framework/TestUtils.java
+++ b/java/systests/src/main/java/org/apache/qpid/test/framework/TestUtils.java
@@ -32,9 +32,12 @@ import javax.naming.InitialContext;
 import javax.naming.NamingException;

 

 /**

+ * TestUtils provides static helper methods that are usefull for writing tests against QPid.

+ *

  * <p/><table id="crc"><caption>CRC Card</caption>

  * <tr><th> Responsibilities <th> Collaborations

- * <tr><td>

+ * <tr><td> Create connections from test properties. <td> {@link MessagingTestConfigProperties}

+ * <tr><td> Inject a short pause in a test.

  * </table>

  */

 public class TestUtils