Author: manik.surtani(a)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 {