CloudEvent Class

Package:
com.azure.core.models
Maven Artifact:
com.azure:azure-core:1.58.0
  • java.lang.Object
    • com.azure.core.models.CloudEvent

Implements

JsonSerializable<CloudEvent>

public final class CloudEvent
implements JsonSerializable<CloudEvent>

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 source, String type, BinaryData data, CloudEventDataFormat format, String dataContentType) to create a CloudEvent, or use the factory method fromString(String cloudEventsJson) 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 source, String type, BinaryData data, CloudEventDataFormat format, String dataContentType) 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 cloudEventsJson) 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

Constructor Description
CloudEvent(String source, String type, BinaryData data, CloudEventDataFormat format, String dataContentType)

Create an instance of CloudEvent.

Method Summary

Modifier and Type Method and Description
CloudEvent addExtensionAttribute(String name, Object value)

Add/Overwrite a single extension attribute to the cloud event.
static CloudEvent fromJson(JsonReader jsonReader)

Reads a JSON stream into a CloudEvent.
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 CloudEvent 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.
JsonWriter toJson(JsonWriter jsonWriter)

Methods inherited from java.lang.Object

clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Details

CloudEvent

public CloudEvent(String source, String type, BinaryData data, CloudEventDataFormat format, String dataContentType)

Create an instance of 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 setId(String id) 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 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 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 - A BinaryData that wraps the original data, which can be a String, byte[], or model class.
format - Set to BYTES to serialize the data to base64 format, or 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.

Method Details

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 contain only lower-case alphanumeric characters and not be any CloudEvent reserved attribute names.
value - the value to associate with the name.

Returns:

the cloud event itself.

fromJson

public static CloudEvent fromJson(JsonReader jsonReader)

Reads a JSON stream into a CloudEvent.

Parameters:

jsonReader - The JsonReader being read.

Returns:

The CloudEvent that the JSON stream represented, or null if it pointed to JSON null.

Throws:

IOException

 - If a CloudEvent fails to be read from the jsonReader.

fromString

public 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. If you want to skip this validation, use fromString(String cloudEventsJson, boolean skipValidation).

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 the events in the payload deserialized as CloudEvent.

fromString

public static List<CloudEvent> fromString(String cloudEventsJson, boolean skipValidation)

Deserialize CloudEvent 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 the events in the payload deserialized as CloudEvent.

getData

public 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[].

Returns:

A BinaryData that wraps the event's data payload.

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.

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.

getId

public String getId()

Get the id of the cloud event.

Returns:

the id.

getSource

public String getSource()

Get the source of the event.

Returns:

the source.

getSubject

public String getSubject()

Get the subject associated with this event.

Returns:

the subject, or null if it is not set.

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.

getType

public String getType()

Get the type of event, e.g. "Contoso.Items.ItemReceived".

Returns:

the type of the event.

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.

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.

setSubject

public CloudEvent setSubject(String subject)

Set the subject of the event.

Parameters:

subject - the subject to set.

Returns:

the cloud event itself.

setTime

public CloudEvent setTime(OffsetDateTime time)

Set the time associated with the occurrence of the event.

At creation, the time is set to the current UTC time. It can be unset by setting it to null.

Parameters:

time - the time to set.

Returns:

the cloud event itself.

toJson

public JsonWriter toJson(JsonWriter jsonWriter)

Parameters:

jsonWriter

Throws:

Applies to