You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@zookeeper.apache.org by ha...@apache.org on 2019/09/05 20:59:24 UTC
[zookeeper] branch master updated: ZOOKEEPER-3528: Revisit
AsyncCallback javadoc
This is an automated email from the ASF dual-hosted git repository.
hanm pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/zookeeper.git
The following commit(s) were added to refs/heads/master by this push:
new 47385c7 ZOOKEEPER-3528: Revisit AsyncCallback javadoc
47385c7 is described below
commit 47385c75e0e0d0a48e71122df989effd55f0fe59
Author: tison <wa...@gmail.com>
AuthorDate: Thu Sep 5 13:59:14 2019 -0700
ZOOKEEPER-3528: Revisit AsyncCallback javadoc
Sub-tasks of ZOOKEEPER-3469. We could improve our javadoc documentation quality.
Author: tison <wa...@gmail.com>
Reviewers: Michael Han <ha...@apache.org>, Enrico Olivelli <eo...@gmail.com>
Closes #1070 from TisonKun/ZOOKEEPER-3528
---
.../java/org/apache/zookeeper/AsyncCallback.java | 301 ++++++++++-----------
1 file changed, 138 insertions(+), 163 deletions(-)
diff --git a/zookeeper-server/src/main/java/org/apache/zookeeper/AsyncCallback.java b/zookeeper-server/src/main/java/org/apache/zookeeper/AsyncCallback.java
index b8e2426..918d118 100644
--- a/zookeeper-server/src/main/java/org/apache/zookeeper/AsyncCallback.java
+++ b/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.