Package org.apache.bookkeeper.util

Class SubTreeCache

  • public class SubTreeCache
extends java.lang.Object
    Caching layer for traversing and monitoring changes on a znode subtree.

    ZooKeeper does not provide a way to perform a recursive watch on a subtree. In order to detect changes to a subtree, we need to maintain a cache of nodes which have been listed and have not changed since. This would mirror the set of nodes with live watches in ZooKeeper (since we can't cancel them at the moment).

    In order to avoid having to pre-read the whole subtree up front, we'll weaken the guarantee to only require firing the watcher for updates on nodes read since the watcher was registered which happened after the read. We'll also permit spurious events elsewhere in the tree to avoid having to distinguish between nodes which were read before and after a watch was established.

    Finally, we'll allow (require, even) the user to cancel a registered watcher once no longer interested.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      (package private) java.util.Map<java.lang.String,​org.apache.bookkeeper.util.SubTreeCache.SubTreeNode> cachedNodes  
      (package private) java.util.Set<org.apache.zookeeper.Watcher> pendingWatchers  
      (package private) SubTreeCache.TreeProvider provider  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void cancelWatcher​(org.apache.zookeeper.Watcher watcher)
      Cancel a watcher (noop if not registered or already fired).
      java.util.List<java.lang.String> getChildren​(java.lang.String path)
      Returns children of node.
      void registerWatcher​(org.apache.zookeeper.Watcher watcher)
      Register a watcher.
      SubTreeCache.WatchGuard registerWatcherWithGuard​(org.apache.zookeeper.Watcher watcher)
      Register watcher and get interest guard object which can be used with try-with-resources.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • pendingWatchers

        java.util.Set<org.apache.zookeeper.Watcher> pendingWatchers

      • cachedNodes

        java.util.Map<java.lang.String,​org.apache.bookkeeper.util.SubTreeCache.SubTreeNode> cachedNodes

    • Method Detail

      • getChildren

        public java.util.List<java.lang.String> getChildren​(java.lang.String path)
                                             throws org.apache.zookeeper.KeeperException,
                                                    java.lang.InterruptedException
        Returns children of node.
        Parameters:
        path - Path of which to get children
        Returns:
        Children of path
        Throws:
        org.apache.zookeeper.KeeperException
        java.lang.InterruptedException

      • registerWatcher

        public void registerWatcher​(org.apache.zookeeper.Watcher watcher)
        Register a watcher.

        See class header for semantics.

        Parameters:
        watcher - watcher to register

      • cancelWatcher

        public void cancelWatcher​(org.apache.zookeeper.Watcher watcher)
        Cancel a watcher (noop if not registered or already fired).
        Parameters:
        watcher - Watcher object to cancel

      • registerWatcherWithGuard

        public SubTreeCache.WatchGuard registerWatcherWithGuard​(org.apache.zookeeper.Watcher watcher)
        Register watcher and get interest guard object which can be used with try-with-resources.

        It's important not to leak watchers into this structure. The returned WatchGuard can be used to ensure that the watch is unregistered upon exiting a scope.

        Parameters:
        watcher - Watcher to register