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.

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

    • 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()
      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()
      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()
      InterruptedException

    • latest

      Latest<T> latest()
      Returns the latest Revision and value of watchFile() 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() 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() 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.

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

    • newChild

      default <U> Watcher<U> newChild​(Function<T,​U> transformer)
      Forks into a new Watcher, that reuses the current watcher and applies a transformation.
      Returns:
      A Watcher that is effectively filtering in a sense that, its listeners are not notified when a change has no effect on the transformed value. Furthermore, it does not need to be closed after use.