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 Summary

Modifier and Type	Method	Description
`static Watcher<JsonNode>`	`atJsonPointer(Watcher<JsonNode> watcher, String jsonPointer)`	Creates a forked `Watcher` based on an existing `JsonNode`-watching `Watcher`.
`default Latest<T>`	`awaitInitialValue()`	Waits for the initial value to be available.
`default Latest<T>`	`awaitInitialValue(long timeout, TimeUnit unit)`	Waits for the initial value to be available.
`default T`	`awaitInitialValue(long timeout, TimeUnit unit, T defaultValue)`	Waits for the initial value to be available and returns the specified default value if failed to retrieve the initial value from the server.
`void`	`close()`	Stops watching the file specified in the `Query` or the `PathPattern` in the repository.
`CompletableFuture<Latest<T>>`	`initialValueFuture()`	Returns the `CompletableFuture` which is completed when the initial value retrieval is done successfully.
`Latest<T>`	`latest()`	Returns the latest `Revision` and value of `watchFile()` or `watchRepository()` result.
`default T`	`latestValue()`	Returns the latest value of `watchFile()` or `watchRepository()` result.
`default T`	`latestValue(T defaultValue)`	Returns the latest value of `watchFile()` or `watchRepository()` result.
`default <U> Watcher<U>`	`newChild(Function<? super T,? extends U> mapper)`	Returns a `Watcher` that applies the `Function` for the `Latest.value()`.
`default <U> Watcher<U>`	`newChild(Function<? super T,? extends U> mapper, Executor executor)`	Returns a `Watcher` that applies the `Function` for the `Latest.value()`.
`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.
`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.
`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.
`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.
`ScheduledExecutorService`	`watchScheduler()`	Returns the `ScheduledExecutorService` that is used to schedule watch.

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().

Interface Watcher<T>

Method Summary

Method Details