Azure Cloud Native Cloud Event client library for Java - version 1.0.0-beta.1

This library can be used to enable publishing the Cloud Native Computing Foundation(CNCF) CloudEvents using the Azure Event Grid library.

Getting started

Prerequisites

You should have an EventGrid client before using this bridge library. Follow Azure EventGrid steps to create an EventGrid client.

Include the package

Include direct dependency

If you want to take dependency on a particular version of the library, add the direct dependency to your project as follows.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-eventgrid-cloudnative-cloudevents</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>

Key concepts

For information about general Event Grid concepts: Concepts in Azure Event Grid.

For detailed information about the Event Grid client library concepts: Event Grid Client Library.

Examples

Sending CNCF CloudEvents To Event Grid Topics

// Prepare Event Grid client
EventGridPublisherClient<com.azure.core.models.CloudEvent> egClient =
    new EventGridPublisherClientBuilder()
        .endpoint(System.getenv("AZURE_EVENTGRID_CLOUDEVENT_ENDPOINT"))
        .credential(new AzureKeyCredential(System.getenv("AZURE_EVENTGRID_CLOUDEVENT_KEY")))
        .buildCloudEventPublisherClient();

// Prepare a native cloud event input, the cloud event input should be replace with your own.
CloudEvent cloudEvent =
    CloudEventBuilder.v1()
        .withData("{\"name\": \"joe\"}".getBytes(StandardCharsets.UTF_8)) // Replace it
        .withId(UUID.randomUUID().toString()) // Replace it
        .withType("User.Created.Text") // Replace it
        .withSource(URI.create("http://localHost")) // Replace it
        .withDataContentType("application/json") // Replace it
        .build();

// Publishing a single event
EventGridCloudNativeEventPublisher.sendEvent(egClient, cloudEvent);

Sending CNCF CloudEvents To Event Grid Domain

When publishing to an Event Grid domain with cloud events, the cloud event source is used as the domain topic. The Event Grid service doesn't support using an absolute URI for a domain topic, so you would need to do something like the following to integrate with the cloud native cloud events:

// Prepare Event Grid client
EventGridPublisherClient<com.azure.core.models.CloudEvent> egClient =
    new EventGridPublisherClientBuilder()
        .endpoint(System.getenv("AZURE_EVENTGRID_CLOUDEVENT_ENDPOINT"))
        .credential(new AzureKeyCredential(System.getenv("AZURE_EVENTGRID_CLOUDEVENT_KEY")))
        .buildCloudEventPublisherClient();

// Prepare a native cloud event input, the cloud event input should be replace with your own.
CloudEvent cloudEvent =
    CloudEventBuilder.v1()
        .withData("{\"name\": \"joe\"}".getBytes(StandardCharsets.UTF_8)) // Replace it
        .withId(UUID.randomUUID().toString()) // Replace it
        .withType("User.Created.Text") // Replace it
        // Replace it. Event Grid does not allow absolute URIs as the domain topic.
        // For example, use the Event Grid Domain resource name as the relative path.
        .withSource(URI.create("/relative/path"))
        .withDataContentType("application/json") // Replace it
        .build();

// Publishing a single event
EventGridCloudNativeEventPublisher.sendEvent(egClient, cloudEvent);

Troubleshooting

Responses and error codes

Service responses are returned in the form of Http status codes, including a number of error codes. These codes can optionally be returned by the PublisherClient. Unexpected status codes are thrown as HttpResponseException which wraps the error code.

Reference documentation for the event grid service can be found [here][service_docs]. This is a good place to start for problems involving configuration of topics/endpoints, as well as for problems involving error codes from the service.

Help and Issues

Reference documentation for the SDK can be found here. This is a good first step to understanding the purpose of each method called, as well as possible reasons for errors or unexpected behavior.

If you encounter any bugs with these SDKs, please file issues via Issues or checkout StackOverflow for Azure Java SDK.

Next steps

  • Azure Java SDKs
  • If you don't have a Microsoft Azure subscription you can get a FREE trial account here

Contributing

If you would like to become an active contributor to this project please refer to our Contribution Guidelines for more information.

Impressions