From 58a6426fe8dc9f319054592ccaa7e8b12763233c Mon Sep 17 00:00:00 2001 From: Francesco Guardiani Date: Wed, 8 Jul 2020 11:12:26 +0200 Subject: [PATCH] Reorganized some readmes/docs (#193) * Added javadocs links both to READMEs and docs Signed-off-by: Francesco Guardiani * Removed old docs of v1 of the sdk Signed-off-by: Francesco Guardiani --- CHANGELOG.md | 100 -------------------------- README.md | 21 +++--- README_v1.md | 126 --------------------------------- api/README.md | 2 + core/README.md | 2 + formats/json-jackson/README.md | 2 + http/restful-ws/README.md | 2 + http/vertx/README.md | 2 + kafka/README.md | 2 + 9 files changed, 23 insertions(+), 236 deletions(-) delete mode 100644 CHANGELOG.md delete mode 100644 README_v1.md diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 96d2dbf1..00000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,100 +0,0 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) - -## [Unreleased] - -## [1.3.0] - -### Added - -- [Editor configuration file](./.editorconfig) - [check it out!](https://editorconfig.org/) - -### Fixed - -- [Map extensions with prefix for Kafka CloudEvent header](https://github.com/cloudevents/sdk-java/pull/98) -- [Add new CloudEventsKafkaHeaders class for kafka API](https://github.com/cloudevents/sdk-java/pull/90) -- [Fix Kafka Transport references](https://github.com/cloudevents/sdk-java/pull/78) - -## [1.2.0] - -### Added - -- Improved base64 marshalling: PR [#79](https://github.com/cloudevents/sdk-java/pull/79) - -## [1.1.0] - -### Added - -- Support for custom validator: PR [#73](https://github.com/cloudevents/sdk-java/pull/73) - -### Fixed - -- Fix for the issue [#74](https://github.com/cloudevents/sdk-java/issues/74) -- Fix for the issue [#67](https://github.com/cloudevents/sdk-java/issues/67) - -## [1.0.0] - -### Added - -- Support for [Spec v1.0](https://github.com/cloudevents/spec/tree/v1.0) -- Improved readme to end request for vertx sample [PR 62](https://github.com/cloudevents/sdk-java/pull/62) -- Allow providing an external validator [PR 65](https://github.com/cloudevents/sdk-java/pull/65) - -## [0.3.1] - -### Fixed - -- Vulnerable dependency `com.fasterxml.jackson.core:jackson-databind` - -## [0.3.0] - -### Added -- [Attributes](./api/src/main/java/io/cloudevents/Attributes.java) marker -interface for context attributes -- Support for [Spec v0.3](https://github.com/cloudevents/spec/tree/v0.3) -- [ExtensionFormat](./api/src/main/java/io/cloudevents/ExtensionFormat.java) -interface for extensions -- [HTTP Marshallers](./api/src/main/java/io/cloudevents/v02/http/Marshallers.java) with bare minium marshallers for HTTP Transport Binding -- [HTTP Unmarshallers](./api/src/main/java/io/cloudevents/v02/http/Unmarshallers.java) with bare minium unmarshallers for HTTP Transport Binding -- [Kafka Marshallers](./kafka/src/main/java/io/cloudevents/v02/kafka/Marshallers.java) with bare minimum marshallers for Kafka Transport Binding -- [CloudEventsKafkaProducer](./kafka/src/main/java//io/cloudevents/kafka/CloudEventsKafkaProducer.java) The CloudEvents producer that uses Kafka Clients API -- [Kafka Unmarshallers](./kafka/src/main/java/io/cloudevents/v02/kafka/Unmarshallers.java) with bare minium unmarshallers for Kafka Transport Binding -- [CloudEventsKafkaConsumer](./kafka/src/main/java//io/cloudevents/kafka/CloudEventsKafkaConsumer.java) The CloudEvents consumer that uses Kafka Clients API -- [BinaryMarshaller](./api/src/main/java/io/cloudevents/format/BinaryMarshaller.java) To help in the case of you need to create your own marshallers for binary content mode -- [BinaryUnmarshaller](./api/src/main/java/io/cloudevents/format/BinaryUnmarshaller.java) To help in the case of you need to create your own unmarshallers for binary content mode -- [StructuredMarshaller](./api/src/main/java/io/cloudevents/format/StructuredMarshaller.java) To help in the case of you need to create your own marshallers for structured content mode -- [StructuredUnmarshaller](./api/src/main/java/io/cloudevents/format/StructuredUnmarshaller.java) To help in the case of you need to create your own unmarshallers for structured content mode - - -### Changed -- CloudEvent interface signature, breaking the backward compatibility -- Class: `io.cloudevents.v02.CloudEvent` moved to `io.cloudevents.v02.CloudEventImpl` -- Class: `io.cloudevents.v02.CloudEventImpl` had changed its signature, breaking the -backward compatibility -- Method: `io.cloudevents.json.Json.fromInputStream` had moved to Generics signature -- Class: `io.cloudevents.http.V02HttpTransportMappers` moved to -`io.cloudevents.v02.http.BinaryAttributeMapperImpl` and had changed is signature breaking the backward compatibility - -### Removed -- Support for Spec v0.1 -- Class: `io.cloudevents.impl.DefaultCloudEventImpl`, in favor of a impl for each -version -- Class: `io.cloudevents.CloudEventBuilder`, in favor of a builder for each version -- Enum: `io.cloudevents.SpecVersion`, in favor of specialization of specs -- Method: `io.cloudevents.json.Json.decodeCloudEvent` -- Class: `io.cloudevents.http.V01HttpTransportMappers` due the unsupported v0.1 -- interface: `io.cloudevents.http.HttpTransportAttributes`, in favor of the new -abstract envelope signature -- interface: `io.cloudevents.Extension` in favor of -`io.cloudevents.extensions.ExtensionFormat` - -[Unreleased]: https://github.com/cloudevents/sdk-java/compare/v1.3.0...HEAD -[1.3.0]: https://github.com/cloudevents/sdk-java/compare/v1.2.0...v1.3.0 -[1.2.0]: https://github.com/cloudevents/sdk-java/compare/v1.1.0...v1.2.0 -[1.1.0]: https://github.com/cloudevents/sdk-java/compare/v1.0.0...v1.1.0 -[1.0.0]: https://github.com/cloudevents/sdk-java/compare/v0.3.1...v1.0.0 -[0.3.1]: https://github.com/cloudevents/sdk-java/compare/v0.3.0...v0.3.1 -[0.3.0]: https://github.com/cloudevents/sdk-java/compare/v0.2.1...v0.3.0 diff --git a/README.md b/README.md index 1e32df92..88729700 100644 --- a/README.md +++ b/README.md @@ -40,17 +40,18 @@ Supported features of the specification: 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 `0.3` 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). -## Java API +## Documentation -For Maven based projects, use the following to configure the CloudEvents Java SDK: +Documentation is available at https://cloudevents.github.io/sdk-java/ -```xml - - io.cloudevents - cloudevents-core - 2.0.0-milestone1 - -``` +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-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) ## Community @@ -63,4 +64,4 @@ For Maven based projects, use the following to configure the CloudEvents Java SD - 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: Fabio José (`@fabiojose` on slack). +- Contact for additional information: Francesco Guardiani (`@slinkydeveloper` on slack), Fabio José (`@fabiojose` on slack). diff --git a/README_v1.md b/README_v1.md deleted file mode 100644 index 0a3af882..00000000 --- a/README_v1.md +++ /dev/null @@ -1,126 +0,0 @@ -# Java SDK for CloudEvents API - -[![Build Status](https://travis-ci.org/cloudevents/sdk-java.png)](https://travis-ci.org/cloudevents/sdk-java) -[![License](https://img.shields.io/:license-Apache2-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0) -[![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) - -__Checkout the [changelog](./CHANGELOG.md)__ - -## Status - -This SDK current supports the following versions of CloudEvents: - -- 0.2 -- 0.3 -- 1.0 - -## 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 `0.3` 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). - -## Java API - -For Maven based projects, use the following to configure the CloudEvents Java SDK: - -```xml - - io.cloudevents - cloudevents-core - 1.3.0 - -``` - -Application developers can now create strongly-typed CloudEvents, such as: - -```java -import io.cloudevents.v1.CloudEventBuilder; -import io.cloudevents.v1.CloudEventImpl; -import io.cloudevents.extensions.ExtensionFormat; -import io.cloudevents.json.Json; -import io.cloudevents.extensions.DistributedTracingExtension; - -// given -final String eventId = UUID.randomUUID().toString(); -final URI src = URI.create("/trigger"); -final String eventType = "My.Cloud.Event.Type"; -final MyCustomEvent payload = ... - -// add trace extension usin the in-memory format -final DistributedTracingExtension dt = new DistributedTracingExtension(); -dt.setTraceparent("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"); -dt.setTracestate("rojo=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"); - -final ExtensionFormat tracing = new DistributedTracingExtension.Format(dt); - -// passing in the given attributes -final CloudEventImpl cloudEvent = - CloudEventBuilder.builder() - .withType(eventType) - .withId(eventId) - .withSource(src) - .withData(payload) - .withExtension(tracing) - .build(); - -// marshalling as json -final String json = Json.encode(cloudEvent); -``` - -Or, an event with binary event data: - -```java -import io.cloudevents.v1.CloudEventBuilder; -import io.cloudevents.v1.CloudEventImpl; -import io.cloudevents.extensions.ExtensionFormat; -import io.cloudevents.json.Json; -import io.cloudevents.extensions.DistributedTracingExtension; - -// given -final String eventId = UUID.randomUUID().toString(); -final URI src = URI.create("/trigger"); -final String eventType = "My.Cloud.Event.Type"; -final byte[] payload = "a-binary-event-data".getBytes(); - -// passing in the given attributes -final CloudEventImpl cloudEvent = - CloudEventBuilder.builder() - .withType(eventType) - .withId(eventId) - .withSource(src) - .withDataBase64(payload) - .build(); - -// marshalling as json that will have the data_base64 -final String json = Json.encode(cloudEvent); -``` - -There are [other detailed ways](./api/README.md) of how to use the marshallers -and unmarshallers with HTTP transport binding. - -## Kafka - -The support for kafka protocol binding is available. Read the -[documentation and examples](./kafka/README.md) of use. - -## Possible Integrations - -The API is kept simple, for allowing a wide range of possible integrations: - -* [CDI](cdi/) -* [Eclipse Vert.x](http/vertx/) - -## 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: Fabio José (`@fabiojose` on slack). diff --git a/api/README.md b/api/README.md index ca3a9760..a6ff8a3d 100644 --- a/api/README.md +++ b/api/README.md @@ -1,5 +1,7 @@ # CloudEvents API +[![Javadocs](http://www.javadoc.io/badge/io.cloudevents/cloudevents-api.svg?color=green)](http://www.javadoc.io/doc/io.cloudevents/cloudevents-api) + For Maven based projects, use the following dependency: ```xml diff --git a/core/README.md b/core/README.md index 53aee465..5b21e9a8 100644 --- a/core/README.md +++ b/core/README.md @@ -1,5 +1,7 @@ # CloudEvents Core +[![Javadocs](http://www.javadoc.io/badge/io.cloudevents/cloudevents-core.svg?color=green)](http://www.javadoc.io/doc/io.cloudevents/cloudevents-core) + The base classes, interfaces and low-level APIs to use CloudEvents. ## How to Use diff --git a/formats/json-jackson/README.md b/formats/json-jackson/README.md index 1bc4465b..5b49d649 100644 --- a/formats/json-jackson/README.md +++ b/formats/json-jackson/README.md @@ -1,5 +1,7 @@ # Json EventFormat implementation with Jackson +[![Javadocs](http://www.javadoc.io/badge/io.cloudevents/cloudevents-json-jackson.svg?color=green)](http://www.javadoc.io/doc/io.cloudevents/cloudevents-json-jackson) + Implementation of [`EventFormat`](../../api/src/main/java/io/cloudevents/format/EventFormat.java) using Jackson. For Maven: diff --git a/http/restful-ws/README.md b/http/restful-ws/README.md index 2e18b2cf..9c1dc0bb 100644 --- a/http/restful-ws/README.md +++ b/http/restful-ws/README.md @@ -1,5 +1,7 @@ # HTTP Protocol Binding for Jakarta RESTful Web Services +[![Javadocs](http://www.javadoc.io/badge/io.cloudevents/cloudevents-http-restful-ws.svg?color=green)](http://www.javadoc.io/doc/io.cloudevents/cloudevents-http-restful-ws) + For Maven based projects, use the following to configure the CloudEvents Jakarta RESTful Web Services Binding: ```xml diff --git a/http/vertx/README.md b/http/vertx/README.md index 463e37c0..f51acfa0 100644 --- a/http/vertx/README.md +++ b/http/vertx/README.md @@ -1,5 +1,7 @@ # HTTP Protocol Binding for Eclipse Vert.x +[![Javadocs](http://www.javadoc.io/badge/io.cloudevents/cloudevents-http-vertx.svg?color=green)](http://www.javadoc.io/doc/io.cloudevents/cloudevents-http-vertx) + For Maven based projects, use the following to configure the CloudEvents Vertx HTTP Transport: ```xml diff --git a/kafka/README.md b/kafka/README.md index 1f595558..8ef8ab1e 100644 --- a/kafka/README.md +++ b/kafka/README.md @@ -1,5 +1,7 @@ # Kafka Protocol Binding +[![Javadocs](http://www.javadoc.io/badge/io.cloudevents/cloudevents-kafka.svg?color=green)](http://www.javadoc.io/doc/io.cloudevents/cloudevents-kafka) + For Maven based projects, use the following to configure the [Kafka Protocol Binding](https://github.com/cloudevents/spec/blob/master/kafka-protocol-binding.md): ```xml