org.apache.zookeeper.AsyncCallback Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.zookeeper;
import java.util.List;
import org.apache.yetus.audience.InterfaceAudience;
import org.apache.zookeeper.data.ACL;
import org.apache.zookeeper.data.Stat;
/**
* Interface definitions of asynchronous callbacks.
*
* ZooKeeper provides asynchronous version as equivalent to synchronous APIs.
*
*
An asynchronous callback is deferred to invoke after a function returns.
* Asynchronous calls usually improve system efficiency on IO-related APIs.
*
*
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 {
/**
* This callback is used to retrieve the stat of the node.
*/
@InterfaceAudience.Public
interface StatCallback extends AsyncCallback {
/**
* Process the result of the asynchronous call.
*
*
On success, rc is {@link KeeperException.Code#OK}.
*
*
On failure, rc is set to the corresponding failure code in {@link KeeperException}.
*
* - {@link KeeperException.Code#NONODE}
* - The node on given path doesn't exist for some API calls.
* - {@link KeeperException.Code#BADVERSION}
* - The given version doesn't match the node's version for some API calls.
*
*
* @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 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.
*
* @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.
*
* @see ZooKeeper#getAllChildrenNumber(String, AllChildrenNumberCallback, Object)
*/
void processResult(int rc, String path, Object ctx, int number);
}
/**
* This callback is used to retrieve the data and stat of the node.
*/
@InterfaceAudience.Public
interface DataCallback extends AsyncCallback {
/**
* Process the result of asynchronous calls.
*
* On success, rc is {@link KeeperException.Code#OK}.
*
*
On failure, rc is set to the corresponding failure code in {@link KeeperException}.
*
* - {@link KeeperException.Code#NONODE}
* - The node on given path doesn't exist for some API calls.
*
*
* @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 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);
}
/**
* This callback is used to retrieve the ACL and stat of the node.
*/
@InterfaceAudience.Public
interface ACLCallback extends AsyncCallback {
/**
* Process the result of the asynchronous call.
*
* On success, rc is {@link KeeperException.Code#OK}.
*
*
On failure, rc is set to the corresponding failure code in {@link KeeperException}.
*
* - {@link KeeperException.Code#NONODE}
* - The node on given path doesn't exist for some API calls.
*
*
* @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 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, Stat stat);
}
/**
* This callback is used to retrieve the children of the node.
*/
@InterfaceAudience.Public
interface ChildrenCallback extends AsyncCallback {
/**
* Process the result of the asynchronous call.
*
* On success, rc is {@link KeeperException.Code#OK}.
*
*
On failure, rc is set to the corresponding failure code in {@link KeeperException}.
*
* - {@link KeeperException.Code#NONODE}
* - The node on given path doesn't exist for some API calls.
*
*
* @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.
*
* @see ZooKeeper#getChildren(String, boolean, ChildrenCallback, Object)
* @see ZooKeeper#getChildren(String, Watcher, ChildrenCallback, Object)
*/
void processResult(int rc, String path, Object ctx, List children);
}
/**
* This callback is used to retrieve the children and stat of the node.
*/
@InterfaceAudience.Public
interface Children2Callback extends AsyncCallback {
/**
* Process the result of the asynchronous call.
*
* @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 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 children, Stat stat);
}
/**
* This callback is used to retrieve the name and stat of the node.
*/
@InterfaceAudience.Public
interface Create2Callback extends AsyncCallback {
/**
* Process the result of the asynchronous call.
*
* @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, name
* and path 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);
}
/**
* This callback is used to retrieve the name of the node.
*/
@InterfaceAudience.Public
interface StringCallback extends AsyncCallback {
/**
* Process the result of the asynchronous call.
*
* On success, rc is {@link KeeperException.Code#OK}.
*
*
On failure, rc is set to the corresponding failure code in {@link KeeperException}.
*
* - {@link KeeperException.Code#NODEEXISTS}
* - The node on give path already exists for some API calls.
* - {@link KeeperException.Code#NONODE}
* - The node on given path doesn't exist for some API calls.
* - {@link KeeperException.Code#NOCHILDRENFOREPHEMERALS}
* - An ephemeral node cannot have children. There is discussion in
* community. It might be changed in the future.
*
*
* @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, name
* and path 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 ZooKeeper#sync(String, VoidCallback, Object)}.
*/
@InterfaceAudience.Public
interface VoidCallback extends AsyncCallback {
/**
* Process the result of the asynchronous call.
*
* On success, rc is {@link KeeperException.Code#OK}.
*
*
On failure, rc is set to the corresponding failure code in {@link KeeperException}.
*
* - {@link KeeperException.Code#NONODE}
* - The node on given path doesn't exist for some API calls.
* - {@link KeeperException.Code#BADVERSION}
* - The given version doesn't match the node's version for some API calls.
* - {@link KeeperException.Code#NOTEMPTY}
* - the node has children and some API calls cannot succeed, e.g.
* {@link ZooKeeper#delete(String, int, VoidCallback, Object)}.
*
*
* @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.
*
* @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.
*/
@InterfaceAudience.Public
interface MultiCallback extends AsyncCallback {
/**
* Process the result of the asynchronous call.
*
* On success, rc is {@link KeeperException.Code#OK}. All {@code opResults} are
* non-{@link OpResult.ErrorResult}.
*
*
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.
*
* @see ZooKeeper#multi(Iterable, MultiCallback, Object)
*/
void processResult(int rc, String path, Object ctx, List opResults);
}
/**
* 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.
*/
void processResult(int rc, Object ctx, List paths);
}
}