cloudevents
/
sdk-java
mirror of https://github.com/cloudevents/sdk-java.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Examples readme (#298) 

* Added readme

Signed-off-by: Francesco Guardiani <francescoguard@gmail.com>

* Improved the quarkus example

Signed-off-by: Francesco Guardiani <francescoguard@gmail.com>

* 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 <francescoguard@gmail.com>
This commit is contained in:
Francesco Guardiani 2020-11-24 10:17:44 +01:00 committed by GitHub
parent de786322aa
commit d2a89a4e08
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 108 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
README.md
View File

@ -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) [![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) [![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. Look at https://cloudevents.github.io/sdk-java/ for more documentation.
## Status ## 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! Stay tuned!
Supported features of the specification: 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) | | | [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: | | CloudEvents Core | :heavy_check_mark: | :heavy_check_mark: |
| AMQP Protocol Binding | :x: | :x: | | AMQP Protocol Binding | :x: | :x: |
| AVRO Event Format | :x: | :x: | | - [Proton](amqp) | :heavy_check_mark: | :heavy_check_mark: |
| HTTP Protocol Binding | :heavy_check_mark: | :heavy_check_mark: | | AVRO Event Format | :x: | :x: |
| - [Vert.x](http/vertx) | :heavy_check_mark: | :heavy_check_mark: | | HTTP Protocol Binding | :heavy_check_mark: | :heavy_check_mark: |
| - [Jakarta Restful WS](http/restful-ws) | :heavy_check_mark: | :heavy_check_mark: | | - [Vert.x](http/vertx) | :heavy_check_mark: | :heavy_check_mark: |
| JSON Event Format | :heavy_check_mark: | :heavy_check_mark: | | - [Jakarta Restful WS](http/restful-ws) | :heavy_check_mark: | :heavy_check_mark: |
| - [Jackson](formats/json-jackson) | :heavy_check_mark: | :heavy_check_mark: | | - [Basic](http/basic) | :heavy_check_mark: | :heavy_check_mark: |
| [Kafka Protocol Binding](kafka) | :heavy_check_mark: | :heavy_check_mark: | | JSON Event Format | :heavy_check_mark: | :heavy_check_mark: |
| MQTT Protocol Binding | :x: | :x: | | - [Jackson](formats/json-jackson) | :heavy_check_mark: | :heavy_check_mark: |
| NATS Protocol Binding | :x: | :x: | | [Kafka Protocol Binding](kafka) | :heavy_check_mark: | :heavy_check_mark: |
| Web hook | :x: | :x: | | MQTT Protocol Binding | :x: | :x: |
| NATS Protocol Binding | :x: | :x: |
| Web hook | :x: | :x: |
## Motivation ## 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 [CloudEvents specification](https://github.com/cloudevents/spec) is a
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). 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 ## 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): Javadocs are available on [javadoc.io](https://www.javadoc.io):
* [cloudevents-api](https://www.javadoc.io/doc/io.cloudevents/cloudevents-api) - [cloudevents-api](https://www.javadoc.io/doc/io.cloudevents/cloudevents-api)
* [cloudevents-core](https://www.javadoc.io/doc/io.cloudevents/cloudevents-core) - [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-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-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-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-http-vertx](https://www.javadoc.io/doc/io.cloudevents/cloudevents-http-vertx)
* [cloudevents-kafka](https://www.javadoc.io/doc/io.cloudevents/cloudevents-kafka) - [cloudevents-kafka](https://www.javadoc.io/doc/io.cloudevents/cloudevents-kafka)
You can check out the examples in the [examples](examples) directory.
## Used By ## 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) |
|-------------|-------------| | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a href="https://occurrent.org"><img src="https://raw.githubusercontent.com/johanhaleby/occurrent/master/occurrent-logo-196x196.png" width="98" height="98" alt="Occurrent" title="Occurrent - Event Sourcing Utilities for the JVM"></img></a> | <a href="https://github.com/knative-sandbox/eventing-kafka-broker"><img src="https://cloudevents.io/img/logos/integrations/knative.png" height="98"></img></a> | | <a href="https://occurrent.org"><img src="https://raw.githubusercontent.com/johanhaleby/occurrent/master/occurrent-logo-196x196.png" width="98" height="98" alt="Occurrent" title="Occurrent - Event Sourcing Utilities for the JVM"></img></a> | <a href="https://github.com/knative-sandbox/eventing-kafka-broker"><img src="https://cloudevents.io/img/logos/integrations/knative.png" height="98"></img></a> |
## Community ## Community
- There are bi-weekly calls immediately following the [Serverless/CloudEvents - There are bi-weekly calls immediately following the
call](https://github.com/cloudevents/spec#meeting-time) at [Serverless/CloudEvents call](https://github.com/cloudevents/spec#meeting-time)
9am PT (US Pacific). Which means they will typically start at 10am PT, but at 9am PT (US Pacific). Which means they will typically start at 10am PT,
if the other call ends early then the SDK call will start early as well. 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#) See the
to determine which week will have the call. [CloudEvents meeting minutes](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#)
- Slack: #cloudeventssdk channel under to determine which week will have the call.
[CNCF's Slack workspace](https://slack.cncf.io/). - Slack: #cloudeventssdk channel under
- Email: https://lists.cncf.io/g/cncf-cloudevents-sdk [CNCF's Slack workspace](https://slack.cncf.io/).
- Contact for additional information: Francesco Guardiani (`@slinkydeveloper` on slack), Fabio José (`@fabiojose` on slack). - 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 Each SDK may have its own unique processes, tooling and guidelines, common
governance related material can be found in the governance related material can be found in the
[CloudEvents `community`](https://github.com/cloudevents/spec/tree/master/community) [CloudEvents `community`](https://github.com/cloudevents/spec/tree/master/community)
directory. In particular, in there you will find information concerning directory. In particular, in there you will find information concerning how SDK
how SDK projects are projects are
[managed](https://github.com/cloudevents/spec/blob/master/community/SDK-GOVERNANCE.md), [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) [guidelines](https://github.com/cloudevents/spec/blob/master/community/SDK-maintainer-guidelines.md)
for how PR reviews and approval, and our for how PR reviews and approval, and our

20
examples/README.md Normal file
View File

@ -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.

37
examples/restful-ws-quarkus/src/main/java/io/cloudevents/examples/quarkus/client/UserEventsGenerator.java
View File

@ -1,28 +1,33 @@
package io.cloudevents.examples.quarkus.client; package io.cloudevents.examples.quarkus.client;
import java.net.URI; import com.fasterxml.jackson.databind.ObjectMapper;
import java.time.Duration; import io.cloudevents.CloudEvent;
import java.util.UUID; 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.context.ApplicationScoped;
import javax.enterprise.event.Observes; import javax.enterprise.event.Observes;
import javax.inject.Inject; import javax.inject.Inject;
import javax.ws.rs.core.MediaType; import javax.ws.rs.core.MediaType;
import java.net.URI;
import io.cloudevents.CloudEvent; import java.time.Duration;
import io.cloudevents.core.builder.CloudEventBuilder; import java.util.UUID;
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;
@ApplicationScoped @ApplicationScoped
public class UserEventsGenerator { public class UserEventsGenerator {
private static final Logger LOGGER = LoggerFactory.getLogger(UserEventsGenerator.class); private static final Logger LOGGER = LoggerFactory.getLogger(UserEventsGenerator.class);
@Inject
ObjectMapper mapper;
@Inject @Inject
@RestClient @RestClient
UserClient userClient; UserClient userClient;
@ -44,16 +49,16 @@ public class UserEventsGenerator {
.withType("io.cloudevents.examples.quarkus.user") .withType("io.cloudevents.examples.quarkus.user")
.withId(UUID.randomUUID().toString()) .withId(UUID.randomUUID().toString())
.withDataContentType(MediaType.APPLICATION_JSON) .withDataContentType(MediaType.APPLICATION_JSON)
.withData(createUserAsByteArray(id)) .withData(createUser(id))
.build(); .build();
} }
private byte[] createUserAsByteArray(Long id) { private CloudEventData createUser(Long id) {
User user = new User() User user = new User()
.setAge(id.intValue()) .setAge(id.intValue())
.setUsername("user" + id) .setUsername("user" + id)
.setFirstName("firstName" + id) .setFirstName("firstName" + id)
.setLastName("lastName" + id); .setLastName("lastName" + id);
return Json.encode(user).getBytes(); return PojoCloudEventData.wrap(user, mapper::writeValueAsBytes);
} }
} }

13
examples/restful-ws-quarkus/src/main/java/io/cloudevents/examples/quarkus/resources/UserResource.java
View File

@ -1,12 +1,13 @@
package io.cloudevents.examples.quarkus.resources; package io.cloudevents.examples.quarkus.resources;
import com.fasterxml.jackson.databind.ObjectMapper;
import io.cloudevents.CloudEvent; import io.cloudevents.CloudEvent;
import io.cloudevents.examples.quarkus.model.User; import io.cloudevents.examples.quarkus.model.User;
import io.vertx.core.buffer.Buffer; import io.cloudevents.jackson.PojoCloudEventDataMapper;
import io.vertx.core.json.Json;
import org.slf4j.Logger; import org.slf4j.Logger;
import org.slf4j.LoggerFactory; import org.slf4j.LoggerFactory;
import javax.inject.Inject;
import javax.ws.rs.*; import javax.ws.rs.*;
import javax.ws.rs.core.Context; import javax.ws.rs.core.Context;
import javax.ws.rs.core.MediaType; import javax.ws.rs.core.MediaType;
@ -22,6 +23,9 @@ public class UserResource {
private static final Logger LOGGER = LoggerFactory.getLogger(UserResource.class); private static final Logger LOGGER = LoggerFactory.getLogger(UserResource.class);
@Inject
ObjectMapper mapper;
@Context @Context
UriInfo uriInfo; UriInfo uriInfo;
@ -46,7 +50,10 @@ public class UserResource {
if (event == null || event.getData() == null) { if (event == null || event.getData() == null) {
throw new BadRequestException("Invalid data received. Null or empty event"); 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())) { if (users.containsKey(user.getUsername())) {
throw new BadRequestException("Username already exists: " + user.getUsername()); throw new BadRequestException("Username already exists: " + user.getUsername());
} }