-
Notifications
You must be signed in to change notification settings - Fork 215
/
DittoHeaders.java
executable file
·411 lines (363 loc) · 13.4 KB
/
DittoHeaders.java
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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
/*
* Copyright (c) 2017 Contributors to the Eclipse Foundation
*
* See the NOTICE file(s) distributed with this work for additional
* information regarding copyright ownership.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0
*
* SPDX-License-Identifier: EPL-2.0
*/
package org.eclipse.ditto.base.model.headers;
import java.time.Duration;
import java.util.Collection;
import java.util.Map;
import java.util.Optional;
import java.util.Set;
import javax.annotation.Nonnull;
import org.eclipse.ditto.base.model.acks.AcknowledgementRequest;
import org.eclipse.ditto.base.model.auth.AuthorizationContext;
import org.eclipse.ditto.base.model.auth.AuthorizationSubject;
import org.eclipse.ditto.base.model.common.ResponseType;
import org.eclipse.ditto.base.model.headers.contenttype.ContentType;
import org.eclipse.ditto.base.model.headers.entitytag.EntityTag;
import org.eclipse.ditto.base.model.headers.entitytag.EntityTagMatchers;
import org.eclipse.ditto.base.model.headers.metadata.MetadataHeaders;
import org.eclipse.ditto.base.model.json.JsonSchemaVersion;
import org.eclipse.ditto.base.model.json.Jsonifiable;
import org.eclipse.ditto.json.JsonObject;
import org.eclipse.ditto.json.JsonPointer;
/**
* Headers for commands and their responses which provide additional information needed for correlation and transfer.
*
* <em>Implementations of this interface are required to be immutable.</em>
*/
public interface DittoHeaders extends Jsonifiable<JsonObject>, Map<String, String>, WithManifest {
/**
* Returns an empty {@code DittoHeaders} object.
*
* @return empty DittoHeaders.
*/
static DittoHeaders empty() {
return DefaultDittoHeadersBuilder.getEmptyHeaders();
}
/**
* Returns a new instance of {@code DittoHeaders} containing the specified key-value-pairs.
*
* @param headers the key-value-pairs of the result.
* @return the DittoHeaders.
* @throws NullPointerException if {@code headers} is {@code null}.
* @throws IllegalArgumentException if {@code headers} contains an invalid key-value-pair.
*/
static DittoHeaders of(final Map<String, String> headers) {
if (headers instanceof DittoHeaders) {
return (DittoHeaders) headers;
}
return newBuilder(headers).build();
}
/**
* Returns a new empty builder for a {@code DittoHeaders} object.
*
* @return the builder.
*/
@SuppressWarnings({"rawtypes", "java:S3740"})
static DittoHeadersBuilder newBuilder() {
return DefaultDittoHeadersBuilder.newInstance();
}
/**
* Returns a new builder for a {@code DittoHeaders} object which is initialised with the specified headers.
*
* @param headers the initial headers.
* @return the builder.
* @throws NullPointerException if {@code headers} is {@code null}.
* @throws IllegalArgumentException if {@code headers} contains an invalid key-value-pair.
*/
@SuppressWarnings({"rawtypes", "java:S3740"})
static DittoHeadersBuilder newBuilder(final Map<String, String> headers) {
return DefaultDittoHeadersBuilder.of(headers);
}
/**
* Returns a new builder for a {@code DittoHeaders} object which is initialised with the headers the specified
* JSON object provides.
*
* @param jsonObject the JSON object which provides the initial headers.
* @return the builder.
* @throws NullPointerException if {@code jsonObject} is {@code null}.
* @throws IllegalArgumentException if {@code jsonObject} contains an invalid header.
*/
@SuppressWarnings({"rawtypes", "java:S3740"})
static DittoHeadersBuilder newBuilder(final JsonObject jsonObject) {
return DefaultDittoHeadersBuilder.of(jsonObject);
}
/**
* Returns a mutable builder with a fluent API for immutable {@code DittoHeaders}. The builder is initialised with
* the entries of this instance.
*
* @return the new builder.
*/
default DittoHeadersBuilder<?, ?> toBuilder() {
return DefaultDittoHeadersBuilder.of(this);
}
/**
* Returns the ID that is used to mark messages which belong together between clients.
*
* @return the correlation identifier.
*/
Optional<String> getCorrelationId();
/**
* Returns the content-type of the entity.
*
* @return the content-type.
*/
Optional<String> getContentType();
/**
* Returns the accept header of the command.
*
* @return the accept header.
* @since 2.4.0
*/
Optional<String> getAccept();
/**
* Returns the parsed content-type of the entity.
*
* @return the parsed content-type.
* @since 1.3.0
*/
Optional<ContentType> getDittoContentType();
/**
* Returns the json schema version.
*
* @return the schema version.
*/
Optional<JsonSchemaVersion> getSchemaVersion();
/**
* Returns the AuthorizationContext for the command containing this header.
*
* @return the AuthorizationContext.
*/
AuthorizationContext getAuthorizationContext();
/**
* Returns the authorization subjects with granted "READ" permissions for the key in the map defining a pointer in
* the Thing.
* Changes on the returned Set are not reflected back to this headers object.
*
* @return the read granted subjects for pointers in the Thing.
* @since 1.1.0
*/
Set<AuthorizationSubject> getReadGrantedSubjects();
/**
* Returns the authorization subjects with explicitly revoked "READ" permissions for the key in the map defining a
* pointer in the Thing.
* Changes on the returned Set are not reflected back to this headers object.
*
* @return the read revoked subjects for pointers in the Thing.
* @since 1.1.0
*/
Set<AuthorizationSubject> getReadRevokedSubjects();
/**
* Returns the channel (twin/live) on which a Signal/Exception was sent/occurred.
*
* @return the channel (twin/live).
*/
Optional<String> getChannel();
/**
* Returns whether a response to a command is required or if it may be omitted (fire and forget semantics).
* By default, this method returns {@code true}.
*
* @return {@code true} if a response is required, {@code false} else.
*/
boolean isResponseRequired();
/**
* Returns whether a command is to be executed as a dry run.
*
* @return the "dry run" value.
*/
boolean isDryRun();
/**
* Indicates whether this command is flagged as sudo command which should ignore some preventions.
*
* @return True if the command is flagged as sudo command, otherwise false.
* @since 2.1.0
*/
boolean isSudo();
/**
* Indicates whether a query command is meant to also retrieve deleted entities
*
* @return True if the command is is meant to also retrieve deleted entities, otherwise false.
* @since 2.1.0
*/
boolean shouldRetrieveDeleted();
/**
* Returns the condition to use for applying the request.
*
* @return the condition contained in the Condition header.
* @since 2.1.0
*/
Optional<String> getCondition();
/**
* Returns the channel condition, if the live-channel shall be used for the request.
*
* @return the condition contained in the Condition header.
* @since 2.3.0
*/
Optional<String> getLiveChannelCondition();
/**
* Returns whether the live channel condition passed to the things persistence via the
* {@link #getLiveChannelCondition()} header did match the persisted state of a thing or not.
*
* @return whether the live channel condition passed to the things persistence matched or not.
* @since 2.3.0
*/
boolean didLiveChannelConditionMatch();
/**
* Returns the id of the originating session (e.g. WebSocket, AMQP, ...)
*
* @return the "origin" value.
*/
Optional<String> getOrigin();
/**
* Returns the eTag of the entity.
*
* @return the "ETag" value.
*/
Optional<EntityTag> getETag();
/**
* Returns the entity-tags contained in the If-Match header.
*
* @return the entity-tags contained in the If-Match header.
*/
Optional<EntityTagMatchers> getIfMatch();
/**
* Returns the entity-tags contained in the If-None-Match header.
*
* @return the entity-tags contained in the If-None-Match header.
*/
Optional<EntityTagMatchers> getIfNoneMatch();
/**
* Returns the inbound {@code MessageMapper} ID which mapped incoming arbitrary payload from external sources.
*
* @return the {@code MessageMapper} which mapped incoming payload.
*/
Optional<String> getInboundPayloadMapper();
/**
* @return the reply target of a command-response.
*/
Optional<Integer> getReplyTarget();
/**
* @return the list of response types that should be published to the reply target.
* @since 1.2.0
*/
Collection<ResponseType> getExpectedResponseTypes();
/**
* Indicates whether the size of the headers entries is greater than the specified size.
*
* @param size the size to compare to.
* @return {@code true} if the size of the headers entries exceeds {@code size}, {@code false} else.
* @throws IllegalArgumentException if {@code maxSizeBytes} is negative.
*/
boolean isEntriesSizeGreaterThan(long size);
/**
* Truncates this headers to the specified size limit, keeping as many header entries as possible.
*
* @param maxSizeBytes the maximum allowed size in bytes.
* @return the headers within the size limit.
* @throws IllegalArgumentException if {@code maxSizeBytes} is negative.
*/
DittoHeaders truncate(long maxSizeBytes);
/**
* Returns the acknowledgements ("ACK") which were requested together with an issued Ditto {@code Command}.
* Such ACKs are sent back to the issuer of the command so that it can be verified which steps were successful.
* <p>
* In addition to built-in ACK labels like
* {@link org.eclipse.ditto.base.model.acks.DittoAcknowledgementLabel#TWIN_PERSISTED} also custom labels may be used
* which can be sent back even by external systems.
* </p>
*
* @return an unsorted Set of the requested acknowledgements.
* Changes on the set are not reflected back to this DittoHeaders instance.
* @since 1.1.0
*/
Set<AcknowledgementRequest> getAcknowledgementRequests();
/**
* Returns the timeout of a command or message.
* <p>
* E.g. used for when {@code AcknowledgementLabel}s were requested as timeout defining how long to wait for those
* Acknowledgements.
* </p>
*
* @return the command timeout.
* @since 1.1.0
*/
Optional<Duration> getTimeout();
/**
* Returns what to do when a thing query command with smart channel selection does not receive a valid live
* response within the given timeout period.
*
* @return the live channel timeout strategy if the headers define any.
* @since 2.3.0
*/
Optional<LiveChannelTimeoutStrategy> getLiveChannelTimeoutStrategy();
/**
* Returns the metadata headers to put/set for the (modifying) command they were added to.
*
* @return the MetadataHeaders to put being a sorted set of {@code MetadataHeader}s.
* Changes on the returned set are not reflected back to this DittoHeaders instance.
* @since 1.2.0
*/
MetadataHeaders getMetadataHeadersToPut();
/**
* Returns the metadata fields to get for the (retrieving) response were they should be added to.
*
* @return set of {@code JsonPointer}s to get {@code Metadata} for.
* Changes on the returned set are not reflected back to this DittoHeaders instance.
* @since 3.0.0
*/
Set<JsonPointer> getMetadataFieldsToGet();
/**
* Returns the metadata fields to delete metadata for the modifying request.
*
* @return set of {@code JsonPointer}s to delete {@code Metadata} for.
* Changes on the returned set are not reflected back to this DittoHeaders instance.
* @since 3.0.0
*/
Set<JsonPointer> getMetadataFieldsToDelete();
/**
* Returns whether the policy lockout is allowed.
*
* @return {@code true} if the policy lockout is allowed
* @since 1.3.0
*/
boolean isAllowPolicyLockout();
/**
* Returns the tags which should be applied by persistence actors when appending an event into the event journal.
*
* @return the tags to apply for event journal persistence.
* @since 2.0.0
*/
Set<String> getJournalTags();
/**
* @return the w3c traceparent header or an empty optional if not available
* @since 2.1.0
*/
Optional<String> getTraceParent();
/**
* @return the w3c tracestate header or an empty optional if not available
* @since 2.1.0
*/
Optional<String> getTraceState();
/**
* Return a copy of the headers with the original capitalization of header keys.
*
* @return headers map with the original capitalization.
* @since 2.0.0
*/
Map<String, String> asCaseSensitiveMap();
@Override
@Nonnull
default String getManifest() {
// subclasses are serialized as DittoHeaders
return DittoHeaders.class.getSimpleName();
}
}