Mailing-List: contact commits-help@geode.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@geode.incubator.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: dschneider@apache.org
To: commits@geode.incubator.apache.org
Date: Thu, 31 Mar 2016 22:45:32 -0000
Message-Id: <fab024ff32fe48d7b2e85e86e8d12c70@git.apache.org>
In-Reply-To: <b27a7fd4b794437a83e5413d8620993a@git.apache.org>
References: <b27a7fd4b794437a83e5413d8620993a@git.apache.org>
Subject: [65/71] [abbrv] incubator-geode git commit: GEODE-1152: improve
 javadocs with guidelines for Awaitility

GEODE-1152: improve javadocs with guidelines for Awaitility


Project: http://git-wip-us.apache.org/repos/asf/incubator-geode/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-geode/commit/7708c3f9
Tree: http://git-wip-us.apache.org/repos/asf/incubator-geode/tree/7708c3f9
Diff: http://git-wip-us.apache.org/repos/asf/incubator-geode/diff/7708c3f9

Branch: refs/heads/feature/GEODE-915
Commit: 7708c3f94c44736c7d3b21a7b4c9bbf0fd64c815
Parents: 51acabc
Author: Kirk Lund <klund@apache.org>
Authored: Wed Mar 30 17:31:23 2016 -0700
Committer: Kirk Lund <klund@apache.org>
Committed: Thu Mar 31 10:31:46 2016 -0700

----------------------------------------------------------------------
 .../com/gemstone/gemfire/test/dunit/Wait.java   | 70 +++++++++++++++++++-
 .../gemfire/test/dunit/WaitCriterion.java       | 12 +++-
 2 files changed, 78 insertions(+), 4 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/7708c3f9/geode-core/src/test/java/com/gemstone/gemfire/test/dunit/Wait.java
----------------------------------------------------------------------
diff --git a/geode-core/src/test/java/com/gemstone/gemfire/test/dunit/Wait.java b/geode-core/src/test/java/com/gemstone/gemfire/test/dunit/Wait.java
index 3e218df..b73a25c 100755
--- a/geode-core/src/test/java/com/gemstone/gemfire/test/dunit/Wait.java
+++ b/geode-core/src/test/java/com/gemstone/gemfire/test/dunit/Wait.java
@@ -28,7 +28,7 @@ import com.gemstone.gemfire.internal.logging.LogService;
  * <code>Wait</code> provides static utility methods to wait for some
  * asynchronous action with intermittent polling.
  * 
- * These methods can be used directly: <code>Wait.waitForCriterion(...)</code>, 
+ * These methods can be used directly: <code>Wait.waitForCriterion(...)</code>,
  * however, they are intended to be referenced through static import:
  *
  * <pre>
@@ -38,8 +38,74 @@ import com.gemstone.gemfire.internal.logging.LogService;
  * </pre>
  *
  * Extracted from DistributedTestCase.
- * 
+ *
+ * <p>Deprecated in favor of using {@link com.jayway.awaitility.Awaitility}.
+ *
+ * <p>Examples of using Awaitility:<pre>
+ *
+ * import static com.jayway.awaitility.Awaitility.*;
+ * import static com.jayway.awaitility.Duration.*; // optional
+ * import static java.util.concurrent.TimeUnit.*; // optional
+ *
+ * await().atMost(2, SECONDS).until(() -> isDone());
+ *
+ * Host.getHost(0).getVM(0).invoke(() -> await().atMost(1, MINUTES).until(() -> isDone()));
+ *
+ * Host.getHost(0).getVM(0).invoke(() -> await("waiting for 4 members").atMost(5, SECONDS).until(() -> getMemberCount(), is(4)));
+ *
+ * await().atMost(5, SECONDS).untilCall(getValue(), equalTo(5));
+ *
+ * volatile boolean done = false;
+ * await().atMost(2, SECONDS).untilCall(Boolean.class, equalTo(this.done));
+ *
+ * AtomicBoolean closed = new AtomicBoolean();
+ * await().atMost(5, SECONDS).untilTrue(closed);
+ *
+ * AtomicBoolean running = new AtomicBoolean();
+ * await().atMost(30, SECONDS).untilFalse(running);
+ *
+ * List members = new ArrayList();
+ * await().untilCall(to(members).size(), greaterThan(2));
+ * </pre>
+ *
+ * <p>NOTE: By default, the pollDelay is equal to the pollInterval which defaults to
+ * ONE_HUNDRED_MILLISECONDS. You may want to add pollDelay(ZERO) to force
+ * Awaitility to check your condition before waiting the pollInterval.
+ *
+ * <p>Example of detailed conversion to Awaitility:<pre>
+ * From:
+ *
+ * public boolean waitForClose() {
+ *   WaitCriterion ev = new WaitCriterion() {
+ *     public boolean done() {
+ *       return isClosed();
+ *     }
+ *     public String description() {
+ *       return "resource never closed";
+ *     }
+ *   };
+ *   Wait.waitForCriterion(ev, 2000, 200, true);
+ *   return true;
+ * }
+ *
+ * To:
+ *
+ * import static com.jayway.awaitility.Awaitility.*;
+ * import static com.jayway.awaitility.Duration.*;
+ * import static java.util.concurrent.TimeUnit.*;
+ *
+ * await("resource never closed").atMost(2, SECONDS).untilCall(() -> isClosed());
+ *
+ * Or:
+ *
+ * await("resource never closed").atMost(2, SECONDS).pollDelay(ZERO).pollInterval(200, MILLISECONDS).untilCall(() -> isClosed());
+ * </pre>
+ *
  * @deprecated Use {@link com.jayway.awaitility.Awaitility} instead.
+ *
+ * @see com.jayway.awaitility.Awaitility
+ * @see com.jayway.awaitility.Duration
+ * @see com.jayway.awaitility.core.ConditionFactory
  */
 @Deprecated
 public class Wait {

http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/7708c3f9/geode-core/src/test/java/com/gemstone/gemfire/test/dunit/WaitCriterion.java
----------------------------------------------------------------------
diff --git a/geode-core/src/test/java/com/gemstone/gemfire/test/dunit/WaitCriterion.java b/geode-core/src/test/java/com/gemstone/gemfire/test/dunit/WaitCriterion.java
index 7575f8c..e62d354 100755
--- a/geode-core/src/test/java/com/gemstone/gemfire/test/dunit/WaitCriterion.java
+++ b/geode-core/src/test/java/com/gemstone/gemfire/test/dunit/WaitCriterion.java
@@ -20,9 +20,17 @@ package com.gemstone.gemfire.test.dunit;
  * Defines an asynchronous criterion to wait for by invoking a method in 
  * {@link Wait}.
  *
- * Extracted from DistributedTestCase.
- * 
+ * <p>Extracted from DistributedTestCase.
+ *
+ * <p>See javadocs on {@link Wait} for examples and guidelines for converting
+ * to Awaitility.
+ *
  * @deprecated Use {@link com.jayway.awaitility.Awaitility} instead.
+ *
+ * @see Wait
+ * @see com.jayway.awaitility.Awaitility
+ * @see com.jayway.awaitility.Duration
+ * @see com.jayway.awaitility.core.ConditionFactory
  */
 public interface WaitCriterion {