Class BackgroundObserver

  • All Implemented Interfaces:
    Closeable, AutoCloseable, Observer

    public class BackgroundObserver
    extends Object
    implements Observer, Closeable
    An observer that uses a change queue and a background thread to forward content changes to another observer. The mechanism is designed so that the contentChanged(NodeState, CommitInfo) method will never block, regardless of the behavior of the other observer. If that observer blocks or is too slow to consume all content changes, causing the change queue to fill up, any further update will automatically be merged into just one external content change, causing potential loss of local commit information. To help prevent such cases, any sequential external content changes that the background observer thread has yet to process are optionally (see alwaysCollapseExternalEvents and oak.observation.alwaysCollapseExternal) automatically merged to just one change.
    • Constructor Detail

      • BackgroundObserver

        public BackgroundObserver​(@NotNull
                                  @NotNull Observer observer,
                                  @NotNull
                                  @NotNull Executor executor,
                                  int queueLength)
      • BackgroundObserver

        public BackgroundObserver​(@NotNull
                                  @NotNull Observer observer,
                                  @NotNull
                                  @NotNull Executor executor)
    • Method Detail

      • added

        protected void added​(int queueSize)
        Called when ever an item has been added to the queue
        Parameters:
        queueSize - size of the queue
      • removed

        protected void removed​(int queueSize,
                               long created)
        Called when ever an item has been removed from the queue.
        Parameters:
        queueSize - the size of the queue after the item was removed.
        created - the time in milliseconds when the removed item was put into the queue.
      • getMaxQueueLength

        public int getMaxQueueLength()
        Returns:
        The max queue length used for this observer's queue
      • close

        public void close()
        Clears the change queue and signals the background thread to stop without making any further contentChanged(NodeState, CommitInfo) calls to the background observer. If the thread is currently in the middle of such a call, then that call is allowed to complete; i.e. the thread is not forcibly interrupted. This method returns immediately without blocking to wait for the thread to finish.

        After a call to this method further calls to contentChanged(NodeState, CommitInfo) will throw a IllegalStateException.

        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Closeable
      • contentChanged

        public void contentChanged​(@NotNull
                                   @NotNull NodeState root,
                                   @NotNull
                                   @NotNull CommitInfo info)
        Description copied from interface: Observer
        Observes a content change. See the Observer class javadocs and relevant repository and observer registration details for more information on when and how this method gets called.
        Specified by:
        contentChanged in interface Observer
        Parameters:
        root - root state of the repository
        info - commit information
        Throws:
        IllegalStateException - if close() has already been called.