Apache Curator（音标[kjʊ(ə)'reɪtə]）Framework是ZooKeeper的Keeper（动物园管理员的管理员）。它是一个Java库，提供了比ZooKeeper更加高层的API，更加易用、可靠。Curator的推荐的ZooKeeper版本是 3.5+，但它也和3.4兼容。

Curator实现了自动的连接管理，当会话过期后，你需要重新创建ZooKeeper客户端，并重新设置Watcher。Curator可以透明的重新创建、重试连接。

Curator以组标识

org.apache.curator

当前版本是4.0.0，通常你需要引用下面这个构件。此构件对curator-framework、curator-client有依赖：

<dependency>
    <groupId>org.apache.curator</groupId>
    <artifactId>curator-recipes</artifactId>
    <version>4.0.0</version>
</dependency>

Curator内置了重连逻辑，因此你不再需要手工Watch和管理了：

String zookeeperConnectionString = "172.21.0.1:2181,172.21.0.2:2181,172.21.0.3:2181";
// 重试策略，如果连接不上ZooKeeper集群如何重连
RetryPolicy retryPolicy = new ExponentialBackoffRetry( 1000, 3 );
CuratorFramework client = CuratorFrameworkFactory.newClient( zookeeperConnectionString, retryPolicy );
client.start();
// 创建znode
client.create().forPath( "/tmp", EMPTY );

client.create().withMode(CreateMode.EPHEMERAL_SEQUENTIAL).forPath("/user", new byte[0]);

client.delete().inBackground().forPath("/user");

client.getData().watched().inBackground().forPath("/user");

Recipes封装了很多高层语义，例如互斥锁、Leader选举，你不再需要手工实现了：

// 分布式互斥锁用法：
InterProcessMutex lock = new InterProcessMutex(client, lockPath);
if ( lock.acquire(maxWait, waitUnit) ) {
    try{
        // 临界区
    }
    finally{
        lock.release();
    }
}

// 在多个进程之间选择Leader
LeaderSelectorListener listener = new LeaderSelectorListenerAdapter() {
    public void takeLeadership(CuratorFramework client) throws Exception {
        // 如果当前进程被选择为Leader则此回调被调用
        // 除非当前进程想放弃Leader地位，不要退出此方法
    }
}

LeaderSelector selector = new LeaderSelector(client, path, listener);
selector.autoRequeue();
selector.start();

Curator提供了此接口，用于处理连接中断：

public interface ConnectionStateListener {
    public void stateChanged(CuratorFramework client, ConnectionState newState);
} 

使用某些Recipe时，你应该通过Listenable.addListener注册此接口的实现。

Recipes是Curator提供的高层封装。大部分Recipes都会自动创建所需要的父znode。

在分布式计算领域，多个同类型服务器（节点）通常需要指定其中一员作为Leader，例如主从复制场景下需要指定主节点（Leader）。

Leader通常通过选举产生，在选举前，任何节点均不知道Leader是谁，选举完毕后，则所有节点对Leader是谁达成共识。

Curator提供了两个Recipes来支持选举。其中LeaderSelectorListener已经在起步一章示例过。

用法示例：

String id = "websvr0";
LeaderLatch ll = new LeaderLatch( client, "/pems/websvr", id );
// 需要先启动
// 一旦启动，LeaderLatch会自动联系其它选举参与者，并随机选择一个作为Leader
ll.start();
// 任何时候，你可以调用下面的接口来判断当前进程是否为Leader
ll.hasLeadership();
// 一直等待，知道变为Leader
ll.await();
// 把当前进程从被选举人列表中移除，如果当前是Leader则放弃此权利，其它进程会被选举为Leader
ll.close();

LeaderLatch会添加一个ConnectionStateListener来监控连接问题：

1. 当连接变为SUSPENDED/LOST状态后，当前Leader的hasLeadership()调用返回false（丢失Leader权限）
2. 当断开的连接变为RECONNECTED，LeaderLatch会删除之前创建的znode，并创建新的

这是一个分布式的可重入（锁的持有者可以反复获得锁）的共享锁，保证任何时刻只能有一个客户端占有锁。

用法示例：

InterProcessMutex mutex = new InterProcessMutex( client, "/mutex/resource" );
// 阻塞，直到获得锁。返回true
mutex.acquire();
// 阻塞一定时间，尝试获得锁，返回true/false
mutex.acquire( 1000, TimeUnit.SECONDS );
// 释放锁，仅仅当调用线程是当初获得锁的线程时，才可以释放
mutex.release();

// 使得锁可被撤销，当其它进程/线程attemptRevoke此锁时，你会得到通知
mutex.makeRevocable( forLock -> {
    // 得到通知后，你可以选择释放锁
    forLock.release();
} );

// 尝试撤销锁
Revoker.attemptRevoke(client,"/mutex/resource" );

你应当设置一个ConnectionStateListener来监听SUSPENDED/LOST状态变更：

1. 当连接变为SUSPENDED状态后，你无法确定当前是否仍然持有锁，除非恢复到RECONNECTED状态
2. 当连接变为LOST状态后，你肯定已经丢失了锁 

API类似于InterProcessMutex，对应类InterProcessSemaphoreMutex。此锁不可以重入。

这是一个可重入的读写锁，所有JVM中的所有线程共享一个分布式的临界区域。此外，该锁是“公平的” —— 每个请求者按照其请求的顺序（ZooKeeper角度）来获得锁。

读写锁维护一对相关联的锁，一个用于读，一个用于写。其中读锁可以被多个进程共同持有，而写锁则是独占的（也不允许读锁被持有）。

持有写锁者，可以继续请求读锁，反之则不行。通过获取写锁 —— 获取读锁 —— 释放写锁，可以实现锁降级。

代码示例：

InterProcessReadWriteLock lock = new InterProcessReadWriteLock( client, "/resource" );
// 获取两个相关的锁，然后调用InterProcessMutex的API即可
InterProcessMutex readLock = lock.readLock();
InterProcessMutex writeLock = lock.writeLock();

你应当设置一个ConnectionStateListener来监听SUSPENDED/LOST状态变更。 

这是一个分布式的信号量。所谓信号量，是一个有限数量的资源集，进程可以租借/归还信号量。此信号量实现是“公平的” —— 每个请求者按照其请求的顺序（ZooKeeper角度）来获得信号量。

确定信号量资源数的方式有两种：

1. 由SharedCountReader类提供
2. 静态声明信号量数量，这要求所有参与者声明相同的数值

代码示例：

// 声明一个具有10个资源的信号量
InterProcessSemaphoreV2 semaphore = new InterProcessSemaphoreV2( client, "/semaphore", 10 );
// 通过SharedCount指定资源数量
SharedCountReader sc = new SharedCount( client, "/sharedcount", 10 );
semaphore = new InterProcessSemaphoreV2( client, "/semaphore", sc );

// 租借一个资源，可选参数等待时间
Lease lease = semaphore.acquire();
// 租借N个资源，可选参数等待时间
Collection<Lease> leases = semaphore.acquire( 2 );

// 归还资源
lease.close();
// 或者：
semaphore.returnLease( lease );
semaphore.returnAll( leases );

你应当设置一个ConnectionStateListener来监听SUSPENDED/LOST状态变更。

持有一系列InterProcessLock的引用，客户端要么获取所有锁，要么失败。当释放时，所有锁一起被释放。

所谓屏障，是一个同步点。每一个进程到达此点都要等待，直到所有进程都到达，则继续。

代码示例： 

DistributedBarrier barrier = new DistributedBarrier( client, "/barrier" );
// 设置屏障，每个客户端设置一次
barrier.setBarrier();

// 等待所有客户端都到达，如果连接丢失，此方法会抛出异常
barrier.waitOnBarrier();

双重屏障，在协作开始之前同步，当足够数量的进程加入到屏障后，开始协作，当所有进程完毕后离开屏障。

代码示例：

// 建立一个10个资源的屏障
DistributedDoubleBarrier barrier = new DistributedDoubleBarrier( client, "/barrier", 10 );
// 进入屏障，当有10个客户端进入屏障后，阻塞解除
barrier.enter();
// 这里是协作逻辑 ...
// 离开屏障，当所有客户端都尝试离开时，阻塞解除
barrier.leave();

如果连接丢失，则enter/leave会抛出异常。 

一个共享的整数，所有客户端均看到一致性的、最新的数值。

代码示例：

// 第三个参数为初始值，假设路径不存在，则自动设置为此值
SharedCount counter = new SharedCount( client, "/counter", 0 );
// 此计数器需要启动
counter.start();
// 设置计数值
counter.setCount( 10 );
// 获取计数值
counter.getCount();
counter.addListener( new SharedCountListener() {
    @Override
    public void countHasChanged( SharedCountReader sharedCount, int newCount ) throws Exception {
        // 计数值变化后异步回调
    }

    @Override
    public void stateChanged( CuratorFramework curatorFramework, ConnectionState connectionState ) {
        // 连接数量变化后的异步回调
        // 如果连接变为SUSPENDED状态，你必须假设计数器的值不再精确
        // 如果连接变为LOST状态，则计数器永久性失效
    }
} );

Curator提供了一个基于Java 8 Completion Stage的纯异步客户端实现。要使用此实现，添加依赖：

<dependency>
    <groupId>org.apache.curator</groupId>
    <artifactId>curator-x-async</artifactId>
    <version>4.0.0</version>
</dependency>

String zookeeperConnectionString = "172.21.0.1:2181,172.21.0.2:2181,172.21.0.3:2181";
RetryPolicy retryPolicy = new ExponentialBackoffRetry( 1000, 3 );
CuratorFramework client = CuratorFrameworkFactory.newClient( zookeeperConnectionString, retryPolicy );
client.start();


// 此包装器提供异步API
AsyncCuratorFramework async = AsyncCuratorFramework.wrap( client );
//    检查znode /user是否存在             如果存在，打印状态结构
async.checkExists().forPath( "/user" ).thenAccept( stat -> LOGGER.debug( stat.toString() ) );

// 获取数据
async.getData().forPath( "/user" ).thenAccept( data -> LOGGER.debug( new String( data ) ) );

// 在最前面添加watched()调用，可以增加Watcher
// 使用AsyncStage（CompletionStage子类型）的event()方法，设置Watcher的回调
async.with( WatchMode.successOnly) // 不关心连接丢失类的事件
     .watched().getData().forPath( "/user" ).event().thenAccept( ev -> LOGGER.debug( ev.toString() ) );

// 同步化
async.create().forPath("/user").toCompletableFuture().get();

通过串行化机制，Apache Curator支持在ZooKeeper的znode中存储类型化的数据。这一功能由Modeled Curator组件负责。

MC不使用原始的字符串形式的路径，而是使用ZPath来抽象ZooKeeper路径。ZPath可以是简单的字符串，也可以包含路径变量，这些变量可以根据需要替换为动态的取值：

// 静态路径
ZPath staticPath = ZPath.parse( "/static/path" );
// 动态路径，使用 {} 包围路径变量，路径变量又叫ID，其中可以包含任何东西，例如{ any thing}但是没有什么意义
// 路径变量（ID）总是从左向右依次解析
ZPath path = ZPath.parseWithIds( "/static/{}/{}" );
// 路径变量可以被替换，如果用于替换的对象是NodeName，则调用其nodeName()方法，否则调用toString()方法
ZPath resolvedPath = path.resolved( "path", new NodeName() {
    public String nodeName() {
        return "name";
    }
}  );
// 输出内容：/static/path/name
System.out.println( resolvedPath );

// 路径可以被部分的解析：
System.out.println( path.resolved( "path" ) );

此类型包含对ZooKeeper路径进行操作（存取强类型对象）所需的全部元数据：

1. 一个ZPath
2. 用于串行化对象的串行化器
3. 关于如何创建znode的选项（顺序、压缩、TTL等）
4. 针对znode的ACL
5. 如何删除znode（是否删除子节点）

要写入一个数据模型到znode的关联数据，参考如下代码： 

public static class ServerInfo implements NodeName {
    private String name;
    private String type;

    @Override
    public String nodeName() {
        return getName();
    }
}

ModelSpec<ServerInfo> spec = ModelSpec.builder(
        ZPath.parseWithIds("/servers/{}"),
        JacksonModelSerializer.build(ServerInfo.class)
).build();
// 依赖异步客户端
ModeledFramework<ServerInfo> modeledClient = ModeledFramework.wrap(async, spec);

ServerInfo info = new ServerInfo();
info.setType("webserver");
info.setName("tk.gmem.cc");
// 输出：/servers/hk.gmem.cc，这个路径是把模型传入ZPath而解析得到的，因为模型实现了NodeName，因此调用其nodeName()替换路径变量
modeledClient.set(info).thenAccept(path -> LOGGER.debug(path)).toCompletableFuture().get();

本例使用JacksonJSON作为串行化机制的实现，需要引入依赖：

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>LATEST</version>
</dependency>

ModelSpec<ServerInfo> spec = ModelSpec.builder(
        ZPath.parseWithIds("/servers/hk.gmem.cc"),
        JacksonModelSerializer.build(ServerInfo.class)
).build();
ModeledFramework<ServerInfo> modeledClient = ModeledFramework.wrap(async, spec);
modeledClient.read().whenComplete((info, e) -> {
    if (e != null) {
        
    } else {
        LOGGER.debug(info.getType());
    }
}).toCompletableFuture().get();

这一功能允许你在一个事务中，执行一系列的ZooKeeper操作。你可以使用迁移来保证某个ZooKeeper子树的数据一致性。示例：

// 一系列操作组成一个迁移
CuratorOp op1 = async.transactionOp().create().forPath("/parent");
CuratorOp op2 = async.transactionOp().create().forPath("/parent/one");
CuratorOp op3 = async.transactionOp().create().forPath("/parent/two");
CuratorOp op4 = async.transactionOp().create().forPath("/parent/three");
// Migration是一个函数式接口，本质上就是一系列操作
Migration migration = () -> Arrays.asList(op1, op2, op3, op4);
// 迁移集可以包含若干个迁移，迁移集必须有个ID
MigrationSet set = MigrationSet.build("main", Collections.singletonList(migration));

// 迁移管理器，负责执行迁移
// 迁移管理器会监控迁移集的执行状态，它只会应用那些没有应用的迁移
MigrationManager manager = new MigrationManager(client,
        lockPath,       // 迁移管理器会锁定此路径
        metaDataPath,   // 存储元数据的路径
        executor,       // 异步执行器
        lockMax         // 锁定最长时间
);
manager.migrate(set).exceptionally(e -> {
    if (e instanceof MigrationException) {
        // migration checksum failed, etc.
    } else {
        // some other kind of error
    }
    return null;
});

在SOA/分布式系统中，服务需要能够相互发现。例如，一个Web服务需要发现缓存服务。可以使用服务发现系统（Service Discovery system）来避免服务位置的硬编码。服务发现系统的功能包括：

1. 允许服务注册自己，便于其它服务调用之
2. 定位某种服务的但个实例
3. 当服务的实例发生变化，可以发出通知

Curator服务发现功能由单独的子项目实现：

<dependency>
    <groupId>org.apache.curator</groupId>
    <artifactId>curator-x-discovery</artifactId>
    <version>4.0.0</version>
</dependency>

这个类代表一个服务的实例，具有名称（同一类型服务共享）、标识符、地址、端口、可选的附加详细信息。服务实例被串行化在znode中，路径为/basePath/serviceName/id。

基于提供策略（provider strategy）对某个特定的命名服务的发现服务进行封装，所谓提供策略，决定了如何从多个服务实例中选择一个实例。内置的策略包括循环选择（Round Robin）、随机、粘性（Sticky，总选择一个实例）。

ServiceProviderBuilder作为ServiceProvider的工厂，由ServiceDiscovery提供。ServiceProviderBuilder允许你设置服务的名称以及其它可选的属性。

ServiceProvider必须在

start()

close()

getInstance()

noteError()

由ServiceDiscoveryBuilder创建，此类负责提供ServiceProviderBuilder。

ServiceProvider必须在

start()

close()

// 当前JVM提供的服务实例
ServiceInstance<InstanceDetail> thisService = ServiceInstance.<InstanceDetail>builder()
        .name( "cacheService" )
        .payload( new InstanceDetail() )
        .address( "192.168.0.89" )
        .port( 8088 )
        .uriSpec( new UriSpec( "http://{address}:{port}" ) )
        .build();

// 服务发现
JsonInstanceSerializer<InstanceDetail> serializer = new JsonInstanceSerializer<InstanceDetail>( InstanceDetail.class );
ServiceDiscovery<InstanceDetail> discovery = ServiceDiscoveryBuilder
        .builder( InstanceDetail.class )
        .client( client )
        .basePath( "/sd" )
        .serializer( serializer )
        .thisInstance( thisService )
        .build();
// 需要启动
discovery.start();

// 服务提供者
ServiceProvider<InstanceDetail> sp = discovery
        .serviceProviderBuilder()
        .serviceName( "cacheService" )
        // 随机选取服务实例
        .providerStrategy( new RandomStrategy<>() )
        // 如果在一分钟内，有10此noteError则认为目标实例宕机
        .downInstancePolicy( new DownInstancePolicy( 60, TimeUnit.SECONDS, 10 ) )
        .build();
// 需要启动
sp.start();


LOGGER.debug( sp.getInstance().buildUriSpec() );

为了让非JVM应用使用服务发现功能，Curator提供了RESTful的WebService，你可以通过HTTP协议来注册、移除、查询服务。

Curator提供了JAX-RS组件，你可以在任何Web容器中，配合JAX-RS提供者（例如Jersey）使用该组件。

可能原因是ZooKeeper服务器的版本与工程声明的ZooKeeper客户端版本不兼容导致。

The post Apache Curator学习笔记 appeared first on 绿色记忆.

ZooKeeper是Hadoop的子项目，实现高可靠的分布式协调服务。它可以提供分布式的配置、同步、命名、集群服务。ZooKeeper暴露了一系列简单的接口，具有Java、C语言绑定。

为了正确构建复杂的服务，ZooKeeper提供以下保证：

1. 顺序一致性：来自客户端的更新，按照它们被发送的顺序应用
2. 原子性：更新要么成功要么失败
3. 单一系统镜像：不管客户端连接到哪个ZooKeeper实例，它都看到服务的一致性视图
4. 可靠性：一旦更新被写入，即是永久的
5. Timeliness：客户端看到的系统视图确保在一定时间范围内更新到最新状态

ZooKeeper由以下组件构成：

1. 服务器：运行在ZooKeeper ensemble节点上的Java服务器
2. 客户端：一个Java类库，用于链接到ZooKeeper集群
3. Native客户端：基于C实现的客户端
4. 其它可选组件

Native客户端和可选组件仅仅支持Linux。

除了Request Processor之外，所有ZooKeeper实例持有一模一样的组件：

1. replicated database，一个内存数据库，包含整个名字空间。对此数据库的更新被刷入磁盘，以便重启后恢复
2. 每个ZooKeeper实例都可以接受客户端请求，读请求基于本地的数据库处理，更新服务状态的写请求基于 agreement protocol处理。此协议：
   1. 将一个实例作为leader，其它实例作为followers
   2. follower从leader接收消息提议，并同意消息递送
   3. 消息层负责leader的故障转移、follower与leader的同步
3. ZooKeeper使用一个定制化的原子消息协议，保证消息层是原子性的。这种原子性保证了本地数据库不会出现数据不一致性 

ZooKeeper很简单，它允许分布式进程通过一个共享的、有层次的名字空间来相互交互。这个名字空间的组织就像文件系统一样，名字空间由数据寄存器（data registers） —— 所谓znodes组成，类似于文件系统的目录/文件，ZooKeeper的数据是驻留内存的，而不是像文件系统那样写在磁盘上。

就像被它管理的分布式进程，ZooKeeper本身也倾向于跨越一组宿主机（所谓ensemble）复制，整体上形成一个ZooKeeper服务。只要大部分节点可用，则ZooKeeper服务可用。

客户端连接到单个ZooKeeper节点，通过一个TCP连接来：

1. 发送请求
2. 获得响应
3. 获得监听的事件
4. 发送心跳

如果此TCP连接丢失，客户端可能连接到另外一个节点。

ZooKeeper使用数字标注每个update，以反应所有ZooKeeper事务的顺序。后续操作可以使用此数字序号实现高层次的抽象，例如同步原语。

ZooKeeper非常高速，特别是在读为主的应用场景下。在上千台机器上运行的ZooKeeper应用，其性能在读写比10:1左右最好。

ZooKeeper提供的名字空间非常类似于Linux目录树，由一系列以 / 分隔的路径元素组成，名字空间中的每个节点以完整路径唯一识别。

ZooKeeper使用多种方式来追踪时间：

1. Zxid：即ZooKeeper事务ID。每次对ZooKeeper的状态做出修改，都对应一个这样的ID。这个ID是单调递增的
2. 版本号：对节点的修改会导致其某个版本号字段变更
3. 时间单元（Ticks）：在集群中，ZooKeeper使用时间单元来界定状态上传、会话过期、Peer连接过期的最小时间间隔
4. 真实时间：节点的创建、修改时间使用真实时间记录

客户端利用C/Java语言绑定库建立会话：

1. 客户端发起调用时，可以指定连接字符串、会话超时、默认Watcher等参数，连接字符串包括逗号分隔的多个ZooKeeper实例的host:port列表
2. 客户端创建一个到ZooKeeper服务集群的句柄（Handle），句柄被创建后，进入CONNECTING状态。这时，ZooKeeper会：
   1. 创建一个代表会话ID的64位整数并分配给客户端
   2. 同时，发送一个会话密码给客户端，客户端重连时需要用到此密码
   3. 根据客户端请求的会话超时ms，确定一个允许的（受限于时间单元，必须在2-20倍之间）会话超时
3. 绑定库尝试建立到某个ZooKeeper实例的TCP连接。连接建立后，句柄进入CONNECTED状态
4. 如果出现不可恢复的错误，包括会话过期、身份验证失败、客户端显式的关闭句柄，则句柄进入CLOSED状态
5. 如果客户端发现连接意外断开，则尝试连接列表中下一个实例，直到重新连接上。客户端重新连接时，会在握手时携带自己的会话ID、密码
6. 客户端重新连接上之后，可能发现会话已经过期
7. 默认Watcher可以在会话状态发生变化（例如连接断开、会话过期）后，通知客户端

从3.2开始，连接字符串可以有一个chroot后缀，例如

127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/pems/webmgr

客户端通过发送PING心跳来保活，这样双方都可以知道连接是否断开。

客户端可以变更连接字符串，也就是变更服务器列表。此变更可能触发一个负载均衡算法，并导致客户端重连到其它服务器。

名字空间的每个节点被称为znode，类似于文件系统的目录。znode有以下特点：

1. 路径是znode的唯一标识
2. znode可以具有关联的数据，还可以具有子节点
3. znode关联的数据通常很小，一般最大KB级别
4. znode具有一个状态结构（Stat Structure），存放版本号、数据长度、修改时间戳等信息
5. znode的数据发生变化，版本号就递增
6. znode同时保存数据的多个版本
7. 读写znode数据的操作都是原子性的，写操作替换掉数据
8. 每个节点包含一个访问控制列表（ACL）用于限制谁能做什么
9. znode可以被监控（watch），一旦数据修改、子节点变化，即可通常关注此znode的客户端。这是ZooKeeper的核心特性

所谓临时（EPHEMERAL）节点，仅仅在创建它的Session存在期间存在。ZooKeeper的客户端Session基于TCP长连接，通过心跳来保活。

当创建一个znode时，你可以要求ZooKeeper在路径尾部自动附加单调递增的计数器。对于父节点来说，此计数器具有唯一性。计数器十位左侧补零，示例：

<path>0000000001

计数器的下一个值，存储在父节点中。如果计数超过2147483647 会出现溢出。

3.6版本新增。这类节点的所有子节点都消失后，可能在未来的某个时间点被自动删除。

ZooKeeper支持监控（Watch）的概念——一次性的事件监听器。它有三个要点：

1. 一次性的：当被监控数据发生变化后，事件发送且仅一次。例如

   getData("/znode1", true)

   导致当znode1的关联数据发生变化后客户端得到通知，但是后续znode1的数据再发生变化则不会自动得到通知
2. 发送给客户端：事件被异步的发送给客户端，并且ZooKeeper提供顺序性保证，客户端不可能在收到通知之前就看到目标数据的变化
3. 监控什么数据：getData/exists针对关联数据进行监控，getChildren()则针对子节点进行监控

ZooKeeper中所有的读操作，包括

getData()

getChildren()

exists()

Watch仅仅在客户端所连接到的服务器上维护，但如果客户端发生重连，则新服务器负责维护客户端之前注册的Watch。有一种情况下，Watch会遗漏监控：

1. 客户端设置了exists监控，然后客户端断开
2. 被监控节点创建，然后又被删除
3. 客户端重连，此时它不会收到Watch

客户端可以调用removeWatches来移除监控。

ZooKeeper对Watch提供以下保证：

1. 先发生的事件，其Watcher先被通知
2. 针对同一事件先注册的Watcher先被通知
3. 先得到Watch通知，然后才能看到目标znode数据的变化

使用Watch时需要注意：

1. 一次性，如果需要获得后续变更通知，需要再次注册Watcher
2. 由于再次注册会有网络延迟，这期间目标znode可能已经发生了多次变化，这些变化是捕获不到的
3. 在连接断开期间，接收不到通知

ZooKeeper支持基于ACL对znode进行访问控制。其实现有些类似UNIX文件模式，不同的是，ZooKeeper没有user/group/world这三种角色，它允许定义无限数量的角色（ID），并为这些角色授权。此外ACL不是递归的，也就是子节点不会继承父节点的授权设置。

ZooKeeper支持可拔插的身份验证方案（scheme）。ID的形式则为

scheme:id

当客户端登录ZooKeeper并对自己进行身份验证时，ZooKeeper将所有对应此客户端的ID都分配给它。当客户端访问znode时，这些ID用来进行ACL验证。

ACL中每个条目的格式为

(scheme:expression, perms)

(ip:172.21.0.0/16, READ)

首先保证1.7或者更高版本的JDK已经安装，然后到稳定频道下载二进制压缩包，解压到合适的目录中。

要启动ZooKeeper服务，需要创建一个配置文件conf/zoo.cfg：

# 基本的时间单元对应的毫秒数，心跳每个时间单元发送一次，会话过期最小时间2时间单元
tickTime=2000
# 内存数据库的快照存放目录
dataDir=/data
# 监听客户端连接的端口
clientPort=2181

独立运行的ZooKeeper可以用户开发、测试目的。在产品环境下，你需要在复制（Replication）模式下运行ZooKeeper。一组复制的ZookKeeper称为Quorum，它们必须共享一致的配置文件：

tickTime=2000
dataDir=/var/lib/zookeeper
clientPort=2181
# 连接到Leader超时时间单元
initLimit=5
# Follower最多落后Leader多少时间单元
syncLimit=2
quorumListenOnAllIPs=true
# 服务器列表，server.X中的X是实例ID，在运行时，每个实例检查自己数据目录下的myid文件，其中以ASCII写着自己的ID
# 前一个端口供Follower连接到Leader使用；后一个端口用于选举Leader
server.1=172.21.0.1:2888:3888
server.2=172.21.0.2:2888:3888
server.3=172.21.0.3:2888:3888

每个Quorum最少应该包含3个ZooKeeper实例，并且应当配置奇数个数的实例。

官方镜像的配置文件路径为/conf/zoo.cfg，下面的命令创建容器：

# ZOO_MY_ID 用于设置myid文件，此镜像假设数据目录是/data
docker run -e "ZOO_MY_ID=2" --name zookeeper-2 --network local --ip 172.21.0.2 -d docker.gmem.cc/zookeeper
docker run -e "ZOO_MY_ID=3" --name zookeeper-3 --network local --ip 172.21.0.3 -d docker.gmem.cc/zookeeper

环境变量

ZOO_LOG_DIR

环境变量

ZOO_LOG4J_PROP

ERROR,ROLLINGFILE

# 在后台启动ZooKeeper服务
zkServer.sh start
# 在前台启动ZooKeeper服务
zkServer.sh start-foreground
# 停止ZooKeeper服务
zkServer.sh stop

# 启动CLI客户端
zkCli -server 127.0.0.1:2181

ZooKeeper具有非常简单的编程接口，它仅仅提供以下操作：

<dependency>
    <groupId>org.apache.zookeeper</groupId>
    <artifactId>zookeeper</artifactId>
    <version>3.4.10</version>
</dependency>

使用模式EPHEMERAL可以创建有序节点，反复针对同一路径创建有序节点，会自动后缀单调递增的编号。

ArrayList<ACL> acl = ZooDefs.Ids.OPEN_ACL_UNSAFE;
byte[] data = { 0 };
// 临时节点不支持子节点
try {
    // 同步创建
    zk.create( "/tmp", data, acl, CreateMode.PERSISTENT );
} catch ( KeeperException e ) {
    if ( e.code() != KeeperException.Code.NODEEXISTS ) throw e;
}
// 异步创建
zk.create( "/tmp/no", data, acl, CreateMode.EPHEMERAL_SEQUENTIAL, ( rc, path, ctx, name ) -> {
    // rc: OK path: /tmp/no, name: /tmp/no0000000000
    // rc: OK path: /tmp/no, name: /tmp/no0000000001
    // rc: OK path: /tmp/no, name: /tmp/no0000000002
    LOGGER.debug( "rc: {} path: {}, name: {}", new Object[]{ KeeperException.Code.get( rc ), path, name } );
}, this );
TimeUnit.SECONDS.sleep( 1 );

这个例子中，我们使用一个Agent来：

1. 管理到ZooKeeper的连接，一旦会话过期即重连
2. 转发ZooKeeper发来的事件通知给客户端
3. 对事件机制进行简单封装，实现了：
   1. 隔离客户端和ZooKeeper
   2. 会话过期后，自动重新注册Watch

Agent代码：

package cc.gmem.study;

import org.apache.zookeeper.WatchedEvent;
import org.apache.zookeeper.Watcher;
import org.apache.zookeeper.ZooKeeper;
import org.apache.zookeeper.data.Stat;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.io.IOException;
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentLinkedDeque;
import java.util.concurrent.ConcurrentLinkedQueue;
import java.util.function.Consumer;

public class ZooKeeperAgent implements Watcher {

    private static final Logger LOGGER = LoggerFactory.getLogger( ZooKeeperAgent.class );


    private ZooKeeper zk;

    private String connectString;

    private int timeout;

    private Map<Event.EventType, Map<String, Queue<Consumer<EventResolver>>>> allListeners;

    // 对WatchedEvent进行简单包装，支持获取znode数据，对客户端屏蔽ZooKeeper
    public class EventResolver {

        private WatchedEvent event;

        public EventResolver( WatchedEvent event ) {
            this.event = event;
        }

        public WatchedEvent getEvent() {
            return event;
        }

        public byte[] getData() {

            return getData( null );
        }

        public byte[] getData( Stat stat ) {
            if ( stat == null ) {
                stat = new Stat();
            }
            try {
                return zk.getData( event.getPath(), false, stat );
            } catch ( Exception e ) {
                throw new RuntimeException( e.getMessage(), e );
            }
        }
    }

    public ZooKeeperAgent( String connectString, int timeout ) {
        this.connectString = connectString;
        this.timeout = timeout;
        allListeners = new ConcurrentHashMap<>();
        allListeners.put( Event.EventType.NodeCreated, new ConcurrentHashMap<>() );
        allListeners.put( Event.EventType.NodeDataChanged, new ConcurrentHashMap<>() );
        allListeners.put( Event.EventType.NodeDeleted, new ConcurrentHashMap<>() );
        allListeners.put( Event.EventType.NodeChildrenChanged, new ConcurrentHashMap<>() );
        allListeners = Collections.unmodifiableMap( allListeners );
        createZooKeeper();
    }

    public void on( Event.EventType eventType, String path, Consumer<EventResolver> listener ) {
        Map<String, Queue<Consumer<EventResolver>>> listenersOfType = this.allListeners.get( eventType );
        Queue<Consumer<EventResolver>> listeners;
        synchronized ( this ) {
            listeners = listenersOfType.get( path );
            if ( listeners == null ) {
                listeners = new ConcurrentLinkedQueue<>();
                listenersOfType.put( path, listeners );
            }
        }
        listeners.add( listener );
        watch( eventType, path );
    }

    private void watch( Event.EventType eventType, String path ) {
        try {
            switch ( eventType ) {
                case NodeCreated:
                    // 这里可以传递一个Watcher类型，也可以传入boolean
                    // 如果为true，使用构造ZooKeeper时提供的Watcher ———— 所谓defaultWatcher
                    zk.exists( path, this );
                    break;
                case NodeDataChanged:
                    Stat stat = new Stat();
                    zk.getData( path, this, stat );
                    break;
                case NodeDeleted:
                    zk.exists( path, this );
                    break;
                case NodeChildrenChanged:
                    zk.getChildren( path, this );
                    break;
            }
        } catch ( Exception e ) {
            LOGGER.error( e.getMessage(), e );
        }
    }

    private void createZooKeeper() {
        try {
            zk = new ZooKeeper( connectString, timeout, this );
            // 新会话，Watch需要重新注册
            allListeners.entrySet().stream().flatMap( entry -> {
                Event.EventType eventType = entry.getKey();
                return entry.getValue().keySet().stream().map( path -> {
                    return new Object[]{ eventType, path };
                } );
            } ).forEach( args -> watch( (Event.EventType) args[0], (String) args[1] ) );
        } catch ( IOException e ) {
            throw new RuntimeException( e.getMessage(), e );
        }
    }

    public void process( WatchedEvent event ) {
        switch ( event.getType() ) {
            case None:
                onKeeperStateEvent( event );
                break;
            default:
                onZnodeEvent( event );
        }
    }

    private void onKeeperStateEvent( WatchedEvent event ) {
        switch ( event.getState() ) {
            case SyncConnected:
                LOGGER.debug( "Connected to server with session id {}", zk.getSessionId() );
                break;
            case Expired:
                LOGGER.debug( "Session expired, recreating" );
                // 一旦会话过期，ZooKeeper对象就废了
                createZooKeeper();
                break;
        }
    }

    private void onZnodeEvent( WatchedEvent event ) {
        Queue<Consumer<EventResolver>> consumers = allListeners.get( event.getType() ).get( event.getPath() );
        if ( consumers != null ) {
            consumers.forEach( consumer -> consumer.accept( new EventResolver( event ) ) );
            // 继续监控
            watch( event.getType(), event.getPath() );
        }
    }

}

客户端代码：

package cc.gmem.study;

import org.apache.zookeeper.KeeperException;
import org.apache.zookeeper.data.Stat;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.concurrent.TimeUnit;

import static org.apache.zookeeper.Watcher.Event.EventType.*;

/**
 * Created by alex on 8/10/16.
 */
public class WatchClient {

    private static final Logger LOGGER = LoggerFactory.getLogger( WatchClient.class );

    public static void main( String[] args ) throws InterruptedException {
        String connectString = "172.21.0.1:2181,172.21.0.2:2181,172.21.0.3:2181";
        ZooKeeperAgent agent = new ZooKeeperAgent( connectString, 2000 * 20 );
        agent.on( NodeCreated, "/user", ( resolver ) -> {
            Stat stat = new Stat();
            LOGGER.debug( "znode craeted with data: {}", new String( resolver.getData( stat ) ) );
        } );
        agent.on( NodeDataChanged, "/user", ( resolver ) -> {
            Stat stat = new Stat();
            LOGGER.debug( "znode data: {}, version: {}", new String( resolver.getData( stat ) ), stat.getVersion() );
        } );
        agent.on( NodeDeleted, "/user", ( resolver ) -> {
            LOGGER.debug( "znode deleted" );
        } );
        TimeUnit.DAYS.sleep( 1 );
    }
}

ZooKeeper名字空间可以直接当做类似于JNDI的命名服务使用，ZooKeeper和JNDI都可以把目录节点关联到特定的资源（但是JNDI的资源是Java对象），ZooKeeper还具有与生俱来的高可用性。

ZooKeeper可以用来管理分布式系统中的配置项，如果多个应用服务实例需要共享很多系统参数，可以交由ZooKeeper来管理，通过Watch的方式，应用服务可以在配置变更后获得通知。

ZooKeeper可以管理服务的集群：

1. 当新增服务器、删除服务器（服务器宕机）时，客户端、ZooKeeper、集群成员可以得到通知。实现原理是：
   1. 每个集群成员启动后，都在某个znode下创建临时子节点，这个子节点依赖于TCP长连接保活
   2. 一旦集群成员宕机，临时子节点由于TCP连接的断开而自动删除
   3. 关注者可以在父节点上调用getChildren( parentPath, true)进行watch，一旦子节点发生增减，此调用即返回
2. 在集群成员中选取Leader（Master）。实现原理是：
   1. 每个成员创建不但是临时，还是有序（SEQUENTIAL）的子节点
   2. 序号最小的成员，总是作为Leader
   3. 如果当前Leader宕机，则次小的成员被选作Leader

要实现独占锁，可以把多个协作者共享的资源抽象为一个znode，然后：

1. 需要占用此资源的协作者，在znode 下创建一个临时、有序子节点
2. 协作者判断自己这个节点序号是否最小：
   1. 如果是，意味着获得锁
   2. 如果否，则在父节点上watch。收到通知后，继续执行步骤2
3.  当需要是否资源时，删除自己创建的子节点即可

所谓屏障（Barrier），即协作者到达某个状态后，等待其它协作者都到达此状态，然后一起继续。基于ZooKeeper可以这样实现屏障：

1. 每个协作者到达状态后，均创建一个子节点
2. 判断子节点总数是否足够：
   1. 如果是，跨越屏障继续执行业务逻辑
   2. 如果否，则在父节点上watch。收到通知后，继续执行步骤2

报错信息：

2017-08-09 17:53:03,750 [myid:1] - ERROR [/172.21.1.1:3888:QuorumCnxManager$Listener@763] - Exception while listening
java.net.BindException: Cannot assign requested address (Bind failed)

解决办法：配置文件添加

quorumListenOnAllIPs=true

可以通过JMX查看，通过Oracle Mission Controll连接到名为 org.apache.zookeeper.server.quorum.QuorumPeerMain  的JVM，在MBean Browser选项卡中可以看到相关信息。

此文件是ZooKeeper运行期间的标准输出，要指定它的存放位置，可以设置

ZOO_LOG_DIR

注意，上述环境变量同时也作为log4j的日志输出目录。

The post ZooKeeper学习笔记 appeared first on 绿色记忆.