Package com.linecorp.centraldogma.client

Interface Watcher<T>

Type Parameters:
T - the watch result type
All Superinterfaces:
AutoCloseable
public interface Watcher<T> extends AutoCloseable
Watches the changes of a repository or a file. The Watcher must be closed via close() after use.

  • Method Details

    • atJsonPointer

      static Watcher<JsonNode> atJsonPointer(Watcher<JsonNode> watcher, String jsonPointer)
      Creates a forked Watcher based on an existing JsonNode-watching Watcher.
      Parameters:
      jsonPointer - a JSON pointer that is encoded
      Returns:
      A new child Watcher, whose transformation is a JSON pointer query.

    • watchScheduler

      ScheduledExecutorService watchScheduler()
      Returns the ScheduledExecutorService that is used to schedule watch.

    • initialValueFuture

      CompletableFuture<Latest<T>> initialValueFuture()
      Returns the CompletableFuture which is completed when the initial value retrieval is done successfully.

    • awaitInitialValue

      default Latest<T> awaitInitialValue() throws InterruptedException
      Waits for the initial value to be available.
      Returns:
      the Latest object that contains the initial value and the Revision where the initial value came from.
      Throws:
      CancellationException - if this watcher has been closed by close()
      EntryNotFoundException - if errorOnEntryNotFound is true and entry isn't found on watching the initial value
      InterruptedException

    • awaitInitialValue

      default Latest<T> awaitInitialValue(long timeout, TimeUnit unit) throws InterruptedException, TimeoutException
      Waits for the initial value to be available. Specify the default value with awaitInitialValue(long, TimeUnit, Object) or make sure to handle a TimeoutException properly if the initial value must be available even when the server is unavailable.
      Parameters:
      timeout - the maximum amount of time to wait for the initial value. Note that timeout is basically a trade-off. If you specify a smaller timeout, this method will have a higher chance of throwing a TimeoutException when the server does not respond in time. If you specify a larger timeout, you will have a better chance of successful retrieval. It is generally recommended to use a value not less than 20 seconds so that the client can retry at least a few times before timing out. Consider using awaitInitialValue(long, TimeUnit, Object) with a sensible default value if you cannot tolerate a timeout or need to use a small timeout.
      unit - the TimeUnit of timeout.
      Returns:
      the Latest object that contains the initial value and the Revision where the initial value came from.
      Throws:
      CancellationException - if this watcher has been closed by close()
      EntryNotFoundException - if errorOnEntryNotFound is true and entry isn't found on watching the initial value
      TimeoutException - if failed to retrieve the initial value within the specified timeout
      InterruptedException

    • awaitInitialValue

      @Nullable default T awaitInitialValue(long timeout, TimeUnit unit, @Nullable T defaultValue) throws InterruptedException
      Waits for the initial value to be available and returns the specified default value if failed to retrieve the initial value from the server.
      Parameters:
      timeout - the maximum amount of time to wait for the initial value. Note that timeout is basically a trade-off. If you specify a smaller timeout, this method will have a higher chance of falling back to the defaultValue when the server does not respond in time. If you specify a larger timeout, you will have a better chance of retrieving an up-to-date initial value. It is generally recommended to use a value not less than 20 seconds so that the client can retry at least a few times before timing out.
      unit - the TimeUnit of timeout.
      defaultValue - the default value to use when timed out.
      Returns:
      the initial value, or the default value if timed out.
      Throws:
      CancellationException - if this watcher has been closed by close()
      EntryNotFoundException - if errorOnEntryNotFound is true and entry isn't found on watching the initial value
      InterruptedException

    • latest

      Latest<T> latest()
      Returns the latest Revision and value of watchFile() or watchRepository() result.
      Throws:
      IllegalStateException - if the value is not available yet. Use awaitInitialValue(long, TimeUnit) first or add a listener using watch(BiConsumer) instead.

    • latestValue

      @Nullable default T latestValue()
      Returns the latest value of watchFile() or watchRepository() result.
      Throws:
      IllegalStateException - if the value is not available yet. Use awaitInitialValue(long, TimeUnit) first or add a listener using watch(BiConsumer) instead.

    • latestValue

      @Nullable default T latestValue(@Nullable T defaultValue)
      Returns the latest value of watchFile() or watchRepository() result.
      Parameters:
      defaultValue - the default value which is returned when the value is not available yet

    • close

      void close()
      Stops watching the file specified in the Query or the PathPattern in the repository.
      Specified by:
      close in interface AutoCloseable

    • watch

      void watch(BiConsumer<? super Revision,? super T> listener)
      Registers a BiConsumer that will be invoked when the value of the watched entry becomes available or changes.

      Note that the specified BiConsumer is not called when errorOnEntryNotFound is true and the target doesn't exist in the Central Dogma server when this Watcher sends the initial watch call. You should use initialValueFuture() or awaitInitialValue() to check the target exists or not.

    • watch

      void watch(BiConsumer<? super Revision,? super T> listener, Executor executor)
      Registers a BiConsumer that will be invoked when the value of the watched entry becomes available or changes.

      Note that the specified BiConsumer is not called when errorOnEntryNotFound is true and the target doesn't exist in the Central Dogma server when this Watcher sends the initial watch call. You should use initialValueFuture() or awaitInitialValue() to check the target exists or not.

      Parameters:
      executor - the Executor that executes the BiConsumer

    • watch

      default void watch(Consumer<? super T> listener)
      Registers a Consumer that will be invoked when the value of the watched entry becomes available or changes.

    • watch

      default void watch(Consumer<? super T> listener, Executor executor)
      Registers a Consumer that will be invoked when the value of the watched entry becomes available or changes.

    • newChild

      default <U> Watcher<U> newChild(Function<? super T,? extends U> mapper)
      Returns a Watcher that applies the Function for the Latest.value().

    • newChild

      default <U> Watcher<U> newChild(Function<? super T,? extends U> mapper, Executor executor)
      Returns a Watcher that applies the Function for the Latest.value().