From d2a89a4e08a3c32f6edbdab5f80d26fb44ffe0cb Mon Sep 17 00:00:00 2001 From: Francesco Guardiani Date: Tue, 24 Nov 2020 10:17:44 +0100 Subject: [PATCH] Examples readme (#298) * Added readme Signed-off-by: Francesco Guardiani * Improved the quarkus example Signed-off-by: Francesco Guardiani * Added amqp proton Fixed and added stuff to the root readme Added link to examples readme to the main readme Signed-off-by: Francesco Guardiani --- README.md | 97 +++++++++++-------- examples/README.md | 20 ++++ .../quarkus/client/UserEventsGenerator.java | 37 ++++--- .../quarkus/resources/UserResource.java | 13 ++- 4 files changed, 108 insertions(+), 59 deletions(-) create mode 100644 examples/README.md diff --git a/README.md b/README.md index 7cb55e95..8ff33f3a 100644 --- a/README.md +++ b/README.md @@ -4,39 +4,52 @@ [![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.cloudevents/cloudevents-parent/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.cloudevents/cloudevents-parent) [![Javadocs](http://www.javadoc.io/badge/io.cloudevents/cloudevents-core.svg?color=green)](http://www.javadoc.io/doc/io.cloudevents/cloudevents-core) -A Java API for the [CloudEvents specification](https://github.com/cloudevents/spec) +A Java API for the +[CloudEvents specification](https://github.com/cloudevents/spec) Look at https://cloudevents.github.io/sdk-java/ for more documentation. ## Status -This SDK is considered **work in progress**. The community is working hard to bring you a new major version of the SDK with major enhancements both to APIs and to implementation. +This SDK is considered **work in progress**. The community is working hard to +bring you a new major version of the SDK with major enhancements both to APIs +and to implementation. -If you want to know more about v1 of this SDK, check out the [v1 readme](https://github.com/cloudevents/sdk-java/tree/1.x) +If you want to know more about v1 of this SDK, check out the +[v1 readme](https://github.com/cloudevents/sdk-java/tree/1.x) Stay tuned! Supported features of the specification: -| | [v0.3](https://github.com/cloudevents/spec/tree/v0.3) | [v1.0](https://github.com/cloudevents/spec/tree/v1.0) | -| :---------------------------: | :----------------------------------------------------------------------------: | :---------------------------------------------------------------------------------: | -| CloudEvents Core | :heavy_check_mark: | :heavy_check_mark: | -| AMQP Protocol Binding | :x: | :x: | -| AVRO Event Format | :x: | :x: | -| HTTP Protocol Binding | :heavy_check_mark: | :heavy_check_mark: | -| - [Vert.x](http/vertx) | :heavy_check_mark: | :heavy_check_mark: | -| - [Jakarta Restful WS](http/restful-ws) | :heavy_check_mark: | :heavy_check_mark: | -| JSON Event Format | :heavy_check_mark: | :heavy_check_mark: | -| - [Jackson](formats/json-jackson) | :heavy_check_mark: | :heavy_check_mark: | -| [Kafka Protocol Binding](kafka) | :heavy_check_mark: | :heavy_check_mark: | -| MQTT Protocol Binding | :x: | :x: | -| NATS Protocol Binding | :x: | :x: | -| Web hook | :x: | :x: | +| | [v0.3](https://github.com/cloudevents/spec/tree/v0.3) | [v1.0](https://github.com/cloudevents/spec/tree/v1.0) | +| :-------------------------------------: | :---------------------------------------------------: | :---------------------------------------------------: | +| CloudEvents Core | :heavy_check_mark: | :heavy_check_mark: | +| AMQP Protocol Binding | :x: | :x: | +| - [Proton](amqp) | :heavy_check_mark: | :heavy_check_mark: | +| AVRO Event Format | :x: | :x: | +| HTTP Protocol Binding | :heavy_check_mark: | :heavy_check_mark: | +| - [Vert.x](http/vertx) | :heavy_check_mark: | :heavy_check_mark: | +| - [Jakarta Restful WS](http/restful-ws) | :heavy_check_mark: | :heavy_check_mark: | +| - [Basic](http/basic) | :heavy_check_mark: | :heavy_check_mark: | +| JSON Event Format | :heavy_check_mark: | :heavy_check_mark: | +| - [Jackson](formats/json-jackson) | :heavy_check_mark: | :heavy_check_mark: | +| [Kafka Protocol Binding](kafka) | :heavy_check_mark: | :heavy_check_mark: | +| MQTT Protocol Binding | :x: | :x: | +| NATS Protocol Binding | :x: | :x: | +| Web hook | :x: | :x: | ## Motivation -The [CloudEvents specification](https://github.com/cloudevents/spec) is a vendor-neutral specification for defining the format of event data that is being exchanged between different cloud systems. The specification basically defines an abstract envelope for any event data payload, without knowing specific implementation details of the actual underlying event. -The current version of the spec is at `1.0` and it describes a simple event format, which was demonstrated at [KubeCon 2018](https://youtu.be/TZPPjAv12KU) using different _Serverless platforms_, such as [Apache Openwhisk](https://github.com/apache/incubator-openwhisk). +The [CloudEvents specification](https://github.com/cloudevents/spec) is a +vendor-neutral specification for defining the format of event data that is being +exchanged between different cloud systems. The specification basically defines +an abstract envelope for any event data payload, without knowing specific +implementation details of the actual underlying event. The current version of +the spec is at `1.0` and it describes a simple event format, which was +demonstrated at [KubeCon 2018](https://youtu.be/TZPPjAv12KU) using different +_Serverless platforms_, such as +[Apache Openwhisk](https://github.com/apache/incubator-openwhisk). ## Documentation @@ -44,38 +57,42 @@ Documentation is available at https://cloudevents.github.io/sdk-java/ Javadocs are available on [javadoc.io](https://www.javadoc.io): -* [cloudevents-api](https://www.javadoc.io/doc/io.cloudevents/cloudevents-api) -* [cloudevents-core](https://www.javadoc.io/doc/io.cloudevents/cloudevents-core) -* [cloudevents-json-jackson](https://www.javadoc.io/doc/io.cloudevents/cloudevents-json-jackson) -* [cloudevents-http-basic](https://www.javadoc.io/doc/io.cloudevents/cloudevents-http-basic) -* [cloudevents-http-restful-ws](https://www.javadoc.io/doc/io.cloudevents/cloudevents-http-restful-ws) -* [cloudevents-http-vertx](https://www.javadoc.io/doc/io.cloudevents/cloudevents-http-vertx) -* [cloudevents-kafka](https://www.javadoc.io/doc/io.cloudevents/cloudevents-kafka) +- [cloudevents-api](https://www.javadoc.io/doc/io.cloudevents/cloudevents-api) +- [cloudevents-core](https://www.javadoc.io/doc/io.cloudevents/cloudevents-core) +- [cloudevents-json-jackson](https://www.javadoc.io/doc/io.cloudevents/cloudevents-json-jackson) +- [cloudevents-http-basic](https://www.javadoc.io/doc/io.cloudevents/cloudevents-http-basic) +- [cloudevents-http-restful-ws](https://www.javadoc.io/doc/io.cloudevents/cloudevents-http-restful-ws) +- [cloudevents-http-vertx](https://www.javadoc.io/doc/io.cloudevents/cloudevents-http-vertx) +- [cloudevents-kafka](https://www.javadoc.io/doc/io.cloudevents/cloudevents-kafka) + +You can check out the examples in the [examples](examples) directory. ## Used By -| [Occurrent](https://occurrent.org) | [Knative Eventing](https://github.com/knative-sandbox/eventing-kafka-broker) | -|-------------|-------------| +| [Occurrent](https://occurrent.org) | [Knative Eventing](https://github.com/knative-sandbox/eventing-kafka-broker) | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Occurrent | | ## Community -- There are bi-weekly calls immediately following the [Serverless/CloudEvents - call](https://github.com/cloudevents/spec#meeting-time) at - 9am PT (US Pacific). Which means they will typically start at 10am PT, but - if the other call ends early then the SDK call will start early as well. - See the [CloudEvents meeting minutes](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) - to determine which week will have the call. -- Slack: #cloudeventssdk channel under - [CNCF's Slack workspace](https://slack.cncf.io/). -- Email: https://lists.cncf.io/g/cncf-cloudevents-sdk -- Contact for additional information: Francesco Guardiani (`@slinkydeveloper` on slack), Fabio José (`@fabiojose` on slack). +- There are bi-weekly calls immediately following the + [Serverless/CloudEvents call](https://github.com/cloudevents/spec#meeting-time) + at 9am PT (US Pacific). Which means they will typically start at 10am PT, + but if the other call ends early then the SDK call will start early as well. + See the + [CloudEvents meeting minutes](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) + to determine which week will have the call. +- Slack: #cloudeventssdk channel under + [CNCF's Slack workspace](https://slack.cncf.io/). +- Email: https://lists.cncf.io/g/cncf-cloudevents-sdk +- Contact for additional information: Francesco Guardiani (`@slinkydeveloper` + on slack), Fabio José (`@fabiojose` on slack). Each SDK may have its own unique processes, tooling and guidelines, common governance related material can be found in the [CloudEvents `community`](https://github.com/cloudevents/spec/tree/master/community) -directory. In particular, in there you will find information concerning -how SDK projects are +directory. In particular, in there you will find information concerning how SDK +projects are [managed](https://github.com/cloudevents/spec/blob/master/community/SDK-GOVERNANCE.md), [guidelines](https://github.com/cloudevents/spec/blob/master/community/SDK-maintainer-guidelines.md) for how PR reviews and approval, and our diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 00000000..a117e85c --- /dev/null +++ b/examples/README.md @@ -0,0 +1,20 @@ +# CloudEvents sdk-java examples + +This directory includes some examples on how to use CloudEvents sdk-java: + +- [amqp-proton](amqp-proton) shows how to use the module + `cloudevents-amqp-proton` to send and receive CloudEvents using AMQP 1.0. +- [kafka](kafka) shows how to use the module `cloudevents-kafka` to produce + and consume CloudEvents on Kafka topics. +- [restful-ws-quarkus](restful-ws-quarkus) shows how to use the module + `cloudevents-http-restful-ws` with Quarkus to receive and send CloudEvents + through HTTP. +- [restful-ws-spring-boot](restful-ws-spring-boot) shows how to use the module + `cloudevents-http-restful-ws` with Spring Boot and Jersey to receive and + send CloudEvents through HTTP. +- [vertx](vertx) shows how to use the module `cloudevents-http-vertx` to + receive and send CloudEvents through HTTP using `vertx-web-client` and + `vertx-core`. +- [basic-http](basic-http) shows how to use the module + `cloudevents-http-basic` to send and receive CloudEvents using `JDK`'s + `HttpServer`, `HttpURLConnection` and Jetty. diff --git a/examples/restful-ws-quarkus/src/main/java/io/cloudevents/examples/quarkus/client/UserEventsGenerator.java b/examples/restful-ws-quarkus/src/main/java/io/cloudevents/examples/quarkus/client/UserEventsGenerator.java index eb249297..61a49786 100644 --- a/examples/restful-ws-quarkus/src/main/java/io/cloudevents/examples/quarkus/client/UserEventsGenerator.java +++ b/examples/restful-ws-quarkus/src/main/java/io/cloudevents/examples/quarkus/client/UserEventsGenerator.java @@ -1,28 +1,33 @@ package io.cloudevents.examples.quarkus.client; -import java.net.URI; -import java.time.Duration; -import java.util.UUID; +import com.fasterxml.jackson.databind.ObjectMapper; +import io.cloudevents.CloudEvent; +import io.cloudevents.CloudEventData; +import io.cloudevents.core.builder.CloudEventBuilder; +import io.cloudevents.core.data.PojoCloudEventData; +import io.cloudevents.examples.quarkus.model.User; +import io.quarkus.runtime.StartupEvent; +import io.smallrye.mutiny.Multi; +import org.eclipse.microprofile.rest.client.inject.RestClient; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + import javax.enterprise.context.ApplicationScoped; import javax.enterprise.event.Observes; import javax.inject.Inject; import javax.ws.rs.core.MediaType; - -import io.cloudevents.CloudEvent; -import io.cloudevents.core.builder.CloudEventBuilder; -import io.cloudevents.examples.quarkus.model.User; -import io.quarkus.runtime.StartupEvent; -import io.smallrye.mutiny.Multi; -import io.vertx.core.json.Json; -import org.eclipse.microprofile.rest.client.inject.RestClient; -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; +import java.net.URI; +import java.time.Duration; +import java.util.UUID; @ApplicationScoped public class UserEventsGenerator { private static final Logger LOGGER = LoggerFactory.getLogger(UserEventsGenerator.class); + @Inject + ObjectMapper mapper; + @Inject @RestClient UserClient userClient; @@ -44,16 +49,16 @@ public class UserEventsGenerator { .withType("io.cloudevents.examples.quarkus.user") .withId(UUID.randomUUID().toString()) .withDataContentType(MediaType.APPLICATION_JSON) - .withData(createUserAsByteArray(id)) + .withData(createUser(id)) .build(); } - private byte[] createUserAsByteArray(Long id) { + private CloudEventData createUser(Long id) { User user = new User() .setAge(id.intValue()) .setUsername("user" + id) .setFirstName("firstName" + id) .setLastName("lastName" + id); - return Json.encode(user).getBytes(); + return PojoCloudEventData.wrap(user, mapper::writeValueAsBytes); } } diff --git a/examples/restful-ws-quarkus/src/main/java/io/cloudevents/examples/quarkus/resources/UserResource.java b/examples/restful-ws-quarkus/src/main/java/io/cloudevents/examples/quarkus/resources/UserResource.java index 6f9e94fe..788e2234 100644 --- a/examples/restful-ws-quarkus/src/main/java/io/cloudevents/examples/quarkus/resources/UserResource.java +++ b/examples/restful-ws-quarkus/src/main/java/io/cloudevents/examples/quarkus/resources/UserResource.java @@ -1,12 +1,13 @@ package io.cloudevents.examples.quarkus.resources; +import com.fasterxml.jackson.databind.ObjectMapper; import io.cloudevents.CloudEvent; import io.cloudevents.examples.quarkus.model.User; -import io.vertx.core.buffer.Buffer; -import io.vertx.core.json.Json; +import io.cloudevents.jackson.PojoCloudEventDataMapper; import org.slf4j.Logger; import org.slf4j.LoggerFactory; +import javax.inject.Inject; import javax.ws.rs.*; import javax.ws.rs.core.Context; import javax.ws.rs.core.MediaType; @@ -22,6 +23,9 @@ public class UserResource { private static final Logger LOGGER = LoggerFactory.getLogger(UserResource.class); + @Inject + ObjectMapper mapper; + @Context UriInfo uriInfo; @@ -46,7 +50,10 @@ public class UserResource { if (event == null || event.getData() == null) { throw new BadRequestException("Invalid data received. Null or empty event"); } - User user = Json.decodeValue(Buffer.buffer(event.getData().toBytes()), User.class); + User user = PojoCloudEventDataMapper + .from(mapper, User.class) + .map(event.getData()) + .getValue(); if (users.containsKey(user.getUsername())) { throw new BadRequestException("Username already exists: " + user.getUsername()); }