diff --git a/docs/http-jakarta-restful-ws-jakarta.md b/docs/http-jakarta-restful-ws-jakarta.md new file mode 100644 index 000000000..e9f8c8280 --- /dev/null +++ b/docs/http-jakarta-restful-ws-jakarta.md @@ -0,0 +1,137 @@ +--- +title: CloudEvents HTTP Jakarta EE 9+ - Jakarta RESTful Web Services +nav_order: 5 +--- + +# HTTP Protocol Binding for Jakarta EE 9+ - Jakarta RESTful Web Services + +[![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) + +For Maven based projects, use the following to configure the CloudEvents Jakarta +RESTful Web Services Binding for Jakarta EE 9+: + +```xml + + io.cloudevents + cloudevents-http-restful-ws-jakarta + 2.5.0-SNAPSHOT + +``` + +This integration is tested with Jersey, RestEasy & Microprofile Liberty. + +#### * Before using this package ensure your web framework does support the `jakarta.*` namespace. + +## Receiving CloudEvents + +You need to configure the `CloudEventsProvider` to enable +marshalling/unmarshalling of CloudEvents. + +Below is a sample on how to read and write CloudEvents: + +```java +import io.cloudevents.CloudEvent; +import io.cloudevents.core.builder.CloudEventBuilder; + +import jakarta.ws.rs.GET; +import jakarta.ws.rs.POST; +import jakarta.ws.rs.Path; +import jakarta.ws.rs.core.Response; + +@Path("/") +public class EventReceiverResource { + + + + @GET + @Path("getMinEvent") + public CloudEvent getMinEvent() { + return CloudEventBuilder.v1() + .withId("hello") + .withType("example.vertx") + .withSource(URI.create("http://localhost")) + .build(); + } + + // Return the CloudEvent using the HTTP binding structured encoding + @GET + @Path("getStructuredEvent") + @StructuredEncoding("application/cloudevents+csv") + public CloudEvent getStructuredEvent() { + return CloudEventBuilder.v1() + .withId("hello") + .withType("example.vertx") + .withSource(URI.create("http://localhost")) + .build(); + } + + @POST + @Path("postEventWithoutBody") + public Response postEvent(CloudEvent inputEvent) { + // Handle the event + return Response.ok().build(); + } +} +``` + +## Sending CloudEvents + +You need to configure the `CloudEventsProvider` to enable +marshalling/unmarshalling of CloudEvents. + +Below is a sample on how to use the client to send a CloudEvent: + +```java +import io.cloudevents.CloudEvent; +import io.cloudevents.http.restful.ws.CloudEventsProvider; + +import jakarta.ws.rs.client.Entity; +import jakarta.ws.rs.client.WebTarget; +import jakarta.ws.rs.core.HttpHeaders; +import jakarta.ws.rs.core.Response; + +public class CloudEventSender { + + public Response sendEvent(WebTarget target, CloudEvent event) { + return target + .path("postEvent") + .request() + .buildPost(Entity.entity(event, CloudEventsProvider.CLOUDEVENT_TYPE)) + .invoke(); + } + + public Response sendEventAsStructured(WebTarget target, CloudEvent event) { + return target + .path("postEvent") + .request() + .buildPost(Entity.entity(event, "application/cloudevents+json")) + .invoke(); + } + + public CloudEvent getEvent(WebTarget target) { + Response response = target + .path("getEvent") + .request() + .buildGet() + .invoke(); + + return response.readEntity(CloudEvent.class); + } +} +``` + +## Migrating EE 8 applications to EE 9+ +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. + +This change largely impacts only `import` statements it does filter down to dependencies such as this. + +### Application migration +For application migration we would recommend reviewing materials available from https://jakarta.ee/resources/#documentation as a starting point. + +### CloudEvents Dependency +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` + +## Examples + +- [Microprofile and Liberty](https://github.com/cloudevents/sdk-java/tree/master/examples/restful-ws-micropofile-liberty) + diff --git a/docs/http-jakarta-restful-ws.md b/docs/http-jakarta-restful-ws.md index a7f08fefb..6cc179944 100644 --- a/docs/http-jakarta-restful-ws.md +++ b/docs/http-jakarta-restful-ws.md @@ -3,12 +3,12 @@ title: CloudEvents HTTP Jakarta RESTful Web Services nav_order: 5 --- -# HTTP Protocol Binding for Jakarta RESTful Web Services +# HTTP Protocol Binding for Jakarta EE8 - 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: +RESTful Web Services Binding for Jakarta EE 8: ```xml diff --git a/docs/index.md b/docs/index.md index ea4552f3a..07664c2ee 100644 --- a/docs/index.md +++ b/docs/index.md @@ -62,7 +62,8 @@ receive CloudEvents, check out the dedicated pages: - [AMQP using Proton](amqp-proton.md) - [HTTP using Vert.x](http-vertx.md) -- [HTTP using Jakarta Restful WS](http-jakarta-restful-ws.md) +- [HTTP using Jakarta EE 8 - Jakarta Restful WS](http-jakarta-restful-ws.md) +- [HTTP using Jakarta EE 9+ - Jakarta Restful WS](http-jakarta-restful-ws-jakarta.md) - [HTTP using Spring](spring.md) - [HTTP using Jackson](json-jackson.md) - [Kafka](kafka.md) @@ -98,7 +99,9 @@ a different feature from the different sub specs of - [`cloudevents-http-vertx`] Implementation of [HTTP Protocol Binding] with [Vert.x Core](https://vertx.io/) - [`cloudevents-http-restful-ws`] Implementation of [HTTP Protocol Binding] - for [Jakarta Restful WS](https://jakarta.ee/specifications/restful-ws/) + for [Jakarta EE 8 Restful WS](https://jakarta.ee/specifications/restful-ws/2.1/) +- [`cloudevents-http-restful-ws-jakarta`] Implementation of [HTTP Protocol Binding] + for [Jakarta EE 9+ Restful WS](https://jakarta.ee/specifications/restful-ws/) - [`cloudevents-http-basic`] Generic implementation of [HTTP Protocol Binding], primarily intended for integrators - [`cloudevents-kafka`] Implementation of [Kafka Protocol Binding] @@ -123,6 +126,7 @@ You can look at the latest published artifacts on [`cloudevents-http-vertx`]: https://github.com/cloudevents/sdk-java/tree/master/http/vertx [`cloudevents-http-basic`]: https://github.com/cloudevents/sdk-java/tree/master/http/basic [`cloudevents-http-restful-ws`]: https://github.com/cloudevents/sdk-java/tree/master/http/restful-ws +[`cloudevents-http-restful-ws-jakarta`]: https://github.com/cloudevents/sdk-java/tree/master/http/restful-ws-jakarta [`cloudevents-kafka`]: https://github.com/cloudevents/sdk-java/tree/master/kafka [`cloudevents-amqp-proton`]: https://github.com/cloudevents/sdk-java/tree/master/amqp [`cloudevents-spring`]: https://github.com/cloudevents/sdk-java/tree/master/spring diff --git a/http/restful-ws-jakarta/README.md b/http/restful-ws-jakarta/README.md new file mode 100644 index 000000000..8f676ce2e --- /dev/null +++ b/http/restful-ws-jakarta/README.md @@ -0,0 +1,7 @@ +# HTTP Protocol Binding for Jakarta EE9+ - Jakarta RESTful Web Services + +Javadocs: [![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) + +Documentation: https://cloudevents.github.io/sdk-java/http-jakarta-restful-ws + +The code for this package lies within the [restful-ws](https://github.com/cloudevents/sdk-java/tree/master/http/restful-ws) directory and is copied within here and has `javax.` replaced with `jakarta.`