Package org.apache.curator.framework.recipes.cache

Interface CuratorCache

All Superinterfaces:
AutoCloseable, Closeable, CuratorCacheAccessor
All Known Subinterfaces:
CuratorCacheBridge
public interface CuratorCache extends Closeable, CuratorCacheAccessor

A utility that attempts to keep the data from a node locally cached. Optionally the entire tree of children below the node can also be cached. Will respond to update/create/delete events, pull down the data, etc. You can register listeners that will get notified when changes occur.

IMPORTANT - Due to how ZooKeeper works you will not get notified of every single event. For example during a network partition the cache will not get events. Imagine the following scenario:

  • Pre-network partition the cache contains "/foo" and "/foo/bar"
  • A network partition occurs and your Curator client loses connection to the server
  • Imagine another client that isn't partitioned, deletes "/foo/bar" and then a third client re-creates "/foo/bar"
  • Your client's partition is fixed. The cache will only see one change - the third client's re-create
Additionally, remember that ZooKeeper is an eventual consistent system. Always use ZNode version numbers when updating nodes.

  • Method Details

    • build

      static CuratorCache build(CuratorFramework client, String path, CuratorCache.Options... options)
      Return a Curator Cache for the given path with the given options using a standard storage instance
      Parameters:
      client - Curator client
      path - path to cache
      options - any options
      Returns:
      cache (note it must be started via start()

    • builder

      static CuratorCacheBuilder builder(CuratorFramework client, String path)
      Start a Curator Cache builder
      Parameters:
      client - Curator client
      path - path to cache
      Returns:
      builder

    • bridgeBuilder

      static CuratorCacheBridgeBuilder bridgeBuilder(CuratorFramework client, String path)
      Start a Curator Cache Bridge builder. A Curator Cache Bridge is a facade that uses CuratorCache if persistent watches are available or TreeCache otherwise (i.e. if you are using ZooKeeper 3.5.x).
      Parameters:
      client - Curator client
      path - path to cache
      Returns:
      bridge builder

    • start

      void start()
      Start the cache. This will cause a complete refresh from the cache's root node and generate events for all nodes found, etc.

    • close

      void close()
      Close the cache, stop responding to events, etc.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • listenable

      Listenable<CuratorCacheListener> listenable()
      Return the listener container so that listeners can be registered to be notified of changes to the cache
      Returns:
      listener container

    • get

      Optional<ChildData> get(String path)
      Return an entry from storage
      Specified by:
      get in interface CuratorCacheAccessor
      Parameters:
      path - path to get
      Returns:
      entry or empty()

    • size

      int size()
      Return the current number of entries in storage
      Specified by:
      size in interface CuratorCacheAccessor
      Returns:
      number of entries

    • stream

      Stream<ChildData> stream()
      Return a stream over the storage entries. Note: for a standard storage instance, the stream behaves like a stream returned by ConcurrentHashMap.entrySet()
      Specified by:
      stream in interface CuratorCacheAccessor
      Returns:
      stream over entries