se.websocket.adoc Maven / Gradle / Ivy
///////////////////////////////////////////////////////////////////////////////
Copyright (c) 2020, 2024 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.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
///////////////////////////////////////////////////////////////////////////////
= WebSocket Introduction
:description: Helidon WebSocket Introduction
:keywords: helidon, webserver, websocket, se
:feature-name: WebSocket
:rootdir: {docdir}/..
include::{rootdir}/includes/se.adoc[]
== Contents
- <>
- <>
- <>
- <>
== Overview
Helidon integrates with link:https://projects.eclipse.org/projects/ee4j.tyrus[Tyrus] to provide support for the
{jakarta-websocket-spec-url}[Jakarta WebSocket API].
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.
Annotated endpoints, as suggested by their name, use Java annotations to provide
the necessary meta-data to define WebSocket handlers; programmatic endpoints
implement API interfaces and are annotation free. Annotated endpoints tend to be
more flexible since they allow different method signatures depending on the
application needs, whereas programmatic endpoints must implement an interface
and are, therefore, bounded to its definition.
Helidon SE support is based on the `WebSocketRouting` class which enables Helidon application to
configure routing for both annotated and programmatic WebSocket endpoints.
include::{rootdir}/includes/dependencies.adoc[]
[source,xml]
----
io.helidon.webserver
helidon-webserver-websocket
----
== Example
This section describes the implementation of a simple application
that uses a REST resource to push messages into a shared queue and a
programmatic 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 complete Helidon SE example is available {helidon-github-examples-url}/webserver/websocket[here]. Let us start by
looking at `MessageQueueService`:
[source,java]
----
include::{sourcedir}/se/WebSocketSnippets.java[tag=snippet_1, indent=0]
----
This class exposes a REST resource where messages can be posted. Upon
receiving a message, it simply pushes it into a shared queue and
returns 204 (No Content).
Messages pushed into the queue can be obtained by opening a WebSocket
connection served by `MessageBoardEndpoint`:
[source,java]
----
include::{sourcedir}/se/WebSocketSnippets.java[tag=snippet_2, indent=0]
----
This is an example of a programmatic endpoint that extends `WsListener`. The method
`onMessage` will be invoked for every message. In this example, when the special `send` message
is received, it empties the shared queue sending messages one at a time over
the WebSocket connection.
In Helidon SE, REST and WebSocket classes need to be manually registered into
the web server. This is accomplished via a `Routing` builder:
[source,java]
----
include::{sourcedir}/se/WebSocketSnippets.java[tag=snippet_3, indent=0]
----
This code snippet registers `MessageBoardEndpoint` at `/websocket/board` and associates.
== Reference
* link:{javadoc-base-url}/io.helidon.webserver.websocket/module-summary.html[Helidon WebSocket JavaDoc]