sdk-java/docs/protobuf.md

title	nav_order
CloudEvents Protocol Buffers	4

CloudEvents Protocol Buffers

This module provides the Protocol Buffer (protobuf) EventFormat implementation using the Java Protobuf runtime and classes generated from the CloudEvents proto spec.

Setup

For Maven based projects, use the following dependency:

<dependency>
    <groupId>io.cloudevents</groupId>
    <artifactId>cloudevents-protobuf</artifactId>
    <version>4.0.0</version>
</dependency>

No further configuration is required is use the module.

Using the Protobuf Event Format

Event serialization

import io.cloudevents.CloudEvent;
import io.cloudevents.core.format.ContentType;
import io.cloudevents.core.format.EventFormatProvider;
import io.cloudevents.core.builder.CloudEventBuilder;

CloudEvent event = CloudEventBuilder.v1()
    .withId("hello")
    .withType("example.vertx")
    .withSource(URI.create("http://localhost"))
    .build();

byte[]serialized = EventFormatProvider
    .getInstance()
    .resolveFormat(ContentType.PROTO)
    .serialize(event);

The EventFormatProvider will automatically resolve the ProtobufFormat using the ServiceLoader APIs.

Passing Protobuf messages as CloudEvent data.

The ProtoCloudEventData capability provides a convenience mechanism to handle Protobuf message object data.

Building

// Build my business event message.
com.google.protobuf.Message myMessage = ..... ;

// Wrap the protobuf message as CloudEventData.
CloudEventData ceData = ProtoCloudEventData.wrap(myMessage);

// Build the CloudEvent
CloudEvent event = CloudEventBuilder.v1()
    .withId("hello")
    .withType("example.protodata")
    .withSource(URI.create("http://localhost"))
    .withData(ceData)
    .build();

Reading

If the ProtobufFormat is used to deserialize a CloudEvent that contains a protobuf message object as data you can use the ProtoCloudEventData to access it as an 'Any' directly.

// Deserialize the event.
CloudEvent myEvent = eventFormat.deserialize(raw);

// Get the Data
CloudEventData eventData = myEvent.getData();

if (ceData instanceOf ProtoCloudEventData) {

    // Obtain the protobuf 'any'
    Any anAny = ((ProtoCloudEventData) eventData).getAny();

    ...
}