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

Reorganized some readmes/docs (#193) 

* Added javadocs links both to READMEs and docs

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

* Removed old docs of v1 of the sdk

Signed-off-by: Francesco Guardiani <francescoguard@gmail.com>
This commit is contained in:
Francesco Guardiani 2020-07-08 11:12:26 +02:00 committed by GitHub
parent d4ee5a6930
commit 58a6426fe8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 23 additions and 236 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
CHANGELOG.md
View File

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

21
README.md
View File

@ -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
<dependency>
<groupId>io.cloudevents</groupId>
<artifactId>cloudevents-core</artifactId>
<version>2.0.0-milestone1</version>
</dependency>
```
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).

126
README_v1.md
View File

@ -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
<dependency>
<groupId>io.cloudevents</groupId>
<artifactId>cloudevents-core</artifactId>
<version>1.3.0</version>
</dependency>
```
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<MyCustomEvent> cloudEvent =
CloudEventBuilder.<MyCustomEvent>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<String> cloudEvent =
CloudEventBuilder.<String>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).

2
api/README.md
View File

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

2
core/README.md
View File

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

2
formats/json-jackson/README.md
View File

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

2
http/restful-ws/README.md
View File

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

2
http/vertx/README.md
View File

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

2
kafka/README.md
View File

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