public final class CloudEvent extends Object
CloudEvents is a specification for describing event data in common formats to provide interoperability across services, platforms and systems.
Some Azure services, for instance, EventGrid, are compatible with this specification. You can use this class to communicate with these Azure services.
Depending on your scenario, you can either use the constructor
CloudEvent.CloudEvent(String, String, BinaryData, CloudEventDataFormat, String)
to
create a CloudEvent, or use the factory method CloudEvent.fromString(String)
to deserialize CloudEvent instances
from a Json String representation of CloudEvents.
If you have the data payload of a CloudEvent and want to send it out, use the constructor
CloudEvent.CloudEvent(String, String, BinaryData, CloudEventDataFormat, String)
to create it. Then you can
serialize the CloudEvent into its Json String representation and send it.
Create CloudEvent Samples
// Use BinaryData.fromBytes() to create data in format CloudEventDataFormat.BYTES byte[] exampleBytes = "Hello World".getBytes(StandardCharsets.UTF_8); CloudEvent cloudEvent = new CloudEvent("/cloudevents/example/source", "Example.EventType", BinaryData.fromBytes(exampleBytes), CloudEventDataFormat.BYTES, "application/octet-stream"); // Use BinaryData.fromObject() to create CloudEvent data in format CloudEventDataFormat.JSON // From a model class User user = new User("Stephen", "James"); CloudEvent cloudEventDataObject = new CloudEvent("/cloudevents/example/source", "Example.EventType", BinaryData.fromObject(user), CloudEventDataFormat.JSON, "application/json"); // From a String CloudEvent cloudEventDataStr = new CloudEvent("/cloudevents/example/source", "Example.EventType", BinaryData.fromObject("Hello World"), CloudEventDataFormat.JSON, "text/plain"); // From an Integer CloudEvent cloudEventDataInt = new CloudEvent("/cloudevents/example/source", "Example.EventType", BinaryData.fromObject(1), CloudEventDataFormat.JSON, "int"); // From a Boolean CloudEvent cloudEventDataBool = new CloudEvent("/cloudevents/example/source", "Example.EventType", BinaryData.fromObject(true), CloudEventDataFormat.JSON, "bool"); // From null CloudEvent cloudEventDataNull = new CloudEvent("/cloudevents/example/source", "Example.EventType", BinaryData.fromObject(null), CloudEventDataFormat.JSON, "null"); // Use BinaryData.fromString() if you have a Json String for the CloudEvent data. String jsonStringForData = "\"Hello World\""; // A json String. CloudEvent cloudEventDataJsonStr = new CloudEvent("/cloudevents/example/source", "Example.EventType", BinaryData.fromString(jsonStringForData), CloudEventDataFormat.JSON, "text/plain");
On the contrary, if you receive CloudEvents and have the Json string representation of one or more of CloudEvents,
use CloudEvent.fromString(String)
to deserialize them from the Json string.
Deserialize CloudEvent Samples
List<CloudEvent> cloudEventList = CloudEvent.fromString(cloudEventJsonString); CloudEvent cloudEvent = cloudEventList.get(0); BinaryData cloudEventData = cloudEvent.getData(); byte[] bytesValue = cloudEventData.toBytes(); // If data payload is in bytes (data_base64 is not null). User objectValue = cloudEventData.toObject(User.class); // If data payload is a User object. int intValue = cloudEventData.toObject(Integer.class); // If data payload is an int. boolean boolValue = cloudEventData.toObject(Boolean.class); // If data payload is boolean. String stringValue = cloudEventData.toObject(String.class); // If data payload is String. String jsonStringValue = cloudEventData.toString(); // The data payload represented in Json String.
Constructor and Description |
---|
CloudEvent(String source,
String type,
BinaryData data,
CloudEventDataFormat format,
String dataContentType)
Create an instance of
CloudEvent . |
Modifier and Type | Method and Description |
---|---|
CloudEvent |
addExtensionAttribute(String name,
Object value)
Add/Overwrite a single extension attribute to the cloud event.
|
static List<CloudEvent> |
fromString(String cloudEventsJson)
Deserialize
CloudEvent JSON string representation that has one CloudEvent object or
an array of CloudEvent objects into a list of CloudEvents, and validate whether any CloudEvents have
null id , source , or type . |
static List<CloudEvent> |
fromString(String cloudEventsJson,
boolean skipValidation)
Deserialize
CloudEvents JSON string representation that has one CloudEvent object or
an array of CloudEvent objects into a list of CloudEvents. |
BinaryData |
getData()
Get the data associated with this event as a
BinaryData , which has API to deserialize the data into
a String, an Object, or a byte[]. |
String |
getDataContentType()
Get the content MIME type that the data is in.
|
String |
getDataSchema()
Get the schema that the data adheres to.
|
Map<String,Object> |
getExtensionAttributes()
Get a map of the additional user-defined attributes associated with this event.
|
String |
getId()
Get the id of the cloud event.
|
String |
getSource()
Get the source of the event.
|
String |
getSubject()
Get the subject associated with this event.
|
OffsetDateTime |
getTime()
Get the time associated with the occurrence of the event.
|
String |
getType()
Get the type of event, e.g.
|
CloudEvent |
setDataSchema(String dataSchema)
Set the schema that the data adheres to.
|
CloudEvent |
setId(String id)
Set a custom id.
|
CloudEvent |
setSubject(String subject)
Set the subject of the event.
|
CloudEvent |
setTime(OffsetDateTime time)
Set the time associated with the occurrence of the event.
|
public CloudEvent(String source, String type, BinaryData data, CloudEventDataFormat format, String dataContentType)
CloudEvent
.
source
, type
, id
, and specversion
are required attributes according to the
CNCF CloudEvent spec.
You must set the source
and type
when using this constructor.
For convenience, id
and specversion
are automatically assigned. You can change the id
by using CloudEvent.setId(String)
after you create a CloudEvent. But you can not change specversion
because this class is specifically for CloudEvent 1.0 schema.
For the CloudEvent data payload, this constructor accepts data
of BinaryData
as the CloudEvent payload.
The data
can be created from objects of type String, bytes, boolean, null, array or other types.
A CloudEvent will be serialized to its Json String representation
to be sent out. Use param format
to indicate whether the data
will be serialized as
bytes, or Json. When CloudEventDataFormat.BYTES
is used, the data payload will be serialized to base64
bytes and stored in attribute data_base64 of the CloudEvent's Json representation. When
CloudEventDataFormat.JSON
is used, the data payload will be serialized as Json data and stored in
attribute data of the CloudEvent's Json representation.
Create CloudEvent Samples
// Use BinaryData.fromBytes() to create data in format CloudEventDataFormat.BYTES byte[] exampleBytes = "Hello World".getBytes(StandardCharsets.UTF_8); CloudEvent cloudEvent = new CloudEvent("/cloudevents/example/source", "Example.EventType", BinaryData.fromBytes(exampleBytes), CloudEventDataFormat.BYTES, "application/octet-stream"); // Use BinaryData.fromObject() to create CloudEvent data in format CloudEventDataFormat.JSON // From a model class User user = new User("Stephen", "James"); CloudEvent cloudEventDataObject = new CloudEvent("/cloudevents/example/source", "Example.EventType", BinaryData.fromObject(user), CloudEventDataFormat.JSON, "application/json"); // From a String CloudEvent cloudEventDataStr = new CloudEvent("/cloudevents/example/source", "Example.EventType", BinaryData.fromObject("Hello World"), CloudEventDataFormat.JSON, "text/plain"); // From an Integer CloudEvent cloudEventDataInt = new CloudEvent("/cloudevents/example/source", "Example.EventType", BinaryData.fromObject(1), CloudEventDataFormat.JSON, "int"); // From a Boolean CloudEvent cloudEventDataBool = new CloudEvent("/cloudevents/example/source", "Example.EventType", BinaryData.fromObject(true), CloudEventDataFormat.JSON, "bool"); // From null CloudEvent cloudEventDataNull = new CloudEvent("/cloudevents/example/source", "Example.EventType", BinaryData.fromObject(null), CloudEventDataFormat.JSON, "null"); // Use BinaryData.fromString() if you have a Json String for the CloudEvent data. String jsonStringForData = "\"Hello World\""; // A json String. CloudEvent cloudEventDataJsonStr = new CloudEvent("/cloudevents/example/source", "Example.EventType", BinaryData.fromString(jsonStringForData), CloudEventDataFormat.JSON, "text/plain");
source
- Identifies the context in which an event happened. The combination of id and source must be unique
for each distinct event.type
- Type of event related to the originating occurrence.data
- A BinaryData
that wraps the original data, which can be a String, byte[], or model class.format
- Set to CloudEventDataFormat.BYTES
to serialize the data to base64 format, or
CloudEventDataFormat.JSON
to serialize the data to JSON value.dataContentType
- The content type of the data. It has no impact on how the data is serialized but tells
the event subscriber how to use the data. Typically the value is of MIME types such as
"application/json", "text/plain", "text/xml", "avro/binary", etc. It can be null.NullPointerException
- if source, type is null, or format is null while data isn't null.IllegalArgumentException
- if format is CloudEventDataFormat.JSON
but the data isn't in a correct
JSON format.public static List<CloudEvent> fromString(String cloudEventsJson)
CloudEvent
JSON string representation that has one CloudEvent object or
an array of CloudEvent objects into a list of CloudEvents, and validate whether any CloudEvents have
null id
, source
, or type
. If you want to skip this validation, use CloudEvent.fromString(String, boolean)
.
Deserialize CloudEvent Samples
List<CloudEvent> cloudEventList = CloudEvent.fromString(cloudEventJsonString); CloudEvent cloudEvent = cloudEventList.get(0); BinaryData cloudEventData = cloudEvent.getData(); byte[] bytesValue = cloudEventData.toBytes(); // If data payload is in bytes (data_base64 is not null). User objectValue = cloudEventData.toObject(User.class); // If data payload is a User object. int intValue = cloudEventData.toObject(Integer.class); // If data payload is an int. boolean boolValue = cloudEventData.toObject(Boolean.class); // If data payload is boolean. String stringValue = cloudEventData.toObject(String.class); // If data payload is String. String jsonStringValue = cloudEventData.toString(); // The data payload represented in Json String.
cloudEventsJson
- the JSON payload containing one or more events.CloudEvents
.NullPointerException
- if cloudEventsJson is null.IllegalArgumentException
- if the input parameter isn't a correct JSON string for a CloudEvent
or an array of CloudEvents, or any deserialized CloudEvents have null id
, source
, or type
.public static List<CloudEvent> fromString(String cloudEventsJson, boolean skipValidation)
CloudEvents
JSON string representation that has one CloudEvent object or
an array of CloudEvent objects into a list of CloudEvents.cloudEventsJson
- the JSON payload containing one or more events.skipValidation
- set to true if you'd like to skip the validation for the deserialized CloudEvents. A valid
CloudEvent should have 'id', 'source' and 'type' not null.CloudEvents
.NullPointerException
- if cloudEventsJson is null.IllegalArgumentException
- if the input parameter isn't a JSON string for a CloudEvent or an array of
CloudEvents, or skipValidation is false and any CloudEvents have null id', 'source', or 'type'.public String getId()
public CloudEvent setId(String id)
id
- the id to set.NullPointerException
- if id is null.IllegalArgumentException
- if id is empty.public String getSource()
public BinaryData getData()
BinaryData
, which has API to deserialize the data into
a String, an Object, or a byte[].BinaryData
that wraps the this event's data payload.public String getType()
public OffsetDateTime getTime()
public CloudEvent setTime(OffsetDateTime time)
time
- the time to set.public String getDataContentType()
public String getDataSchema()
public CloudEvent setDataSchema(String dataSchema)
dataSchema
- a String identifying the schema of the data. The
CNCF CloudEvent spec dataschema is defined as a URI. For compatibility with legacy system, this class
accepts any String. But for interoperability, you should use a URI format string.public String getSubject()
public CloudEvent setSubject(String subject)
subject
- the subject to set.public Map<String,Object> getExtensionAttributes()
public CloudEvent addExtensionAttribute(String name, Object value)
name
- the name of the attribute. It must contains only lower-case alphanumeric characters and not be be any
CloudEvent reserved attribute names.value
- the value to associate with the name.NullPointerException
- if name or value is null.IllegalArgumentException
- if name format isn't correct.Copyright © 2021 Microsoft Corporation. All rights reserved.