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
  • Image 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.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    CuratorCache.Options
    cache build options

  • Method Summary

    Modifier and Type
    Method
    Description
    static CuratorCacheBridgeBuilder
    bridgeBuilder(org.apache.curator.framework.CuratorFramework client, String path)
    Start a Curator Cache Bridge builder.
    static CuratorCache
    build(org.apache.curator.framework.CuratorFramework client, String path, CuratorCache.Options... options)
    Return a Curator Cache for the given path with the given options using a standard storage instance
    static CuratorCacheBuilder
    builder(org.apache.curator.framework.CuratorFramework client, String path)
    Start a Curator Cache builder
    void
    close()
    Close the cache, stop responding to events, etc.
    Optional<ChildData>
    get(String path)
    Return an entry from storage
    org.apache.curator.framework.listen.Listenable<CuratorCacheListener>
    listenable()
    Return the listener container so that listeners can be registered to be notified of changes to the cache
    int
    size()
    Return the current number of entries in storage
    void
    start()
    Start the cache.
    Stream<ChildData>
    stream()
    Return a stream over the storage entries.

  • Method Details

    • build

      static CuratorCache build(org.apache.curator.framework.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(org.apache.curator.framework.CuratorFramework client, String path)
      Start a Curator Cache builder
      Parameters:
      client - Curator client
      path - path to cache
      Returns:
      builder

    • bridgeBuilder

      static CuratorCacheBridgeBuilder bridgeBuilder(org.apache.curator.framework.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

      org.apache.curator.framework.listen.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