Class CloudEvent
- java.lang.Object
-
- com.azure.core.models.CloudEvent
-
public final class CloudEvent extends Object
Represents the CloudEvent conforming to the 1.0 schema defined by the Cloud Native Computing Foundation.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 methodfromString(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
Constructors Constructor Description CloudEvent(String source, String type, BinaryData data, CloudEventDataFormat format, String dataContentType)
Create an instance ofCloudEvent
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description CloudEvent
addExtensionAttribute(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.BinaryData
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[].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.
-
-
-
Constructor Detail
-
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 Detail
-
fromString
public 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
. 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
public 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.- 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
public String getId()
Get the id of the cloud event.- Returns:
- the id.
-
setId
public CloudEvent setId(String id)
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
public String getSource()
Get the source of the event.- Returns:
- the source.
-
getData
public BinaryData 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
public String getType()
Get the type of event, e.g. "Contoso.Items.ItemReceived".- Returns:
- the type of the event.
-
getTime
public OffsetDateTime getTime()
Get the time associated with the occurrence of the event.- Returns:
- the event time, or null if the time is not set.
-
setTime
public CloudEvent setTime(OffsetDateTime time)
Set the time associated with the occurrence of the event.- Parameters:
time
- the time to set.- Returns:
- the cloud event itself.
-
getDataContentType
public String 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
public String getDataSchema()
Get the schema that the data adheres to.- Returns:
- a URI of the data schema, or null if it is not set.
-
setDataSchema
public CloudEvent setDataSchema(String dataSchema)
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
public String getSubject()
Get the subject associated with this event.- Returns:
- the subject, or null if it is not set.
-
setSubject
public CloudEvent setSubject(String subject)
Set the subject of the event.- Parameters:
subject
- the subject to set.- Returns:
- the cloud event itself.
-
getExtensionAttributes
public Map<String,Object> getExtensionAttributes()
Get a map of the additional user-defined attributes associated with this event.- Returns:
- an unmodifiable map of the extension attributes.
-
addExtensionAttribute
public CloudEvent addExtensionAttribute(String name, Object value)
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.
-
-