1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
// Copyright Vespa.ai. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package ai.vespa.feed.client;
import java.io.Closeable;
import java.time.Duration;
import java.util.List;
import java.util.concurrent.CompletableFuture;
/**
* Asynchronous feed client accepting document operations as JSON. The payload should be
* the same as the HTTP payload required by the /document/v1 HTTP API, i.e., <pre>
* {
* "fields": {
* ...
* }
* }
* </pre>
*
* @author bjorncs
* @author jonmv
*/
public interface FeedClient extends Closeable {
/**
* Send a document put with the given parameters, returning a future with the result of the operation.
* Exceptional completion will use be an instance of {@link FeedException} or one of its sub-classes.
*/
CompletableFuture<Result> put(DocumentId documentId, String documentJson, OperationParameters params);
/**
* Send a document update with the given parameters, returning a future with the result of the operation.
* Exceptional completion will use be an instance of {@link FeedException} or one of its sub-classes.
*/
CompletableFuture<Result> update(DocumentId documentId, String updateJson, OperationParameters params);
/**
* Send a document remove with the given parameters, returning a future with the result of the operation.
* Exceptional completion will use be an instance of {@link FeedException} or one of its sub-classes.
*/
CompletableFuture<Result> remove(DocumentId documentId, OperationParameters params);
/**
* Waits for all feed operations to complete, either successfully or with exception.
* @throws MultiFeedException if any operation fails
* @return list of results with the same ordering as the {@code promises} parameter
* */
static List<Result> await(List<CompletableFuture<Result>> promises) throws MultiFeedException {
return Helper.await(promises);
}
/**
* Same as {@link #await(List)} except {@code promises} parameter is a vararg
* @see #await(List)
*/
@SafeVarargs
static List<Result> await(CompletableFuture<Result>... promises) throws MultiFeedException {
return Helper.await(promises);
}
/** Returns a snapshot of the stats for this feed client, such as requests made, and responses by status. */
OperationStats stats();
/** Current state of the circuit breaker. */
CircuitBreaker.State circuitBreakerState();
/** Shut down, and reject new operations. Operations in flight are allowed to complete normally if graceful. */
void close(boolean graceful);
/** Initiates graceful shutdown. See {@link #close(boolean)}. */
default void close() { close(true); }
/** Controls what to retry, and how many times. */
interface RetryStrategy {
/** Whether to retry operations of the given type. */
default boolean retry(OperationType type) { return true; }
/** Maximum number of retries per operation for assumed transient, non-backpressure problems. */
default int retries() { return Integer.MAX_VALUE; }
}
/** Allows slowing down or halting completely operations against the configured endpoint on high failure rates. */
interface CircuitBreaker {
/** A circuit breaker which is always closed. */
CircuitBreaker FUSED = () -> State.CLOSED;
/** Called by the client whenever a successful response is obtained. */
default void success() { }
/** Called by the client whenever an error HTTP response is received. */
default void failure(HttpResponse response) { }
/** Called by the client whenever an exception occurs trying to obtain a HTTP response. */
default void failure(Throwable cause) { }
/** The current state of the circuit breaker. */
State state();
enum State {
/** Circuit is closed: business as usual. */
CLOSED,
/** Circuit is half-open: something is wrong, perhaps it recovers? */
HALF_OPEN,
/** Circuit is open: we have given up. */
OPEN;
}
}
enum OperationType {
/** A document put operation. This is idempotent. */
PUT,
/** A document update operation. This is idempotent if all its contained updates are. */
UPDATE,
/** A document remove operation. This is idempotent. */
REMOVE;
}
}
|
