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

Interface CuratorCache

  • All Superinterfaces:
    java.lang.AutoCloseable, java.io.Closeable, CuratorCacheAccessor
    All Known Subinterfaces:
    CuratorCacheBridge
    public interface CuratorCache
extends java.io.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 class  CuratorCache.Options
      cache build options

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      static CuratorCacheBridgeBuilder bridgeBuilder​(org.apache.curator.framework.CuratorFramework client, java.lang.String path)
      Start a Curator Cache Bridge builder.
      static CuratorCache build​(org.apache.curator.framework.CuratorFramework client, java.lang.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, java.lang.String path)
      Start a Curator Cache builder
      void close()
      Close the cache, stop responding to events, etc.
      java.util.Optional<ChildData> get​(java.lang.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.
      java.util.stream.Stream<ChildData> stream()
      Return a stream over the storage entries.

    • Method Detail

      • build

        static CuratorCache build​(org.apache.curator.framework.CuratorFramework client,
                          java.lang.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,
                                   java.lang.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,
                                               java.lang.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 java.lang.AutoCloseable
        Specified by:
        close in interface java.io.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

        java.util.Optional<ChildData> get​(java.lang.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

        java.util.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