//  ========================================================================
//  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.*");
----