Interface Metadata
- All Superinterfaces:
Iterable<Metadata.MetadataEntry>
The exact semantics of how metadata is handled depends on the underlying transport. This API exposes case insensitive lookups on metadata, but maintains the original case of the keys as received or inserted. If case matters, the iterator should be used to access elements.
Multiple values are also supported per key, if the underlying transport does not support multiple values per key, which value will be used is undefined.
Metadata can either have a string or a binary value. If the underlying transport doesn't support one or the other, how those values are handled is undefined - eg, text values may be UTF-8 encoded in binary, or binary values may be Base64 encoded, it depends on the transport.
This API maintains the order of entries, but the underlying transport may not.
Implementations of this class should be immutable, all update operations should return a copy of the metadata.
-
Nested Class Summary
-
Field Summary
-
Method Summary
Modifier and TypeMethodDescriptionAdd the string value for the given key.addBinary
(String key, ByteBuffer value) Add the binary value for the given key.Return a CloudEvent representation of this Metadata.asCloudEvent
(String id, URI source, String type) Convert this metadata to a CloudEvent, adding the given required CloudEvent fields.clear()
Clear all metadata entries.Get the string value for the given key, if found.Get all the string values for a given key.Get all the keys for all the entries.Get the binary value for the given key, if found.getBinaryAll
(String key) Get all the binary values for a given key.boolean
Check whether this metadata has a entry for the given key.boolean
Whether this metadata is also a CloudEvent.Get the JWT claims present in this metadata.Get the principals associated with this request metadata.Remove all metadata entries with the given key.Set the string value for the given key.setBinary
(String key, ByteBuffer value) Set the binary value for the given key.Get the trace context associated with this request metadata.withStatusCode
(StatusCode.Redirect httpStatusCode) Add an HTTP response code to this metadata.withStatusCode
(StatusCode.Success httpStatusCode) Add an HTTP response code to this metadata.Methods inherited from interface java.lang.Iterable
forEach, iterator, spliterator
-
Field Details
-
EMPTY
An empty Metadata object.
-
-
Method Details
-
get
Get the string value for the given key, if found.If the entry is a binary entry, nothing will be returned.
The key lookup is case insensitive. If multiple entries with the same key are present, the first string entry will be returned.
- Parameters:
key
- The key to lookup.- Returns:
- The value, if found.
-
getAll
Get all the string values for a given key.Binary values will be ignored. The key lookup is case insensitive.
- Parameters:
key
- The key to lookup.- Returns:
- A list of all the string values for the given key.
-
getBinary
Get the binary value for the given key, if found.If the entry is a string entry, nothing will be returned.
The key lookup is case insensitive. If multiple entries with the same key are present, the first binary entry will be returned.
- Parameters:
key
- The key to lookup.- Returns:
- The value, if found.
-
getBinaryAll
Get all the binary values for a given key.String values will be ignored. The key lookup is case insensitive.
- Parameters:
key
- The key to lookup.- Returns:
- A list of all the binary values for the given key.
-
has
Check whether this metadata has a entry for the given key.The key lookup will be case insensitive.
- Parameters:
key
- The key to lookup.- Returns:
- True if an entry for the given key exists, otherwise false.
-
getAllKeys
Get all the keys for all the entries.This list may contain duplicate keys if there are multiple entries with the same key.
The case of the keys will be the case as passed from the proxy or from other APIs.
- Returns:
- A list of all the keys in this metadata.
-
set
Set the string value for the given key.This will replace any existing entries that case insensitively match the given key.
This method does not modify this Metadata object, it returns a copy of this Metadata object with the entry set.
- Parameters:
key
- The key to set.value
- The value to set.- Returns:
- A copy of this Metadata object with the entry set.
-
setBinary
Set the binary value for the given key.This will replace any existing entries that case insensitively match the given key.
This method does not modify this Metadata object, it returns a copy of this Metadata object with the entry set.
- Parameters:
key
- The key to set.value
- The value to set.- Returns:
- A copy of this Metadata object with the entry set.
-
add
Add the string value for the given key.This will not replace any existing entries, it will simply append the entry to the end of the list.
This method does not modify this Metadata object, it returns a copy of this Metadata object with the entry added.
- Parameters:
key
- The key to add.value
- The value to add.- Returns:
- A copy of this Metadata object with the entry added.
-
addBinary
Add the binary value for the given key.This will not replace any existing entries, it will simply append the entry to the end of the list.
This method does not modify this Metadata object, it returns a copy of this Metadata object with the entry added.
- Parameters:
key
- The key to add.value
- The value to add.- Returns:
- A copy of this Metadata object with the entry added.
-
remove
Remove all metadata entries with the given key.The key will be matched against entries case insensitively.
This method does not modify this Metadata object, it returns a copy of this Metadata object with the entries removed.
- Parameters:
key
- The key to remove.- Returns:
- A copy of this Metadata object with the entries removed.
-
clear
Metadata clear()Clear all metadata entries.This method does not modify this Metadata object, it returns an empty Metadata object.
- Returns:
- An empty metadata object.
-
isCloudEvent
boolean isCloudEvent()Whether this metadata is also a CloudEvent.This will return true if all of the required CloudEvent fields are set, that is, the specversion, id, source and type fields.
- Returns:
- True if the CloudEvent required attributes are set in this Metadata.
-
asCloudEvent
CloudEvent asCloudEvent()Return a CloudEvent representation of this Metadata.Note that the CloudEvent representation will retain any non CloudEvent metadata when converted back to Metadata.
- Returns:
- This Metadata expressed as CloudEvent metadata.
- Throws:
IllegalStateException
- If this metadata is not a CloudEvent, that is, if it doesn't have any of specversion, id, source or type CloudEvent fields defined.
-
asCloudEvent
Convert this metadata to a CloudEvent, adding the given required CloudEvent fields.Any metadata in this Metadata object will be left intact when asMetadata is called
- Parameters:
id
- The id of the CloudEvent.source
- The source of the CloudEvent.type
- The type of the CloudEvent.- Returns:
- This metadata, represented as a CloudEvent with the specified fields.
-
jwtClaims
JwtClaims jwtClaims()Get the JWT claims present in this metadata.- Returns:
- The JWT claims.
-
principals
Principals principals()Get the principals associated with this request metadata.- Returns:
- The principals associated with this request metadata.
-
traceContext
TraceContext traceContext()Get the trace context associated with this request metadata.- Returns:
- The trace context.
-
withStatusCode
Add an HTTP response code to this metadata. This will only take effect when HTTP transcoding is in use. It will be ignored for gRPC requests.- Parameters:
httpStatusCode
- The success status code to add.- Returns:
- a copy of this metadata with the HTTP response code set.
-
withStatusCode
Add an HTTP response code to this metadata. This will only take effect when HTTP transcoding is in use. It will be ignored for gRPC requests.- Parameters:
httpStatusCode
- The redirect status code to add.- Returns:
- a copy of this metadata with the HTTP response code set.
-