Skip to content

Commit 3399747

Browse files
robp94abutch3r
robp94
and
abutch3r
authored
Support westful-ws jakarta ee9 namespace (#469)
* Replace javax restful-ws namespace usage with jakarata in own module * Add microprofile with openliberty example using new jar * Update gitignore to cover all copied directories * Update Jersey Version to support jakarta.* namespace packages * Port jersey integration tests from javax.* to jakarta.* * Undo changes to existing integration test package names * Add Integration test for Microprofile/Liberty for Jee9 package * Add documentation for new Jakarta package Signed-off-by: Robert Pospisil <robert.pospisil@mobilexag.de> Co-authored-by: Alex Butcher <21243172+abutch3r@users.noreply.github.com>
1 parent f16a48c commit 3399747

File tree

27 files changed

+1655
-4
lines changed

27 files changed

+1655
-4
lines changed

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,3 +45,5 @@ _site/
4545

4646
# MacOS
4747
*.DS_Store
48+
/http/restful-ws-jakarta/src/main/*
49+

‎docs/http-jakarta-restful-ws-jakarta.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
title: CloudEvents HTTP Jakarta EE 9+ - Jakarta RESTful Web Services
3+
nav_order: 5
4+
---
5+
6+
# HTTP Protocol Binding for Jakarta EE 9+ - Jakarta RESTful Web Services
7+
8+
[![Javadocs](https://www.javadoc.io/badge/io.cloudevents/cloudevents-http-restful-ws.svg?color=green)](https://www.javadoc.io/doc/io.cloudevents/cloudevents-http-restful-ws)
9+
10+
For Maven based projects, use the following to configure the CloudEvents Jakarta
11+
RESTful Web Services Binding for Jakarta EE 9+:
12+
13+
```xml
14+
<dependency>
15+
<groupId>io.cloudevents</groupId>
16+
<artifactId>cloudevents-http-restful-ws-jakarta</artifactId>
17+
<version>2.4.3</version>
18+
</dependency>
19+
```
20+
21+
This integration is tested with Jersey (Requires JDK11 or higher), RestEasy & Microprofile Liberty.
22+
23+
#### * Before using this package ensure your web framework does support the `jakarta.*` namespace.
24+
25+
## Receiving CloudEvents
26+
27+
You need to configure the `CloudEventsProvider` to enable
28+
marshalling/unmarshalling of CloudEvents.
29+
30+
Below is a sample on how to read and write CloudEvents:
31+
32+
```java
33+
import io.cloudevents.CloudEvent;
34+
import io.cloudevents.core.builder.CloudEventBuilder;
35+
36+
import jakarta.ws.rs.GET;
37+
import jakarta.ws.rs.POST;
38+
import jakarta.ws.rs.Path;
39+
import jakarta.ws.rs.core.Response;
40+
41+
@Path("/")
42+
public class EventReceiverResource {
43+
44+
45+
46+
@GET
47+
@Path("getMinEvent")
48+
public CloudEvent getMinEvent() {
49+
return CloudEventBuilder.v1()
50+
.withId("hello")
51+
.withType("example.vertx")
52+
.withSource(URI.create("http://localhost"))
53+
.build();
54+
}
55+
56+
// Return the CloudEvent using the HTTP binding structured encoding
57+
@GET
58+
@Path("getStructuredEvent")
59+
@StructuredEncoding("application/cloudevents+csv")
60+
public CloudEvent getStructuredEvent() {
61+
return CloudEventBuilder.v1()
62+
.withId("hello")
63+
.withType("example.vertx")
64+
.withSource(URI.create("http://localhost"))
65+
.build();
66+
}
67+
68+
@POST
69+
@Path("postEventWithoutBody")
70+
public Response postEvent(CloudEvent inputEvent) {
71+
// Handle the event
72+
return Response.ok().build();
73+
}
74+
}
75+
```
76+
77+
## Sending CloudEvents
78+
79+
You need to configure the `CloudEventsProvider` to enable
80+
marshalling/unmarshalling of CloudEvents.
81+
82+
Below is a sample on how to use the client to send a CloudEvent:
83+
84+
```java
85+
import io.cloudevents.CloudEvent;
86+
import io.cloudevents.http.restful.ws.CloudEventsProvider;
87+
88+
import jakarta.ws.rs.client.Entity;
89+
import jakarta.ws.rs.client.WebTarget;
90+
import jakarta.ws.rs.core.HttpHeaders;
91+
import jakarta.ws.rs.core.Response;
92+
93+
public class CloudEventSender {
94+
95+
public Response sendEvent(WebTarget target, CloudEvent event) {
96+
return target
97+
.path("postEvent")
98+
.request()
99+
.buildPost(Entity.entity(event, CloudEventsProvider.CLOUDEVENT_TYPE))
100+
.invoke();
101+
}
102+
103+
public Response sendEventAsStructured(WebTarget target, CloudEvent event) {
104+
return target
105+
.path("postEvent")
106+
.request()
107+
.buildPost(Entity.entity(event, "application/cloudevents+json"))
108+
.invoke();
109+
}
110+
111+
public CloudEvent getEvent(WebTarget target) {
112+
Response response = target
113+
.path("getEvent")
114+
.request()
115+
.buildGet()
116+
.invoke();
117+
118+
return response.readEntity(CloudEvent.class);
119+
}
120+
}
121+
```
122+
123+
## Migrating EE 8 applications to EE 9+
124+
The main change between Jakarta EE 8 and Jakarta EE 9 and future versions is the changing of the `javax.` to `jakarta.` namespaces used by key packages such as `jakarta.ws.rs-api` which provides the restful-ws API.
125+
126+
This change largely impacts only `import` statements it does filter down to dependencies such as this.
127+
128+
### Application migration
129+
For application migration we would recommend reviewing materials available from https://jakarta.ee/resources/#documentation as a starting point.
130+
131+
### CloudEvents Dependency
132+
To migrate to use EE 9+ supported package - replace `cloudevents-http-restful-ws` with `cloudevents-http-restful-ws-jakarta` and ensure the version is a minimum of `2.5.0-SNAPSHOT`
133+
134+
## Examples
135+
136+
- [Microprofile and Liberty](https://github.com/cloudevents/sdk-java/tree/master/examples/restful-ws-micropofile-liberty)
137+

‎docs/http-jakarta-restful-ws.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@ title: CloudEvents HTTP Jakarta RESTful Web Services
33
nav_order: 5
44
---
55

6-
# HTTP Protocol Binding for Jakarta RESTful Web Services
6+
# HTTP Protocol Binding for Jakarta EE8 - RESTful Web Services
77

88
[![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)
99

1010
For Maven based projects, use the following to configure the CloudEvents Jakarta
11-
RESTful Web Services Binding:
11+
RESTful Web Services Binding for Jakarta EE 8:
1212

1313
```xml
1414
<dependency>

‎docs/index.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,8 @@ receive CloudEvents, check out the dedicated pages:
6262

6363
- [AMQP using Proton](amqp-proton.md)
6464
- [HTTP using Vert.x](http-vertx.md)
65-
- [HTTP using Jakarta Restful WS](http-jakarta-restful-ws.md)
65+
- [HTTP using Jakarta EE 8 - Jakarta Restful WS](http-jakarta-restful-ws.md)
66+
- [HTTP using Jakarta EE 9+ - Jakarta Restful WS](http-jakarta-restful-ws-jakarta.md)
6667
- [HTTP using Spring](spring.md)
6768
- [HTTP using Jackson](json-jackson.md)
6869
- [Kafka](kafka.md)
@@ -98,7 +99,9 @@ a different feature from the different sub specs of
9899
- [`cloudevents-http-vertx`] Implementation of [HTTP Protocol Binding] with
99100
[Vert.x Core](https://vertx.io/)
100101
- [`cloudevents-http-restful-ws`] Implementation of [HTTP Protocol Binding]
101-
for [Jakarta Restful WS](https://jakarta.ee/specifications/restful-ws/)
102+
for [Jakarta EE 8 Restful WS](https://jakarta.ee/specifications/restful-ws/2.1/)
103+
- [`cloudevents-http-restful-ws-jakarta`] Implementation of [HTTP Protocol Binding]
104+
for [Jakarta EE 9+ Restful WS](https://jakarta.ee/specifications/restful-ws/)
102105
- [`cloudevents-http-basic`] Generic implementation of [HTTP Protocol
103106
Binding], primarily intended for integrators
104107
- [`cloudevents-kafka`] Implementation of [Kafka Protocol Binding]
@@ -123,6 +126,7 @@ You can look at the latest published artifacts on
123126
[`cloudevents-http-vertx`]: https://github.com/cloudevents/sdk-java/tree/master/http/vertx
124127
[`cloudevents-http-basic`]: https://github.com/cloudevents/sdk-java/tree/master/http/basic
125128
[`cloudevents-http-restful-ws`]: https://github.com/cloudevents/sdk-java/tree/master/http/restful-ws
129+
[`cloudevents-http-restful-ws-jakarta`]: https://github.com/cloudevents/sdk-java/tree/master/http/restful-ws-jakarta
126130
[`cloudevents-kafka`]: https://github.com/cloudevents/sdk-java/tree/master/kafka
127131
[`cloudevents-amqp-proton`]: https://github.com/cloudevents/sdk-java/tree/master/amqp
128132
[`cloudevents-spring`]: https://github.com/cloudevents/sdk-java/tree/master/spring

‎examples/pom.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
<modules>
2222
<module>kafka</module>
2323
<module>restful-ws-quarkus</module>
24+
<module>restful-ws-microprofile-liberty</module>
2425
<module>vertx</module>
2526
<module>basic-http</module>
2627
<module>restful-ws-spring-boot</module>

‎examples/restful-ws-microprofile-liberty/README.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Cloudevents Restful WS Microprofile Example
2+
3+
This project uses Microprofile 5.0 with OpenLiberty
4+
5+
If you would like to know more about Microprofile go to https://microprofile.io
6+
7+
This Example uses Jakarta EE9 features as such the top level namespace of the `ws-api` packages has changed from `javax` to `jakarta` and uses the `cloudevents-http-restful-ws-jakarta` artifact.
8+
9+
## Build and Execution
10+
11+
### Running the application in dev mode
12+
13+
You can run your application in dev mode that enables live coding using:
14+
```
15+
mvn liberty:dev
16+
```
17+
18+
### Packaging and running the application
19+
20+
To Package and run as a minimum jar without a full OpenLiberty server
21+
```
22+
mvn liberty:package -Drunnable=mvn liberty:package -Dinclude=runnable
23+
```
24+
25+
### Making requests against the server
26+
27+
This sample application has a `/events` RESTful endpoint on the application `cloudevents-restful-ws-microprofile-example
28+
the base application is available at `http://localhost:9080/cloudevents-restful-ws-microprofile-example/`
29+
30+
There are three operations that can be performed:
31+
#### GET /events
32+
Returns a Cloud event with a payload containing a message
33+
34+
```shell
35+
curl -v http://localhost:9080/cloudevents-restful-ws-microprofile-example/events
36+
37+
* Trying 127.0.0.1:9080...
38+
* Connected to localhost (127.0.0.1) port 9080 (#0)
39+
> GET /cloudevents-restful-ws-microprofile-example/events HTTP/1.1
40+
> Host: localhost:9080
41+
> User-Agent: curl/7.83.1
42+
> Accept: */*
43+
>
44+
* Mark bundle as not supporting multiuse
45+
< HTTP/1.1 201 no-content
46+
< Ce-Id: hello
47+
< Ce-Source: http://localhost
48+
< Ce-Specversion: 1.0
49+
< Ce-Type: example.http
50+
< Content-Type: application/json
51+
< Content-Language: en-GB
52+
< Content-Length: 64
53+
< Date: Wed, 17 Aug 2022 14:01:50 GMT
54+
<
55+
{"message":"Welcome to this Cloudevents + Microprofile example"}
56+
```
57+
58+
#### POST /events
59+
POST a Cloudevent with a payload that is printed out in the server logs
60+
61+
```shell
62+
curl -v http://localhost:9080/cloudevents-restful-ws-microprofile-example/events \
63+
-H "Ce-Specversion: 1.0" \
64+
-H "Ce-Type: User" \
65+
-H "Ce-Source: io.cloudevents.examples/user" \
66+
-H "Ce-Id: 536808d3-88be-4077-9d7a-a3f162705f78" \
67+
-H "Content-Type: application/json" \
68+
-H "Ce-Subject: SUBJ-0001" \
69+
-d "hello"
70+
71+
* Trying 127.0.0.1:9080...
72+
* Connected to localhost (127.0.0.1) port 9080 (#0)
73+
> POST /cloudevents-restful-ws-microprofile-example/events HTTP/1.1
74+
> Host: localhost:9080
75+
> User-Agent: curl/7.83.1
76+
> Accept: */*
77+
> Ce-Specversion: 1.0
78+
> Ce-Type: User
79+
> Ce-Source: io.cloudevents.examples/user
80+
> Ce-Id: 536808d3-88be-4077-9d7a-a3f162705f78
81+
> Content-Type: application/json
82+
> Ce-Subject: SUBJ-0001
83+
> Content-Length: 5
84+
>
85+
* Mark bundle as not supporting multiuse
86+
< HTTP/1.1 204 No Content
87+
< Content-Language: en-GB
88+
< Content-Length: 0
89+
< Date: Thu, 18 Aug 2022 13:33:03 GMT
90+
<
91+
* Connection #0 to host localhost left intact
92+
```
93+
Server log statement
94+
```
95+
[INFO] Received request providing a event with body hello
96+
[INFO] CloudEvent{id='536808d3-88be-4077-9d7a-a3f162705f78', source=io.cloudevents.examples/user, type='User', datacontenttype='application/json', subject='SUBJ-0001', data=BytesCloudEventData{value=[104, 101, 108, 108, 111]}, extensions={}}
97+
```
98+
99+
#### POST /events/echo
100+
POST a Cloudevent with a payload and have it echoed back as a Cloudevent
101+
102+
```shell
103+
curl -v http://localhost:9080/cloudevents-restful-ws-microprofile-example/events/echo \
104+
-H "Ce-Specversion: 1.0" \
105+
-H "Ce-Type: User" \
106+
-H "Ce-Source: io.cloudevents.examples/user" \
107+
-H "Ce-Id: 536808d3-88be-4077-9d7a-a3f162705f78" \
108+
-H "Content-Type: application/json" \
109+
-H "Ce-Subject: SUBJ-0001" \
110+
-d "hello"
111+
112+
* Trying 127.0.0.1:9080...
113+
* Connected to localhost (127.0.0.1) port 9080 (#0)
114+
> POST /cloudevents-restful-ws-microprofile-example/rest/events/echo HTTP/1.1
115+
> Host: localhost:9080
116+
> User-Agent: curl/7.83.1
117+
> Accept: */*
118+
> Ce-Specversion: 1.0
119+
> Ce-Type: User
120+
> Ce-Source: io.cloudevents.examples/user
121+
> Ce-Id: 536808d3-88be-4077-9d7a-a3f162705f78
122+
> Content-Type: application/json
123+
> Ce-Subject: SUBJ-0001
124+
> Content-Length: 5
125+
>
126+
* Mark bundle as not supporting multiuse
127+
< HTTP/1.1 200 OK
128+
< Ce-Id: echo
129+
< Ce-Source: http://localhost
130+
< Ce-Specversion: 1.0
131+
< Ce-Type: echo.http
132+
< Content-Type: application/json
133+
< Content-Language: en-GB
134+
< Content-Length: 17
135+
< Date: Wed, 17 Aug 2022 12:57:59 GMT
136+
<
137+
{"echo": "hello"}* Connection #0 to host localhost left intact
138+
```
139+
140+

0 commit comments

Comments
 (0)