CloudEvents Core

This package includes implementations and utilities to create and process CloudEvent and interfaces to deal with Protocol Bindings and Event Formats.

For Maven based projects, use the following dependency:

<dependency>
    <groupId>io.cloudevents</groupId>
    <artifactId>cloudevents-core</artifactId>
    <version>2.3.0</version>
</dependency>

Using CloudEvents

To create an event, you can use the CloudEventBuilder:

import io.cloudevents.CloudEvent;
import io.cloudevents.core.builder.CloudEventBuilder;

import java.net.URI;

final CloudEvent event = CloudEventBuilder.v1()
    .withId("000")
    .withType("example.demo")
    .withSource(URI.create("http://example.com"))
    .withData("text/plain","Hello world!".getBytes("UTF-8"))
    .build();

Now you can access the event context attributes and data:

// Get an event attribute
String id = event.getId();

// Get an event extension
Object someExtension = event.getExtension("myextension");

// Retrieve the event data
CloudEventData data = event.getData();

Creating and accessing to the event data

CloudEventData is an abstraction that can wrap any kind of data payload, while still enforcing the conversion to bytes. To convert to bytes:

// Convert the event data to bytes
byte[]bytes = cloudEventData.toBytes();

If you want to map the JSON event data to POJOs using Jackson, check out the CloudEvents Jackson documentation.

When building an event, you can wrap a POJO inside its payload using PojoCloudEventData, providing the function to convert it back to bytes:

CloudEventData pojoData = PojoCloudEventData.wrap(myPojo, myPojo::toBytes);

Using Event Formats

The SDK implements Event Formats in various submodules, but keeping a single entrypoint for users who wants to serialize/deserialize events back and forth to event formats.

To use an Event Format, you just need to add the event format implementation you prefer as dependency in your project and the core module, through the ServiceLoader mechanism, will load it into the classpath. For example, to use the JSON event format with Jackson, add cloudevents-json-jackson as a dependency and then using the EventFormatProvider:

import io.cloudevents.core.format.EventFormatProvider;
import io.cloudevents.jackson.JsonFormat;

EventFormat format = EventFormatProvider
  .getInstance()
  .resolveFormat(JsonFormat.CONTENT_TYPE);

// Serialize event
byte[] serialized = format.serialize(event);

// Deserialize event
CloudEvent event = format.deserialize(bytes);

Materialize an Extension

CloudEvent extensions can be materialized in their respective POJOs using the ExtensionProvider:

import io.cloudevents.core.extensions.DistributedTracingExtension;
import io.cloudevents.core.provider.ExtensionProvider;

DistributedTracingExtension dte = ExtensionProvider.getInstance()
    .parseExtension(DistributedTracingExtension.class, event);