[New Docs PR] - Helidon MP WebSocket 4213

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,35 @@
 :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, Overview>>
+- <<Maven Coordinates, Maven Coordinates>>
+- <<Usage, Usage>>
+- <<API, API>>
+- <<Examples, Examples>>
+- <<Reference, Reference>>
+
+== Overview
 
 Helidon integrates with {tyrus-project-url}[Tyrus] to provide support for the {websocket-spec-url}[Jakarta WebSocket API].
+
+
+include::{common-deps-page-prefix-inc}[tag=maven-dependency]
+[source,xml,subs="attributes+"]
+----
+<dependency>
+    <groupId>io.helidon.microprofile.websocket</groupId>
+    <artifactId>helidon-microprofile-websocket</artifactId>
+</dependency>
+----
+
+== 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,22 +68,40 @@ 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.
 
-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.
+|@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 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.
+|@OnOpen
+|This method level annotation can be used to decorate a Java method that will be called when a new web socket session is open.
 
-The REST endpoint is implemented as a JAX-RS resource, and the shared
-queue (in application scope) is directly injected:
+
+|@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.
+
+|@OnError
+|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 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.
+
+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:
 
 [source,java]
 ----
@@ -75,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]
 ----
@@ -100,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:
 
@@ -143,17 +169,15 @@ 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.
+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.
+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].
+
+
+== 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]