From 6a0ce957fb277524a5652be523c26574eae9e0f9 Mon Sep 17 00:00:00 2001 From: Dmitry Aleksandrov Date: Mon, 27 Jun 2022 11:40:21 +0300 Subject: [PATCH 1/5] Helidon MP OpenTracing new style doc initial commit --- docs/mp/websocket/01_overview.adoc | 65 ++++++++++++++++++++++++++++-- 1 file changed, 62 insertions(+), 3 deletions(-) diff --git a/docs/mp/websocket/01_overview.adoc b/docs/mp/websocket/01_overview.adoc index 1e19f0a728b..66612792193 100644 --- a/docs/mp/websocket/01_overview.adoc +++ b/docs/mp/websocket/01_overview.adoc @@ -1,6 +1,6 @@ /////////////////////////////////////////////////////////////////////////////// - Copyright (c) 2020 Oracle and/or its affiliates. + Copyright (c) 2020, 2022 Oracle and/or its affiliates. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -23,9 +23,39 @@ :keywords: helidon, webserver, websocket, mp :websocket-spec-url: https://projects.eclipse.org/projects/ee4j.websocket :tyrus-project-url: https://projects.eclipse.org/projects/ee4j.tyrus -:helidon-websocket-example-url: https://github.com/oracle/helidon/tree/master/examples/webserver/websocket +:helidon-websocket-example-url: https://github.com/oracle/helidon/tree/master/examples/microprofile/websocket/ +:common-deps-page-prefix-inc: ../../shared/dependencies/common_shared.adoc + + +== ToC + +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> + +== Overview Helidon integrates with {tyrus-project-url}[Tyrus] to provide support for the {websocket-spec-url}[Jakarta WebSocket API]. + + +== Maven dependency + +include::{common-deps-page-prefix-inc}[tag=maven-dependency] +[source,xml,subs="attributes+"] +---- + + io.helidon.microprofile.websocket + helidon-microprofile-websocket + +---- + +== Usage + The WebSocket API enables Java applications to participate in WebSocket interactions as both servers and clients. The server API supports two flavors: annotated and programmatic endpoints. @@ -42,7 +72,32 @@ CDI. Developers can choose between annotated and programmatic endpoints or use any combination of them. Using annotated endpoints is recommended in MP as they usually result in more succinct and easier-to-read code. -== Helidon MP Example +== API + + +|=== +|Annotation |Description + +|ServerEndpoint +|This class level annotation declares that the class it decorates is a web socket endpoint that will be deployed and made available in the URI-space of a web socket server. The annotation allows the developer to define the URL (or URI template) which this endpoint will be published, and other important properties of the endpoint to the websocket runtime, such as the encoders it uses to send messages. + +| +| + +|=== + + + +== Configuration + +TODO: add configuration details if applicable + + +== Reference + +TODO + +== Examples This section describes the implementation of a simple application that uses a REST resource to push messages into a shared queue and a @@ -157,3 +212,7 @@ for blocking or long-running operations as these will not affect Netty's ability to process networking data. For more information see the {helidon-websocket-example-url}[example]. + +== Additional information + +More information: https://datatracker.ietf.org/doc/html/rfc6455 \ No newline at end of file From 951f2f688b734064300e3687bedf44931f3c10b8 Mon Sep 17 00:00:00 2001 From: Dmitry Aleksandrov Date: Mon, 27 Jun 2022 11:40:21 +0300 Subject: [PATCH 2/5] Helidon MP WebSocket new style doc initial commit --- docs/mp/websocket/01_overview.adoc | 65 ++++++++++++++++++++++++++++-- 1 file changed, 62 insertions(+), 3 deletions(-) diff --git a/docs/mp/websocket/01_overview.adoc b/docs/mp/websocket/01_overview.adoc index 1e19f0a728b..66612792193 100644 --- a/docs/mp/websocket/01_overview.adoc +++ b/docs/mp/websocket/01_overview.adoc @@ -1,6 +1,6 @@ /////////////////////////////////////////////////////////////////////////////// - Copyright (c) 2020 Oracle and/or its affiliates. + Copyright (c) 2020, 2022 Oracle and/or its affiliates. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -23,9 +23,39 @@ :keywords: helidon, webserver, websocket, mp :websocket-spec-url: https://projects.eclipse.org/projects/ee4j.websocket :tyrus-project-url: https://projects.eclipse.org/projects/ee4j.tyrus -:helidon-websocket-example-url: https://github.com/oracle/helidon/tree/master/examples/webserver/websocket +:helidon-websocket-example-url: https://github.com/oracle/helidon/tree/master/examples/microprofile/websocket/ +:common-deps-page-prefix-inc: ../../shared/dependencies/common_shared.adoc + + +== ToC + +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> + +== Overview Helidon integrates with {tyrus-project-url}[Tyrus] to provide support for the {websocket-spec-url}[Jakarta WebSocket API]. + + +== Maven dependency + +include::{common-deps-page-prefix-inc}[tag=maven-dependency] +[source,xml,subs="attributes+"] +---- + + io.helidon.microprofile.websocket + helidon-microprofile-websocket + +---- + +== Usage + The WebSocket API enables Java applications to participate in WebSocket interactions as both servers and clients. The server API supports two flavors: annotated and programmatic endpoints. @@ -42,7 +72,32 @@ CDI. Developers can choose between annotated and programmatic endpoints or use any combination of them. Using annotated endpoints is recommended in MP as they usually result in more succinct and easier-to-read code. -== Helidon MP Example +== API + + +|=== +|Annotation |Description + +|ServerEndpoint +|This class level annotation declares that the class it decorates is a web socket endpoint that will be deployed and made available in the URI-space of a web socket server. The annotation allows the developer to define the URL (or URI template) which this endpoint will be published, and other important properties of the endpoint to the websocket runtime, such as the encoders it uses to send messages. + +| +| + +|=== + + + +== Configuration + +TODO: add configuration details if applicable + + +== Reference + +TODO + +== Examples This section describes the implementation of a simple application that uses a REST resource to push messages into a shared queue and a @@ -157,3 +212,7 @@ for blocking or long-running operations as these will not affect Netty's ability to process networking data. For more information see the {helidon-websocket-example-url}[example]. + +== Additional information + +More information: https://datatracker.ietf.org/doc/html/rfc6455 \ No newline at end of file From 42e87837f58cce5c402dbf2dbe987c475cbe07c8 Mon Sep 17 00:00:00 2001 From: Dmitry Aleksandrov Date: Mon, 27 Jun 2022 13:40:11 +0300 Subject: [PATCH 3/5] Added reference and usage --- docs/mp/websocket/01_overview.adoc | 33 +++++++++++++++++++----------- 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/docs/mp/websocket/01_overview.adoc b/docs/mp/websocket/01_overview.adoc index 66612792193..b4337f0c508 100644 --- a/docs/mp/websocket/01_overview.adoc +++ b/docs/mp/websocket/01_overview.adoc @@ -43,8 +43,6 @@ Helidon integrates with {tyrus-project-url}[Tyrus] to provide support for the {websocket-spec-url}[Jakarta WebSocket API]. -== Maven dependency - include::{common-deps-page-prefix-inc}[tag=maven-dependency] [source,xml,subs="attributes+"] ---- @@ -78,24 +76,32 @@ they usually result in more succinct and easier-to-read code. |=== |Annotation |Description -|ServerEndpoint +|@ServerEndpoint |This class level annotation declares that the class it decorates is a web socket endpoint that will be deployed and made available in the URI-space of a web socket server. The annotation allows the developer to define the URL (or URI template) which this endpoint will be published, and other important properties of the endpoint to the websocket runtime, such as the encoders it uses to send messages. -| -| +|@ClientEndpoint +|The ClientEndpoint annotation a class level annotation is used to denote that a POJO is a web socket client and can be deployed as such. Similar to ServerEndpoint, POJOs that are annotated with this annotation can have methods that, using the web socket method level annotations, are web socket lifecycle methods. -|=== +|@OnOpen +|This method level annotation can be used to decorate a Java method that wishes to be called when a new web socket session is open. +|@OnMessage +|This method level annotation can be used to make a Java method receive incoming web socket messages. Each websocket endpoint may only have one message handling method for each of the native websocket message formats: text, binary and pong. Methods using this annotation are allowed to have parameters of types described below, otherwise the container will generate an error at deployment time. -== Configuration +|@OnError +|This method level annotation can be used to decorate a Java method that wishes to be called in order to handle errors. See Endpoint.onError(javax.websocket.Session, java.lang.Throwable) for a description of the different categories of error. -TODO: add configuration details if applicable +|@OnClose +|This method level annotation can be used to decorate a Java method that wishes to be called when a web socket session is closing. +|=== -== Reference -TODO + +== Configuration + +TODO: add configuration details if applicable == Examples @@ -213,6 +219,9 @@ to process networking data. For more information see the {helidon-websocket-example-url}[example]. -== Additional information -More information: https://datatracker.ietf.org/doc/html/rfc6455 \ No newline at end of file +== Reference + +* https://projects.eclipse.org/proposals/eclipse-tyrus[Eclipse Tyrus] +* https://datatracker.ietf.org/doc/html/rfc6455[WebSocket RFC 6455] +* https://helidon.io/docs/v2/apidocs/io.helidon.microprofile.tyrus/module-summary.html[Helidon MicroProfile Tyrus JavaDoc] \ No newline at end of file From 03770cc2b9781d3d565155859f6fbfbca20ec041 Mon Sep 17 00:00:00 2001 From: Dmitry Aleksandrov Date: Tue, 28 Jun 2022 13:08:16 +0300 Subject: [PATCH 4/5] Document clean up --- docs/mp/websocket/01_overview.adoc | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/mp/websocket/01_overview.adoc b/docs/mp/websocket/01_overview.adoc index b4337f0c508..df5f57c995a 100644 --- a/docs/mp/websocket/01_overview.adoc +++ b/docs/mp/websocket/01_overview.adoc @@ -33,9 +33,7 @@ - <> - <> - <> -- <> - <> -- <> - <> == Overview @@ -97,12 +95,6 @@ they usually result in more succinct and easier-to-read code. |=== - - -== Configuration - -TODO: add configuration details if applicable - == Examples This section describes the implementation of a simple application From f1a6524dd37d16c83c6e2c159811b6d797245dd2 Mon Sep 17 00:00:00 2001 From: Dmitry Aleksandrov Date: Thu, 30 Jun 2022 12:21:50 +0300 Subject: [PATCH 5/5] Fix Santiago's comments. Reworked. --- docs/mp/websocket/01_overview.adoc | 70 ++++++++---------------------- 1 file changed, 17 insertions(+), 53 deletions(-) diff --git a/docs/mp/websocket/01_overview.adoc b/docs/mp/websocket/01_overview.adoc index df5f57c995a..2813021e288 100644 --- a/docs/mp/websocket/01_overview.adoc +++ b/docs/mp/websocket/01_overview.adoc @@ -78,39 +78,30 @@ they usually result in more succinct and easier-to-read code. |This class level annotation declares that the class it decorates is a web socket endpoint that will be deployed and made available in the URI-space of a web socket server. The annotation allows the developer to define the URL (or URI template) which this endpoint will be published, and other important properties of the endpoint to the websocket runtime, such as the encoders it uses to send messages. |@ClientEndpoint -|The ClientEndpoint annotation a class level annotation is used to denote that a POJO is a web socket client and can be deployed as such. Similar to ServerEndpoint, POJOs that are annotated with this annotation can have methods that, using the web socket method level annotations, are web socket lifecycle methods. +|The ClientEndpoint annotation, a class level annotation, is used to denote that a POJO is a web socket client and can be deployed as such. Similar to `@ServerEndpoint`, POJOs that are annotated with this annotation can have methods that, using the web socket method level annotations, are web socket lifecycle methods. |@OnOpen -|This method level annotation can be used to decorate a Java method that wishes to be called when a new web socket session is open. +|This method level annotation can be used to decorate a Java method that will be called when a new web socket session is open. |@OnMessage -|This method level annotation can be used to make a Java method receive incoming web socket messages. Each websocket endpoint may only have one message handling method for each of the native websocket message formats: text, binary and pong. Methods using this annotation are allowed to have parameters of types described below, otherwise the container will generate an error at deployment time. +|This method level annotation can be used to make a Java method receive incoming web socket messages. Each websocket endpoint may only have one message handling method for each of the native websocket message formats: text, binary and pong. |@OnError -|This method level annotation can be used to decorate a Java method that wishes to be called in order to handle errors. See Endpoint.onError(javax.websocket.Session, java.lang.Throwable) for a description of the different categories of error. +|This method level annotation can be used to decorate a Java method that will be called in order to handle errors. |@OnClose -|This method level annotation can be used to decorate a Java method that wishes to be called when a web socket session is closing. +|This method level annotation can be used to decorate a Java method that will be called when a web socket session is closing. |=== == Examples -This section describes the implementation of a simple application -that uses a REST resource to push messages into a shared queue and a -WebSocket endpoint to download messages from the queue, one at a time, -over a connection. -The example will show how REST and WebSocket connections can -be seamlessly combined into a Helidon application. +This section describes the implementation of a simple application that uses a REST resource to push messages into a shared queue and a WebSocket endpoint to download messages from the queue, one at a time, over a connection. The example will show how REST and WebSocket connections can be seamlessly combined into a Helidon application. -The Helidon MP application shown here takes full advantage of -CDI and class scanning and does not require any additional code -given that the necessary information is available from the -code annotations. +The Helidon MP application shown here takes full advantage of CDI and class scanning and does not require any additional code given that the necessary information is available from the code annotations. -The REST endpoint is implemented as a JAX-RS resource, and the shared -queue (in application scope) is directly injected: +The REST endpoint is implemented as a JAX-RS resource, and the shared queue (in application scope) is directly injected: [source,java] ---- @@ -128,9 +119,7 @@ public class MessageQueueResource { } ---- -Here we opt for the use of an annotated WebSocket endpoint decorated -by `@ServerEndpoint` that provides all the meta-data necessary -for Helidon to create the endpoint. +Here we opt for the use of an annotated WebSocket endpoint decorated by `@ServerEndpoint` that provides all the meta-data necessary for Helidon to create the endpoint. [source,java] ---- @@ -153,27 +142,11 @@ public class MessageBoardEndpoint { } ---- -Since `MessageBoardEndpoint` is just a POJO, it uses additional -annotations for event handlers such as `@OnMessage`. One advantage of -this approach, much like in the JAX-RS API, is that method -signatures are not fixed. In the snipped above, the parameters -(which could be specified in any order!) include the WebSocket -session and the message received that triggered the call. - -So what else is needed to run this Helidon MP app? Nothing else -other than the supporting classes `MessageQueue` and `UppercaseEncoder`. -Helidon MP declares both `@Path` and `@ServerEndpoint` as -bean defining annotation, so all that is needed is for CDI -discovery to be enabled --typically in your `beans.xml` file. - -By default, both JAX-RS resources and WebSocket endpoints will -be available under the _root path_ `"/"`. This default value can be -overridden by providing subclasses/implementations for `jakarta.ws.rs.Application` -and `jakarta.websocket.server.ServerApplicationConfig`, respectively. -JAX-RS uses `@ApplicationPath` on application subclasses to provide -this root path, but since there is no equivalent in the WebSocket -API, Helidon MP uses its own annotation `@RoutingPath` -on `jakarta.websocket.server.ServerApplicationConfig` implementations. +Since `MessageBoardEndpoint` is just a POJO, it uses additional annotations for event handlers such as `@OnMessage`. One advantage of this approach, much like in the JAX-RS API, is that method signatures are not fixed. In the snipped above, the parameters (which could be specified in any order!) include the WebSocket session and the message received that triggered the call. + +So what else is needed to run this Helidon MP app? Nothing else other than the supporting classes `MessageQueue` and `UppercaseEncoder`. Helidon MP declares both `@Path` and `@ServerEndpoint` as bean defining annotation, so all that is needed is for CDI discovery to be enabled --typically in your `beans.xml` file. + +By default, both JAX-RS resources and WebSocket endpoints will be available under the _root path_ `"/"`. This default value can be overridden by providing subclasses/implementations for `jakarta.ws.rs.Application` and `jakarta.websocket.server.ServerApplicationConfig`, respectively. JAX-RS uses `@ApplicationPath` on application subclasses to provide this root path, but since there is no equivalent in the WebSocket API, Helidon MP uses its own annotation `@RoutingPath` on `jakarta.websocket.server.ServerApplicationConfig` implementations. For instance, if in our example we include the following class: @@ -196,18 +169,9 @@ public class MessageBoardApplication implements ServerApplicationConfig { } ---- -the root path for WebSocket endpoints will be `"/web"` instead of the default -`"/"`. Note that `@RoutingPath` is _not_ a bean defining annotation, -thus the need to use `@ApplicationScoped` --which, as before, requires CDI -bean discovery mode to be `annotated`. In addition to `@RoutingPath`, these -classes can be annotated with `@RoutingName` to associate an endpoint -with a Helidon named socket. Please refer to the Javadoc of that annotation -for additional information. - -All endpoint methods in Helidon MP are executed in a separate thread pool, -independently of Netty. Therefore, there is no need to create additional threads -for blocking or long-running operations as these will not affect Netty's ability -to process networking data. +the root path for WebSocket endpoints will be `"/web"` instead of the default `"/"`. Note that `@RoutingPath` is _not_ a bean defining annotation, thus the need to use `@ApplicationScoped` --which, as before, requires CDI bean discovery mode to be `annotated`. In addition to `@RoutingPath`, these classes can be annotated with `@RoutingName` to associate an endpoint with a Helidon named socket. Please refer to the Javadoc of that annotation for additional information. + +All endpoint methods in Helidon MP are executed in a separate thread pool, independently of Netty. Therefore, there is no need to create additional threads for blocking or long-running operations as these will not affect Netty's ability to process networking data. For more information see the {helidon-websocket-example-url}[example].