[jbosscache-commits] JBoss Cache SVN: r7615 - core/branches/flat/src/test/java/org/horizon.

[jbosscache-commits at lists.jboss.org]

Author: manik.surtani at jboss.com
Date: 2009-01-30 09:22:32 -0500 (Fri, 30 Jan 2009)
New Revision: 7615

Modified:
   core/branches/flat/src/test/java/org/horizon/BaseClusteredTest.java
Log:
Javadoc

Modified: core/branches/flat/src/test/java/org/horizon/BaseClusteredTest.java
===================================================================
--- core/branches/flat/src/test/java/org/horizon/BaseClusteredTest.java	2009-01-30 14:10:03 UTC (rev 7614)
+++ core/branches/flat/src/test/java/org/horizon/BaseClusteredTest.java	2009-01-30 14:22:32 UTC (rev 7615)
@@ -22,6 +22,17 @@
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
 
+/**
+ * A base class that <i>all</i> tests that use clustering needs to extend.  <tt>CacheManager</tt>s should <i>only</b> be
+ * created using the methods here, since this class takes care of proper cleanup of the clustering stack.
+ * <p/>
+ * This class also offers some cluster-specific helper methods, like {@link #assertClusterSize(String, int)} and {@link
+ * #attachReplicationListener(Cache)}, the latter which allows you to attach listeners to caches and block until RPC
+ * calls are received.  While this is most useful on asynchronous tests, it does not break synchronous tests either so
+ * test code could be reused.
+ * <p/>
+ * See {@link org.horizon.BaseClusteredTest.ReplListener} for details.
+ */
 public abstract class BaseClusteredTest {
    ThreadLocal<List<CacheManager>> cacheManagerThreadLocal = new ThreadLocal<List<CacheManager>>() {
       @Override
@@ -91,6 +102,10 @@
       cacheManagerThreadLocal.get().clear();
    }
 
+   /**
+    * A listener that listens for replication events on a cache it is watching.  Typical usage: <code> ReplListener r =
+    * attachReplicationListener(cache); r.expect(RemoveCommand.class); // ... r.waitForRPC(); </code>
+    */
    protected static class ReplListener {
       Cache c;
       Set<Class<? extends VisitableCommand>> expectedCommands;
@@ -101,10 +116,21 @@
          this.c.addInterceptor(new ReplListenerInterceptor(), 0);
       }
 
+      /**
+       * Expects any commands.  The moment a single command is detected, the {@link #waitForRPC()} command will be
+       * unblocked.
+       */
       public void expectAny() {
          expect();
       }
 
+      /**
+       * Expects a specific set of commands, within transactional scope (i.e., as a payload to a PrepareCommand).  If
+       * the cache mode is synchronous, a CommitCommand is expected as well.
+       *
+       * @param commands commands to expect (not counting transaction boundary commands like PrepareCommand and
+       *                 CommitCommand)
+       */
       public void expectWithTx(Class<? extends VisitableCommand>... commands) {
          expect(PrepareCommand.class);
          expect(commands);
@@ -112,12 +138,22 @@
          if (c.getConfiguration().getCacheMode().isSynchronous()) expect(CommitCommand.class);
       }
 
+      /**
+       * Expects any commands, within transactional scope (i.e., as a payload to a PrepareCommand).  If the cache mode
+       * is synchronous, a CommitCommand is expected as well.
+       */
       public void expectAnyWithTx() {
          expect(PrepareCommand.class);
          //this is because for async replication we have an 1pc transaction
          if (c.getConfiguration().getCacheMode().isSynchronous()) expect(CommitCommand.class);
       }
 
+      /**
+       * Expects a specific set of commands.  {@link #waitForRPC()} will block until all of these commands are
+       * detected.
+       *
+       * @param expectedCommands commands to expect
+       */
       public void expect(Class<? extends VisitableCommand>... expectedCommands) {
          if (this.expectedCommands == null) {
             this.expectedCommands = new HashSet<Class<? extends VisitableCommand>>();
@@ -125,10 +161,17 @@
          this.expectedCommands.addAll(Arrays.asList(expectedCommands));
       }
 
+      /**
+       * Blocks for a predefined amount of time (120 Seconds) until commands defined in any of the expect*() methods
+       * have been detected.  If the commands have not been detected by this time, an exception is thrown.
+       */
       public void waitForRPC() {
          waitForRPC(120, TimeUnit.SECONDS);
       }
 
+      /**
+       * The same as {@link #waitForRPC()} except that you are allowed to specify the max wait time.
+       */
       public void waitForRPC(long time, TimeUnit unit) {
          assert expectedCommands != null : "there are no replication expectations; please use ReplListener.expect() before calling this method";
          try {