ZOOKEEPER-3528: Revisit AsyncCallback javadoc

Sub-tasks of ZOOKEEPER-3469. We could improve our javadoc documentation quality.

Author: tison <wander4096@gmail.com>

Reviewers: Michael Han <hanm@apache.org>, Enrico Olivelli <eolivelli@gmail.com>

Closes #1070 from TisonKun/ZOOKEEPER-3528

zookeeper-server/src/main/java/org/apache/zookeeper/AsyncCallback.java

@@ -25,10 +25,15 @@ import org.apache.zookeeper.data.Stat;
 
 /**
  * Interface definitions of asynchronous callbacks.
- * An asynchronous callback is deferred to invoke after a function returns.
+ *
+ * <p>ZooKeeper provides asynchronous version as equivalent to synchronous APIs.
+ *
+ * <p>An asynchronous callback is deferred to invoke after a function returns.
  * Asynchronous calls usually improve system efficiency on IO-related APIs.
- * <p>
- * ZooKeeper provides asynchronous version as equivalent to synchronous APIs.
+ *
+ * <p>It is highly recommended NOT to perform any blocking operation inside
+ * the callbacks. If you block the thread the ZooKeeper client won't process
+ * other events.
  */
 @InterfaceAudience.Public
 public interface AsyncCallback {
@@ -41,46 +46,45 @@ public interface AsyncCallback {
 
         /**
          * Process the result of the asynchronous call.
-         * <p>
-         * On success, rc is
-         * {@link org.apache.zookeeper.KeeperException.Code#OK}.
-         * <p>
-         * On failure, rc is set to the corresponding failure code in
-         * {@link org.apache.zookeeper.KeeperException}.
+         *
+         * <p>On success, rc is {@link KeeperException.Code#OK}.
+         *
+         * <p>On failure, rc is set to the corresponding failure code in {@link KeeperException}.
          * <ul>
-         * <li>
-         * {@link org.apache.zookeeper.KeeperException.Code#NONODE}
-         * - The node on given path doesn't exist for some API calls.
-         * </li>
-         * <li>
-         * {@link org.apache.zookeeper.KeeperException.Code#BADVERSION}
-         * - The given version doesn't match the node's version
-         * for some API calls.
-         * </li>
+         *  <li> {@link KeeperException.Code#NONODE}
+         *              - The node on given path doesn't exist for some API calls.</li>
+         *  <li> {@link KeeperException.Code#BADVERSION}
+         *              - The given version doesn't match the node's version for some API calls.</li>
          * </ul>
          *
          * @param rc   The return code or the result of the call.
          * @param path The path that we passed to asynchronous calls.
-         * @param ctx  Whatever context object that we passed to
-         *             asynchronous calls.
-         * @param stat {@link org.apache.zookeeper.data.Stat} object of
-         *             the node on given path.
+         * @param ctx  Whatever context object that we passed to asynchronous calls.
+         * @param stat {@link Stat} object of the node on given path.
+         *
+         * @see ZooKeeper#exists(String, boolean, StatCallback, Object)
+         * @see ZooKeeper#exists(String, Watcher, StatCallback, Object)
+         * @see ZooKeeper#setData(String, byte[], int, StatCallback, Object)
+         * @see ZooKeeper#setACL(String, List, int, StatCallback, Object)
          */
         void processResult(int rc, String path, Object ctx, Stat stat);
 
     }
 
     /**
-     *  This callback is used to get all children node number of the node.
+     * This callback is used to get all children node number of the node.
+     *
+     * @since 3.6.0
      */
     @InterfaceAudience.Public
     interface AllChildrenNumberCallback extends AsyncCallback {
 
         /**
-         *
          * @param rc      The return code or the result of the call.
          * @param ctx     Whatever context object that we passed to asynchronous calls.
-         * @param number  the number of children nodes under a specific path
+         * @param number  The number of children nodes under a specific path.
+         *
+         * @see ZooKeeper#getAllChildrenNumber(String, AllChildrenNumberCallback, Object)
          */
         void processResult(int rc, String path, Object ctx, int number);
 
@@ -94,27 +98,25 @@ public interface AsyncCallback {
 
         /**
          * Process the result of asynchronous calls.
-         * <p>
-         * On success, rc is
-         * {@link org.apache.zookeeper.KeeperException.Code#OK}.
-         * <p>
-         * On failure, rc is set to the corresponding failure code in
-         * {@link org.apache.zookeeper.KeeperException}.
+         *
+         * <p>On success, rc is {@link KeeperException.Code#OK}.
+         *
+         * <p>On failure, rc is set to the corresponding failure code in {@link KeeperException}.
          * <ul>
-         * <li>
-         * {@link org.apache.zookeeper.KeeperException.Code#NONODE}
-         * - The node on given path doesn't exist for some API calls.
-         * </li>
+         *  <li>{@link KeeperException.Code#NONODE}
+         *             - The node on given path doesn't exist for some API calls.</li>
          * </ul>
          *
          * @param rc   The return code or the result of the call.
          * @param path The path that we passed to asynchronous calls.
-         * @param ctx  Whatever context object that we passed to
-         *             asynchronous calls.
-         * @param data The {@link org.apache.zookeeper.server.DataNode#data}
-         *             of the node.
-         * @param stat {@link org.apache.zookeeper.data.Stat} object of
-         *             the node on given path.
+         * @param ctx  Whatever context object that we passed to asynchronous calls.
+         * @param data The data of the node.
+         * @param stat {@link Stat} object of the node on given path.
+         *
+         * @see ZooKeeper#getData(String, boolean, DataCallback, Object)
+         * @see ZooKeeper#getData(String, Watcher, DataCallback, Object)
+         * @see ZooKeeper#getConfig(boolean, DataCallback, Object)
+         * @see ZooKeeper#getConfig(Watcher, DataCallback, Object)
          */
         void processResult(int rc, String path, Object ctx, byte[] data, Stat stat);
 
@@ -128,27 +130,22 @@ public interface AsyncCallback {
 
         /**
          * Process the result of the asynchronous call.
-         * <p>
-         * On success, rc is
-         * {@link org.apache.zookeeper.KeeperException.Code#OK}.
-         * <p>
-         * On failure, rc is set to the corresponding failure code in
-         * {@link org.apache.zookeeper.KeeperException}.
+         *
+         * <p>On success, rc is {@link KeeperException.Code#OK}.
+         *
+         * <p>On failure, rc is set to the corresponding failure code in {@link KeeperException}.
          * <ul>
-         * <li>
-         * {@link org.apache.zookeeper.KeeperException.Code#NONODE}
-         * - The node on given path doesn't exist for some API calls.
-         * </li>
+         *  <li>{@link KeeperException.Code#NONODE}
+         *             - The node on given path doesn't exist for some API calls.</li>
          * </ul>
          *
          * @param rc   The return code or the result of the call.
          * @param path The path that we passed to asynchronous calls.
-         * @param ctx  Whatever context object that we passed to
-         *             asynchronous calls.
-         * @param acl  ACL Id in
-         *             {@link org.apache.zookeeper.ZooDefs.Ids}.
-         * @param stat {@link org.apache.zookeeper.data.Stat} object of
-         *             the node on given path.
+         * @param ctx  Whatever context object that we passed to asynchronous calls.
+         * @param acl  ACL Id in {@link ZooDefs.Ids}.
+         * @param stat {@link Stat} object of the node on given path.
+         *
+         * @see ZooKeeper#getACL(String, Stat, ACLCallback, Object)
          */
         void processResult(int rc, String path, Object ctx, List<ACL> acl, Stat stat);
 
@@ -162,25 +159,22 @@ public interface AsyncCallback {
 
         /**
          * Process the result of the asynchronous call.
-         * <p>
-         * On success, rc is
-         * {@link org.apache.zookeeper.KeeperException.Code#OK}.
-         * <p>
-         * On failure, rc is set to the corresponding failure code in
-         * {@link org.apache.zookeeper.KeeperException}.
+         *
+         * <p>On success, rc is {@link KeeperException.Code#OK}.
+         *
+         * <p>On failure, rc is set to the corresponding failure code in {@link KeeperException}.
          * <ul>
-         * <li>
-         * {@link org.apache.zookeeper.KeeperException.Code#NONODE}
-         * - The node on given path doesn't exist for some API calls.
-         * </li>
+         *  <li>{@link KeeperException.Code#NONODE}
+         *             - The node on given path doesn't exist for some API calls.</li>
          * </ul>
          *
          * @param rc       The return code or the result of the call.
          * @param path     The path that we passed to asynchronous calls.
-         * @param ctx      Whatever context object that we passed to
-         *                 asynchronous calls.
-         * @param children An unordered array of children of the node on
-         *                 given path.
+         * @param ctx      Whatever context object that we passed to asynchronous calls.
+         * @param children An unordered array of children of the node on given path.
+         *
+         * @see ZooKeeper#getChildren(String, boolean, ChildrenCallback, Object)
+         * @see ZooKeeper#getChildren(String, Watcher, ChildrenCallback, Object)
          */
         void processResult(int rc, String path, Object ctx, List<String> children);
 
@@ -194,16 +188,16 @@ public interface AsyncCallback {
 
         /**
          * Process the result of the asynchronous call.
-         * See {@link org.apache.zookeeper.AsyncCallback.ChildrenCallback}.
          *
          * @param rc       The return code or the result of the call.
          * @param path     The path that we passed to asynchronous calls.
-         * @param ctx      Whatever context object that we passed to
-         *                 asynchronous calls.
-         * @param children An unordered array of children of the node on
-         *                 given path.
-         * @param stat     {@link org.apache.zookeeper.data.Stat} object of
-         *                 the node on given path.
+         * @param ctx      Whatever context object that we passed to asynchronous calls.
+         * @param children An unordered array of children of the node on given path.
+         * @param stat     {@link Stat} object of the node on given path.
+         *
+         * @see ChildrenCallback
+         * @see ZooKeeper#getChildren(String, boolean, Children2Callback, Object)
+         * @see ZooKeeper#getChildren(String, Watcher, Children2Callback, Object)
          */
         void processResult(int rc, String path, Object ctx, List<String> children, Stat stat);
 
@@ -217,17 +211,18 @@ public interface AsyncCallback {
 
         /**
          * Process the result of the asynchronous call.
-         * See {@link org.apache.zookeeper.AsyncCallback.StringCallback}.
          *
          * @param rc   The return code or the result of the call.
          * @param path The path that we passed to asynchronous calls.
-         * @param ctx  Whatever context object that we passed to
-         *             asynchronous calls.
-         * @param name The name of the Znode that was created.
-         *             On success, <i>name</i> and <i>path</i> are usually
-         *             equal, unless a sequential node has been created.
-         * @param stat {@link org.apache.zookeeper.data.Stat} object of
-         *             the node on given path.
+         * @param ctx  Whatever context object that we passed to asynchronous calls.
+         * @param name The name of the Znode that was created. On success, <i>name</i>
+         *             and <i>path</i> are usually equal, unless a sequential node has
+         *             been created.
+         * @param stat {@link Stat} object of the node on given path.
+         *
+         * @see StringCallback
+         * @see ZooKeeper#create(String, byte[], List, CreateMode, Create2Callback, Object)
+         * @see ZooKeeper#create(String, byte[], List, CreateMode, Create2Callback, Object, long)
          */
         void processResult(int rc, String path, Object ctx, String name, Stat stat);
 
@@ -241,130 +236,110 @@ public interface AsyncCallback {
 
         /**
          * Process the result of the asynchronous call.
-         * <p>
-         * On success, rc is
-         * {@link org.apache.zookeeper.KeeperException.Code#OK}.
-         * <p>
-         * On failure, rc is set to the corresponding failure code in
-         * {@link org.apache.zookeeper.KeeperException}.
+         *
+         * <p>On success, rc is {@link KeeperException.Code#OK}.
+         *
+         * <p>On failure, rc is set to the corresponding failure code in {@link KeeperException}.
          * <ul>
-         * <li>
-         * {@link org.apache.zookeeper.KeeperException.Code#NODEEXISTS}
-         * - The node on give path already exists for some API calls.
-         * </li>
-         * <li>
-         * {@link org.apache.zookeeper.KeeperException.Code#NONODE}
-         * - The node on given path doesn't exist for some API calls.
-         * </li>
-         * <li>
-         * {@link
-         * org.apache.zookeeper.KeeperException.Code#NOCHILDRENFOREPHEMERALS}
-         * - an ephemeral node cannot have children. There is discussion in
-         * community. It might be changed in the future.
-         * </li>
+         *  <li>{@link KeeperException.Code#NODEEXISTS}
+         *             - The node on give path already exists for some API calls.</li>
+         *  <li>{@link KeeperException.Code#NONODE}
+         *             - The node on given path doesn't exist for some API calls.</li>
+         *  <li>{@link KeeperException.Code#NOCHILDRENFOREPHEMERALS}
+         *             - An ephemeral node cannot have children. There is discussion in
+         *             community. It might be changed in the future.</li>
          * </ul>
          *
          * @param rc   The return code or the result of the call.
          * @param path The path that we passed to asynchronous calls.
-         * @param ctx  Whatever context object that we passed to
-         *             asynchronous calls.
-         * @param name The name of the Znode that was created.
-         *             On success, <i>name</i> and <i>path</i> are usually
-         *             equal, unless a sequential node has been created.
+         * @param ctx  Whatever context object that we passed to asynchronous calls.
+         * @param name The name of the znode that was created. On success, <i>name</i>
+         *             and <i>path</i> are usually equal, unless a sequential node has
+         *             been created.
+         *
+         * @see ZooKeeper#create(String, byte[], List, CreateMode, StringCallback, Object)
          */
         void processResult(int rc, String path, Object ctx, String name);
 
     }
 
     /**
-     * This callback doesn't retrieve anything from the node. It is useful
-     * for some APIs that doesn't want anything sent back, e.g. {@link
-     * org.apache.zookeeper.ZooKeeper#sync(String,
-     * org.apache.zookeeper.AsyncCallback.VoidCallback, Object)}.
+     * This callback doesn't retrieve anything from the node. It is useful for some APIs
+     * that doesn't want anything sent back, e.g. {@link ZooKeeper#sync(String, VoidCallback, Object)}.
      */
     @InterfaceAudience.Public
     interface VoidCallback extends AsyncCallback {
 
         /**
          * Process the result of the asynchronous call.
-         * <p>
-         * On success, rc is
-         * {@link org.apache.zookeeper.KeeperException.Code#OK}.
-         * <p>
-         * On failure, rc is set to the corresponding failure code in
-         * {@link org.apache.zookeeper.KeeperException}.
+         *
+         * <p>On success, rc is {@link KeeperException.Code#OK}.
+         *
+         * <p>On failure, rc is set to the corresponding failure code in {@link KeeperException}.
          * <ul>
-         * <li>
-         * {@link org.apache.zookeeper.KeeperException.Code#NONODE}
-         * - The node on given path doesn't exist for some API calls.
-         * </li>
-         * <li>
-         * {@link org.apache.zookeeper.KeeperException.Code#BADVERSION}
-         * - The given version doesn't match the node's version
-         * for some API calls.
-         * </li>
-         * <li>
-         * {@link org.apache.zookeeper.KeeperException.Code#NOTEMPTY}
-         * - the node has children and some API calls cannnot succeed,
-         * e.g. {@link
-         * org.apache.zookeeper.ZooKeeper#delete(String, int,
-         * org.apache.zookeeper.AsyncCallback.VoidCallback, Object)}.
-         * </li>
+         *  <li>{@link KeeperException.Code#NONODE}
+         *             - The node on given path doesn't exist for some API calls.</li>
+         *  <li>{@link KeeperException.Code#BADVERSION}
+         *             - The given version doesn't match the node's version for some API calls.</li>
+         *  <li>{@link KeeperException.Code#NOTEMPTY}
+         *             - the node has children and some API calls cannot succeed, e.g.
+         *             {@link ZooKeeper#delete(String, int, VoidCallback, Object)}.</li>
          * </ul>
          *
          * @param rc   The return code or the result of the call.
          * @param path The path that we passed to asynchronous calls.
-         * @param ctx  Whatever context object that we passed to
-         *             asynchronous calls.
+         * @param ctx  Whatever context object that we passed to asynchronous calls.
+         *
+         * @see ZooKeeper#delete(String, int, VoidCallback, Object)
+         * @see ZooKeeper#removeAllWatches(String, Watcher.WatcherType, boolean, VoidCallback, Object)
+         * @see ZooKeeper#removeWatches(String, Watcher, Watcher.WatcherType, boolean, VoidCallback, Object)
+         * @see ZooKeeper#sync(String, VoidCallback, Object)
+         *
          */
         void processResult(int rc, String path, Object ctx);
 
     }
 
     /**
-     * This callback is used to process the multiple results from
-     * a single multi call.
-     * See {@link org.apache.zookeeper.ZooKeeper#multi} for more information.
+     * This callback is used to process the multiple results from a single multi call.
      */
     @InterfaceAudience.Public
     interface MultiCallback extends AsyncCallback {
 
         /**
          * Process the result of the asynchronous call.
-         * <p>
-         * On success, rc is
-         * {@link org.apache.zookeeper.KeeperException.Code#OK}.
-         * All opResults are
-         * non-{@link org.apache.zookeeper.OpResult.ErrorResult},
-         *
-         * <p>
-         * On failure, rc is a failure code in
-         * {@link org.apache.zookeeper.KeeperException.Code}.
-         * Either opResults is null, or all opResults are
-         * {@link org.apache.zookeeper.OpResult.ErrorResult}.
-         * All operations will be rolled back even if operations
-         * before the failing one were successful.
+         *
+         * <p>On success, rc is {@link KeeperException.Code#OK}. All {@code opResults} are
+         * non-{@link OpResult.ErrorResult}.
+         *
+         * <p>On failure, rc is a failure code in {@link KeeperException.Code}. Either
+         * {@code opResults} is null, or all {@code opResults} are {@link OpResult.ErrorResult}.
+         * All operations will be rolled back even if operations before the failing one were
+         * successful.
          *
          * @param rc   The return code or the result of the call.
          * @param path The path that we passed to asynchronous calls.
-         * @param ctx  Whatever context object that we passed to
-         *             asynchronous calls.
-         * @param opResults The list of results.
-         *                  One result for each operation,
-         *                  and the order matches that of input.
+         * @param ctx  Whatever context object that we passed to asynchronous calls.
+         * @param opResults The list of results. One result for each operation, and the order
+         *                  matches that of input.
+         *
+         * @see ZooKeeper#multi(Iterable, MultiCallback, Object)
          */
         void processResult(int rc, String path, Object ctx, List<OpResult> opResults);
 
     }
 
     /**
-     * This callback is used to process the getEphemerals results from
-     * a single getEphemerals call.
+     * This callback is used to process the getEphemerals results from a single getEphemerals call.
+     *
+     * @see ZooKeeper#getEphemerals(EphemeralsCallback, Object)
+     * @see ZooKeeper#getEphemerals(String, EphemeralsCallback, Object)
+     *
+     * @since 3.6.0
      */
     interface EphemeralsCallback extends AsyncCallback {
 
         /**
-         *
          * @param rc      The return code or the result of the call.
          * @param ctx     Whatever context object that we passed to asynchronous calls.
          * @param paths   The path that we passed to asynchronous calls.