ZooKeeper 常用操作API详解

转载：http://www.aboutyun.com/thread-12817-1-1.html

问题导读：

1、ZooKeeper的常用API方法都有那些？
2、Zookeeper 到底能帮我们解决那些问题？
3、如何实现共享锁（Locks）？




  ZooKeeper是一个用于分布式应用程序的分布式开源协调服务。它使用一组简单的操作原语，使得分布式应用可以实现更高层次的服务——如同步、配置维护、群组和命名管理等。ZK具有高性能、高可用（复制）、有序等特征。请参考上一篇译文zookeeper：一个用于分布式应用的分布式协调服务。本文简单介绍一下开发中经常使用的方法（文档：ZooKeeper API）。
1. create
Class ：org.apache.zookeeper.ZooKeeper

1. public String create(String path, byte[] data, List acl, CreateMode createMode) throws KeeperException, InterruptedException
   
2. public void create(String path, byte[] data, List acl, CreateMode createMode, AsyncCallback.StringCallback cb, Object ctx)

复制代码

创建一个给定路径（path）的节点，并给它设置数据（data）和访问控制列表（acl）。ZooKeeper中的节点相对于文件系统中的目录结构，即是”directory”又是”regular file”。第二个create方法是create的异步版本，当创建完成时则调用异步callback。

(1). org.apache.zookeeper.data.ACL
     这部分节选 说说Zookeeper中的ACL
     ZooKeeper通过ACL来对ZNode进行访问控制。ZooKeeper客户端为znode指定ACL列表，ZooKeeper服务器根据ACL列表判定某个请求ZNode的客户端是否有对应操作的权限。
    一个ACL对象由schema:ID和Permissions组成。

a). scheme: scheme对应于采用哪种方案来进行权限管理，zookeeper实现了一个pluggable的ACL方案，可以通过扩展scheme，来扩展ACL的机制。zookeeper-3.4.4缺省支持下面几种scheme:

    * world: 它下面只有一个id, 叫anyone, world:anyone代表任何人，zookeeper中对所有人有权限的结点就是属于world:anyone的
    * auth: 它不需要id, 只要是通过authentication的user都有权限（zookeeper支持通过kerberos来进行authencation, 也支持username/password形式的authentication)
    * digest: 它对应的id为username:BASE64(SHA1(password))，它需要先通过username:password形式的authentication
    * ip: 它对应的id为客户机的IP地址，设置的时候可以设置一个ip段，比如ip:192.168.1.0/16, 表示匹配前16个bit的IP段
    * super: 在这种scheme情况下，对应的id拥有超级权限，可以做任何事情(cdrwa)

b). perm. ZooKeeper中有5种权限，从低位到高位分别是READ、WRITE、CREATE、DELETE和ADMIN，ACL的Permissions可以是5种权限中的1种或多种，它们的含义是：
* READ: 允许获取该节点的值和列出子节点。
* WRITE: 允许设置该节点的值。
* CREATE: 允许创建子节点。
* DELETE: 可以删除子节点。
* ADMIN: 允许为该节点设置权限。

(2). org.apache.zookeeper.CreateMode
org.apache.zookeeper.CreateMode可以设置znode是否为EPHEMERAL或者SEQUENTIAL。可以为下面四种值:
PERSISTENT 持久化目录znode
PERSISTENT_SEQUENTIAL 顺序自动编号的目录znode。这个目录节点是根据当前已存在的节点数递增。
EPHEMERAL 临时目录znode，一旦创建这个znode的客户端和服务器断开，这个节点就会自动删除。临时节点（EPHEMERAL）不能有子节点数据
EPHEMERAL_SEQUENTIAL 临时自动编号znode。

(3). zkCli命令
在zkCli中实现了create的命令封装，可以用户测试和数据管理：

1. create [-s] [-e] path data acl

复制代码

其中”-s”表示创建一个顺序自动编号的节点,”-e”表示创建一个临时节点.默认为持久性节点
例如：
创建一个永久节点和临时节点

1. create  /test null
   
2. Created /test
   
3. create -e /test0 null
   
4. Created /test0

复制代码

     创建一个顺序自动编号的节点，ACL为使用digest（用户名:test 密码:debugo）,权限为所有（rwcda）。关于digest的产生，可以参考zookeeper中 DigestAuthenticationProvider.generateDigest(String ipName)方法;通过向此方法指定原始的用户名和密码即可获得”digest”之后的字符串,比如传入”test:test”,将会得 到”test:V28q/NynI4JI3Rk54h0r8O5kMug=”,其内部原理是将”密码”部分进行MD5 + sha1操作.

1. create -s /test0/test null digest:test:V28q/NynI4JI3Rk54h0r8O5kMug=:rwcda
   
2. Ephemerals cannot have children: /test0/test
   
3. create -s /test/test null digest:test:V28q/NynI4JI3Rk54h0r8O5kMug=:rwcda
   
4. Created /test/test0000000000

复制代码

创建一个节点，其ACL使用ip（172.19.17.0/24）只具有读权限

1. create /test/test1 "hello world" ip:172.19.17.0/24:r
   
2. Created /test/test1

复制代码

2. exist
class： org.apache.zookeeper.ZooKeeper

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

复制代码

      返回某个path的znode是否存在。并设置是否监控这个节点（第二个参数boolean watcher）。当第二个参数为true且这个语句执行成功时，监听器（watcher）就会在成功执行建立节点/删除节点/修改该节点数据时候被触发。

1. exists(String, Watcher)

复制代码

重载方法，这里可以指定特定的监听器（watcher）对象。

1. exists(String, Watcher, AsyncCallback.StatCallback, Object)
   
2. exists(String, boolean, AsyncCallback.StatCallback, Object)

复制代码

exist的异步实现

3. delete

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

复制代码

删除path对应的znode，version为-1可以匹配任何版本，也就是删除这个节点所有的数据。此外，delete同样存在异步版本。

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

复制代码

delete的异步版本。
例如zkCli中删除某个节点：

1. delete /test/test1

复制代码

4. getChildren

1. public List getChildren(String path, boolean watch) throws KeeperException, InterruptedException

复制代码

  获取指定path下所有的子znode，这个方法和exist一样同样可以设置watcher/指定特定的Watcher对象。

5. setData & getData

1. Stat setData(String path, byte[] data, int version)

复制代码

当给定path的节点存在时给path设置数据，可以指定这个数据的版本号。如果version为-1则可以匹配任意版本。

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

复制代码

setData的异步版本。
byte[] getData(String path, Watcher watcher, Stat stat)
获取这个path对应的znode节点的数据，数据的版本等信息可以通过stat来指定。
void getData(String path, Watcher watcher, AsyncCallback.DataCallback cb, Object ctx)
getData的异步版本。

6. setACL和getACL
Stat setACL(String path, List acl, int version)
给某个znode节点重新设置访问权限，需要注意的是ZooKeeper中的目录节点权限都不具有传递性，父znode节点的权限不能传递给子目录节点。在create中已经介绍了ACL的设置方法，可以设置一系列ACL规则（即指定一系列ACL对象）。
void setACL(String path, List acl, int version, AsyncCallback.StatCallback cb, Object ctx)
setACL的异步版本
List getACL(String path, Stat stat)
返回某个znode节点的ACL对象的列表。
void getACL(String path, Stat stat, AsyncCallback.ACLCallback cb, Object ctx)
getACL的异步版本
例如zkCli中设置某个ACL规则：

1. [zk: localhost:2181(CONNECTED) 43] setAcl /test world:anyone:r
   
2. cZxid = 0xf000500ed
   
3. ctime = Wed Sep 24 15:13:29 CST 2014
   
4. ......
   
5. [zk: localhost:2181(CONNECTED) 44] getAcl /test
   
6. 'world,'anyone
   
7. : r

复制代码

下面的内容摘自 http://www.ibm.com/developerworks/cn/opensource/os-cn-zookeeper/ ，写得很好，转过来自己学习一下。

ZooKeeper 典型的应用场景
     Zookeeper 从设计模式角度来看，是一个基于观察者模式设计的分布式服务管理框架，它负责存储和管理大家都关心的数据，然后接受观察者的注册，一旦这些数据的状态发生变化，Zookeeper 就将负责通知已经在 Zookeeper 上注册的那些观察者做出相应的反应，从而实现集群中类似 Master/Slave 管理模式，关于 Zookeeper 的详细架构等内部细节可以阅读 Zookeeper 的源码

下面详细介绍这些典型的应用场景，也就是 Zookeeper 到底能帮我们解决那些问题？下面将给出答案。

统一命名服务（Name Service）
      分布式应用中，通常需要有一套完整的命名规则，既能够产生唯一的名称又便于人识别和记住，通常情况下用树形的名称结构是一个理想的选择，树形的名称结构是一个有层次的目录结构，既对人友好又不会重复。说到这里你可能想到了 JNDI，没错 Zookeeper 的 Name Service 与 JNDI 能够完成的功能是差不多的，它们都是将有层次的目录结构关联到一定资源上，但是 Zookeeper 的 Name Service 更加是广泛意义上的关联，也许你并不需要将名称关联到特定资源上，你可能只需要一个不会重复名称，就像数据库中产生一个唯一的数字主键一样。

    Name Service 已经是 Zookeeper 内置的功能，你只要调用 Zookeeper 的 API 就能实现。如调用 create 接口就可以很容易创建一个目录节点。

配置管理（Configuration Management）
      配置的管理在分布式应用环境中很常见，例如同一个应用系统需要多台 PC Server 运行，但是它们运行的应用系统的某些配置项是相同的，如果要修改这些相同的配置项，那么就必须同时修改每台运行这个应用系统的 PC Server，这样非常麻烦而且容易出错。

      像这样的配置信息完全可以交给 Zookeeper 来管理，将配置信息保存在 Zookeeper 的某个目录节点中，然后将所有需要修改的应用机器监控配置信息的状态，一旦配置信息发生变化，每台应用机器就会收到 Zookeeper 的通知，然后从 Zookeeper 获取新的配置信息应用到系统中。
图 2. 配置管理结构图

 

集群管理（Group Membership）
      Zookeeper 能够很容易的实现集群管理的功能，如有多台 Server 组成一个服务集群，那么必须要一个“总管”知道当前集群中每台机器的服务状态，一旦有机器不能提供服务，集群中其它集群必须知道，从而做出调整重新分配服务策略。同样当增加集群的服务能力时，就会增加一台或多台 Server，同样也必须让“总管”知道。

      Zookeeper 不仅能够帮你维护当前的集群中机器的服务状态，而且能够帮你选出一个“总管”，让这个总管来管理集群，这就是 Zookeeper 的另一个功能 Leader Election。

     它们的实现方式都是在 Zookeeper 上创建一个 EPHEMERAL 类型的目录节点，然后每个 Server 在它们创建目录节点的父目录节点上调用  getChildren (String path, boolean watch) 方法并设置 watch 为 true，由于是 EPHEMERAL 目录节点，当创建它的 Server 死去，这个目录节点也随之被删除，所以 Children 将会变化，这时  getChildren 上的 Watch 将会被调用，所以其它 Server 就知道已经有某台 Server 死去了。新增 Server 也是同样的原理。
     Zookeeper 如何实现 Leader Election，也就是选出一个 Master Server。和前面的一样每台 Server 创建一个 EPHEMERAL 目录节点，不同的是它还是一个 SEQUENTIAL 目录节点，所以它是个 EPHEMERAL_SEQUENTIAL 目录节点。之所以它是 EPHEMERAL_SEQUENTIAL 目录节点，是因为我们可以给每台 Server 编号，我们可以选择当前是最小编号的 Server 为 Master，假如这个最小编号的 Server 死去，由于是 EPHEMERAL 节点，死去的 Server 对应的节点也被删除，所以当前的节点列表中又出现一个最小编号的节点，我们就选择这个节点为当前 Master。这样就实现了动态选择 Master，避免了传统意义上单 Master 容易出现单点故障的问题。
图 3. 集群管理结构图

 

这部分的示例代码如下，完整的代码请看附件：
清单 3. Leader Election 关键代码

1. void findLeader() throws InterruptedException {
   
2.         byte[] leader = null;
   
3.         try {
   
4.             leader = zk.getData(root + "/leader", true, null);
   
5.         } catch (Exception e) {
   
6.             logger.error(e);
   
7.         }
   
8.         if (leader != null) {
   
9.             following();
   
10.         } else {
    
11.             String newLeader = null;
    
12.             try {
    
13.                 byte[] localhost = InetAddress.getLocalHost().getAddress();
    
14.                 newLeader = zk.create(root + "/leader", localhost,
    
15.                 ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode.EPHEMERAL);
    
16.             } catch (Exception e) {
    
17.                 logger.error(e);
    
18.             }
    
19.             if (newLeader != null) {
    
20.                 leading();
    
21.             } else {
    
22.                 mutex.wait();
    
23.             }
    
24.         }
    
25.     }

复制代码

共享锁（Locks）
      共享锁在同一个进程中很容易实现，但是在跨进程或者在不同 Server 之间就不好实现了。Zookeeper 却很容易实现这个功能，实现方式也是需要获得锁的 Server 创建一个 EPHEMERAL_SEQUENTIAL 目录节点，然后调用 getChildren方法获取当前的目录节点列表中最小的目录节点是不是就是自己创建的目录节点，如果正是自己创建的，那么它就获得了这个锁，如果不是那么它就调用 exists(String path, boolean watch) 方法并监控 Zookeeper 上目录节点列表的变化，一直到自己创建的节点是列表中最小编号的目录节点，从而获得锁，释放锁很简单，只要删除前面它自己所创建的目录节点就行了。
图 4. Zookeeper 实现 Locks 的流程图

 

同步锁的实现代码如下，完整的代码请看附件：
清单 4. 同步锁的关键代码

1. void getLock() throws KeeperException, InterruptedException{
   
2.         List list = zk.getChildren(root, false);
   
3.         String[] nodes = list.toArray(new String[list.size()]);
   
4.         Arrays.sort(nodes);
   
5.         if(myZnode.equals(root+"/"+nodes[0])){
   
6.             doAction();
   
7.         }
   
8.         else{
   
9.             waitForLock(nodes[0]);
   
10.         }
    
11.     }
    
12.     void waitForLock(String lower) throws InterruptedException, KeeperException {
    
13.         Stat stat = zk.exists(root + "/" + lower,true);
    
14.         if(stat != null){
    
15.             mutex.wait();
    
16.         }
    
17.         else{
    
18.             getLock();
    
19.         }
    
20.     }

复制代码

队列管理
Zookeeper 可以处理两种类型的队列：
当一个队列的成员都聚齐时，这个队列才可用，否则一直等待所有成员到达，这种是同步队列。
队列按照 FIFO 方式进行入队和出队操作，例如实现生产者和消费者模型。

同步队列用 Zookeeper 实现的实现思路如下：
      创建一个父目录 /synchronizing，每个成员都监控标志（Set Watch）位目录 /synchronizing/start 是否存在，然后每个成员都加入这个队列，加入队列的方式就是创建 /synchronizing/member_i 的临时目录节点，然后每个成员获取 / synchronizing 目录的所有目录节点，也就是 member_i。判断 i 的值是否已经是成员的个数，如果小于成员个数等待 /synchronizing/start 的出现，如果已经相等就创建 /synchronizing/start。
用下面的流程图更容易理解：
图 5. 同步队列流程图

 

同步队列的关键代码如下，完整的代码请看附件：
清单 5. 同步队列

1. void addQueue() throws KeeperException, InterruptedException{
   
2.         zk.exists(root + "/start",true);
   
3.         zk.create(root + "/" + name, new byte[0], Ids.OPEN_ACL_UNSAFE,
   
4.         CreateMode.EPHEMERAL_SEQUENTIAL);
   
5.         synchronized (mutex) {
   
6.             List list = zk.getChildren(root, false);
   
7.             if (list.size() < size) {
   
8.                 mutex.wait();
   
9.             } else {
   
10.                 zk.create(root + "/start", new byte[0], Ids.OPEN_ACL_UNSAFE,
    
11.                  CreateMode.PERSISTENT);
    
12.             }
    
13.         }
    
14. }

复制代码

当队列没满是进入 wait()，然后会一直等待 Watch 的通知，Watch 的代码如下：

1. public void process(WatchedEvent event) {
   
2.         if(event.getPath().equals(root + "/start") &&
   
3.          event.getType() == Event.EventType.NodeCreated){
   
4.             System.out.println("得到通知");
   
5.             super.process(event);
   
6.             doAction();
   
7.         }
   
8.     }

复制代码

FIFO 队列用 Zookeeper 实现思路如下：
实现的思路也非常简单，就是在特定的目录下创建 SEQUENTIAL 类型的子目录 /queue_i，这样就能保证所有成员加入队列时都是有编号的，出队列时通过 getChildren( ) 方法可以返回当前所有的队列中的元素，然后消费其中最小的一个，这样就能保证 FIFO。
下面是生产者和消费者这种队列形式的示例代码，完整的代码请看附件：
清单 6. 生产者代码

1. boolean produce(int i) throws KeeperException, InterruptedException{
   
2.         ByteBuffer b = ByteBuffer.allocate(4);
   
3.         byte[] value;
   
4.         b.putInt(i);
   
5.         value = b.array();
   
6.         zk.create(root + "/element", value, ZooDefs.Ids.OPEN_ACL_UNSAFE,
   
7.                     CreateMode.PERSISTENT_SEQUENTIAL);
   
8.         return true;
   
9.     }

复制代码

清单 7. 消费者代码

1. int consume() throws KeeperException, InterruptedException{
   
2.         int retvalue = -1;
   
3.         Stat stat = null;
   
4.         while (true) {
   
5.             synchronized (mutex) {
   
6.                 List list = zk.getChildren(root, true);
   
7.                 if (list.size() == 0) {
   
8.                     mutex.wait();
   
9.                 } else {
   
10.                     Integer min = new Integer(list.get(0).substring(7));
    
11.                     for(String s : list){
    
12.                         Integer tempValue = new Integer(s.substring(7));
    
13.                         if(tempValue < min) min = tempValue;
    
14.                     }
    
15.                     byte[] b = zk.getData(root + "/element" + min,false, stat);
    
16.                     zk.delete(root + "/element" + min, 0);
    
17.                     ByteBuffer buffer = ByteBuffer.wrap(b);
    
18.                     retvalue = buffer.getInt();
    
19.                     return retvalue;
    
20.                 }
    
21.             }
    
22.         }
    
23. }

复制代码

总结
      Zookeeper 作为 Hadoop 项目中的一个子项目，是 Hadoop 集群管理的一个必不可少的模块，它主要用来控制集群中的数据，如它管理 Hadoop 集群中的 NameNode，还有 Hbase 中 Master Election、Server 之间状态同步等。

      本文介绍的 Zookeeper 的基本知识，以及介绍了几个典型的应用场景。这些都是 Zookeeper 的基本功能，最重要的是 Zoopkeeper 提供了一套很好的分布式集群管理的机制，就是它这种基于层次型的目录树的数据结构，并对树中的节点进行有效管理，从而可以设计出多种多样的分布式的数据管理模型，而不仅仅局限于上面提到的几个常用应用场景。