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 <wander4...@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 <wander4...@gmail.com> Reviewers: Michael Han <h...@apache.org>, Enrico Olivelli <eolive...@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.