Skip to content

Commit 3a22557

Browse files
slinkydeveloperslinkydeveloper
authored
Website docs (cloudevents#324)
* Halfway through it Signed-off-by: Francesco Guardiani <[email protected]> * That should be it Signed-off-by: Francesco Guardiani <[email protected]> * Prettier run Signed-off-by: Francesco Guardiani <[email protected]> * Removed code sample Signed-off-by: Francesco Guardiani <[email protected]> * Suggestions + fixed up the mess made by prettier Signed-off-by: Francesco Guardiani <[email protected]> * Suggestion Signed-off-by: Francesco Guardiani <[email protected]>
1 parent 87c6915 commit 3a22557

23 files changed

+883
-602
lines changed

‎README.md

+17-16
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,20 @@
44
[![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)
55
[![Javadocs](http://www.javadoc.io/badge/io.cloudevents/cloudevents-core.svg?color=green)](http://www.javadoc.io/doc/io.cloudevents/cloudevents-core)
66

7-
A Java API for the
8-
[CloudEvents specification](https://github.com/cloudevents/spec)
7+
The Java SDK for CloudEvents is a collection of Java packages to adopt
8+
[CloudEvents](https://github.com/cloudevents/spec) in your Java application.
99

10-
Look at https://cloudevents.github.io/sdk-java/ for more documentation.
10+
Using the Java SDK you can:
11+
12+
- Access, create and manipulate `CloudEvent` inside your application.
13+
- Serialize and deserialize `CloudEvent` back and forth using the _CloudEvents
14+
Event Format_, like Json.
15+
- Read and write `CloudEvent` back and forth to HTTP, Kafka, AMQP using the
16+
_CloudEvents Protocol Binding_ implementations we provide for a wide range
17+
of well known Java frameworks/libraries.
18+
19+
To check out the complete documentation and how to get started, look at the dedicated website
20+
https://cloudevents.github.io/sdk-java/.
1121

1222
## Status
1323

@@ -32,28 +42,17 @@ Supported features of the specification:
3242
| - [Vert.x](http/vertx) | :heavy_check_mark: | :heavy_check_mark: |
3343
| - [Jakarta Restful WS](http/restful-ws) | :heavy_check_mark: | :heavy_check_mark: |
3444
| - [Basic](http/basic) | :heavy_check_mark: | :heavy_check_mark: |
45+
| - [Spring](spring) | :heavy_check_mark: | :heavy_check_mark: |
3546
| JSON Event Format | :heavy_check_mark: | :heavy_check_mark: |
3647
| - [Jackson](formats/json-jackson) | :heavy_check_mark: | :heavy_check_mark: |
3748
| [Kafka Protocol Binding](kafka) | :heavy_check_mark: | :heavy_check_mark: |
3849
| MQTT Protocol Binding | :x: | :x: |
3950
| NATS Protocol Binding | :x: | :x: |
4051
| Web hook | :x: | :x: |
4152

42-
## Motivation
43-
44-
The [CloudEvents specification](https://github.com/cloudevents/spec) is a
45-
vendor-neutral specification for defining the format of event data that is being
46-
exchanged between different cloud systems. The specification basically defines
47-
an abstract envelope for any event data payload, without knowing specific
48-
implementation details of the actual underlying event. The current version of
49-
the spec is at `1.0` and it describes a simple event format, which was
50-
demonstrated at [KubeCon 2018](https://youtu.be/TZPPjAv12KU) using different
51-
_Serverless platforms_, such as
52-
[Apache Openwhisk](https://github.com/apache/incubator-openwhisk).
53-
5453
## Documentation
5554

56-
Documentation is available at https://cloudevents.github.io/sdk-java/
55+
Documentation is available at https://cloudevents.github.io/sdk-java/.
5756

5857
Javadocs are available on [javadoc.io](https://www.javadoc.io):
5958

@@ -64,6 +63,8 @@ Javadocs are available on [javadoc.io](https://www.javadoc.io):
6463
- [cloudevents-http-restful-ws](https://www.javadoc.io/doc/io.cloudevents/cloudevents-http-restful-ws)
6564
- [cloudevents-http-vertx](https://www.javadoc.io/doc/io.cloudevents/cloudevents-http-vertx)
6665
- [cloudevents-kafka](https://www.javadoc.io/doc/io.cloudevents/cloudevents-kafka)
66+
- [cloudevents-amqp](https://www.javadoc.io/doc/io.cloudevents/cloudevents-amqp)
67+
- [cloudevents-spring](https://www.javadoc.io/doc/io.cloudevents/cloudevents-spring)
6768

6869
You can check out the examples in the [examples](examples) directory.
6970

‎amqp/README.md

+2-32
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,5 @@
11
# AMQP Protocol Binding
22

3-
[![Javadocs](http://www.javadoc.io/badge/io.cloudevents/cloudevents-amqp-proton.svg?color=green)](http://www.javadoc.io/doc/io.cloudevents/cloudevents-amqp-proton)
3+
Javadoc: [![Javadocs](http://www.javadoc.io/badge/io.cloudevents/cloudevents-amqp-proton.svg?color=green)](http://www.javadoc.io/doc/io.cloudevents/cloudevents-amqp-proton)
44

5-
This module implements `MessageReader` and `MessageWriter` using the Qpid Proton library. It can be used with Qpid Proton or any integrations based on Qpid Proton (e.g vertx-proton).
6-
7-
For Maven based projects, use the following to configure the `proton` AMQP binding for CloudEvents:
8-
9-
```xml
10-
<dependency>
11-
<groupId>io.cloudevents</groupId>
12-
<artifactId>cloudevents-amqp-proton</artifactId>
13-
<version>2.0.0.RC1</version>
14-
</dependency>
15-
```
16-
17-
## Sending and Receiving CloudEvents
18-
19-
To send and receive CloudEvents we use `MessageWriter` and `MessageReader`, respectively.
20-
This module offers factory methods for creation of those in `ProtonAmqpMessageFactory`.
21-
22-
```java
23-
public class ProtonAmqpMessageFactory {
24-
public static MessageReader createReader(final Message message);
25-
public static MessageReader createReader(final String contentType, final byte[] payload);
26-
public static MessageReader createReader(final String contentType, final ApplicationProperties props, final byte[] payload);
27-
public static MessageWriter createWriter();
28-
}
29-
```
30-
31-
Examples:
32-
33-
The example uses the vertx-proton integration to send/receive CloudEvent messages over AMQP.
34-
* [Vertx AmqpServer](../examples/amqp-proton/src/main/java/io/cloudevents/examples/amqp/vertx/AmqpServer.java)
35-
* [Vertx AmqpClient](../examples/amqp-proton/src/main/java/io/cloudevents/examples/amqp/vertx/AmqpClient.java)
5+
Documentation: https://cloudevents.github.io/sdk-java/amqp-proton

‎api/README.md

+2-25
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,5 @@
11
# CloudEvents API
22

3-
[![Javadocs](http://www.javadoc.io/badge/io.cloudevents/cloudevents-api.svg?color=green)](http://www.javadoc.io/doc/io.cloudevents/cloudevents-api)
3+
Javadoc: [![Javadocs](http://www.javadoc.io/badge/io.cloudevents/cloudevents-api.svg?color=green)](http://www.javadoc.io/doc/io.cloudevents/cloudevents-api)
44

5-
For Maven based projects, use the following dependency:
6-
7-
```xml
8-
<dependency>
9-
<groupId>io.cloudevents</groupId>
10-
<artifactId>cloudevents-api</artifactId>
11-
<version>2.0.0.RC1</version>
12-
</dependency>
13-
```
14-
15-
## Features
16-
17-
This package provides the base interfaces used by the SDK. In particular:
18-
19-
- `CloudEvent` is the main interface representing a read only CloudEvent in-memory representation
20-
- `Extension` represents a _materialized_ in-memory representation of a CloudEvent extension
21-
- `SpecVersion` is an enum of CloudEvents' specification versions supported by this SDK version.
22-
- `CloudEventVisitor`/`CloudEventVisitable` are the interfaces used by the SDK to implement protocol bindings/event formats.
23-
A 3rd party implementer can implement these interfaces directly in its `CloudEvent` in order
24-
to customize/implement efficiently the marshalling/unmarshalling process.
25-
These interfaces are optional and, if your `CloudEvent` doesn't implement it, a default implementation is provided by the SDK.
26-
27-
`cloudevents-core` provides the implementation of these interfaces, and a 3rd party implementer can grab this package
28-
to implement specialized CloudEvent in-memory representations.
5+
Documentation: https://cloudevents.github.io/sdk-java/api

‎core/README.md

+2-64
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,5 @@
11
# CloudEvents Core
22

3-
[![Javadocs](http://www.javadoc.io/badge/io.cloudevents/cloudevents-core.svg?color=green)](http://www.javadoc.io/doc/io.cloudevents/cloudevents-core)
3+
Javadoc: [![Javadocs](http://www.javadoc.io/badge/io.cloudevents/cloudevents-core.svg?color=green)](http://www.javadoc.io/doc/io.cloudevents/cloudevents-core)
44

5-
The base classes, interfaces and low-level APIs to use CloudEvents.
6-
7-
## How to Use
8-
9-
For Maven based projects, use the following dependency:
10-
11-
```xml
12-
<dependency>
13-
<groupId>io.cloudevents</groupId>
14-
<artifactId>cloudevents-api</artifactId>
15-
<version>2.0.0.RC1</version>
16-
</dependency>
17-
```
18-
19-
### Create an Event
20-
21-
```java
22-
import io.cloudevents.CloudEvent;
23-
import io.cloudevents.core.builder.CloudEventBuilder;
24-
import java.net.URI;
25-
26-
final CloudEvent event = CloudEventBuilder.v1()
27-
.withId("000")
28-
.withType("example.demo")
29-
.withSource(URI.create("http://example.com"))
30-
.withData("application/json", "{}".getBytes())
31-
.build();
32-
```
33-
34-
### Materialize an Extension
35-
36-
CloudEvent extensions can be materialized in their respective POJOs:
37-
38-
```java
39-
import io.cloudevents.core.extensions.DistributedTracingExtension;
40-
import io.cloudevents.core.extensions.ExtensionsParser;
41-
42-
DistributedTracingExtension dte = ExtensionsParser.getInstance()
43-
.parseExtension(DistributedTracingExtension.class, event);
44-
```
45-
46-
### Using Event Formats
47-
48-
The SDK implements [Event Formats](https://github.com/cloudevents/spec/blob/v1.0/spec.md#event-format) in submodules.
49-
To use them, you just need to add them as dependencies to your project and the SDK,
50-
through the `ServiceLoader` mechanism, will load them into the classpath.
51-
For example, to use the [JSON event format](https://github.com/cloudevents/spec/blob/v1.0/json-format.md) with Jackson,
52-
add `cloudevents-json-jackson` as a dependency and then:
53-
54-
```java
55-
import io.cloudevents.core.format.EventFormatProvider;
56-
import io.cloudevents.jackson.JsonFormat;
57-
58-
EventFormat format = EventFormatProvider
59-
.getInstance()
60-
.resolveFormat(JsonFormat.CONTENT_TYPE);
61-
62-
// Serialize event
63-
byte[] serialized = format.serialize(event);
64-
65-
// Deserialize event
66-
CloudEvent event = format.deserialize(bytes);
67-
```
5+
Documentation: https://cloudevents.github.io/sdk-java/core

‎docs/_config.yml

+5-5
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
title: Java SDK for CloudEvents
55
remote_theme: pmarsceill/just-the-docs
66
plugins:
7-
- jemoji
7+
- jemoji
88

99
search_enabled: true
1010

@@ -16,7 +16,7 @@ gh_edit_source: docs
1616
gh_edit_view_mode: "tree"
1717

1818
aux_links:
19-
"GitHub Repository":
20-
- "https://github.com/cloudevents/sdk-java"
21-
"CloudEvents home":
22-
- "https://cloudevents.io/"
19+
"GitHub Repository":
20+
- "https://github.com/cloudevents/sdk-java"
21+
"CloudEvents home":
22+
- "https://cloudevents.io/"

‎docs/amqp-proton.md

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: CloudEvents AMQP Proton
3+
nav_order: 5
4+
---
5+
6+
# CloudEvents AMQP Proton
7+
8+
[![Javadocs](http://www.javadoc.io/badge/io.cloudevents/cloudevents-amqp-proton.svg?color=green)](http://www.javadoc.io/doc/io.cloudevents/cloudevents-amqp-proton)
9+
10+
This module implements `MessageReader` and `MessageWriter` using the Qpid Proton
11+
library. It can be used with Qpid Proton or any integrations based on Qpid
12+
Proton (e.g vertx-proton).
13+
14+
For Maven based projects, use the following to configure the `proton` AMQP
15+
binding for CloudEvents:
16+
17+
```xml
18+
<dependency>
19+
<groupId>io.cloudevents</groupId>
20+
<artifactId>cloudevents-amqp-proton</artifactId>
21+
<version>2.0.0.RC1</version>
22+
</dependency>
23+
```
24+
25+
## Sending and Receiving CloudEvents
26+
27+
To send and receive CloudEvents we use `MessageWriter` and `MessageReader`,
28+
respectively. This module offers factory methods for creation of those in
29+
`ProtonAmqpMessageFactory`.
30+
31+
```java
32+
public class ProtonAmqpMessageFactory {
33+
public static MessageReader createReader(final Message message);
34+
35+
public static MessageReader createReader(final String contentType, final byte[] payload);
36+
37+
public static MessageReader createReader(final String contentType, final ApplicationProperties props, final byte[] payload);
38+
39+
public static MessageWriter createWriter();
40+
}
41+
```
42+
43+
## Examples:
44+
45+
The example uses the `vertx-proton` integration to send/receive CloudEvent
46+
messages over AMQP:
47+
48+
- [Vertx AmqpServer](https://github.com/cloudevents/sdk-java/tree/master/examples/amqp-proton/src/main/java/io/cloudevents/examples/amqp/vertx/AmqpServer.java)
49+
- [Vertx AmqpClient](https://github.com/cloudevents/sdk-java/tree/master/examples/amqp-proton/src/main/java/io/cloudevents/examples/amqp/vertx/AmqpClient.java)

‎docs/api.md

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: CloudEvents API
3+
nav_order: 2
4+
---
5+
6+
# CloudEvents API
7+
8+
[![Javadocs](http://www.javadoc.io/badge/io.cloudevents/cloudevents-api.svg?color=green)](http://www.javadoc.io/doc/io.cloudevents/cloudevents-api)
9+
10+
This module contains the interfaces to represent `CloudEvent` in memory and to
11+
read and write an object using as CloudEvent.
12+
13+
For Maven based projects, use the following dependency:
14+
15+
```xml
16+
17+
<dependency>
18+
<groupId>io.cloudevents</groupId>
19+
<artifactId>cloudevents-api</artifactId>
20+
<version>2.0.0.RC1</version>
21+
</dependency>
22+
```
23+
24+
## `CloudEvent` hierarchy
25+
26+
`CloudEvent` is the main interface representing a read-only CloudEvent in-memory
27+
representation. A `CloudEvent` is composed by its context attributes, including
28+
the predefined attributes and the extensions, and the data.
29+
30+
![](api.png)
31+
32+
`CloudEventData` is an abstraction to allow carrying any kind of data payload
33+
inside a `CloudEvent`, while enforcing the ability of convert such data to
34+
`[]byte`, ultimately used to send `CloudEvent` on the wire.
35+
36+
## Reader and Writer
37+
38+
The package `io.cloudevents.rw` contains the interfaces to read and write
39+
objects as CloudEvents.
40+
41+
![](rw.png)
42+
43+
In other words, you can use these interfaces to perform an unstructured
44+
read/write of an entity as CloudEvent. For example, an HTTP server request in
45+
binary mode containing a valid CloudEvent can be translated to a
46+
`CloudEventReader`. Similarly, an HTTP server response can be written as a
47+
CloudEvent, hence an eventual response builder could implement
48+
`CloudEventWriter`.
49+
50+
`CloudEventReader` and `CloudEventWriter` implementations doesn't have any
51+
particular knowledge about specification version, difference between attributes
52+
and extensions, and so on. Their only concern is how to read and write context
53+
attributes and data back and forth to the "CloudEvents type system", as defined
54+
in the package `io.cloudevents`.
55+
56+
A 3rd party implementer can implement these interfaces directly in its
57+
`CloudEvent` in order to customize/implement efficiently the
58+
marshalling/unmarshalling process. These interfaces are optional and, if your
59+
`CloudEvent` doesn't implement it, a default implementation is provided by the
60+
core module.
61+
62+
## Other interfaces
63+
64+
- `Extension` represents a _materialized_ in-memory representation of a
65+
CloudEvent extension
66+
- `SpecVersion` is an enum of CloudEvents' specification versions supported by
67+
this SDK version.

‎docs/api.png

41.9 KB
Loading

0 commit comments

Comments
 (0)