Package com.azure.core.models

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 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 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) 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");
      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 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.
      Throws:
      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.

  • Method Details

    • 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, 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 null id, source, or type.

    • fromString

      public 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.
      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 a BinaryData, 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.