ZooKeeper (Apache ZooKeeper - Server 3.7.0 API)
Date: 2021-03-17

org.apache.zookeeper

## Class ZooKeeper

- java.lang.Object
- - org.apache.zookeeper.ZooKeeper

- All Implemented Interfaces:
    AutoCloseable
  Direct Known Subclasses:
    ZooKeeperAdmin

      @InterfaceAudience.Public
      public class ZooKeeper
      extends Object
      implements AutoCloseable

  This is the main class of ZooKeeper client library. To use a ZooKeeper service, an application must first instantiate an object of ZooKeeper class. All the iterations will be done by calling the methods of ZooKeeper class. The methods of this class are thread-safe unless otherwise noted.

  Once a connection to a server is established, a session ID is assigned to the client. The client will send heart beats to the server periodically to keep the session valid.

  The application can call ZooKeeper APIs through a client as long as the session ID of the client remains valid.

  If for some reason, the client fails to send heart beats to the server for a prolonged period of time (exceeding the sessionTimeout value, for instance), the server will expire the session, and the session ID will become invalid. The client object will no longer be usable. To make ZooKeeper API calls, the application must create a new client object.

  If the ZooKeeper server the client currently connects to fails or otherwise does not respond, the client will automatically try to connect to another server before its session ID expires. If successful, the application can continue to use the client.

  The ZooKeeper API methods are either synchronous or asynchronous. Synchronous methods blocks until the server has responded. Asynchronous methods just queue the request for sending and return immediately. They take a callback object that will be executed either on successful execution of the request or on error with an appropriate return code (rc) indicating the error.

  Some successful ZooKeeper API calls can leave watches on the "data nodes" in the ZooKeeper server. Other successful ZooKeeper API calls can trigger those watches. Once a watch is triggered, an event will be delivered to the client which left the watch at the first place. Each watch can be triggered only once. Thus, up to one event will be delivered to a client for every watch it leaves.

  A client needs an object of a class implementing Watcher interface for processing the events delivered to the client. When a client drops the current connection and re-connects to a server, all the existing watches are considered as being triggered but the undelivered events are lost. To emulate this, the client will generate a special event to tell the event handler a connection has been dropped. This special event has EventType None and KeeperState Disconnected.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ZooKeeper.States`
    `static class` | `ZooKeeper.WatchRegistration` Register a watcher for a particular path.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected ClientCnxn` | `cnxn`
    `protected HostProvider` | `hostProvider`
    `static String` | `SECURE_CLIENT` Deprecated. Use `ZKClientConfig.SECURE_CLIENT` instead.
    `static String` | `ZOOKEEPER_CLIENT_CNXN_SOCKET` Deprecated. Use `ZKClientConfig.ZOOKEEPER_CLIENT_CNXN_SOCKET` instead.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ZooKeeper(String connectString, int sessionTimeout, Watcher watcher)` To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.
    `ZooKeeper(String connectString, int sessionTimeout, Watcher watcher, boolean canBeReadOnly)` To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.
    `ZooKeeper(String connectString, int sessionTimeout, Watcher watcher, boolean canBeReadOnly, HostProvider aHostProvider)` To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.
    `ZooKeeper(String connectString, int sessionTimeout, Watcher watcher, boolean canBeReadOnly, HostProvider hostProvider, ZKClientConfig clientConfig)` To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.
    `ZooKeeper(String connectString, int sessionTimeout, Watcher watcher, boolean canBeReadOnly, ZKClientConfig conf)` To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.
    `ZooKeeper(String connectString, int sessionTimeout, Watcher watcher, long sessionId, byte[] sessionPasswd)` To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.
    `ZooKeeper(String connectString, int sessionTimeout, Watcher watcher, long sessionId, byte[] sessionPasswd, boolean canBeReadOnly)` To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.
    `ZooKeeper(String connectString, int sessionTimeout, Watcher watcher, long sessionId, byte[] sessionPasswd, boolean canBeReadOnly, HostProvider aHostProvider)` To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.
    `ZooKeeper(String connectString, int sessionTimeout, Watcher watcher, long sessionId, byte[] sessionPasswd, boolean canBeReadOnly, HostProvider hostProvider, ZKClientConfig clientConfig)` To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.
    `ZooKeeper(String connectString, int sessionTimeout, Watcher watcher, ZKClientConfig conf)` To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addAuthInfo(String scheme, byte[] auth)` Add the specified scheme:auth information to this connection.
    `void` | `addWatch(String basePath, AddWatchMode mode)` Add a watch to the given znode using the given mode.
    `void` | `addWatch(String basePath, AddWatchMode mode, AsyncCallback.VoidCallback cb, Object ctx)` Async version of `addWatch(String, AddWatchMode)` (see it for details)
    `void` | `addWatch(String basePath, Watcher watcher, AddWatchMode mode)` Add a watch to the given znode using the given mode.
    `void` | `addWatch(String basePath, Watcher watcher, AddWatchMode mode, AsyncCallback.VoidCallback cb, Object ctx)` Async version of `addWatch(String, Watcher, AddWatchMode)` (see it for details)
    `void` | `close()` Close this client object.
    `boolean` | `close(int waitForShutdownTimeoutMs)` Close this client object as the `close()` method.
    `String` | `create(String path, byte[] data, List<ACL> acl, CreateMode createMode)` Create a node with the given path.
    `void` | `create(String path, byte[] data, List<ACL> acl, CreateMode createMode, AsyncCallback.Create2Callback cb, Object ctx)` The asynchronous version of create.
    `void` | `create(String path, byte[] data, List<ACL> acl, CreateMode createMode, AsyncCallback.Create2Callback cb, Object ctx, long ttl)` The asynchronous version of create with ttl.
    `void` | `create(String path, byte[] data, List<ACL> acl, CreateMode createMode, AsyncCallback.StringCallback cb, Object ctx)` The asynchronous version of create.
    `String` | `create(String path, byte[] data, List<ACL> acl, CreateMode createMode, Stat stat)` Create a node with the given path and returns the Stat of that node.
    `String` | `create(String path, byte[] data, List<ACL> acl, CreateMode createMode, Stat stat, long ttl)` same as `create(String, byte[], List, CreateMode, Stat)` but allows for specifying a TTL when mode is `CreateMode.PERSISTENT_WITH_TTL` or `CreateMode.PERSISTENT_SEQUENTIAL_WITH_TTL`.
    `void` | `delete(String path, int version)` Delete the node with the given path.
    `void` | `delete(String path, int version, AsyncCallback.VoidCallback cb, Object ctx)` The asynchronous version of delete.
    `Stat` | `exists(String path, boolean watch)` Return the stat of the node of the given path.
    `void` | `exists(String path, boolean watch, AsyncCallback.StatCallback cb, Object ctx)` The asynchronous version of exists.
    `Stat` | `exists(String path, Watcher watcher)` Return the stat of the node of the given path.
    `void` | `exists(String path, Watcher watcher, AsyncCallback.StatCallback cb, Object ctx)` The asynchronous version of exists.
    `List<ACL>` | `getACL(String path, Stat stat)` Return the ACL and stat of the node of the given path.
    `void` | `getACL(String path, Stat stat, AsyncCallback.ACLCallback cb, Object ctx)` The asynchronous version of getACL.
    `int` | `getAllChildrenNumber(String path)` Synchronously gets all numbers of children nodes under a specific path
    `void` | `getAllChildrenNumber(String path, AsyncCallback.AllChildrenNumberCallback cb, Object ctx)` Asynchronously gets all numbers of children nodes under a specific path
    `List<String>` | `getChildren(String path, boolean watch)` Return the list of the children of the node of the given path.
    `void` | `getChildren(String path, boolean watch, AsyncCallback.Children2Callback cb, Object ctx)` The asynchronous version of getChildren.
    `void` | `getChildren(String path, boolean watch, AsyncCallback.ChildrenCallback cb, Object ctx)` The asynchronous version of getChildren.
    `List<String>` | `getChildren(String path, boolean watch, Stat stat)` For the given znode path return the stat and children list.
    `List<String>` | `getChildren(String path, Watcher watcher)` Return the list of the children of the node of the given path.
    `void` | `getChildren(String path, Watcher watcher, AsyncCallback.Children2Callback cb, Object ctx)` The asynchronous version of getChildren.
    `void` | `getChildren(String path, Watcher watcher, AsyncCallback.ChildrenCallback cb, Object ctx)` The asynchronous version of getChildren.
    `List<String>` | `getChildren(String path, Watcher watcher, Stat stat)` For the given znode path return the stat and children list.
    `protected List<String>` | `getChildWatches()`
    `ZKClientConfig` | `getClientConfig()`
    `void` | `getConfig(boolean watch, AsyncCallback.DataCallback cb, Object ctx)` The Asynchronous version of getConfig.
    `byte[]` | `getConfig(boolean watch, Stat stat)` Return the last committed configuration (as known to the server to which the client is connected) and the stat of the configuration.
    `void` | `getConfig(Watcher watcher, AsyncCallback.DataCallback cb, Object ctx)` The asynchronous version of getConfig.
    `byte[]` | `getConfig(Watcher watcher, Stat stat)` Return the last committed configuration (as known to the server to which the client is connected) and the stat of the configuration.
    `void` | `getData(String path, boolean watch, AsyncCallback.DataCallback cb, Object ctx)` The asynchronous version of getData.
    `byte[]` | `getData(String path, boolean watch, Stat stat)` Return the data and the stat of the node of the given path.
    `void` | `getData(String path, Watcher watcher, AsyncCallback.DataCallback cb, Object ctx)` The asynchronous version of getData.
    `byte[]` | `getData(String path, Watcher watcher, Stat stat)` Return the data and the stat of the node of the given path.
    `protected List<String>` | `getDataWatches()`
    `List<String>` | `getEphemerals()` Synchronously gets all the ephemeral nodes created by this session.
    `void` | `getEphemerals(AsyncCallback.EphemeralsCallback cb, Object ctx)` Asynchronously gets all the ephemeral nodes created by this session.
    `List<String>` | `getEphemerals(String prefixPath)` Synchronously gets all the ephemeral nodes matching prefixPath created by this session.
    `void` | `getEphemerals(String prefixPath, AsyncCallback.EphemeralsCallback cb, Object ctx)` Asynchronously gets all the ephemeral nodes matching prefixPath created by this session.
    `protected List<String>` | `getExistWatches()`
    `protected List<String>` | `getPersistentRecursiveWatches()`
    `protected List<String>` | `getPersistentWatches()`
    `ZooKeeperSaslClient` | `getSaslClient()`
    `long` | `getSessionId()` The session id for this ZooKeeper client instance.
    `byte[]` | `getSessionPasswd()` The session password for this ZooKeeper client instance.
    `int` | `getSessionTimeout()` The negotiated session timeout for this ZooKeeper client instance.
    `ZooKeeper.States` | `getState()`
    `Testable` | `getTestable()`
    `List<OpResult>` | `multi(Iterable<Op> ops)` Executes multiple ZooKeeper operations.
    `void` | `multi(Iterable<Op> ops, AsyncCallback.MultiCallback cb, Object ctx)` The asynchronous version of multi.
    `protected List<OpResult>` | `multiInternal(MultiOperationRecord request)`
    `protected void` | `multiInternal(MultiOperationRecord request, AsyncCallback.MultiCallback cb, Object ctx)`
    `void` | `register(Watcher watcher)` Specify the default watcher for the connection (overrides the one specified during construction).
    `void` | `removeAllWatches(String path, Watcher.WatcherType watcherType, boolean local)` For the given znode path, removes all the registered watchers of given watcherType.
    `void` | `removeAllWatches(String path, Watcher.WatcherType watcherType, boolean local, AsyncCallback.VoidCallback cb, Object ctx)` The asynchronous version of removeAllWatches.
    `void` | `removeWatches(String path, Watcher watcher, Watcher.WatcherType watcherType, boolean local)` For the given znode path, removes the specified watcher of given watcherType.
    `void` | `removeWatches(String path, Watcher watcher, Watcher.WatcherType watcherType, boolean local, AsyncCallback.VoidCallback cb, Object ctx)` The asynchronous version of removeWatches.
    `Stat` | `setACL(String path, List<ACL> acl, int aclVersion)` Set the ACL for the node of the given path if such a node exists and the given aclVersion matches the acl version of the node.
    `void` | `setACL(String path, List<ACL> acl, int version, AsyncCallback.StatCallback cb, Object ctx)` The asynchronous version of setACL.
    `Stat` | `setData(String path, byte[] data, int version)` Set the data for the node of the given path if such a node exists and the given version matches the version of the node (if the given version is -1, it matches any node's versions).
    `void` | `setData(String path, byte[] data, int version, AsyncCallback.StatCallback cb, Object ctx)` The asynchronous version of setData.
    `void` | `sync(String path, AsyncCallback.VoidCallback cb, Object ctx)` Asynchronous sync.
    `protected SocketAddress` | `testableLocalSocketAddress()` Returns the local address to which the socket is bound.
    `protected SocketAddress` | `testableRemoteSocketAddress()` Returns the address to which the socket is connected.
    `protected boolean` | `testableWaitForShutdown(int wait)` Wait up to wait milliseconds for the underlying threads to shutdown.
    `String` | `toString()` String representation of this ZooKeeper client.
    `Transaction` | `transaction()` A Transaction is a thin wrapper on the `multi(java.lang.Iterable<org.apache.zookeeper.Op>)` method which provides a builder object that can be used to construct and commit an atomic set of operations.
    `void` | `updateServerList(String connectString)` This function allows a client to update the connection string by providing a new comma separated list of host:port pairs, each corresponding to a ZooKeeper server.
    `List<ClientInfo>` | `whoAmI()` Gives all authentication information added into the current session.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### ZOOKEEPER_CLIENT_CNXN_SOCKET

          @Deprecated
          public static final String ZOOKEEPER_CLIENT_CNXN_SOCKET

      Deprecated. Use `ZKClientConfig.ZOOKEEPER_CLIENT_CNXN_SOCKET` instead.
      See Also:
        Constant Field Values

    - #### SECURE_CLIENT

          @Deprecated
          public static final String SECURE_CLIENT

      Deprecated. Use `ZKClientConfig.SECURE_CLIENT` instead.
      See Also:
        Constant Field Values

    - #### cnxn

          protected final ClientCnxn cnxn

    - #### hostProvider

          protected final HostProvider hostProvider

  - ### Constructor Detail

    - #### ZooKeeper

          public ZooKeeper(String connectString,
                           int sessionTimeout,
                           Watcher watcher)
                    throws IOException

      To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.

      Session establishment is asynchronous. This constructor will initiate connection to the server and return immediately - potentially (usually) before the session is fully established. The watcher argument specifies the watcher that will be notified of any changes in state. This notification can come at any point before or after the constructor call has returned.

      The instantiated ZooKeeper client object will pick an arbitrary server from the connectString and attempt to connect to it. If establishment of the connection fails, another server in the connect string will be tried (the order is non-deterministic, as we random shuffle the list), until a connection is established. The client will continue attempts until the session is explicitly closed.

      Added in 3.2.0: An optional "chroot" suffix may also be appended to the connection string. This will run the client commands while interpreting all paths relative to this root (similar to the unix chroot command).

      Parameters:
        `connectString` - comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" If the optional chroot suffix is used the example would look like: "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/app/a" where the client would be rooted at "/app/a" and all paths would be relative to this root - ie getting/setting/etc... "/foo/bar" would result in operations being run on "/app/a/foo/bar" (from the server perspective).
        `sessionTimeout` - session timeout in milliseconds
        `watcher` - a watcher object which will be notified of state changes, may also be notified for node events
      Throws:
        `IOException` - in cases of network failure
        `IllegalArgumentException` - if an invalid chroot path is specified

    - #### ZooKeeper

          public ZooKeeper(String connectString,
                           int sessionTimeout,
                           Watcher watcher,
                           ZKClientConfig conf)
                    throws IOException

      To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.

      Session establishment is asynchronous. This constructor will initiate connection to the server and return immediately - potentially (usually) before the session is fully established. The watcher argument specifies the watcher that will be notified of any changes in state. This notification can come at any point before or after the constructor call has returned.

      The instantiated ZooKeeper client object will pick an arbitrary server from the connectString and attempt to connect to it. If establishment of the connection fails, another server in the connect string will be tried (the order is non-deterministic, as we random shuffle the list), until a connection is established. The client will continue attempts until the session is explicitly closed.

      Added in 3.2.0: An optional "chroot" suffix may also be appended to the connection string. This will run the client commands while interpreting all paths relative to this root (similar to the unix chroot command).

      Parameters:
        `connectString` - comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" If the optional chroot suffix is used the example would look like: "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/app/a" where the client would be rooted at "/app/a" and all paths would be relative to this root - ie getting/setting/etc... "/foo/bar" would result in operations being run on "/app/a/foo/bar" (from the server perspective).
        `sessionTimeout` - session timeout in milliseconds
        `watcher` - a watcher object which will be notified of state changes, may also be notified for node events
        `conf` - (added in 3.5.2) passing this conf object gives each client the flexibility of configuring properties differently compared to other instances
      Throws:
        `IOException` - in cases of network failure
        `IllegalArgumentException` - if an invalid chroot path is specified

    - #### ZooKeeper

          public ZooKeeper(String connectString,
                           int sessionTimeout,
                           Watcher watcher,
                           boolean canBeReadOnly,
                           HostProvider aHostProvider)
                    throws IOException

      To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.

      Session establishment is asynchronous. This constructor will initiate connection to the server and return immediately - potentially (usually) before the session is fully established. The watcher argument specifies the watcher that will be notified of any changes in state. This notification can come at any point before or after the constructor call has returned.

      The instantiated ZooKeeper client object will pick an arbitrary server from the connectString and attempt to connect to it. If establishment of the connection fails, another server in the connect string will be tried (the order is non-deterministic, as we random shuffle the list), until a connection is established. The client will continue attempts until the session is explicitly closed.

      Added in 3.2.0: An optional "chroot" suffix may also be appended to the connection string. This will run the client commands while interpreting all paths relative to this root (similar to the unix chroot command).

      For backward compatibility, there is another version `ZooKeeper(String, int, Watcher, boolean)` which uses default `StaticHostProvider`

      Parameters:
        `connectString` - comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" If the optional chroot suffix is used the example would look like: "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/app/a" where the client would be rooted at "/app/a" and all paths would be relative to this root - ie getting/setting/etc... "/foo/bar" would result in operations being run on "/app/a/foo/bar" (from the server perspective).
        `sessionTimeout` - session timeout in milliseconds
        `watcher` - a watcher object which will be notified of state changes, may also be notified for node events
        `canBeReadOnly` - (added in 3.4) whether the created client is allowed to go to read-only mode in case of partitioning. Read-only mode basically means that if the client can't find any majority servers but there's partitioned server it could reach, it connects to one in read-only mode, i.e. read requests are allowed while write requests are not. It continues seeking for majority in the background.
        `aHostProvider` - use this as HostProvider to enable custom behaviour.
      Throws:
        `IOException` - in cases of network failure
        `IllegalArgumentException` - if an invalid chroot path is specified

    - #### ZooKeeper

          public ZooKeeper(String connectString,
                           int sessionTimeout,
                           Watcher watcher,
                           boolean canBeReadOnly,
                           HostProvider hostProvider,
                           ZKClientConfig clientConfig)
                    throws IOException

      To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.

      Session establishment is asynchronous. This constructor will initiate connection to the server and return immediately - potentially (usually) before the session is fully established. The watcher argument specifies the watcher that will be notified of any changes in state. This notification can come at any point before or after the constructor call has returned.

      The instantiated ZooKeeper client object will pick an arbitrary server from the connectString and attempt to connect to it. If establishment of the connection fails, another server in the connect string will be tried (the order is non-deterministic, as we random shuffle the list), until a connection is established. The client will continue attempts until the session is explicitly closed.

      Added in 3.2.0: An optional "chroot" suffix may also be appended to the connection string. This will run the client commands while interpreting all paths relative to this root (similar to the unix chroot command).

      For backward compatibility, there is another version `ZooKeeper(String, int, Watcher, boolean)` which uses default `StaticHostProvider`

      Parameters:
        `connectString` - comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" If the optional chroot suffix is used the example would look like: "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/app/a" where the client would be rooted at "/app/a" and all paths would be relative to this root - ie getting/setting/etc... "/foo/bar" would result in operations being run on "/app/a/foo/bar" (from the server perspective).
        `sessionTimeout` - session timeout in milliseconds
        `watcher` - a watcher object which will be notified of state changes, may also be notified for node events
        `canBeReadOnly` - (added in 3.4) whether the created client is allowed to go to read-only mode in case of partitioning. Read-only mode basically means that if the client can't find any majority servers but there's partitioned server it could reach, it connects to one in read-only mode, i.e. read requests are allowed while write requests are not. It continues seeking for majority in the background.
        `hostProvider` - use this as HostProvider to enable custom behaviour.
        `clientConfig` - (added in 3.5.2) passing this conf object gives each client the flexibility of configuring properties differently compared to other instances
      Throws:
        `IOException` - in cases of network failure
        `IllegalArgumentException` - if an invalid chroot path is specified

    - #### ZooKeeper

          public ZooKeeper(String connectString,
                           int sessionTimeout,
                           Watcher watcher,
                           boolean canBeReadOnly)
                    throws IOException

      To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.

      Session establishment is asynchronous. This constructor will initiate connection to the server and return immediately - potentially (usually) before the session is fully established. The watcher argument specifies the watcher that will be notified of any changes in state. This notification can come at any point before or after the constructor call has returned.

      The instantiated ZooKeeper client object will pick an arbitrary server from the connectString and attempt to connect to it. If establishment of the connection fails, another server in the connect string will be tried (the order is non-deterministic, as we random shuffle the list), until a connection is established. The client will continue attempts until the session is explicitly closed.

      Added in 3.2.0: An optional "chroot" suffix may also be appended to the connection string. This will run the client commands while interpreting all paths relative to this root (similar to the unix chroot command).

      Parameters:
        `connectString` - comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" If the optional chroot suffix is used the example would look like: "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/app/a" where the client would be rooted at "/app/a" and all paths would be relative to this root - ie getting/setting/etc... "/foo/bar" would result in operations being run on "/app/a/foo/bar" (from the server perspective).
        `sessionTimeout` - session timeout in milliseconds
        `watcher` - a watcher object which will be notified of state changes, may also be notified for node events
        `canBeReadOnly` - (added in 3.4) whether the created client is allowed to go to read-only mode in case of partitioning. Read-only mode basically means that if the client can't find any majority servers but there's partitioned server it could reach, it connects to one in read-only mode, i.e. read requests are allowed while write requests are not. It continues seeking for majority in the background.
      Throws:
        `IOException` - in cases of network failure
        `IllegalArgumentException` - if an invalid chroot path is specified

    - #### ZooKeeper

          public ZooKeeper(String connectString,
                           int sessionTimeout,
                           Watcher watcher,
                           boolean canBeReadOnly,
                           ZKClientConfig conf)
                    throws IOException

      To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.

      Session establishment is asynchronous. This constructor will initiate connection to the server and return immediately - potentially (usually) before the session is fully established. The watcher argument specifies the watcher that will be notified of any changes in state. This notification can come at any point before or after the constructor call has returned.

      The instantiated ZooKeeper client object will pick an arbitrary server from the connectString and attempt to connect to it. If establishment of the connection fails, another server in the connect string will be tried (the order is non-deterministic, as we random shuffle the list), until a connection is established. The client will continue attempts until the session is explicitly closed.

      Added in 3.2.0: An optional "chroot" suffix may also be appended to the connection string. This will run the client commands while interpreting all paths relative to this root (similar to the unix chroot command).

      Parameters:
        `connectString` - comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" If the optional chroot suffix is used the example would look like: "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/app/a" where the client would be rooted at "/app/a" and all paths would be relative to this root - ie getting/setting/etc... "/foo/bar" would result in operations being run on "/app/a/foo/bar" (from the server perspective).
        `sessionTimeout` - session timeout in milliseconds
        `watcher` - a watcher object which will be notified of state changes, may also be notified for node events
        `canBeReadOnly` - (added in 3.4) whether the created client is allowed to go to read-only mode in case of partitioning. Read-only mode basically means that if the client can't find any majority servers but there's partitioned server it could reach, it connects to one in read-only mode, i.e. read requests are allowed while write requests are not. It continues seeking for majority in the background.
        `conf` - (added in 3.5.2) passing this conf object gives each client the flexibility of configuring properties differently compared to other instances
      Throws:
        `IOException` - in cases of network failure
        `IllegalArgumentException` - if an invalid chroot path is specified

    - #### ZooKeeper

          public ZooKeeper(String connectString,
                           int sessionTimeout,
                           Watcher watcher,
                           long sessionId,
                           byte[] sessionPasswd)
                    throws IOException

      To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.

      Session establishment is asynchronous. This constructor will initiate connection to the server and return immediately - potentially (usually) before the session is fully established. The watcher argument specifies the watcher that will be notified of any changes in state. This notification can come at any point before or after the constructor call has returned.

      The instantiated ZooKeeper client object will pick an arbitrary server from the connectString and attempt to connect to it. If establishment of the connection fails, another server in the connect string will be tried (the order is non-deterministic, as we random shuffle the list), until a connection is established. The client will continue attempts until the session is explicitly closed (or the session is expired by the server).

      Added in 3.2.0: An optional "chroot" suffix may also be appended to the connection string. This will run the client commands while interpreting all paths relative to this root (similar to the unix chroot command).

      Use `getSessionId()` and `getSessionPasswd()` on an established client connection, these values must be passed as sessionId and sessionPasswd respectively if reconnecting. Otherwise, if not reconnecting, use the other constructor which does not require these parameters.

      Parameters:
        `connectString` - comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" If the optional chroot suffix is used the example would look like: "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/app/a" where the client would be rooted at "/app/a" and all paths would be relative to this root - ie getting/setting/etc... "/foo/bar" would result in operations being run on "/app/a/foo/bar" (from the server perspective).
        `sessionTimeout` - session timeout in milliseconds
        `watcher` - a watcher object which will be notified of state changes, may also be notified for node events
        `sessionId` - specific session id to use if reconnecting
        `sessionPasswd` - password for this session
      Throws:
        `IOException` - in cases of network failure
        `IllegalArgumentException` - if an invalid chroot path is specified
        `IllegalArgumentException` - for an invalid list of ZooKeeper hosts

    - #### ZooKeeper

          public ZooKeeper(String connectString,
                           int sessionTimeout,
                           Watcher watcher,
                           long sessionId,
                           byte[] sessionPasswd,
                           boolean canBeReadOnly,
                           HostProvider aHostProvider)
                    throws IOException

      To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.

      Session establishment is asynchronous. This constructor will initiate connection to the server and return immediately - potentially (usually) before the session is fully established. The watcher argument specifies the watcher that will be notified of any changes in state. This notification can come at any point before or after the constructor call has returned.

      The instantiated ZooKeeper client object will pick an arbitrary server from the connectString and attempt to connect to it. If establishment of the connection fails, another server in the connect string will be tried (the order is non-deterministic, as we random shuffle the list), until a connection is established. The client will continue attempts until the session is explicitly closed (or the session is expired by the server).

      Added in 3.2.0: An optional "chroot" suffix may also be appended to the connection string. This will run the client commands while interpreting all paths relative to this root (similar to the unix chroot command).

      Use `getSessionId()` and `getSessionPasswd()` on an established client connection, these values must be passed as sessionId and sessionPasswd respectively if reconnecting. Otherwise, if not reconnecting, use the other constructor which does not require these parameters.

      For backward compatibility, there is another version `ZooKeeper(String, int, Watcher, long, byte[], boolean)` which uses default `StaticHostProvider`

      Parameters:
        `connectString` - comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" If the optional chroot suffix is used the example would look like: "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/app/a" where the client would be rooted at "/app/a" and all paths would be relative to this root - ie getting/setting/etc... "/foo/bar" would result in operations being run on "/app/a/foo/bar" (from the server perspective).
        `sessionTimeout` - session timeout in milliseconds
        `watcher` - a watcher object which will be notified of state changes, may also be notified for node events
        `sessionId` - specific session id to use if reconnecting
        `sessionPasswd` - password for this session
        `canBeReadOnly` - (added in 3.4) whether the created client is allowed to go to read-only mode in case of partitioning. Read-only mode basically means that if the client can't find any majority servers but there's partitioned server it could reach, it connects to one in read-only mode, i.e. read requests are allowed while write requests are not. It continues seeking for majority in the background.
        `aHostProvider` - use this as HostProvider to enable custom behaviour.
      Throws:
        `IOException` - in cases of network failure
        `IllegalArgumentException` - if an invalid chroot path is specified

    - #### ZooKeeper

          public ZooKeeper(String connectString,
                           int sessionTimeout,
                           Watcher watcher,
                           long sessionId,
                           byte[] sessionPasswd,
                           boolean canBeReadOnly,
                           HostProvider hostProvider,
                           ZKClientConfig clientConfig)
                    throws IOException

      To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.

      Session establishment is asynchronous. This constructor will initiate connection to the server and return immediately - potentially (usually) before the session is fully established. The watcher argument specifies the watcher that will be notified of any changes in state. This notification can come at any point before or after the constructor call has returned.

      The instantiated ZooKeeper client object will pick an arbitrary server from the connectString and attempt to connect to it. If establishment of the connection fails, another server in the connect string will be tried (the order is non-deterministic, as we random shuffle the list), until a connection is established. The client will continue attempts until the session is explicitly closed (or the session is expired by the server).

      Added in 3.2.0: An optional "chroot" suffix may also be appended to the connection string. This will run the client commands while interpreting all paths relative to this root (similar to the unix chroot command).

      Use `getSessionId()` and `getSessionPasswd()` on an established client connection, these values must be passed as sessionId and sessionPasswd respectively if reconnecting. Otherwise, if not reconnecting, use the other constructor which does not require these parameters.

      For backward compatibility, there is another version `ZooKeeper(String, int, Watcher, long, byte[], boolean)` which uses default `StaticHostProvider`

      Parameters:
        `connectString` - comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" If the optional chroot suffix is used the example would look like: "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/app/a" where the client would be rooted at "/app/a" and all paths would be relative to this root - ie getting/setting/etc... "/foo/bar" would result in operations being run on "/app/a/foo/bar" (from the server perspective).
        `sessionTimeout` - session timeout in milliseconds
        `watcher` - a watcher object which will be notified of state changes, may also be notified for node events
        `sessionId` - specific session id to use if reconnecting
        `sessionPasswd` - password for this session
        `canBeReadOnly` - (added in 3.4) whether the created client is allowed to go to read-only mode in case of partitioning. Read-only mode basically means that if the client can't find any majority servers but there's partitioned server it could reach, it connects to one in read-only mode, i.e. read requests are allowed while write requests are not. It continues seeking for majority in the background.
        `hostProvider` - use this as HostProvider to enable custom behaviour.
        `clientConfig` - (added in 3.5.2) passing this conf object gives each client the flexibility of configuring properties differently compared to other instances
      Throws:
        `IOException` - in cases of network failure
        `IllegalArgumentException` - if an invalid chroot path is specified
      Since:
        3.5.5

    - #### ZooKeeper

          public ZooKeeper(String connectString,
                           int sessionTimeout,
                           Watcher watcher,
                           long sessionId,
                           byte[] sessionPasswd,
                           boolean canBeReadOnly)
                    throws IOException

      To create a ZooKeeper client object, the application needs to pass a connection string containing a comma separated list of host:port pairs, each corresponding to a ZooKeeper server.

      Session establishment is asynchronous. This constructor will initiate connection to the server and return immediately - potentially (usually) before the session is fully established. The watcher argument specifies the watcher that will be notified of any changes in state. This notification can come at any point before or after the constructor call has returned.

      The instantiated ZooKeeper client object will pick an arbitrary server from the connectString and attempt to connect to it. If establishment of the connection fails, another server in the connect string will be tried (the order is non-deterministic, as we random shuffle the list), until a connection is established. The client will continue attempts until the session is explicitly closed (or the session is expired by the server).

      Added in 3.2.0: An optional "chroot" suffix may also be appended to the connection string. This will run the client commands while interpreting all paths relative to this root (similar to the unix chroot command).

      Use `getSessionId()` and `getSessionPasswd()` on an established client connection, these values must be passed as sessionId and sessionPasswd respectively if reconnecting. Otherwise, if not reconnecting, use the other constructor which does not require these parameters.

      This constructor uses a StaticHostProvider; there is another one to enable custom behaviour.

      Parameters:
        `connectString` - comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" If the optional chroot suffix is used the example would look like: "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/app/a" where the client would be rooted at "/app/a" and all paths would be relative to this root - ie getting/setting/etc... "/foo/bar" would result in operations being run on "/app/a/foo/bar" (from the server perspective).
        `sessionTimeout` - session timeout in milliseconds
        `watcher` - a watcher object which will be notified of state changes, may also be notified for node events
        `sessionId` - specific session id to use if reconnecting
        `sessionPasswd` - password for this session
        `canBeReadOnly` - (added in 3.4) whether the created client is allowed to go to read-only mode in case of partitioning. Read-only mode basically means that if the client can't find any majority servers but there's partitioned server it could reach, it connects to one in read-only mode, i.e. read requests are allowed while write requests are not. It continues seeking for majority in the background.
      Throws:
        `IOException` - in cases of network failure
        `IllegalArgumentException` - if an invalid chroot path is specified

  - ### Method Detail

    - #### updateServerList

          public void updateServerList(String connectString)
                                throws IOException

      This function allows a client to update the connection string by providing a new comma separated list of host:port pairs, each corresponding to a ZooKeeper server.

      The function invokes a probabilistic load-balancing algorithm which may cause the client to disconnect from its current host with the goal to achieve expected uniform number of connections per server in the new list. In case the current host to which the client is connected is not in the new list this call will always cause the connection to be dropped. Otherwise, the decision is based on whether the number of servers has increased or decreased and by how much. For example, if the previous connection string contained 3 hosts and now the list contains these 3 hosts and 2 more hosts, 40% of clients connected to each of the 3 hosts will move to one of the new hosts in order to balance the load. The algorithm will disconnect from the current host with probability 0.4 and in this case cause the client to connect to one of the 2 new hosts, chosen at random.

      If the connection is dropped, the client moves to a special mode "reconfigMode" where he chooses a new server to connect to using the probabilistic algorithm. After finding a server, or exhausting all servers in the new list after trying all of them and failing to connect, the client moves back to the normal mode of operation where it will pick an arbitrary server from the connectString and attempt to connect to it. If establishment of the connection fails, another server in the connect string will be tried (the order is non-deterministic, as we random shuffle the list), until a connection is established. The client will continue attempts until the session is explicitly closed (or the session is expired by the server).

      Parameters:
        `connectString` - comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" If the optional chroot suffix is used the example would look like: "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/app/a" where the client would be rooted at "/app/a" and all paths would be relative to this root - ie getting/setting/etc... "/foo/bar" would result in operations being run on "/app/a/foo/bar" (from the server perspective).
      Throws:
        `IOException` - in cases of network failure

    - #### getSaslClient

          public ZooKeeperSaslClient getSaslClient()

    - #### getClientConfig

          public ZKClientConfig getClientConfig()

    - #### getDataWatches

          protected List<String> getDataWatches()

    - #### getExistWatches

          protected List<String> getExistWatches()

    - #### getChildWatches

          protected List<String> getChildWatches()

    - #### getPersistentWatches

          protected List<String> getPersistentWatches()

    - #### getPersistentRecursiveWatches

          protected List<String> getPersistentRecursiveWatches()

    - #### getTestable

          public Testable getTestable()

    - #### getSessionId

          public long getSessionId()

      The session id for this ZooKeeper client instance. The value returned is not valid until the client connects to a server and may change after a re-connect. This method is NOT thread safe
      Returns:
        current session id

    - #### getSessionPasswd

          public byte[] getSessionPasswd()

      The session password for this ZooKeeper client instance. The value returned is not valid until the client connects to a server and may change after a re-connect. This method is NOT thread safe
      Returns:
        current session password

    - #### getSessionTimeout

          public int getSessionTimeout()

      The negotiated session timeout for this ZooKeeper client instance. The value returned is not valid until the client connects to a server and may change after a re-connect. This method is NOT thread safe
      Returns:
        current session timeout

    - #### addAuthInfo

          public void addAuthInfo(String scheme,
                                  byte[] auth)

      Add the specified scheme:auth information to this connection. This method is NOT thread safe
      Parameters:
        `scheme` -
        `auth` -

    - #### register

          public void register(Watcher watcher)

      Specify the default watcher for the connection (overrides the one specified during construction).

    - #### close

          public void close()
                     throws InterruptedException

      Close this client object. Once the client is closed, its session becomes invalid. All the ephemeral nodes in the ZooKeeper server associated with the session will be removed. The watches left on those nodes (and on their parents) will be triggered.

      Added in 3.5.3: try-with-resources may be used instead of calling close directly.

      This method does not wait for all internal threads to exit. Use the `close(int)` method to wait for all resources to be released

      Specified by:
        `close` in interface `AutoCloseable`
      Throws:
        `InterruptedException`

    - #### close

          public boolean close(int waitForShutdownTimeoutMs)
                        throws InterruptedException

      Close this client object as the `close()` method. This method will wait for internal resources to be released.
      Parameters:
        `waitForShutdownTimeoutMs` - timeout (in milliseconds) to wait for resources to be released. Use zero or a negative value to skip the wait
      Returns:
        true if waitForShutdownTimeout is greater than zero and all of the resources have been released
      Throws:
        `InterruptedException`
      Since:
        3.5.4

    - #### create

          public String create(String path,
                               byte[] data,
                               List<ACL> acl,
                               CreateMode createMode)
                        throws KeeperException,
                               InterruptedException

      Create a node with the given path. The node data will be the given data, and node acl will be the given acl.

      The flags argument specifies whether the created node will be ephemeral or not.

      An ephemeral node will be removed by the ZooKeeper automatically when the session associated with the creation of the node expires.

      The flags argument can also specify to create a sequential node. The actual path name of a sequential node will be the given path plus a suffix "i" where i is the current sequential number of the node. The sequence number is always fixed length of 10 digits, 0 padded. Once such a node is created, the sequential number will be incremented by one.

      If a node with the same actual path already exists in the ZooKeeper, a KeeperException with error code KeeperException.NodeExists will be thrown. Note that since a different actual path is used for each invocation of creating sequential node with the same path argument, the call will never throw "file exists" KeeperException.

      If the parent node does not exist in the ZooKeeper, a KeeperException with error code KeeperException.NoNode will be thrown.

      An ephemeral node cannot have children. If the parent node of the given path is ephemeral, a KeeperException with error code KeeperException.NoChildrenForEphemerals will be thrown.

      This operation, if successful, will trigger all the watches left on the node of the given path by exists and getData API calls, and the watches left on the parent node by getChildren API calls.

      If a node is created successfully, the ZooKeeper server will trigger the watches on the path left by exists calls, and the watches on the parent of the node by getChildren calls.

      The maximum allowable size of the data array is 1 MB (1,048,576 bytes). Arrays larger than this will cause a KeeperExecption to be thrown.

      Parameters:
        `path` - the path for the node
        `data` - the initial data for the node
        `acl` - the acl for the node
        `createMode` - specifying whether the node to be created is ephemeral and/or sequential
      Returns:
        the actual path of the created node
      Throws:
        `KeeperException` - if the server returns a non-zero error code
        `KeeperException.InvalidACLException` - if the ACL is invalid, null, or empty
        `InterruptedException` - if the transaction is interrupted
        `IllegalArgumentException` - if an invalid path is specified

    - #### create

          public String create(String path,
                               byte[] data,
                               List<ACL> acl,
                               CreateMode createMode,
                               Stat stat)
                        throws KeeperException,
                               InterruptedException

      Create a node with the given path and returns the Stat of that node. The node data will be the given data and node acl will be the given acl.

      The flags argument specifies whether the created node will be ephemeral or not.

      An ephemeral node will be removed by the ZooKeeper automatically when the session associated with the creation of the node expires.

      The flags argument can also specify to create a sequential node. The actual path name of a sequential node will be the given path plus a suffix "i" where i is the current sequential number of the node. The sequence number is always fixed length of 10 digits, 0 padded. Once such a node is created, the sequential number will be incremented by one.

      If a node with the same actual path already exists in the ZooKeeper, a KeeperException with error code KeeperException.NodeExists will be thrown. Note that since a different actual path is used for each invocation of creating sequential node with the same path argument, the call will never throw "file exists" KeeperException.

      If the parent node does not exist in the ZooKeeper, a KeeperException with error code KeeperException.NoNode will be thrown.

      An ephemeral node cannot have children. If the parent node of the given path is ephemeral, a KeeperException with error code KeeperException.NoChildrenForEphemerals will be thrown.

      This operation, if successful, will trigger all the watches left on the node of the given path by exists and getData API calls, and the watches left on the parent node by getChildren API calls.

      If a node is created successfully, the ZooKeeper server will trigger the watches on the path left by exists calls, and the watches on the parent of the node by getChildren calls.

      The maximum allowable size of the data array is 1 MB (1,048,576 bytes). Arrays larger than this will cause a KeeperExecption to be thrown.

      Parameters:
        `path` - the path for the node
        `data` - the initial data for the node
        `acl` - the acl for the node
        `createMode` - specifying whether the node to be created is ephemeral and/or sequential
        `stat` - The output Stat object.
      Returns:
        the actual path of the created node
      Throws:
        `KeeperException` - if the server returns a non-zero error code
        `KeeperException.InvalidACLException` - if the ACL is invalid, null, or empty
        `InterruptedException` - if the transaction is interrupted
        `IllegalArgumentException` - if an invalid path is specified

    - #### create

          public String create(String path,
                               byte[] data,
                               List<ACL> acl,
                               CreateMode createMode,
                               Stat stat,
                               long ttl)
                        throws KeeperException,
                               InterruptedException

      same as `create(String, byte[], List, CreateMode, Stat)` but allows for specifying a TTL when mode is `CreateMode.PERSISTENT_WITH_TTL` or `CreateMode.PERSISTENT_SEQUENTIAL_WITH_TTL`. If the znode has not been modified within the given TTL, it will be deleted once it has no children. The TTL unit is milliseconds and must be greater than 0 and less than or equal to `EphemeralType.maxValue()` for `EphemeralType.TTL`.
      Throws:
        `KeeperException`
        `InterruptedException`

    - #### create

          public void create(String path,
                             byte[] data,
                             List<ACL> acl,
                             CreateMode createMode,
                             AsyncCallback.StringCallback cb,
                             Object ctx)

      The asynchronous version of create.
      See Also:
        `create(String, byte[], List, CreateMode)`

    - #### create

          public void create(String path,
                             byte[] data,
                             List<ACL> acl,
                             CreateMode createMode,
                             AsyncCallback.Create2Callback cb,
                             Object ctx)

      The asynchronous version of create.
      See Also:
        `create(String, byte[], List, CreateMode, Stat)`

    - #### create

          public void create(String path,
                             byte[] data,
                             List<ACL> acl,
                             CreateMode createMode,
                             AsyncCallback.Create2Callback cb,
                             Object ctx,
                             long ttl)

      The asynchronous version of create with ttl.
      See Also:
        `create(String, byte[], List, CreateMode, Stat, long)`

    - #### delete

          public void delete(String path,
                             int version)
                      throws InterruptedException,
                             KeeperException

      Delete the node with the given path. The call will succeed if such a node exists, and the given version matches the node's version (if the given version is -1, it matches any node's versions).

      A KeeperException with error code KeeperException.NoNode will be thrown if the nodes does not exist.

      A KeeperException with error code KeeperException.BadVersion will be thrown if the given version does not match the node's version.

      A KeeperException with error code KeeperException.NotEmpty will be thrown if the node has children.

      This operation, if successful, will trigger all the watches on the node of the given path left by exists API calls, and the watches on the parent node left by getChildren API calls.

      Parameters:
        `path` - the path of the node to be deleted.
        `version` - the expected node version.
      Throws:
        `InterruptedException` - IF the server transaction is interrupted
        `KeeperException` - If the server signals an error with a non-zero return code.
        `IllegalArgumentException` - if an invalid path is specified

    - #### multi

          public List<OpResult> multi(Iterable<Op> ops)
                               throws InterruptedException,
                                      KeeperException

      Executes multiple ZooKeeper operations. In case of transactions all of them or none of them will be executed.

      On success, a list of results is returned. On failure, an exception is raised which contains partial results and error details, see `KeeperException.getResults()`

      Note: The maximum allowable size of all of the data arrays in all of the setData operations in this single request is typically 1 MB (1,048,576 bytes). This limit is specified on the server via jute.maxbuffer. Requests larger than this will cause a KeeperException to be thrown.

      Parameters:
        `ops` - An iterable that contains the operations to be done. These should be created using the factory methods on `Op` and must be the same kind of ops.
      Returns:
        A list of results, one for each input Op, the order of which exactly matches the order of the `ops` input operations.
      Throws:
        `InterruptedException` - If the operation was interrupted. The operation may or may not have succeeded, but will not have partially succeeded if this exception is thrown.
        `KeeperException` - If the operation could not be completed due to some error in doing one of the specified ops.
        `IllegalArgumentException` - if an invalid path is specified or different kind of ops are mixed
      Since:
        3.4.0

    - #### multi

          public void multi(Iterable<Op> ops,
                            AsyncCallback.MultiCallback cb,
                            Object ctx)

      The asynchronous version of multi.
      See Also:
        `multi(Iterable)`

    - #### multiInternal

          protected void multiInternal(MultiOperationRecord request,
                                       AsyncCallback.MultiCallback cb,
                                       Object ctx)
                                throws IllegalArgumentException

      Throws:
        `IllegalArgumentException`

    - #### multiInternal

          protected List<OpResult> multiInternal(MultiOperationRecord request)
                                          throws InterruptedException,
                                                 KeeperException,
                                                 IllegalArgumentException

      Throws:
        `InterruptedException`
        `KeeperException`
        `IllegalArgumentException`

    - #### transaction

          public Transaction transaction()

      A Transaction is a thin wrapper on the `multi(java.lang.Iterable<org.apache.zookeeper.Op>)` method which provides a builder object that can be used to construct and commit an atomic set of operations.
      Returns:
        a Transaction builder object
      Since:
        3.4.0

    - #### delete

          public void delete(String path,
                             int version,
                             AsyncCallback.VoidCallback cb,
                             Object ctx)

      The asynchronous version of delete.
      See Also:
        `delete(String, int)`

    - #### exists

          public Stat exists(String path,
                             Watcher watcher)
                      throws KeeperException,
                             InterruptedException

      Return the stat of the node of the given path. Return null if no such a node exists.

      If the watch is non-null and the call is successful (no exception is thrown), a watch will be left on the node with the given path. The watch will be triggered by a successful operation that creates/delete the node or sets the data on the node.

      Parameters:
        `path` - the node path
        `watcher` - explicit watcher
      Returns:
        the stat of the node of the given path; return null if no such a node exists.
      Throws:
        `KeeperException` - If the server signals an error
        `InterruptedException` - If the server transaction is interrupted.
        `IllegalArgumentException` - if an invalid path is specified

    - #### exists

          public Stat exists(String path,
                             boolean watch)
                      throws KeeperException,
                             InterruptedException

      Return the stat of the node of the given path. Return null if no such a node exists.

      If the watch is true and the call is successful (no exception is thrown), a watch will be left on the node with the given path. The watch will be triggered by a successful operation that creates/delete the node or sets the data on the node.

      Parameters:
        `path` - the node path
        `watch` - whether need to watch this node
      Returns:
        the stat of the node of the given path; return null if no such a node exists.
      Throws:
        `KeeperException` - If the server signals an error
        `IllegalStateException` - if watch this node with a null default watcher
        `InterruptedException` - If the server transaction is interrupted.

    - #### exists

          public void exists(String path,
                             Watcher watcher,
                             AsyncCallback.StatCallback cb,
                             Object ctx)

      The asynchronous version of exists.
      See Also:
        `exists(String, Watcher)`

    - #### exists

          public void exists(String path,
                             boolean watch,
                             AsyncCallback.StatCallback cb,
                             Object ctx)

      The asynchronous version of exists.
      Throws:
        `IllegalStateException` - if watch this node with a null default watcher
      See Also:
        `exists(String, boolean)`

    - #### getData

          public byte[] getData(String path,
                                Watcher watcher,
                                Stat stat)
                         throws KeeperException,
                                InterruptedException

      Return the data and the stat of the node of the given path.

      If the watch is non-null and the call is successful (no exception is thrown), a watch will be left on the node with the given path. The watch will be triggered by a successful operation that sets data on the node, or deletes the node.

      A KeeperException with error code KeeperException.NoNode will be thrown if no node with the given path exists.

      Parameters:
        `path` - the given path
        `watcher` - explicit watcher
        `stat` - the stat of the node
      Returns:
        the data of the node
      Throws:
        `KeeperException` - If the server signals an error with a non-zero error code
        `InterruptedException` - If the server transaction is interrupted.
        `IllegalArgumentException` - if an invalid path is specified

    - #### getData

          public byte[] getData(String path,
                                boolean watch,
                                Stat stat)
                         throws KeeperException,
                                InterruptedException

      Return the data and the stat of the node of the given path.

      If the watch is true and the call is successful (no exception is thrown), a watch will be left on the node with the given path. The watch will be triggered by a successful operation that sets data on the node, or deletes the node.

      A KeeperException with error code KeeperException.NoNode will be thrown if no node with the given path exists.

      Parameters:
        `path` - the given path
        `watch` - whether need to watch this node
        `stat` - the stat of the node
      Returns:
        the data of the node
      Throws:
        `KeeperException` - If the server signals an error with a non-zero error code
        `IllegalStateException` - if watch this node with a null default watcher
        `InterruptedException` - If the server transaction is interrupted.

    - #### getData

          public void getData(String path,
                              Watcher watcher,
                              AsyncCallback.DataCallback cb,
                              Object ctx)

      The asynchronous version of getData.
      See Also:
        `getData(String, Watcher, Stat)`

    - #### getData

          public void getData(String path,
                              boolean watch,
                              AsyncCallback.DataCallback cb,
                              Object ctx)

      The asynchronous version of getData.
      Throws:
        `IllegalStateException` - if watch this node with a null default watcher
      See Also:
        `getData(String, boolean, Stat)`

    - #### getConfig

          public byte[] getConfig(Watcher watcher,
                                  Stat stat)
                           throws KeeperException,
                                  InterruptedException

      Return the last committed configuration (as known to the server to which the client is connected) and the stat of the configuration.

      If the watch is non-null and the call is successful (no exception is thrown), a watch will be left on the configuration node (ZooDefs.CONFIG_NODE). The watch will be triggered by a successful reconfig operation

      A KeeperException with error code KeeperException.NoNode will be thrown if the configuration node doesn't exists.

      Parameters:
        `watcher` - explicit watcher
        `stat` - the stat of the configuration node ZooDefs.CONFIG_NODE
      Returns:
        configuration data stored in ZooDefs.CONFIG_NODE
      Throws:
        `KeeperException` - If the server signals an error with a non-zero error code
        `InterruptedException` - If the server transaction is interrupted.

    - #### getConfig

          public void getConfig(Watcher watcher,
                                AsyncCallback.DataCallback cb,
                                Object ctx)

      The asynchronous version of getConfig.
      See Also:
        `getConfig(Watcher, Stat)`

    - #### getConfig

          public byte[] getConfig(boolean watch,
                                  Stat stat)
                           throws KeeperException,
                                  InterruptedException

      Return the last committed configuration (as known to the server to which the client is connected) and the stat of the configuration.

      If the watch is true and the call is successful (no exception is thrown), a watch will be left on the configuration node (ZooDefs.CONFIG_NODE). The watch will be triggered by a successful reconfig operation

      A KeeperException with error code KeeperException.NoNode will be thrown if no node with the given path exists.

      Parameters:
        `watch` - whether need to watch this node
        `stat` - the stat of the configuration node ZooDefs.CONFIG_NODE
      Returns:
        configuration data stored in ZooDefs.CONFIG_NODE
      Throws:
        `KeeperException` - If the server signals an error with a non-zero error code
        `IllegalStateException` - if watch this node with a null default watcher
        `InterruptedException` - If the server transaction is interrupted.

    - #### getConfig

          public void getConfig(boolean watch,
                                AsyncCallback.DataCallback cb,
                                Object ctx)

      The Asynchronous version of getConfig.
      Throws:
        `IllegalStateException` - if watch this node with a null default watcher
      See Also:
        `getData(String, boolean, Stat)`

    - #### setData

          public Stat setData(String path,
                              byte[] data,
                              int version)
                       throws KeeperException,
                              InterruptedException

      Set the data for the node of the given path if such a node exists and the given version matches the version of the node (if the given version is -1, it matches any node's versions). Return the stat of the node.

      This operation, if successful, will trigger all the watches on the node of the given path left by getData calls.

      A KeeperException with error code KeeperException.NoNode will be thrown if no node with the given path exists.

      A KeeperException with error code KeeperException.BadVersion will be thrown if the given version does not match the node's version.

      The maximum allowable size of the data array is 1 MB (1,048,576 bytes). Arrays larger than this will cause a KeeperException to be thrown.

      Parameters:
        `path` - the path of the node
        `data` - the data to set
        `version` - the expected matching version
      Returns:
        the state of the node
      Throws:
        `InterruptedException` - If the server transaction is interrupted.
        `KeeperException` - If the server signals an error with a non-zero error code.
        `IllegalArgumentException` - if an invalid path is specified

    - #### setData

          public void setData(String path,
                              byte[] data,
                              int version,
                              AsyncCallback.StatCallback cb,
                              Object ctx)

      The asynchronous version of setData.
      See Also:
        `setData(String, byte[], int)`

    - #### getACL

          public List<ACL> getACL(String path,
                                  Stat stat)
                           throws KeeperException,
                                  InterruptedException

      Return the ACL and stat of the node of the given path.

      A KeeperException with error code KeeperException.NoNode will be thrown if no node with the given path exists.

      Parameters:
        `path` - the given path for the node
        `stat` - the stat of the node will be copied to this parameter if not null.
      Returns:
        the ACL array of the given node.
      Throws:
        `InterruptedException` - If the server transaction is interrupted.
        `KeeperException` - If the server signals an error with a non-zero error code.
        `IllegalArgumentException` - if an invalid path is specified

    - #### getACL

          public void getACL(String path,
                             Stat stat,
                             AsyncCallback.ACLCallback cb,
                             Object ctx)

      The asynchronous version of getACL.
      See Also:
        `getACL(String, Stat)`

    - #### setACL

          public Stat setACL(String path,
                             List<ACL> acl,
                             int aclVersion)
                      throws KeeperException,
                             InterruptedException

      Set the ACL for the node of the given path if such a node exists and the given aclVersion matches the acl version of the node. Return the stat of the node.

      A KeeperException with error code KeeperException.NoNode will be thrown if no node with the given path exists.

      A KeeperException with error code KeeperException.BadVersion will be thrown if the given aclVersion does not match the node's aclVersion.

      Parameters:
        `path` - the given path for the node
        `acl` - the given acl for the node
        `aclVersion` - the given acl version of the node
      Returns:
        the stat of the node.
      Throws:
        `InterruptedException` - If the server transaction is interrupted.
        `KeeperException` - If the server signals an error with a non-zero error code.
        `KeeperException.InvalidACLException` - If the acl is invalide.
        `IllegalArgumentException` - if an invalid path is specified

    - #### setACL

          public void setACL(String path,
                             List<ACL> acl,
                             int version,
                             AsyncCallback.StatCallback cb,
                             Object ctx)

      The asynchronous version of setACL.
      See Also:
        `setACL(String, List, int)`

    - #### getChildren

          public List<String> getChildren(String path,
                                          Watcher watcher)
                                   throws KeeperException,
                                          InterruptedException

      Return the list of the children of the node of the given path.

      If the watch is non-null and the call is successful (no exception is thrown), a watch will be left on the node with the given path. The watch will be triggered by a successful operation that deletes the node of the given path or creates/delete a child under the node.

      The list of children returned is not sorted and no guarantee is provided as to its natural or lexical order.

      A KeeperException with error code KeeperException.NoNode will be thrown if no node with the given path exists.

      Parameters:
        `path` -
        `watcher` - explicit watcher
      Returns:
        an unordered array of children of the node with the given path
      Throws:
        `InterruptedException` - If the server transaction is interrupted.
        `KeeperException` - If the server signals an error with a non-zero error code.
        `IllegalArgumentException` - if an invalid path is specified

    - #### getChildren

          public List<String> getChildren(String path,
                                          boolean watch)
                                   throws KeeperException,
                                          InterruptedException

      Return the list of the children of the node of the given path.

      If the watch is true and the call is successful (no exception is thrown), a watch will be left on the node with the given path. The watch will be triggered by a successful operation that deletes the node of the given path or creates/delete a child under the node.

      The list of children returned is not sorted and no guarantee is provided as to its natural or lexical order.

      A KeeperException with error code KeeperException.NoNode will be thrown if no node with the given path exists.

      Parameters:
        `path` - the node path
        `watch` - whether need to watch this node
      Returns:
        an unordered array of children of the node with the given path
      Throws:
        `IllegalStateException` - if watch this node with a null default watcher
        `InterruptedException` - If the server transaction is interrupted.
        `KeeperException` - If the server signals an error with a non-zero error code.

    - #### getChildren

          public void getChildren(String path,
                                  Watcher watcher,
                                  AsyncCallback.ChildrenCallback cb,
                                  Object ctx)

      The asynchronous version of getChildren.
      See Also:
        `getChildren(String, Watcher)`

    - #### getChildren

          public void getChildren(String path,
                                  boolean watch,
                                  AsyncCallback.ChildrenCallback cb,
                                  Object ctx)

      The asynchronous version of getChildren.
      Throws:
        `IllegalStateException` - if watch this node with a null default watcher
      See Also:
        `getChildren(String, boolean)`

    - #### getChildren

          public List<String> getChildren(String path,
                                          Watcher watcher,
                                          Stat stat)
                                   throws KeeperException,
                                          InterruptedException

      For the given znode path return the stat and children list.

      If the watch is non-null and the call is successful (no exception is thrown), a watch will be left on the node with the given path. The watch will be triggered by a successful operation that deletes the node of the given path or creates/delete a child under the node.

      The list of children returned is not sorted and no guarantee is provided as to its natural or lexical order.

      A KeeperException with error code KeeperException.NoNode will be thrown if no node with the given path exists.

      Parameters:
        `path` -
        `watcher` - explicit watcher
        `stat` - stat of the znode designated by path
      Returns:
        an unordered array of children of the node with the given path
      Throws:
        `InterruptedException` - If the server transaction is interrupted.
        `KeeperException` - If the server signals an error with a non-zero error code.
        `IllegalArgumentException` - if an invalid path is specified
      Since:
        3.3.0

    - #### getChildren

          public List<String> getChildren(String path,
                                          boolean watch,
                                          Stat stat)
                                   throws KeeperException,
                                          InterruptedException

      For the given znode path return the stat and children list.

      If the watch is true and the call is successful (no exception is thrown), a watch will be left on the node with the given path. The watch will be triggered by a successful operation that deletes the node of the given path or creates/delete a child under the node.

      The list of children returned is not sorted and no guarantee is provided as to its natural or lexical order.

      A KeeperException with error code KeeperException.NoNode will be thrown if no node with the given path exists.

      Parameters:
        `path` - the node path
        `watch` - whether need to watch this node
        `stat` - stat of the znode designated by path
      Returns:
        an unordered array of children of the node with the given path
      Throws:
        `IllegalStateException` - if watch this node with a null default watcher
        `InterruptedException` - If the server transaction is interrupted.
        `KeeperException` - If the server signals an error with a non-zero error code.
      Since:
        3.3.0

    - #### getChildren

          public void getChildren(String path,
                                  Watcher watcher,
                                  AsyncCallback.Children2Callback cb,
                                  Object ctx)

      The asynchronous version of getChildren.
      Since:
        3.3.0
      See Also:
        `getChildren(String, Watcher, Stat)`

    - #### getChildren

          public void getChildren(String path,
                                  boolean watch,
                                  AsyncCallback.Children2Callback cb,
                                  Object ctx)

      The asynchronous version of getChildren.
      Throws:
        `IllegalStateException` - if watch this node with a null default watcher
      Since:
        3.3.0
      See Also:
        `getChildren(String, boolean, Stat)`

    - #### getAllChildrenNumber

          public int getAllChildrenNumber(String path)
                                   throws KeeperException,
                                          InterruptedException

      Synchronously gets all numbers of children nodes under a specific path
      Parameters:
        `path` -
      Returns:
        Children nodes count under path
      Throws:
        `KeeperException`
        `InterruptedException`
      Since:
        3.6.0

    - #### getAllChildrenNumber

          public void getAllChildrenNumber(String path,
                                           AsyncCallback.AllChildrenNumberCallback cb,
                                           Object ctx)

      Asynchronously gets all numbers of children nodes under a specific path
      Parameters:
        `path` -
      Since:
        3.6.0

    - #### getEphemerals

          public List<String> getEphemerals()
                                     throws KeeperException,
                                            InterruptedException

      Synchronously gets all the ephemeral nodes created by this session.
      Throws:
        `KeeperException`
        `InterruptedException`
      Since:
        3.6.0

    - #### getEphemerals

          public List<String> getEphemerals(String prefixPath)
                                     throws KeeperException,
                                            InterruptedException

      Synchronously gets all the ephemeral nodes matching prefixPath created by this session. If prefixPath is "/" then it returns all ephemerals
      Throws:
        `KeeperException`
        `InterruptedException`
      Since:
        3.6.0

    - #### getEphemerals

          public void getEphemerals(String prefixPath,
                                    AsyncCallback.EphemeralsCallback cb,
                                    Object ctx)

      Asynchronously gets all the ephemeral nodes matching prefixPath created by this session. If prefixPath is "/" then it returns all ephemerals
      Since:
        3.6.0

    - #### getEphemerals

          public void getEphemerals(AsyncCallback.EphemeralsCallback cb,
                                    Object ctx)

      Asynchronously gets all the ephemeral nodes created by this session. ephemerals
      Since:
        3.6.0

    - #### sync

          public void sync(String path,
                           AsyncCallback.VoidCallback cb,
                           Object ctx)

      Asynchronous sync. Flushes channel between process and leader.
      Parameters:
        `path` -
        `cb` - a handler for the callback
        `ctx` - context to be provided to the callback
      Throws:
        `IllegalArgumentException` - if an invalid path is specified

    - #### removeWatches

          public void removeWatches(String path,
                                    Watcher watcher,
                                    Watcher.WatcherType watcherType,
                                    boolean local)
                             throws InterruptedException,
                                    KeeperException

      For the given znode path, removes the specified watcher of given watcherType.

      Watcher shouldn't be null. A successful call guarantees that, the removed watcher won't be triggered.

      Parameters:
        `path` - - the path of the node
        `watcher` - - a concrete watcher
        `watcherType` - - the type of watcher to be removed
        `local` - - whether the watcher can be removed locally when there is no server connection
      Throws:
        `InterruptedException` - if the server transaction is interrupted.
        `KeeperException.NoWatcherException` - if no watcher exists that match the specified parameters
        `KeeperException` - if the server signals an error with a non-zero error code.
        `IllegalArgumentException` - if any of the following is true:
        - `path` is invalid
        - `watcher` is null
      Since:
        3.5.0

    - #### removeWatches

          public void removeWatches(String path,
                                    Watcher watcher,
                                    Watcher.WatcherType watcherType,
                                    boolean local,
                                    AsyncCallback.VoidCallback cb,
                                    Object ctx)

      The asynchronous version of removeWatches.
      See Also:
        `removeWatches(java.lang.String, org.apache.zookeeper.Watcher, org.apache.zookeeper.Watcher.WatcherType, boolean)`

    - #### removeAllWatches

          public void removeAllWatches(String path,
                                       Watcher.WatcherType watcherType,
                                       boolean local)
                                throws InterruptedException,
                                       KeeperException

      For the given znode path, removes all the registered watchers of given watcherType.

      A successful call guarantees that, the removed watchers won't be triggered.

      Parameters:
        `path` - - the path of the node
        `watcherType` - - the type of watcher to be removed
        `local` - - whether watches can be removed locally when there is no server connection
      Throws:
        `InterruptedException` - if the server transaction is interrupted.
        `KeeperException.NoWatcherException` - if no watcher exists that match the specified parameters
        `KeeperException` - if the server signals an error with a non-zero error code.
        `IllegalArgumentException` - if an invalid `path` is specified
      Since:
        3.5.0

    - #### removeAllWatches

          public void removeAllWatches(String path,
                                       Watcher.WatcherType watcherType,
                                       boolean local,
                                       AsyncCallback.VoidCallback cb,
                                       Object ctx)

      The asynchronous version of removeAllWatches.
      See Also:
        `removeAllWatches(java.lang.String, org.apache.zookeeper.Watcher.WatcherType, boolean)`

    - #### addWatch

          public void addWatch(String basePath,
                               Watcher watcher,
                               AddWatchMode mode)
                        throws KeeperException,
                               InterruptedException

      Add a watch to the given znode using the given mode. Note: not all watch types can be set with this method. Only the modes available in `AddWatchMode` can be set with this method.
      Parameters:
        `basePath` - the path that the watcher applies to
        `watcher` - the watcher
        `mode` - type of watcher to add
      Throws:
        `InterruptedException` - If the server transaction is interrupted.
        `KeeperException` - If the server signals an error with a non-zero error code.
      Since:
        3.6.0

    - #### addWatch

          public void addWatch(String basePath,
                               AddWatchMode mode)
                        throws KeeperException,
                               InterruptedException

      Add a watch to the given znode using the given mode. Note: not all watch types can be set with this method. Only the modes available in `AddWatchMode` can be set with this method. In this version of the method, the default watcher is used
      Parameters:
        `basePath` - the path that the watcher applies to
        `mode` - type of watcher to add
      Throws:
        `InterruptedException` - If the server transaction is interrupted.
        `KeeperException` - If the server signals an error with a non-zero error code.
      Since:
        3.6.0

    - #### addWatch

          public void addWatch(String basePath,
                               Watcher watcher,
                               AddWatchMode mode,
                               AsyncCallback.VoidCallback cb,
                               Object ctx)

      Async version of `addWatch(String, Watcher, AddWatchMode)` (see it for details)
      Parameters:
        `basePath` - the path that the watcher applies to
        `watcher` - the watcher
        `mode` - type of watcher to add
        `cb` - a handler for the callback
        `ctx` - context to be provided to the callback
      Throws:
        `IllegalArgumentException` - if an invalid path is specified
      Since:
        3.6.0

    - #### addWatch

          public void addWatch(String basePath,
                               AddWatchMode mode,
                               AsyncCallback.VoidCallback cb,
                               Object ctx)

      Async version of `addWatch(String, AddWatchMode)` (see it for details)
      Parameters:
        `basePath` - the path that the watcher applies to
        `mode` - type of watcher to add
        `cb` - a handler for the callback
        `ctx` - context to be provided to the callback
      Throws:
        `IllegalArgumentException` - if an invalid path is specified
      Since:
        3.6.0

    - #### getState

          public ZooKeeper.States getState()

    - #### toString

          public String toString()

      String representation of this ZooKeeper client. Suitable for things like logging. Do NOT count on the format of this string, it may change without warning.
      Overrides:
        `toString` in class `Object`
      Since:
        3.3.0

    - #### testableWaitForShutdown

          protected boolean testableWaitForShutdown(int wait)
                                             throws InterruptedException

      Wait up to wait milliseconds for the underlying threads to shutdown. THIS METHOD IS EXPECTED TO BE USED FOR TESTING ONLY!!!
      Parameters:
        `wait` - max wait in milliseconds
      Returns:
        true iff all threads are shutdown, otw false
      Throws:
        `InterruptedException`
      Since:
        3.3.0

    - #### testableRemoteSocketAddress

          protected SocketAddress testableRemoteSocketAddress()

      Returns the address to which the socket is connected. Useful for testing against an ensemble - test client may need to know which server to shutdown if interested in verifying that the code handles disconnection/reconnection correctly. THIS METHOD IS EXPECTED TO BE USED FOR TESTING ONLY!!!
      Returns:
        ip address of the remote side of the connection or null if not connected
      Since:
        3.3.0

    - #### testableLocalSocketAddress

          protected SocketAddress testableLocalSocketAddress()

      Returns the local address to which the socket is bound. THIS METHOD IS EXPECTED TO BE USED FOR TESTING ONLY!!!
      Returns:
        ip address of the remote side of the connection or null if not connected
      Since:
        3.3.0

    - #### whoAmI

          public List<ClientInfo> whoAmI()
                                  throws InterruptedException

      Gives all authentication information added into the current session.
      Returns:
        list of authentication info
      Throws:
        `InterruptedException` - when interrupted

Copyright © 2008–2021 The Apache Software Foundation. All rights reserved.