Class CloudEvent
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(String, String, BinaryData, CloudEventDataFormat, String)
to
create a CloudEvent, or use the factory method 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(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 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 Summary
ConstructorDescriptionCloudEvent
(String source, String type, BinaryData data, CloudEventDataFormat format, String dataContentType) Create an instance ofCloudEvent
. -
Method Summary
Modifier and TypeMethodDescriptionaddExtensionAttribute
(String name, Object value) Add/Overwrite a single extension attribute to the cloud event.static List<CloudEvent>
fromString
(String cloudEventsJson) DeserializeCloudEvent
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 nullid
,source
, ortype
.static List<CloudEvent>
fromString
(String cloudEventsJson, boolean skipValidation) DeserializeCloudEvents
JSON string representation that has one CloudEvent object or an array of CloudEvent objects into a list of CloudEvents.getData()
Get the data associated with this event as aBinaryData
, which has API to deserialize the data into a String, an Object, or a byte[].Get the content MIME type that the data is in.Get the schema that the data adheres to.Get a map of the additional user-defined attributes associated with this event.getId()
Get the id of the cloud event.Get the source of the event.Get the subject associated with this event.getTime()
Get the time associated with the occurrence of the event.getType()
Get the type of event, e.g.setDataSchema
(String dataSchema) Set the schema that the data adheres to.Set a custom id.setSubject
(String subject) Set the subject of the event.setTime
(OffsetDateTime time) Set the time associated with the occurrence of the event.
-
Constructor Details
-
CloudEvent
public CloudEvent(String source, String type, BinaryData data, CloudEventDataFormat format, String dataContentType) Create an instance ofCloudEvent
.source
,type
,id
, andspecversion
are required attributes according to the CNCF CloudEvent spec. You must set thesource
andtype
when using this constructor. For convenience,id
andspecversion
are automatically assigned. You can change theid
by usingsetId(String)
after you create a CloudEvent. But you can not changespecversion
because this class is specifically for CloudEvent 1.0 schema.For the CloudEvent data payload, this constructor accepts
data
ofBinaryData
as the CloudEvent payload. Thedata
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 paramformat
to indicate whether thedata
will be serialized as bytes, or Json. WhenCloudEventDataFormat.BYTES
is used, the data payload will be serialized to base64 bytes and stored in attribute data_base64 of the CloudEvent's Json representation. WhenCloudEventDataFormat.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");
- Parameters:
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
- ABinaryData
that wraps the original data, which can be a String, byte[], or model class.format
- Set toCloudEventDataFormat.BYTES
to serialize the data to base64 format, orCloudEventDataFormat.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.- Throws:
NullPointerException
- if source, type is null, or format is null while data isn't null.IllegalArgumentException
- if format isCloudEventDataFormat.JSON
but the data isn't in a correct JSON format.
-
-
Method Details
-
fromString
DeserializeCloudEvent
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 nullid
,source
, ortype
. If you want to skip this validation, usefromString(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.
- Parameters:
cloudEventsJson
- the JSON payload containing one or more events.- Returns:
- all of the events in the payload deserialized as
CloudEvents
. - Throws:
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 nullid
,source
, ortype
.
-
fromString
DeserializeCloudEvents
JSON string representation that has one CloudEvent object or an array of CloudEvent objects into a list of CloudEvents.- Parameters:
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.- Returns:
- all of the events in the payload deserialized as
CloudEvents
. - Throws:
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'.
-
getId
Get the id of the cloud event.- Returns:
- the id.
-
setId
Set a custom id. Note that a random id is already set by default.- Parameters:
id
- the id to set.- Returns:
- the cloud event itself.
- Throws:
NullPointerException
- if id is null.IllegalArgumentException
- if id is empty.
-
getSource
Get the source of the event.- Returns:
- the source.
-
getData
Get the data associated with this event as aBinaryData
, which has API to deserialize the data into a String, an Object, or a byte[].- Returns:
- A
BinaryData
that wraps the this event's data payload.
-
getType
Get the type of event, e.g. "Contoso.Items.ItemReceived".- Returns:
- the type of the event.
-
getTime
Get the time associated with the occurrence of the event.- Returns:
- the event time, or null if the time is not set.
-
setTime
Set the time associated with the occurrence of the event.- Parameters:
time
- the time to set.- Returns:
- the cloud event itself.
-
getDataContentType
Get the content MIME type that the data is in.- Returns:
- the content type the data is in, or null it is not set.
-
getDataSchema
Get the schema that the data adheres to.- Returns:
- a URI of the data schema, or null if it is not set.
-
setDataSchema
Set the schema that the data adheres to.- Parameters:
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.- Returns:
- the cloud event itself.
-
getSubject
Get the subject associated with this event.- Returns:
- the subject, or null if it is not set.
-
setSubject
Set the subject of the event.- Parameters:
subject
- the subject to set.- Returns:
- the cloud event itself.
-
getExtensionAttributes
Get a map of the additional user-defined attributes associated with this event.- Returns:
- an unmodifiable map of the extension attributes.
-
addExtensionAttribute
Add/Overwrite a single extension attribute to the cloud event.- Parameters:
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.- Returns:
- the cloud event itself.
- Throws:
NullPointerException
- if name or value is null.IllegalArgumentException
- if name format isn't correct.
-