Improvements to the Jetty documentation.
Updated the WebSocket documentation in the operations guide. Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet
parent
e341f4ca58
commit
480767a03b
|
|
@ -24,14 +24,23 @@ If you are new to Eclipse Jetty, read xref:og-begin[here] to download, install,
|
|||
|
||||
If you know Eclipse Jetty already, jump to a feature:
|
||||
|
||||
* xref:og-sessions[HTTP Session Caching and Clustering]
|
||||
Protocols::
|
||||
* xref:og-protocols-http[HTTP/1.1 Support]
|
||||
* xref:og-protocols-http2[HTTP/2 Support]
|
||||
* xref:og-annotations[Annotations]
|
||||
* xref:og-quickstart[Faster Web Application Deployment]
|
||||
* xref:og-protocols-websocket[WebSocket Support]
|
||||
|
||||
Technologies::
|
||||
* xref:og-annotations[Servlet Annotations]
|
||||
* xref:og-jaas[JAAS]
|
||||
* xref:og-jndi[JNDI]
|
||||
* xref:og-jsp[JSP]
|
||||
* xref:og-jmx[Monitoring & Management]
|
||||
* xref:og-jmx[JMX Monitoring & Management]
|
||||
|
||||
Clustering::
|
||||
* xref:og-sessions[HTTP Session Caching and Clustering]
|
||||
|
||||
Performance::
|
||||
* xref:og-quickstart[Faster Web Application Deployment]
|
||||
|
||||
TODO
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,117 @@
|
|||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[og-protocols-websocket]]
|
||||
==== WebSocket
|
||||
|
||||
WebSocket is a network protocol for bidirectional data communication initiated via the link:https://tools.ietf.org/html/rfc7230#section-6.7[HTTP/1.1 upgrade mechanism].
|
||||
WebSocket provides a simple, low-level, framing protocol layered over TCP.
|
||||
One or more WebSocket frames compose a WebSocket _message_ that is either a UTF-8 _text_ message or _binary_ message.
|
||||
|
||||
Jetty provides an implementation of the following standards and specifications.
|
||||
|
||||
http://tools.ietf.org/html/rfc6455[RFC-6455] - The WebSocket Protocol::
|
||||
Jetty supports version 13 of the released and final specification.
|
||||
|
||||
http://www.jcp.org/en/jsr/detail?id=356[JSR-356] - The Java WebSocket API (`javax.websocket`)::
|
||||
This is the official Java API for working with WebSockets.
|
||||
|
||||
https://tools.ietf.org/html/rfc7692[RFC-7692] - WebSocket Per-Message Deflate Extension::
|
||||
This is the replacement for perframe-compression, switching the compression to being based on the entire message, not the individual frames.
|
||||
|
||||
https://tools.ietf.org/html/rfc8441[RFC-8441] - Bootstrapping WebSockets with HTTP/2::
|
||||
Allows a single stream of an HTTP/2 connection to be upgraded to WebSocket.
|
||||
This allows one TCP connection to be shared by both protocols and extends HTTP/2's more efficient use of the network to WebSockets.
|
||||
|
||||
[[og-protocols-websocket-configure]]
|
||||
==== Configuring WebSocket
|
||||
|
||||
Jetty provides two WebSocket implementations: one based on the Java WebSocket APIs defined by JSR 356, provided by module `websocket-javax`, and one based on Jetty specific WebSocket APIs, provided by module `websocket-jetty`.
|
||||
The Jetty `websocket` module enables both implementations, but each implementation can be enabled independently.
|
||||
|
||||
NOTE: Remember that a WebSocket connection is always initiated from the HTTP protocol (either an HTTP/1.1 upgrade or an HTTP/2 connect), therefore to enable WebSocket you need to enable HTTP.
|
||||
|
||||
To enable WebSocket support, you also need to decide what version of the HTTP protocol you want WebSocket to be initiated from, and whether you want secure HTTP.
|
||||
|
||||
For example, to enable clear-text WebSocket from HTTP/1.1, use the following command (issued from within the `$JETTY_BASE` directory):
|
||||
|
||||
----
|
||||
$ java -jar $JETTY_HOME/start.jar --add-modules=http,websocket
|
||||
----
|
||||
|
||||
To enable secure WebSocket from HTTP/2, use the following command (issued from within the `$JETTY_BASE` directory):
|
||||
|
||||
----
|
||||
$ java -jar $JETTY_HOME/start.jar --add-modules=http2,websocket
|
||||
----
|
||||
|
||||
When enabling secure protocols you need a valid KeyStore (read xref:og-keystore[this section] to create your own KeyStore).
|
||||
As a quick example, you can enable the xref:og-module-test-keystore[`test-keystore` module], that provides a KeyStore containing a self-signed certificate:
|
||||
|
||||
----
|
||||
$ java -jar $JETTY_HOME/start.jar --add-modules=test-keystore
|
||||
----
|
||||
|
||||
To enable WebSocket on both HTTP/1.1 and HTTP/2, both clear-text and secure, use the following command (issued from within the `$JETTY_BASE` directory):
|
||||
|
||||
----
|
||||
$ java -jar $JETTY_HOME/start.jar --add-modules=http,https,http2c,http2,websocket
|
||||
----
|
||||
|
||||
[[og-protocols-websocket-disable]]
|
||||
==== Selectively Disabling WebSocket
|
||||
|
||||
Enabling the WebSocket Jetty modules comes with a startup cost because Jetty must perform two steps:
|
||||
|
||||
. Scan web applications `+*.war+` files (and all the jars and classes inside it) looking for WebSocket EndPoints classes (either annotated with WebSocket API annotations or extending/implementing WebSocket API classes/interfaces).
|
||||
This can be a significant cost if your web application contains a lot of classes and/or jar files.
|
||||
|
||||
. Configure and wire WebSocket EndPoints so that WebSocket messages are delivered to the correspondent WebSocket EndPoint.
|
||||
|
||||
WebSocket support is by default enabled for all web applications.
|
||||
|
||||
For a specific web application, you can disable step 2 for Java WebSocket support (i.e. when the `websocket-javax` module is enabled) by setting the context attribute `org.eclipse.jetty.websocket.javax` to `false`:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
|
||||
version="4.0">
|
||||
|
||||
<!-- Disable Javax WebSocket -->
|
||||
<context-param>
|
||||
<param-name>org.eclipse.jetty.websocket.javax</param-name>
|
||||
<param-value>false</param-value>
|
||||
</context-param>
|
||||
|
||||
...
|
||||
|
||||
</web-app>
|
||||
----
|
||||
|
||||
Furthermore, for a specific web application, you can disable step 1 (and therefore also step 2) as described in the xref:og-annotations[annotations processing section].
|
||||
|
||||
[[og-protocols-websocket-webapp-client]]
|
||||
==== Using WebSocket Client in WebApps
|
||||
|
||||
Web applications may need to use a WebSocket client to communicate with third party WebSocket services.
|
||||
|
||||
If the web application uses the Java WebSocket APIs, the WebSocket client APIs are provided by the Servlet Container and are available to the web application by enabling the WebSocket server APIs, and therefore you must enable the `websocket-javax` Jetty module.
|
||||
|
||||
However, the Java WebSocket Client APIs are quite limited (for example, they do not support secure WebSocket).
|
||||
For this reason, web applications may want to use the Jetty WebSocket Client APIs.
|
||||
|
||||
When using the Jetty WebSocket Client APIs, web applications should include the required jars and their dependencies in the `WEB-INF/lib` directory of the `+*.war+` file.
|
||||
Alternatively, when deploying your web applications in Jetty, you can enable the `websocket-jetty-client` Jetty module to allow web applications to use the Jetty WebSocket Client APIs provided by Jetty, without the need to include jars and their dependencies in the `+*.war+` file.
|
||||
|
|
@ -1,105 +0,0 @@
|
|||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[og-websocket]]
|
||||
=== WebSocket
|
||||
|
||||
WebSocket is a protocol for bidirectional communications initiated via HTTP/1.1 upgrade which provides basic message framing, layered over TCP.
|
||||
It is based on a low-level framing protocol that delivers messages in either UTF-8 TEXT or BINARY format.
|
||||
|
||||
A single message in WebSocket can be of any size (the underlying framing however has a maximum size limit of 2^63 bytes).
|
||||
There can be an unlimited number of messages sent.
|
||||
Messages are sent sequentially, the base protocol does not support interleaved messages.
|
||||
|
||||
A WebSocket connection goes through some basic state changes:
|
||||
|
||||
.WebSocket connection states
|
||||
[width="50%",cols=",",options="header",]
|
||||
|=======================================================================
|
||||
|State |Description
|
||||
|CONNECTING |A HTTP Upgrade to WebSocket is in progress.
|
||||
|OPEN |The HTTP Upgrade succeeded and the socket is now open and ready to read / write.
|
||||
|CLOSING |A WebSocket Close Handshake has been started.
|
||||
|CLOSED |WebSocket is now closed, no more read/write possible.
|
||||
|=======================================================================
|
||||
|
||||
When a WebSocket is closed, a link:{JDURL}/org/eclipse/jetty/websocket/api/StatusCode.html[status code] and short reason string is provided.
|
||||
|
||||
[[og-websocket-provides]]
|
||||
==== What Jetty Provides
|
||||
|
||||
Jetty provides an implementation of the following standards and specs.
|
||||
|
||||
http://tools.ietf.org/html/rfc6455[RFC-6455] - The WebSocket Protocol::
|
||||
We support the version 13 of the released and final spec.
|
||||
Jetty tests its WebSocket protocol implementation using the https://github.com/crossbario/autobahn-testsuite[autobahn testsuite].
|
||||
|
||||
[IMPORTANT]
|
||||
====
|
||||
The early drafts of WebSocket were supported in Jetty 7 and Jetty 8, but this support has been removed in later versions of Jetty.
|
||||
This means that Jetty will no longer not support the old browsers that implemented the early drafts of WebSocket. (such as Safari 5.0 or Opera 12)
|
||||
====
|
||||
|
||||
[TIP]
|
||||
====
|
||||
Want to know if the browser you are targeting supports WebSocket?
|
||||
Use http://caniuse.com/websockets[caniuse.com/websockets] to find out.
|
||||
====
|
||||
|
||||
http://www.jcp.org/en/jsr/detail?id=356[JSR-356] - The Java WebSocket API (`javax.websocket`)::
|
||||
This is the official Java API for working with WebSockets.
|
||||
|
||||
https://tools.ietf.org/html/rfc7692[RFC-7692] - WebSocket Per-Message Deflate Extension.::
|
||||
This is the replacement for perframe-compression, switching the compression to being based on the entire message, not the individual frames.
|
||||
|
||||
https://tools.ietf.org/html/rfc8441[RFC-8441] - Bootstrapping WebSockets with HTTP/2::
|
||||
Allows a single stream of an HTTP/2 connection to be upgraded to WebSocket.
|
||||
This allows one TCP connection to be shared by both protocols and extends HTTP/2's more efficient use of the network to WebSockets.
|
||||
|
||||
[[og-websocket-jetty]]
|
||||
==== Jetty Native WebSocket API
|
||||
|
||||
Jetty provides its own more powerful WebSocket API, with shared API interfaces for both server and client use of WebSockets.
|
||||
Here are the different APIs and libraries to implement your WebSockets using Jetty.
|
||||
|
||||
Jetty WebSocket API::
|
||||
The basic common API for creating and working with WebSockets using Jetty.
|
||||
Jetty WebSocket Server API::
|
||||
Write WebSocket Server Endpoints for Jetty.
|
||||
Jetty WebSocket Client API::
|
||||
Connect to WebSocket servers with Jetty.
|
||||
|
||||
[[og-websocket-modules]]
|
||||
==== Enabling WebSocket
|
||||
|
||||
To use WebSockets on a Jetty server, you need to enable one of the websocket modules.
|
||||
Add the `websocket` module to enable both Jetty and Javax WebSocket modules for deployed web applications.
|
||||
The `websocket-jetty` and `websocket-javax` modules can be used to only enable the specific API to use.
|
||||
|
||||
----
|
||||
$ java -jar $JETTY_HOME/start.jar --add-module=websocket
|
||||
----
|
||||
|
||||
To use the Jetty WebSocket Client API in a webapp, the required jars should be include in the WEB-INF/lib directory.
|
||||
Alternatively the `websocket-jetty-client` module can be enabled to allow a webapp to use provided WebSocket client dependencies from the server.
|
||||
|
||||
Once you have enabled one of these modules for your Jetty base, it will apply to all webapps deployed to that base. If you want to be more selective about which webapps use Websocket, then you can:
|
||||
|
||||
Disable Websocket for a particular webapp:::
|
||||
You can disable jsr-356 for a particular webapp by setting the context attribute `org.eclipse.jetty.websocket.javax` to `false`.
|
||||
This will mean that websockets are not available to your webapp, however deployment time scanning for websocket-related classes such as endpoints will still occur.
|
||||
This can be a significant impost if your webapp contains a lot of classes and/or jar files.
|
||||
Completely disable Websocket for a particular webapp:::
|
||||
To completely disable websockets and avoid all setup costs associated with it for a particular webapp, use the context attribute `org.eclipse.jetty.containerInitializerExclusionPattern`.
|
||||
This allows you to exclude the websocket ServletContainerInitializer that causes the scanning.
|
||||
For example the `org.eclipse.jetty.containerInitializerExclusionPattern` context attribute can be set to `org.eclipse.jetty.websocket.javax.server.config.JavaxWebSocketServletContainerInitializer`.
|
||||
|
|
@ -1,7 +1,5 @@
|
|||
# DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html
|
||||
|
||||
[description]
|
||||
Enable both jetty and javax websocket modules for deployed web applications.
|
||||
Enable both websocket-javax and websocket-jetty modules for deployed web applications.
|
||||
|
||||
[tags]
|
||||
websocket
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
# DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html
|
||||
|
||||
[description]
|
||||
Enable javax.websocket for deployed web applications.
|
||||
Enable Java WebSocket APIs for deployed web applications.
|
||||
|
||||
[tags]
|
||||
websocket
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
# DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html
|
||||
|
||||
[description]
|
||||
Enable the Jetty WebSocket API for deployed web applications.
|
||||
Enable the Jetty WebSocket API support for deployed web applications.
|
||||
|
||||
[tags]
|
||||
websocket
|
||||
|
|
|
|||
Loading…
Reference in New Issue