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

Class PathChildrenCache

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
    public class PathChildrenCache
extends java.lang.Object
implements java.io.Closeable

    A utility that attempts to keep all data from all children of a ZK path locally cached. This class will watch the ZK path, respond to update/create/delete events, pull down the data, etc. You can register a listener that will get notified when changes occur.

    IMPORTANT - it's not possible to stay transactionally in sync. Users of this class must be prepared for false-positives and false-negatives. Additionally, always use the version number when updating data to avoid overwriting another process' change.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.util.concurrent.ThreadFactory defaultThreadFactory  

    • Constructor Summary

      Constructors 
      Constructor Description
      PathChildrenCache​(org.apache.curator.framework.CuratorFramework client, java.lang.String path, boolean cacheData)  
      PathChildrenCache​(org.apache.curator.framework.CuratorFramework client, java.lang.String path, boolean cacheData, boolean dataIsCompressed, java.util.concurrent.ExecutorService executorService)  
      PathChildrenCache​(org.apache.curator.framework.CuratorFramework client, java.lang.String path, boolean cacheData, boolean dataIsCompressed, java.util.concurrent.ThreadFactory threadFactory)  
      PathChildrenCache​(org.apache.curator.framework.CuratorFramework client, java.lang.String path, boolean cacheData, boolean dataIsCompressed, org.apache.curator.utils.CloseableExecutorService executorService)  
      PathChildrenCache​(org.apache.curator.framework.CuratorFramework client, java.lang.String path, boolean cacheData, java.util.concurrent.ThreadFactory threadFactory)  
      PathChildrenCache​(org.apache.curator.framework.CuratorFramework client, java.lang.String path, PathChildrenCacheMode mode)
      Deprecated.
      use PathChildrenCache(CuratorFramework, String, boolean) instead
      PathChildrenCache​(org.apache.curator.framework.CuratorFramework client, java.lang.String path, PathChildrenCacheMode mode, java.util.concurrent.ThreadFactory threadFactory)
      Deprecated.
      use PathChildrenCache(CuratorFramework, String, boolean, ThreadFactory) instead

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void clear()
      Clears the current data without beginning a new query and without generating any events for listeners.
      void clearAndRefresh()
      Clear out current data and begin a new query on the path
      void clearDataBytes​(java.lang.String fullPath)
      As a memory optimization, you can clear the cached data bytes for a node.
      boolean clearDataBytes​(java.lang.String fullPath, int ifVersion)
      As a memory optimization, you can clear the cached data bytes for a node.
      void close()
      Close/end the cache
      protected void ensurePath()  
      java.util.List<ChildData> getCurrentData()
      Return the current data.
      ChildData getCurrentData​(java.lang.String fullPath)
      Return the current data for the given path.
      org.apache.curator.framework.listen.ListenerContainer<PathChildrenCacheListener> getListenable()
      Return the cache listenable
      protected void handleException​(java.lang.Throwable e)
      Default behavior is just to log the exception
      void rebuild()
      NOTE: this is a BLOCKING method.
      void rebuildNode​(java.lang.String fullPath)
      NOTE: this is a BLOCKING method.
      protected void remove​(java.lang.String fullPath)  
      void start()
      Start the cache.
      void start​(boolean buildInitial)
      Deprecated.
      use start(StartMode)
      void start​(PathChildrenCache.StartMode mode)
      Start the cache.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • defaultThreadFactory

        public static final java.util.concurrent.ThreadFactory defaultThreadFactory

    • Constructor Detail

      • PathChildrenCache

        @Deprecated
public PathChildrenCache​(org.apache.curator.framework.CuratorFramework client,
                         java.lang.String path,
                         PathChildrenCacheMode mode,
                         java.util.concurrent.ThreadFactory threadFactory)
        Deprecated.
        use PathChildrenCache(CuratorFramework, String, boolean, ThreadFactory) instead
        Parameters:
        client - the client
        path - path to watch
        mode - caching mode
        threadFactory - factory to use when creating internal threads

      • PathChildrenCache

        public PathChildrenCache​(org.apache.curator.framework.CuratorFramework client,
                         java.lang.String path,
                         boolean cacheData)
        Parameters:
        client - the client
        path - path to watch
        cacheData - if true, node contents are cached in addition to the stat

      • PathChildrenCache

        public PathChildrenCache​(org.apache.curator.framework.CuratorFramework client,
                         java.lang.String path,
                         boolean cacheData,
                         java.util.concurrent.ThreadFactory threadFactory)
        Parameters:
        client - the client
        path - path to watch
        cacheData - if true, node contents are cached in addition to the stat
        threadFactory - factory to use when creating internal threads

      • PathChildrenCache

        public PathChildrenCache​(org.apache.curator.framework.CuratorFramework client,
                         java.lang.String path,
                         boolean cacheData,
                         boolean dataIsCompressed,
                         java.util.concurrent.ThreadFactory threadFactory)
        Parameters:
        client - the client
        path - path to watch
        cacheData - if true, node contents are cached in addition to the stat
        dataIsCompressed - if true, data in the path is compressed
        threadFactory - factory to use when creating internal threads

      • PathChildrenCache

        public PathChildrenCache​(org.apache.curator.framework.CuratorFramework client,
                         java.lang.String path,
                         boolean cacheData,
                         boolean dataIsCompressed,
                         java.util.concurrent.ExecutorService executorService)
        Parameters:
        client - the client
        path - path to watch
        cacheData - if true, node contents are cached in addition to the stat
        dataIsCompressed - if true, data in the path is compressed
        executorService - ExecutorService to use for the PathChildrenCache's background thread. This service should be single threaded, otherwise the cache may see inconsistent results.

      • PathChildrenCache

        public PathChildrenCache​(org.apache.curator.framework.CuratorFramework client,
                         java.lang.String path,
                         boolean cacheData,
                         boolean dataIsCompressed,
                         org.apache.curator.utils.CloseableExecutorService executorService)
        Parameters:
        client - the client
        path - path to watch
        cacheData - if true, node contents are cached in addition to the stat
        dataIsCompressed - if true, data in the path is compressed
        executorService - Closeable ExecutorService to use for the PathChildrenCache's background thread. This service should be single threaded, otherwise the cache may see inconsistent results.

    • Method Detail

      • start

        public void start()
           throws java.lang.Exception
        Start the cache. The cache is not started automatically. You must call this method.
        Throws:
        java.lang.Exception - errors

      • start

        @Deprecated
public void start​(boolean buildInitial)
           throws java.lang.Exception
        Deprecated.
        use start(StartMode)
        Same as start() but gives the option of doing an initial build
        Parameters:
        buildInitial - if true, rebuild() will be called before this method returns in order to get an initial view of the node; otherwise, the cache will be initialized asynchronously
        Throws:
        java.lang.Exception - errors

      • start

        public void start​(PathChildrenCache.StartMode mode)
           throws java.lang.Exception
        Start the cache. The cache is not started automatically. You must call this method.
        Parameters:
        mode - Method for priming the cache
        Throws:
        java.lang.Exception - errors

      • rebuild

        public void rebuild()
             throws java.lang.Exception
        NOTE: this is a BLOCKING method. Completely rebuild the internal cache by querying for all needed data WITHOUT generating any events to send to listeners.
        Throws:
        java.lang.Exception - errors

      • rebuildNode

        public void rebuildNode​(java.lang.String fullPath)
                 throws java.lang.Exception
        NOTE: this is a BLOCKING method. Rebuild the internal cache for the given node by querying for all needed data WITHOUT generating any events to send to listeners.
        Parameters:
        fullPath - full path of the node to rebuild
        Throws:
        java.lang.Exception - errors

      • close

        public void close()
           throws java.io.IOException
        Close/end the cache
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Throws:
        java.io.IOException - errors

      • getListenable

        public org.apache.curator.framework.listen.ListenerContainer<PathChildrenCacheListener> getListenable()
        Return the cache listenable
        Returns:
        listenable

      • getCurrentData

        public java.util.List<ChildData> getCurrentData()
        Return the current data. There are no guarantees of accuracy. This is merely the most recent view of the data. The data is returned in sorted order.
        Returns:
        list of children and data

      • getCurrentData

        public ChildData getCurrentData​(java.lang.String fullPath)
        Return the current data for the given path. There are no guarantees of accuracy. This is merely the most recent view of the data. If there is no child with that path, null is returned.
        Parameters:
        fullPath - full path to the node to check
        Returns:
        data or null

      • clearDataBytes

        public void clearDataBytes​(java.lang.String fullPath)
        As a memory optimization, you can clear the cached data bytes for a node. Subsequent calls to ChildData.getData() for this node will return null.
        Parameters:
        fullPath - the path of the node to clear

      • clearDataBytes

        public boolean clearDataBytes​(java.lang.String fullPath,
                              int ifVersion)
        As a memory optimization, you can clear the cached data bytes for a node. Subsequent calls to ChildData.getData() for this node will return null.
        Parameters:
        fullPath - the path of the node to clear
        ifVersion - if non-negative, only clear the data if the data's version matches this version
        Returns:
        true if the data was cleared

      • clearAndRefresh

        public void clearAndRefresh()
                     throws java.lang.Exception
        Clear out current data and begin a new query on the path
        Throws:
        java.lang.Exception - errors

      • clear

        public void clear()
        Clears the current data without beginning a new query and without generating any events for listeners.

      • handleException

        protected void handleException​(java.lang.Throwable e)
        Default behavior is just to log the exception
        Parameters:
        e - the exception

      • ensurePath

        protected void ensurePath()
                   throws java.lang.Exception
        Throws:
        java.lang.Exception

      • remove

        protected void remove​(java.lang.String fullPath)