| // ======================================================================== |
| // Copyright (c) 1995-2017 Mort Bay Consulting Pty. Ltd. |
| // ======================================================================== |
| // All rights reserved. This program and the accompanying materials |
| // are made available under the terms of the Eclipse Public License v1.0 |
| // and Apache License v2.0 which accompanies this distribution. |
| // |
| // The Eclipse Public License is available at |
| // http://www.eclipse.org/legal/epl-v10.html |
| // |
| // The Apache License v2.0 is available at |
| // http://www.opensource.org/licenses/apache2.0.php |
| // |
| // You may elect to redistribute this code under either of these licenses. |
| // ======================================================================== |
| |
| [[websocket-intro]] |
| == WebSocket Introduction |
| |
| WebSocket is a new protocol for bidirectional communications over HTTP. |
| |
| 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 does have a single frame limit of http://en.wikipedia.org/wiki/9223372036854775807[63-bits]) |
| |
| 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. |
| |
| [[ws-intro-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 http://autobahn.ws/testsuite[autobahn testsuite]. |
| |
| ____ |
| [IMPORTANT] |
| The early drafts of WebSocket were supported in Jetty 7 and Jetty 8, but this support has been removed in Jetty 9. |
| This means that Jetty 9 will 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. |
| |
| Unstable standards and specs: |
| |
| https://datatracker.ietf.org/doc/draft-ietf-hybi-websocket-perframe-compression/[perframe-compression]:: |
| Per Frame Compression Extension. |
| + |
| An early extension draft from the Google/Chromium team that would provide WebSocket frame compression. |
| + |
| perframe-compression using deflate algorithm is present on many versions of Chrome/Chromium. |
| + |
| Jetty's support for perframe-compression is based on the draft-04 spec. |
| + |
| This standard is being replaced with permessage-compression. |
| |
| https://datatracker.ietf.org/doc/draft-tyoshino-hybi-permessage-compression/[permessage-compression]:: |
| Per Frame Compression Extension. |
| + |
| This is the replacement for perframe-compression, switching the compression to being based on the entire message, not the individual frames. |
| |
| [[ws-intro-api]] |
| === WebSocket APIs |
| |
| 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. |
| Java WebSocket Client API:: |
| The new standard Java WebSocket Client API (`javax.websocket`) [JSR-356] |
| Java WebSocket Server API:: |
| The new standard Java WebSocket Server API (`javax.websocket.server`) [JSR-356] |
| |
| === Enabling WebSocket |
| |
| To enable websocket, you need to link:#enabling-modules[enable] the `websocket` link:#enabling-modules[module]. |
| |
| Once this module is enabled 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 jsr-356 for a particular webapp::: |
| You can disable jsr-356 for a particular webapp by setting the link:#context_attributes[context attribute] `org.eclipse.jetty.websocket.jsr356` 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. |
| To completely disable websockets and avoid all setup costs associated with it for a particular webapp, use instead the context attribute `org.eclipse.jetty.containerInitializerExclusionPattern`, described next, which allows you to exclude the websocket ServletContainerInitializer that causes the scanning. |
| Completely disable jsr-356 for a particular webapp::: |
| Set the `org.eclipse.jetty.containerInitializerExclusionPattern` link:#context_attributes[context attribute] to include `org.eclipse.jetty.websocket.jsr356.server.deploy.WebSocketServerContainerInitializer`. |
| Here's an example of doing this in code, although you can do the link:#intro-jetty-configuration-webapps[same in xml]: |
| + |
| [source, java, subs="{sub-order}"] |
| ---- |
| WebAppContext context = new WebAppContext(); |
| context.setAttribute("org.eclipse.jetty.containerInitializerExclusionPattern", |
| "org.eclipse.jetty.websocket.jsr356.server.deploy.WebSocketServerContainerInitializer|com.acme.*"); |
| ---- |