Introduction

ZooKeeper watches are not continuous subscriptions by default. A standard watch fires once, and if you still care about future changes, your client must set the watch again as part of handling the event or performing the next read.

Understand the One-Time Nature of Watches

This is the most important rule: a watch is consumed when the matching event occurs. If you call getData, exists, or getChildren with watch enabled, ZooKeeper sends a notification when something changes, but that watch does not stay active forever.

That means the normal pattern is:

1. read node state while setting a watch
2. receive a watch event
3. read again and set a new watch

If you skip step three, future updates on that path will not trigger another notification.

Re-Register Inside the Watch Handling Flow

In Java, the most common approach is to perform another read inside the watcher callback and set the watcher again.

1import org.apache.zookeeper.WatchedEvent;
2import org.apache.zookeeper.Watcher;
3import org.apache.zookeeper.ZooKeeper;
4
5public final class DataWatcher implements Watcher {
6    private final ZooKeeper zooKeeper;
7
8    public DataWatcher(ZooKeeper zooKeeper) {
9        this.zooKeeper = zooKeeper;
10    }
11
12    @Override
13    public void process(WatchedEvent event) {
14        try {
15            if (event.getPath() != null) {
16                byte[] data = zooKeeper.getData(event.getPath(), this, null);
17                System.out.println("Updated data length: " + data.length);
18            }
19        } catch (Exception ex) {
20            ex.printStackTrace();
21        }
22    }
23}

The key point is that getData(..., this, ...) both reads the latest state and installs the next watch in one step.

Choose the Right Read Method

Different read calls watch different kinds of changes:

• 'exists(path, watcher) watches node creation, deletion, and data changes depending on the current state'
• 'getData(path, watcher, stat) watches data changes and deletion'
• 'getChildren(path, watcher) watches child-list changes'

You should re-register with the same semantic read that matches what you care about. Replacing getChildren with getData, for example, changes the meaning of the watch.

Handle Disconnects and Session Events Separately

ZooKeeper also sends connection-related events such as SyncConnected and Expired. Those are not normal znode events, and they need different handling.

If the session expires, ephemeral nodes disappear and previously registered standard watches are gone with the old session. The correct recovery path is usually:

1. create a new ZooKeeper session
2. rebuild any ephemeral state
3. issue fresh reads that install fresh watches

Re-registering only inside the old callback is not enough after session expiration.

Prefer Persistent Watches When Available

Newer ZooKeeper versions added persistent watches. Those remain active until you remove them, which avoids the repeated re-registration cycle for many use cases.

1import org.apache.zookeeper.AddWatchMode;
2
3zooKeeper.addWatch("/services", event -> {
4    System.out.println("watch event: " + event);
5}, AddWatchMode.PERSISTENT);

Persistent watches simplify client logic, but you still need to handle reconnection, session state, and application-level consistency carefully.

Keep the Callback Lightweight

Watcher callbacks should be quick. If processing is expensive, hand the work off to another thread or executor. Blocking heavily inside the callback can make event handling harder to reason about and can delay follow-up reads that re-establish watches.

A common production pattern is:

• callback logs the event
• callback submits work to another component
• worker reloads current state and re-establishes the next watch

Common Pitfalls

• Assuming a standard watch stays active after the first event.
• Re-registering the wrong type of watch by calling a different read method.
• Ignoring session expiration and expecting old watches to survive it.
• Doing heavy business logic directly inside the watcher callback.
• Treating persistent watches as a reason to stop thinking about reconnection and state recovery.

Summary

• Standard ZooKeeper watches are one-time triggers and must usually be re-registered.
• Re-registration normally happens by reading the node again with watch enabled.
• Use exists, getData, or getChildren based on the kind of change you need to observe.
• Session expiration requires full recovery, not just another callback action.
• Persistent watches reduce re-registration overhead but do not remove the need for sound client design.