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 Summary
Modifier and Type Method Description static Watcher<JsonNode>
atJsonPointer(Watcher<JsonNode> watcher, String jsonPointer)
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 theQuery
or thepathPattern
in the repository.CompletableFuture<Latest<T>>
initialValueFuture()
Returns theCompletableFuture
which is completed when the initial value retrieval is done successfully.Latest<T>
latest()
Returns the latestRevision
and value ofwatchFile()
result.default T
latestValue()
Returns the latest value ofwatchFile()
result.default T
latestValue(T defaultValue)
Returns the latest value ofwatchFile()
result.default <U> Watcher<U>
newChild(Function<T,U> transformer)
Forks into a newWatcher
, that reuses the current watcher and applies a transformation.void
watch(BiConsumer<? super Revision,? super T> listener)
Registers aBiConsumer
that will be invoked when the value of the watched entry becomes available or changes.default void
watch(Consumer<? super T> listener)
Registers aConsumer
that will be invoked when the value of the watched entry becomes available or changes.
-
Method Details
-
atJsonPointer
- 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 theCompletableFuture
which is completed when the initial value retrieval is done successfully. -
awaitInitialValue
Waits for the initial value to be available.- Returns:
- the
Latest
object that contains the initial value and theRevision
where the initial value came from. - Throws:
CancellationException
- if this watcher has been closed byclose()
InterruptedException
-
awaitInitialValue
default Latest<T> awaitInitialValue(long timeout, TimeUnit unit) throws InterruptedException, TimeoutExceptionWaits for the initial value to be available. Specify the default value withawaitInitialValue(long, TimeUnit, Object)
or make sure to handle aTimeoutException
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 aTimeoutException
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 usingawaitInitialValue(long, TimeUnit, Object)
with a sensible default value if you cannot tolerate a timeout or need to use a small timeout.unit
- theTimeUnit
oftimeout
.- Returns:
- the
Latest
object that contains the initial value and theRevision
where the initial value came from. - Throws:
CancellationException
- if this watcher has been closed byclose()
TimeoutException
- if failed to retrieve the initial value within the specified timeoutInterruptedException
-
awaitInitialValue
@Nullable default T awaitInitialValue(long timeout, TimeUnit unit, @Nullable T defaultValue) throws InterruptedExceptionWaits 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 thedefaultValue
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
- theTimeUnit
oftimeout
.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 byclose()
InterruptedException
-
latest
Returns the latestRevision
and value ofwatchFile()
result.- Throws:
IllegalStateException
- if the value is not available yet. UseawaitInitialValue(long, TimeUnit)
first or add a listener usingwatch(BiConsumer)
instead.
-
latestValue
Returns the latest value ofwatchFile()
result.- Throws:
IllegalStateException
- if the value is not available yet. UseawaitInitialValue(long, TimeUnit)
first or add a listener usingwatch(BiConsumer)
instead.
-
latestValue
Returns the latest value ofwatchFile()
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 theQuery
or thepathPattern
in the repository.- Specified by:
close
in interfaceAutoCloseable
-
watch
Registers aBiConsumer
that will be invoked when the value of the watched entry becomes available or changes. -
watch
Registers aConsumer
that will be invoked when the value of the watched entry becomes available or changes. -
newChild
Forks into a newWatcher
, 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.
-