ZooKeeper的原生API

    之所以称之为“原生”，是为了和下次讲的Curator有所区别。讲述的版本还是以3.5.1为例。

    API中一共有5个包：

org.apache.zookeeper

org.apache.zookeeper.client

org.apache.zookeeper.data

org.apache.zookeeper.server

org.apache.zookeeper.server.quorum

    其中，最后两个是用来给应用起内置的独立模式或仲裁模式的zk服务的，我个人不太赞同这种用法，还是鼓励使用专用的zk集群，因此这两个包略过。剩下3个包，org.apache.zookeeper是大头，我们先看简单的，再看大头。

1 org.apache.zookeeper.client

    这个包下只有一个类FourLetterWordMain，是用来执行四字命令的。三种构造函数如下，很简单：

static String send4LetterWord(String host, int port, String cmd)

static String send4LetterWord(String host, int port, String cmd, boolean secure)

static String send4LetterWord(String host, int port, String cmd, boolean secure, int timeout)

    关于四字命令多说几句，这些命令是给客户端检查zk集群状态的。常用的有以下几个：

• conf：列出zk服务器使用的基本配置参数
• cons：列出zk服务器上每个连接的统计信息
• crst：重置每个连接的计数器为0
• dump：列出当前活动的会话信息及这些会话的超时时间，只能在leader服务器上运行
• envi：列出zk服务器的JVM参数
• mntr：列出zk服务器的统计数据，比stat命令更详细，leader服务器的话还将列出只用于leader的额外参数信息
• ruok：提供zk服务器是否ok的信息，只是一个简单的连通性测试
• stat：提供zk服务器的状态信息和当前连接信息，以及该服务器的角色（leader，follower，observer），和所知的最大zxid。
• srvr：和stat信息差不多，只是省略连接信息
• wchc：列出zk服务器设置的监视点的详细信息，根据会话分组
• wchp：列出zk服务器设置的监视点的详细信息，根据znode分组
• wchs：列出zk服务器设置的监视点的简短信息

2 org.apache.zookeeper.data

    该包下总共有4个类：

ACL

Id

Stat

StatPersisted

    顾名思义，该包下都是一些数据的包装类，虽然这些类下也有不少方法可调，不过基本都是get/set，意义比较明显，略过。

3 org.apache.zookeeper

    该包下的接口：

AsyncCallback    

AsyncCallback.ACLCallback    

AsyncCallback.Children2Callback    

AsyncCallback.ChildrenCallback    

AsyncCallback.Create2Callback    

AsyncCallback.DataCallback    

AsyncCallback.MultiCallback    

AsyncCallback.StatCallback    

AsyncCallback.StringCallback    

AsyncCallback.VoidCallback    

KeeperException.CodeDeprecated

Watcher    

Watcher.Event    

ZooDefs.Ids     

ZooDefs.OpCode     

ZooDefs.Perms

    其中，AsyncCallback接口是用于异步操作的回调函数，而AsyncCallback.*的接口都是该接口的具体实现。另一个重要的接口是Watcher。其余都是用于定义常量或参数的，不重要。

    该包下的类：

ServerAdminClient

WatchedEvent

ZooDefs

ZooKeeper

ZooKeeperMain

    其中，ServerAdminClient提供了一个四字命令客户端的封装，不重要。WatchedEvent用于Watcher处理的事件，在讲Watcher时会一并提到。ZooDefs用于定义常量和参数，不重要。ZooKeeper是客户端类的主类，非常重要。ZooKeeperMain提供了一个命令行客户端的实现，某些场景下会有用处，一般重要。

3.1 AsyncCallback.DataCallback  

    以该接口为例看一下AsyncCallback.*的用法，其余都差不多的。

    该接口需要实现的方法只有一个，用于处理异步请求返回的数据：

void processResult(int rc, String path, Object ctx, byte[] data, Stat stat)

    几个参数含义如下：

• rc：调用的返回码，如果成功是KeeperException.Code.OK，如果异常的话是各类异常代码
• path：传给异步操作的znode名字空间路径，对Data接口来说，就是需要获取数据的znode路径
• ctx：传给异步操作的上下文对象，当然可以不传
• data：在这里是获取到数据后返回的byte数组。对其他类型的AsyncCallback.*接口的同名方法，这一项的参数类型可能有变化，比如Create2Callback中该参数是String name，Children2Callback中该参数是List<String> children
• stat：该path的统计信息。对其他类型的AsyncCallback.*接口的同名方法，该参数可能不存在

3.2 Watcher

    该接口需要实现的方法也只有一个，用于当watcher被触发时的处理：

void process(WatchedEvent event)

    参数只有一个，但WatchedEvent这个类有以下几个方法，值得一说：

• String    getPath() ：获取事件发生的名字空间路径
• Watcher.Event.KeeperState    getState() ：用于描述事件发生时，客户端和zk集群间的连接状态，有以下几种值，AuthFailed，ConnectedReadOnly，Disconnected，Expired，SaslAuthenticated，SyncConnected。意义都是比较明显的，客户端代码可以对不同的状态做不同的处理
• Watcher.Event.EventType    getType() ：用于描述事件的类型，有以下几种值，ChildWatchRemoved，DataWatchRemoved，NodeChildrenChanged，NodeCreated，NodeDataChanged，NodeDeleted，None。前几章在讲zk的watcher机制时，已经介绍了绝大多数的事件类型
• org.apache.zookeeper.proto.WatcherEvent    getWrapper()：用于序列化WatchedEvent
• String    toString()：意思显然

3.3 ZooKeeper

    这个类的构造函数有6种，不过主要区别只在于是否只读、是否指定连接的session和密码，其实差别不大：

ZooKeeper(String connectString, int sessionTimeout, Watcher watcher)

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

ZooKeeper(String connectString, int sessionTimeout, Watcher watcher, boolean canBeReadOnly, org.apache.zookeeper.client.HostProvider aHostProvider)

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

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

ZooKeeper(String connectString, int sessionTimeout, Watcher watcher, long sessionId, byte[] sessionPasswd, boolean canBeReadOnly, org.apache.zookeeper.client.HostProvider aHostProvider)

    该类下面的方法则比较多，但也不是都常用，主要方法都有同步和异步两个版本，所以看着很多：

• void    addAuthInfo(String scheme, byte[] auth)：调用ClientCnxn类下的方法，为本连接线程增加认证信息
• void    close()：关闭本客户端连接
• String    create(String path, byte[] data, List<ACL> acl, CreateMode createMode)：同步的建目录方法
• void    create(String path, byte[] data, List<ACL> acl, CreateMode createMode, AsyncCallback.Create2Callback cb, Object ctx)：异步的建目录方法
• void    create(String path, byte[] data, List<ACL> acl, CreateMode createMode, AsyncCallback.StringCallback cb, Object ctx)：另一个异步的建目录方法
• String    create(String path, byte[] data, List<ACL> acl, CreateMode createMode, Stat stat)：同步的建目录方法，顺便返回目录的统计信息
• void    delete(String path, int version)：同步的删目录方法
• void    delete(String path, int version, AsyncCallback.VoidCallback cb, Object ctx)：异步的删目录方法
• Stat    exists(String path, boolean watch)：同步的检验目录存在方法，如果watch设为true，则使用默认的WatchManager给本连接设置一个watcher
• void    exists(String path, boolean watch, AsyncCallback.StatCallback cb, Object ctx)：上一个方法的异步版本
• Stat    exists(String path, Watcher watcher)：同步的检验目录存在方法，和上上个方法不同的是，用指定的Watcher实现来设置watcher
• void    exists(String path, Watcher watcher, AsyncCallback.StatCallback cb, Object ctx)：上一个方法的异步版本
• List<ACL>    getACL(String path, Stat stat)：获取目录的ACL信息，如果stat不为空，将把返回的统计信息放到stat中（以下的stat参数都是这个意思，不再赘述）
• void    getACL(String path, Stat stat, AsyncCallback.ACLCallback cb, Object ctx)：上一个方法的异步版本
• List<String>    getChildren(String path, boolean watch)：同步的获取子目录方法，如果watch设为true，则使用默认的WatchManager给本连接设置一个watcher
• void    getChildren(String path, boolean watch, AsyncCallback.Children2Callback cb, Object ctx)：上一个方法的异步版本
• void    getChildren(String path, boolean watch, AsyncCallback.ChildrenCallback cb, Object ctx)：上上个方法的另一个异步版本
• List<String>    getChildren(String path, boolean watch, Stat stat)：同步的获取子目录方法
• List<String>    getChildren(String path, Watcher watcher)：同步的获取子目录方法，用指定的Watcher实现来设置watcher
• void    getChildren(String path, Watcher watcher, AsyncCallback.Children2Callback cb, Object ctx)：上一个方法的异步版本
• void    getChildren(String path, Watcher watcher, AsyncCallback.ChildrenCallback cb, Object ctx)：上上个方法的另一个异步版本
• List<String>    getChildren(String path, Watcher watcher, Stat stat)：同步的获取子目录方法
• void    getConfig(boolean watch, AsyncCallback.DataCallback cb, Object ctx)：下一个方法的异步版本
• byte[]    getConfig(boolean watch, Stat stat)：同步的获取最近提交的配置信息，如果watch设为true，则使用默认的WatchManager给本连接设置一个watcher
• void    getConfig(Watcher watcher, AsyncCallback.DataCallback cb, Object ctx)：下一个方法的异步版本
• byte[]    getConfig(Watcher watcher, Stat stat)：同步的获取最近提交的配置信息，用指定的Watcher实现来设置watcher
• void    getData(String path, boolean watch, AsyncCallback.DataCallback cb, Object ctx)：下一个方法的异步版本
• byte[]    getData(String path, boolean watch, Stat stat)：同步的获取目录数据的方法，如果watch设为true，则使用默认的WatchManager给本连接设置一个watcher
• void    getData(String path, Watcher watcher, AsyncCallback.DataCallback cb, Object ctx)：下一个方法的异步版本
• byte[]    getData(String path, Watcher watcher, Stat stat)：同步的获取目录数据的方法，用指定的Watcher实现来设置watcher
• org.apache.zookeeper.client.ZooKeeperSaslClient    getSaslClient() ：调用ClientCnxn类下的方法，获取一个SASL认证的客户端，当zk集群有kerberos认证时有用
• long    getSessionId()：获取session id
• byte[]    getSessionPasswd()：获取session的密码
• int    getSessionTimeout()：获取session的超时时间
• ZooKeeper.States    getState() ：获取本连接的状态
• org.apache.zookeeper.Testable    getTestable() ：获取本连接的ZooKeeperTestable封装，没用
• List<org.apache.zookeeper.OpResult>    multi(Iterable<org.apache.zookeeper.Op> ops)：原子地执行多步zk操作
• void    multi(Iterable<org.apache.zookeeper.Op> ops, AsyncCallback.MultiCallback cb, Object ctx)：上一个方法的异步版本
• void    reconfig(List<String> joiningServers, List<String> leavingServers, List<String> newMembers, long fromConfig, AsyncCallback.DataCallback cb, Object ctx)：下一个方法的异步版本
• byte[]    reconfig(List<String> joiningServers, List<String> leavingServers, List<String> newMembers, long fromConfig, Stat stat)：在当前集群增加/移除多台服务器，服务器的列表为List<String>
• void    reconfig(String joiningServers, String leavingServers, String newMembers, long fromConfig, AsyncCallback.DataCallback cb, Object ctx)：下一个方法的异步版本
• byte[]    reconfig(String joiningServers, String leavingServers, String newMembers, long fromConfig, Stat stat)：在当前集群增加/移除多台服务器，服务器的列表为一个逗号分隔的String
• void    register(Watcher watcher)：为当前连接指定一个默认的watcher，将替换构造时WatchManager生成的默认watcher
• void    removeAllWatches(String path, Watcher.WatcherType watcherType, boolean local)：对指定的路径，移除指定类型的所有watcher，如果local设为true，则客户端和zk服务器没有连接时，允许客户端本地移除watcher
• void    removeAllWatches(String path, Watcher.WatcherType watcherType, boolean local, AsyncCallback.VoidCallback cb, Object ctx)：上一个方法的异步版本
• void    removeWatches(String path, Watcher watcher, Watcher.WatcherType watcherType, boolean local)：对指定的路径，移除某个指定类型的watcher
• void    removeWatches(String path, Watcher watcher, Watcher.WatcherType watcherType, boolean local, AsyncCallback.VoidCallback cb, Object ctx)：上一个方法的异步版本
• Stat    setACL(String path, List<ACL> acl, int version)：设置ACL
• void    setACL(String path, List<ACL> acl, int version, AsyncCallback.StatCallback cb, Object ctx)：上一个方法的异步版本
• Stat    setData(String path, byte[] data, int version)：设置数据
• void    setData(String path, byte[] data, int version, AsyncCallback.StatCallback cb, Object ctx)：上一个方法的异步版本
• void    sync(String path, AsyncCallback.VoidCallback cb, Object ctx)：对指定的路径，强制本连接所在的服务器和leader同步信息，异步调用
• String    toString()：没啥说的
• org.apache.zookeeper.Transaction    transaction()：返回一个Transaction builder，Transaction类型是multi操作的瘦包装器
• void    updateServerList(String connectString)：使本客户端更新zk的连接字串

3.4 ZooKeeperMain

    这个类可以看作ZooKeeper类的一个包装，只用于命令行方式连接。

    构造函数有两个，后一种是直接用ZooKeeper类构造的，比较常用。

ZooKeeperMain(String[] args) 

ZooKeeperMain(ZooKeeper zk)

    方法不多：

• static boolean    createQuota(ZooKeeper zk, String path, long bytes, int numNodes)：设置zk某路径的配额，bytes代表存储数据的大小限制，numNodes代表子节点数的限制
• static boolean    delQuota(ZooKeeper zk, String path, boolean bytes, boolean numNodes)：删除配额，bytes设为true代表删除大小限制，numNodes设为true代表删除子节点数限制
• void    executeLine(String line) ：执行一行命令
• static List<String>    getCommands() ：返回命令列表
• boolean    getPrintWatches() ：返回一个布尔值，用于控制watcher触发时是否打印信息
• static void    main(String[] args) ：入口，使其可以以命令行方式运行
• static void    printMessage(String msg)：只是简单打印出msg

    以上就是主要的接口和类。枚举及异常类型的介绍省略。示例代码也不贴了，想看代码的可以参考http://wujiu.iteye.com/blog/2207872  ，是一份不错的异步连接示例代码。总之，想调API还是很容易的，搞清楚原理才是最困难的。