Java™ API for WebSocket

Version 1.1 Maintenance Release

August 5, 2014

Pavel Bucek
Comments to: [email protected]

Oracle Corporation
500 Oracle Parkway, Redwood Shores, CA 94065 USA.
ii Java Web Socket API August 5, 2014
JSR 356 Java™ API for WebSocket (“Specification”)
Version: 1.1
Status: Maintenance Release
Release: August 5, 2014
Copyright 2011-2014 Oracle America, Inc. (“Oracle”)
500 Oracle Parkway, Redwood Shores, California 94065, U.S.A
All rights reserved.

LIMITED LICENSE GRANTS

1. License for Evaluation Purposes. Specification Lead hereby grants you a fully-paid, non-exclusive,
non-transferable, worldwide, limited license (without the right to sublicense), under Specification Lead’s applicable
intellectual property rights to view, download, use and reproduce the Specification only for the purpose of internal
evaluation. This includes (i) developing applications intended to run on an implementation of the Specification,
provided that such applications do not themselves implement any portion(s) of the Specification, and (ii) discussing
the Specification with any third party; and (iii) excerpting brief portions of the Specification in oral or written
communications which discuss the Specification provided that such excerpts do not in the aggregate constitute a
significant portion of the Specification.
2. License for the Distribution of Compliant Implementations. Specification Lead also grants you a perpetual,
non-exclusive, non-transferable, worldwide, fully paid-up, royalty free, limited license (without the right to
sublicense) under any applicable copyrights or, subject to the provisions of subsection 4 below, patent rights it may
have covering the Specification to create and/or distribute an Independent Implementation of the Specification that:
(a) fully implements the Specification including all its required interfaces and functionality; (b) does not modify,
subset, superset or otherwise extend the Licensor Name Space, or include any public or protected packages, classes,
Java interfaces, fields or methods within the Licensor Name Space other than those required/authorized by the
Specification or Specifications being implemented; and (c) passes the Technology Compatibility Kit (including
satisfying the requirements of the applicable TCK Users Guide) for such Specification (”Compliant
Implementation”). In addition, the foregoing license is expressly conditioned on your not acting outside its scope. No
license is granted hereunder for any other purpose (including, for example, modifying the Specification, other than to
the extent of your fair use rights, or distributing the Specification to third parties). Also, no right, title, or interest in or
to any trademarks, service marks, or trade names of Specification Lead or Specification Lead’s licensors is granted
hereunder. Java, and Java-related logos, marks and names are trademarks or registered trademarks of Oracle
America, Inc. in the U.S. and other countries.
3. Pass-through Conditions. You need not include limitations (a)-(c) from the previous paragraph or any other
particular ”pass through” requirements in any license You grant concerning the use of your Independent
Implementation or products derived from it. However, except with respect to Independent Implementations (and
products derived from them) that satisfy limitations (a)-(c) from the previous paragraph, You may neither: (a) grant
or otherwise pass through to your licensees any licenses under Specification Lead’s applicable intellectual property
rights; nor (b) authorize your licensees to make any claims concerning their implementation’s compliance with the
Specification in question.
4. Reciprocity Concerning Patent Licenses.
a. With respect to any patent claims covered by the license granted under subparagraph 2 above that would be
infringed by all technically feasible implementations of the Specification, such license is conditioned upon your
offering on fair, reasonable and non-discriminatory terms, to any party seeking it from You, a perpetual,
non-exclusive, non-transferable, worldwide license under Your patent rights which are or would be infringed by all
technically feasible implementations of the Specification to develop, distribute and use a Compliant Implementation.
b. With respect to any patent claims owned by Specification Lead and covered by the license granted under
subparagraph 2, whether or not their infringement can be avoided in a technically feasible manner when
implementing the Specification, such license shall terminate with respect to such claims if You initiate a claim against
Specification Lead that it has, in the course of performing its responsibilities as the Specification Lead, induced any
other entity to infringe Your patent rights.
c. Also with respect to any patent claims owned by Specification Lead and covered by the license granted under
subparagraph 2 above, where the infringement of such claims can be avoided in a technically feasible manner when

August 5, 2014 Java Web Socket API iii

implementing the Specification such license, with respect to such claims, shall terminate if You initiate a claim
against Specification Lead that its making, having made, using, offering to sell, selling or importing a Compliant
Implementation infringes Your patent rights.
5. Definitions. For the purposes of this Agreement: ”Independent Implementation” shall mean an implementation of
the Specification that neither derives from any of Specification Lead’s source code or binary code materials nor,
except with an appropriate and separate license from Specification Lead, includes any of Specification Lead’s source
code or binary code materials; ”Licensor Name Space” shall mean the public class or interface declarations whose
names begin with ”java”, ”javax”, ”com.sun” and com.oracle or their equivalents in any subsequent naming
convention adopted by Oracle America, Inc. through the Java Community Process, or any recognized successors or
replacements thereof; and ”Technology Compatibility Kit” or ”TCK” shall mean the test suite and accompanying
TCK User’s Guide provided by Specification Lead which corresponds to the Specification and that was available
either (i) from Specification Lead’s 120 days before the first release of Your Independent Implementation that allows
its use for commercial purposes, or (ii) more recently than 120 days from such release but against which You elect to
test Your implementation of the Specification.
This Agreement will terminate immediately without notice from Specification Lead if you breach the Agreement or
act outside the scope of the licenses granted above.
DISCLAIMER OF WARRANTIES
THE SPECIFICATION IS PROVIDED ”AS IS”. SPECIFICATION LEAD MAKES NO REPRESENTATIONS OR
WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT (INCLUDING AS
A CONSEQUENCE OF ANY PRACTICE OR IMPLEMENTATION OF THE SPECIFICATION), OR THAT THE
CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE. This document does not represent
any commitment to release or implement any portion of the Specification in any product. In addition, the
Specification could include technical inaccuracies or typographical errors.
LIMITATION OF LIABILITY
TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SPECIFICATION LEAD OR ITS
LICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE,
PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE
DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF
OR RELATED IN ANY WAY TO YOUR HAVING, IMPLEMENTING OR OTHERWISE USING USING THE
SPECIFICATION, EVEN IF SPECIFICATION LEAD AND/OR ITS LICENSORS HAVE BEEN ADVISED OF
THE POSSIBILITY OF SUCH DAMAGES. You will indemnify, hold harmless, and defend Specification Lead and
its licensors from any claims arising or resulting from: (i) your use of the Specification; (ii) the use or distribution of
your Java application, applet and/or implementation; and/or (iii) any claims that later versions or releases of any
Specification furnished to you are incompatible with the Specification provided to you under this license.
RESTRICTED RIGHTS LEGEND
U.S. Government: If this Specification is being acquired by or on behalf of the U.S. Government or by a U.S.
Government prime contractor or subcontractor (at any tier), then the Government’s rights in the Software and
accompanying documentation shall be only as set forth in this license; this is in accordance with 48 C.F.R. 227.7201
through 227.7202-4 (for Department of Defense (DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for
non-DoD acquisitions).
REPORT
If you provide Specification Lead with any comments or suggestions concerning the Specification (”Feedback”), you
hereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential basis, and (ii) grant
Specification Lead a perpetual, non-exclusive, worldwide, fully paid-up, irrevocable license, with the right to
sublicense through multiple levels of sublicensees, to incorporate, disclose, and use without limitation the Feedback
for any purpose.
GENERAL TERMS
Any action related to this Agreement will be governed by California law and controlling U.S. federal law. The U.N.
Convention for the International Sale of Goods and the choice of law rules of any jurisdiction will not apply.

iv Java Web Socket API August 5, 2014

The Specification is subject to U.S. export control laws and may be subject to export or import regulations in other
countries. Licensee agrees to comply strictly with all such laws and regulations and acknowledges that it has the
responsibility to obtain such licenses to export, re-export or import as may be required after delivery to Licensee.
This Agreement is the parties’ entire agreement relating to its subject matter. It supersedes all prior or
contemporaneous oral or written communications, proposals, conditions, representations and warranties and prevails
over any conflicting or additional terms of any quote, order, acknowledgment, or other communication between the
parties relating to its subject matter during the term of this Agreement. No modification to this Agreement will be
binding, unless in writing and signed by an authorized representative of each party.

August 5, 2014 Java Web Socket API v

vi Java Web Socket API August 5, 2014
 Contents

1 Introduction 1
1.1 Purpose of this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Goals of the Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.3 Terminology used throughout the Specification . . . . . . . . . . . . . . . . . . . . . . . . 2
1.4 Specification Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.5 Expert Group Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.6 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Applications 5
2.1 API Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.1 Endpoint Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.2 Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1.3 Receiving Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1.4 Sending Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1.5 Closing Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.6 Clients and Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1.7 WebSocketContainers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2 Endpoints using WebSocket Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.1 Annotated Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.2 Websocket Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.3 Handling Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2.4 Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2.5 Pings and Pongs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3 Java WebSocket Client API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3 Configuration 11
3.1 Server Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

August 5, 2014 Java Web Socket API vii

 3.1.1 URI Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.1.2 Subprotocol Negotiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.1.3 Extension Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.1.4 Origin Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.1.5 Handshake Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.1.6 Custom State or Processing Across Server Endpoint Instances . . . . . . . . . . . . 13
3.1.7 Customizing Endpoint Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2 Client Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.2.1 Subprotocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.2.2 Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.2.3 Client Configuration Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

4 Annotations 15
4.1 @ServerEndpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.1.1 value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.1.2 encoders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.1.3 decoders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.1.4 subprotocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.1.5 configurator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2 @ClientEndpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2.1 encoders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2.2 decoders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2.3 configurator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2.4 subprotocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.3 @PathParam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.4 @OnOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.5 @OnClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.6 @OnError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.7 @OnMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.7.1 maxMessageSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.8 WebSockets and Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

5 Exception handling and Threading 23

5.1 Threading Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.2 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

viii Java Web Socket API August 5, 2014

 5.2.1 Deployment Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.2.2 Errors Originating in Websocket Application Code . . . . . . . . . . . . . . . . . . 24
5.2.3 Errors Originating in the Container and/or Underlying Connection . . . . . . . . . . 24

6 Packaging and Deployment 25

6.1 Client Deployment on JDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6.2 Application Deployment on Web Containers . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6.3 Application Deployment in Standalone Websocket Server Containers . . . . . . . . . . . . . 26
6.4 Programmatic Server Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
6.5 Websocket Server Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
6.6 Platform Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

7 Java EE Environment 29
7.1 Java EE Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
7.1.1 Websocket Endpoints and Dependency Injection . . . . . . . . . . . . . . . . . . . 29
7.2 Relationship with Http Session and Authenticated State . . . . . . . . . . . . . . . . . . . . 29

8 Server Security 31
8.1 Authentication of Websockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
8.2 Authorization of Websockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
8.3 Transport Guarantee . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
8.4 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

A Changes Since 1.0 Final Release 33

B Changes Since EDR 35

Bibliography 41

August 5, 2014 Java Web Socket API ix

x Java Web Socket API August 5, 2014
 Chapter 1

Introduction

This specification defines a set of Java APIs for the development of websocket applications. Readers are
assumed to be familiar with the WebSocket protocol. The WebSocket protocol, developed as part of the
collection of technologies that make up HTML5 promises to bring a new level of ease of development
and network efficiency to modern, interactive web applications. For more information on the WebSocket
protocol see:

• The WebSocket Protocol specification [1]

• The WebSocket API for JavaScript [2]

1.1 Purpose of this document

This document in combination with the API documentation for the Java WebSocket API is the specification
of the Java WebSocket API. The specification defines the requirements that an implementation must meet
in order to be an implementation of the Java WebSocket API. This specification has been developed under
the rules of the Java Community Process. Together with the Test Compatibility Kit (TCK) which tests that a
given implementation meets the requirements of the specification, and Reference Implementation (RI) that
implements this specification and which passes the TCK, this specification defines the Java standard for
WebSocket application development.
While there is much useful information in this document for developers using the Java WebSocket API, its
purpose is not to be a developers guide. Similarly, while there is much useful information in this document
for developers who are creating an implementation of the Java WebSocket API, its purpose is not to be a
How To guide as to how to implement all the required features.

1.2 Goals of the Specification

The goal of this specification is to define the requirements on containers that wish to support APIs for
websocket programming on the Java Platform. While the document may be a useful reference for developers
who use the APIs defined by this specification, this document is not a developer guide.

August 5, 2014 Java WebSocket API 1

Chapter 1. Introduction

1.3 Terminology used throughout the Specification

endpoint A websocket endpoint is a Java component that represents one side of a sequence of websocket
interactions between two connected peers.

connection A websocket connection is the networking connection between the two endpoints which are
interacting using the websocket protocol.

peer Used in the context of a websocket endpoint, the websocket peer is used to represent the another
participant of the websocket interactions with the endpoint.

session The term websocket session is used to represent a sequence of websocket interactions between an
endpoint and a single peer.

client endpoints and server endpoints A client endpoint is one that initiates a connection to a peer but
does not accept new ones. A server endpoint is one that accepts websocket connections from peers
but does not initiate connections to peers.

1.4 Specification Conventions

The keywords ‘MUST’, ‘MUST NOT’, ‘REQUIRED’, ‘SHALL’, ‘SHALL NOT’, ‘SHOULD’, ‘SHOULD
NOT’, ‘RECOMMENDED’, ‘MAY’, and ‘OPTIONAL’ in this document are to be interpreted as described
in RFC 2119 [3].
Additionally, requirements of the specification that can be tested using the conformance test suite are marked
with the figure WSC (WebSocket Compatibility) followed by a number which is used to identify the require-
ment, for example WSC-12.
Java code and sample data fragments are formatted as shown in figure 1.1:

Figure 1.1: Example Java Code

1 package com.example.hello;
2
3 public class Hello {
4 public static void main(String args[]) {
5 System.out.println("Hello World");
6 }
7 }

URIs of the general form ‘http://example.org/...’ and ‘http://example.com/...’ represent application or

context-dependent URIs.
All parts of this specification are normative, with the exception of examples, notes and sections explicitly
marked as ‘Non-Normative’. Non-normative notes are formatted as shown below.

Note: This is a note.

2 Java WebSocket API August 5, 2014

 1.5. Expert Group Members

1.5 Expert Group Members

This specification was developed in the Java Community Process as part of JSR 356 [4]. It is the result of
the collaborative work of the members of the JSR 356 expert group. The full public mail archive can be
found at [5]. The following are the expert group members:

− Jean-Francois Arcand (Individual Member)

− Greg Wilkins (Intalio)
− Scott Ferguson (Caucho Technology, Inc)
− Joe Walnes (DRW Holdings, LLC)
− Minehiko IIDA (Fujitsu Limited)
− Wenbo Zhu (Google Inc.)
− Bill Wigger (IBM)
− Justin Lee (Individual Member)
− Danny Coward (Oracle)
− Rmy Maucherat (RedHat)
− Moon Namkoong (TmaxSoft, Inc.)
− Mark Thomas (VMware)
− Wei Chen (Voxeo Corporation)
− Rossen Stoyanchev (VMware)

1.6 Acknowledgements

During the development of this specification we received many review comments, feedback and suggestions.
Thanks in particular to: Jitendra Kotamraju, Martin Matula, Štěpán Kopřiva, Dhiru Panday, Jondean Healey,
Joakim Erdfelt, Dianne Jiao, Michal Čonos and Jan Šupol.

August 5, 2014 Java WebSocket API 3

Chapter 1. Introduction

4 Java WebSocket API August 5, 2014

 Chapter 2

Applications

Java WebSocket applications consist of websocket endpoints. A websocket endpoint is a Java object that
represents one end of a websocket connection between two peers.
There are two main means by which an endpoint can be created. The first means is to implement certain of
the API classes from the Java WebSocket API with the required behavior to handle the endpoint lifecycle,
consume and send messages, publish itself, or connect to a peer. Often, this specification will refer to this
kind of endpoint as a programmatic endpoint. The second means is to decorate a Plain Old Java Object
(POJO) with certain of the annotations from the Java WebSocket API. The implementation then takes these
annotated classes and creates the appropriate objects at runtime to deploy the POJO as a websocket endpoint.
Often, this specification will refer to this kind of endpoint as an annotated endpoint. The specification will
refer to an endpoint when it is talking about either kind of endpoint: programmatic or annotated.
The endpoint participates in the opening handshake that establishes the websocket connection. The endpoint
will typically send and receive a variety of websocket messages. The endpoints lifecycle comes to an end
when the websocket connection is closed.

2.1 API Overview

This section gives a brief overview of the Java WebSocket API in order to set the stage for the detailed
requirements that follow.

2.1.1 Endpoint Lifecycle

A logical websocket endpoint is represented in the Java WebSocket API by instances of the Endpoint class.
Developers may subclass the Endpoint class with a public, concrete class in order to intercept lifecycle
events of the endpoint: those of a peer connecting, an open connection ending and an error being raised
during the lifetime of the endpoint.
Unless otherwise overridden by a developer provided configurator (see 3.1.7), the websocket implementation
must use one instance per application per VM of the Endpoint class to represent the logical endpoint
per connected peer. [WSC 2.1.1-1] Each instance of the Endpoint class in this typical case only handles
connections to the endpoint from one and only one peer.

August 5, 2014 Java WebSocket API 5

Chapter 2. Applications

2.1.2 Sessions

The Java WebSocket API models the sequence of interactions between an endpoint and each of its peers
using an instance of the Session class. The interactions between a peer and an endpoint begin with an open
notification, followed by some number, possibly zero, of websocket messages between the endpoint and
peer, followed by a close notification or possibly a fatal error which terminates the connection. For each
peer that is interacting with an endpoint, there is one unique Session instance that represents that interaction.
[WSC 2.1.2-1] This Session instance corresponding to the connection with that peer is passed to the endpoint
instance representing the logical endpoint at the key events in its lifecycle.
Developers may use the user property map accessible through the getUserProperties() call on the Session
object to associate application specific information with a particular session. The websocket implementa-
tion must preserve this session data for later access until the completion of the onClose() method on the
endpoint instance. [WSC 2.1.2-2]. After that time, the websocket implementation is permitted to discard
the developer data. A websocket implementation that chooses to pool Session instances may at that point
re-use the same Session instance to represent a new connection provided it issues a new unique Session id.
[WSC 2.1.2-3]
Websocket implementations that are part of a distributed container may need to migrate websocket sessions
from one node to another in the case of a failover. Implementations are required to preserve developer data
objects inserted into the websocket session if the data is marked java.io.Serializable. [WSC 2.1.2-4]

2.1.3 Receiving Messages

The Java WebSocket API presents a variety of means for an endpoint to receive messages from its peers.
Developers implement the subtype of the MessageHandler interface that suits the message delivery style
that best suits their needs, and register the interest in messages from a particular peer by registering the
handler on the Session instance corresponding to the peer.
The API limits the registration of MessageHandlers per Session to be one MessageHandler per native
websocket message type. [WSC 2.1.3-1] In other words, the developer can only register at most one Mes-
sageHandler for incoming text messages, one MessageHandler for incoming binary messages, and one
MessageHandler for incoming pong messages. The websocket implementation must generate an error if
this restriction is violated [WSC 2.1.3-2].
Future versions of the specification may lift this restriction.
Method Session.addMessageHandler(MessageHandler) is not safe for use in all circumstances, especially
when using Lambda Expressions. The API forces implementations to get the MessageHandler’s type pa-
rameter in runtime, which is not always possible. The only case where you can safely use this method
is when you are directly implementing MessageHandler.Whole or MessageHandler.Partial as an anony-
mous class. This approach guarantees that generic type information will be present in the generated class
file and the runtime will be able to get it. For any other case (Lambda Expressions included), one of follow-
ing methods have to be used: Session.addMessageHandler(Class<T>, MessageHandler.Partial<T>)
or Session.addMessageHandler(Class<T>, MessageHandler.Whole<T>).

2.1.4 Sending Messages

The Java WebSocket API models each peer of a session with an endpoint as an instance of the Remo-
teEndpoint interface. This interface and its two subtypes (RemoteEndpoint.Whole and RemoteEnd-
point.Partial) contain a variety of methods for sending websocket messages from the endpoint to its peer.

6 Java WebSocket API August 5, 2014

 2.1. API Overview

Example
Here is an example of a server endpoint that waits for incoming text messages, and responds immediately
when it gets one to the client that sent it. The example endpoint is shown, first using only the API classes:

1 public class HelloServer extends Endpoint {

2 @Override
3 public void onOpen(Session session, EndpointConfig ec) {
4 final RemoteEndpoint.Basic remote = session.getBasicRemote();
5 session.addMessageHandler(String.class,
6 new MessageHandler.Whole<String>() {
7 public void onMessage(String text) {
8 try {
9 remote.sendText("Got your message (" + text + "). Thanks !");
10 } catch (IOException ioe) {
11 ioe.printStackTrace();
12 }
13 }
14 });
15 }
16 }

and second using the annotations in the API:

1 @ServerEndpoint("/hello")
2 public class MyHelloServer {
3 @OnMessage
4 public String handleMessage(String message) {
5 return "Got your message (" + message + "). Thanks !";
6 }
7 }

Note: the examples are almost equivalent save for the annotated endpoint carries its own path mapping.

2.1.5 Closing Connections

If an open connection to a websocket endpoint is to be closed for any reason, whether as a result of receiving
a websocket close event from the peer, or because the underlying implementation has reason to close the
connection, the websocket implementation must invoke the onClose() method of the websocket endpoint.
[WSC 2.1.5-1]
If the close was initiated by the remote peer, the implementation must use the close code and reason sent in
the websocket protocol close frame. If the close was initiated by the local container, for example if the local
container determines the session has timed out, the local implementation must use the websocket protocol
close code 1006 (a code especially disallowed in close frames on the wire), with a suitable close reason.
That way the endpoint can determine whether the close was initiated remotely or locally. If the session
is closed locally, the implementation must attempt to send the websocket close frame prior to calling the
onClose() method of the websocket endpoint.

August 5, 2014 Java WebSocket API 7

Chapter 2. Applications

2.1.6 Clients and Servers

The websocket protocol is a two-way protocol. Once established, the websocket protocol is symmetrical
between the two parties in the conversation. The difference between a websocket client and a websocket
server lies only in the means by which the two parties are connected. In this specification, we will say that a
websocket client is a websocket endpoint that initiates a connection to a peer. We will say that a websocket
server is a websocket endpoint that is published and awaits connections from peers. In most deployments, a
websocket client will connect to only one websocket server, and a websocket server will accept connections
from several clients.
Accordingly, the WebSocket API only distinguishes between endpoints that are websocket clients from
endpoints that are websocket servers in the configuration and setup phase.

2.1.7 WebSocketContainers

The websocket implementation is represented to applications by instances of the WebSocketContainer

class. Each WebSocketContainer instance carries a number of configuration properties that apply to end-
points deployed within it. In server deployments of websocket implementations, there is one unique Web-
SocketContainer instance per application per Java VM. [WSC 2.1.7-1] In client deployments of websocket
implementations, applications obtain instances of the WebSocketContainer from the ContainerProvider
class.

2.2 Endpoints using WebSocket Annotations

Java annotations have become widely used as a means to add deployment characteristics to Java objects,
particularly in the Java EE platform. The Java WebSocket specification defines a small number of websocket
annotations that allow developers to take Java classes and turn them into websocket endpoints. This section
gives a short overview to set the stage for more detailed requirements later in this specification.

2.2.1 Annotated Endpoints

The class level @ServerEndpoint annotation indicates that a Java class is to become a websocket endpoint
at runtime. Developers may use the value attribute to specify a URI mapping for the endpoint. The encoders
and decoders attributes allow the developer to specify classes that encode application objects into websocket
messages, and decode websocket messages into application objects.

2.2.2 Websocket Lifecycle

The method level @OnOpen and @OnClose annotations allow the developers to decorate methods on their
@ServerEndpoint annotated Java class to specify that they must be called by the implementation when
the resulting endpoint receives a new connection from a peer or when a connection from a peer is closed,
respectively. [WSC 2.2.2-1]

8 Java WebSocket API August 5, 2014

 2.3. Java WebSocket Client API

2.2.3 Handling Messages

In order that the annotated endpoint can process incoming messages, the method level @OnMessage an-
notation allows the developer to indicate which methods the implementation must call when a message is
received. [WSC 2.2.3-1]

2.2.4 Handling Errors

In order that an annotated endpoint can handle errors that occur as a arising from external events, for example
on decoding an incoming message, an annotated endpoint can use the @OnError annotation to mark one of
its methods must be called by the implementation with information about the error whenever such an error
occurs. [WSC 2.2.4-1]

2.2.5 Pings and Pongs

The ping/pong mechanism in the websocket protocol serves as a check that the connection is still active.
Following the requirements of the protocol, if a websocket implementation receives a ping message from
a peer, it must respond as soon as possible to that peer with a pong message containing the same appli-
cation data. [WSC 2.2.5-1] Developers who wish to send a unidirectional pong message may do so using
the RemoteEndpoint API. Developers wishing to listen for returning pong messages may either define a
MessageHandler for them, or annotate a method using the @OnMessage annotation where the method
stipulates a PongMessage as its message entity parameter. In either case, if the implementation receives
a pong message addressed to this endpoint, it must call that MessageHandler or that annotated message.
[WSC 2.2.5-2]

2.3 Java WebSocket Client API

This specification defines two configurations of the Java WebSocket API. The Java WebSocket API is used
to mean the full functionality defined in this specification. This API is intended to be implemented either
as a standalone websocket implementation, as part of a Java servlet container, or as part of a full Java EE
platform implementation. The APIs that must be implemented to conform to the Java WebSocket API are
all the Java apis in the packages javax.websocket.* and javax.websocket.server.*. Some of the non-api
features of the Java WebSocket API are optional when the API is not implemented as part of the full Java
EE platform, for example, the requirement that websocket endpoints be non-contextual managed beans (see
Chapter 7). Such Java EE only features are clearly marked where they are described.
The Java WebSocket API also contains a subset of its functionality intended for desktop, tablet or smart-
phone devices. This subset does not contain the ability to deploy server endpoints. This subset known as the
Java WebSocket Client API. The APIs that must be implemented to conform to the Java WebSocket Client
API are all the Java apis in the packages javax.websocket.*.

August 5, 2014 Java WebSocket API 9

Chapter 2. Applications

10 Java WebSocket API August 5, 2014

 Chapter 3

Configuration

WebSocket applications are configured with a number of key parameters: the path mapping that identifies
a websocket endpoint in the URI-space of the container, the subprotocols that the endpoint supports, the
extensions that the application requires. Additionally, during the opening handshake, the application may
choose to perform other configuration tasks, such as checking the hostname of the requesting client, or
processing cookies. This section details the requirements on the container to support these configuration
tasks.
Both client and server endpoint configurations include a list of application provided encoder and decoder
classes that the implementation must use to translate between websocket messages and application defined
message objects. [WSC-3-1]
Here follows the definition of the server-specific and client-specific configuration options.

3.1 Server Configurations

In order to deploy a programmatic endpoint into the URI space available for client connections, the con-
tainer requires a ServerEndpointConfig instance. This object holds configuration data and the default im-
plementation provided algorithms needed by the implementation to configure the endpoint. The WebSocket
API allow certain of these configuration operations to be overriden by developers by providing a custom
ServerEndpointConfig.Configurator implementation with the ServerEndpointConfig. [WSC-3.1-1]
These operations are laid out below.

3.1.1 URI Mapping

This section describes the the URI mapping policy for server endpoints. The websocket implementation
must compare the incoming URI to the collection of all endpoint paths and determine the best match. The
incoming URI in an opening handshake request matches an enpoint path if either it is an exact match in the
case where the endpoint path is a relative URI, and if it is a valid expansion of the endpoint path in the case
where the endpoint path is a URI template. [WSC-3.1.1-1]
An application that contains multiple endpoint paths that are the same relative URI is not a valid applica-
tion. An application that contains multiple endpoint paths that are equivalent URI-templates is not a valid
application. [WSC-3.1.1-2]
However, it is possible for an incoming URI in an opening handshake request theoretically to match more

August 5, 2014 Java WebSocket API 11

Chapter 3. Configuration

than one endpoint path. For example, consider the following case:-
incoming URI: ”/a/b”
endpoint A is mapped to ”/a/b”
endpoint B is mapped to /a/{customer-name}
The websocket implementation will attempt to match an incoming URI to an endpoint path (URI or level 1
URI-template) in the application in a manner equivalent to the following: [WSC-3.1.1-3]
Since the endpoint paths are either relative URIs or URI templates level 1, the paths do not match if they do
not have the same number of segments, using ’/’ as the separator. So, the container will traverse the segments
of the endpoint paths with the same number of segments as the incoming URI from left to right, comparing
each segment with the corresponding segment of the incoming URI. At each segment, the implementation
will retain those endpoint paths that match exactly, or if there are none, those that are a variable segment,
before moving to check the next segment. If there is an endpoint path at the end of this process there is a
match.
Because of the requirement disallowing multiple endpoint paths and equivalent URI-templates, and the
preference for exact matches at each segment, there can only be at most one path, and it is the best match.
Examples
i) suppose an endpoint has path /a/b/, the only incoming URI that matches this is /a/b/
ii) suppose an endpoint is mapped to /a/{var}
incoming URIs that do match: /a/b (with var=b), /a/apple (with var=apple)
URIs that do NOT match: /a, /a/b/c (because empty string and strings with reserved characters ”/” are not
valid URI-template level 1 expansions.)
iii) suppose we have three endpoints and their paths:
endpoint A: /a/{var}/c
endpoint B: /a/b/c
endpoint C: /a/{var1}/{var2}
incoming URI: a/b/c matches B, not A or C, because an exact match is preferred.
incoming URI: a/d/c matches A with variable var=d, because an exact matching segment is preferred over a
variable segment
incoming URI: a/x/y/ matches C, with var1=x, var2=y
iv) suppose we have two endpoints
endpoint A: /{var1}/d
endpoint B: /b/{var2}
incoming URI: /b/d matches B with var2=d, not A with var1=b because the matching process works from
left to right.
The implementation must not establish the connection unless there is a match. [WSC-3.1.1-4]

12 Java WebSocket API August 5, 2014

 3.1. Server Configurations

3.1.2 Subprotocol Negotiation

The default server configuration must be provided a list of supported protocols in order of preference at
creation time. During subprotocol negotiation, this configuration examines the client-supplied subprotocol
list and selects the first subprotocol in the list it supports that is contained within the list provided by the
client, or none if there is no match. [WSC-3.1.2-1]

3.1.3 Extension Modification

In the opening handshake, the client supplies a list of extensions that it would like to use. The default
server configuration selects from those extensions the ones it supports, and places them in the same order as
requested by the client. [WSC-3.1.3-1]

3.1.4 Origin Check

The default server configuration makes a check of the hostname provided in the Origin header, failing the
handshake if the hostname cannot be verified. [WSC-3.1.4-1]

3.1.5 Handshake Modification

The default server configuration makes no modification of the opening handshake process other than that
described above. [WSC-3.1.5-1]
Developers may wish to customize the configuration and handshake negotiation policies laid out above. In
order to do so, they may provide their own implementations of ServerEndpointConfig.Configurator.
For example, developers may wish to intervene more in the handshake process. They may wish to use Http
cookies to track clients, or insert application specific headers in the handshake response. In order to do
this, they may implement the modifyHandshake() method on the ServerEndpointConfig.Configurator,
wherein they have full access to the HandshakeRequest and HandshakeResponse of the handshake.

3.1.6 Custom State or Processing Across Server Endpoint Instances

The developer may also implement ServerEndpointConfig.Configurator in order to hold custom applica-
tion state or methods for other kinds of application specific processing that is accessible from all Endpoint
instances of the same logical endpoint via the EndpointConfig object.

3.1.7 Customizing Endpoint Creation

The developer may control the creation of endpoint instances by supplying a ServerEndpointConfig.Configurator
object that overrides the getEndpointInstance() call. The implementation must call this method each time
a new client connects to the logical endpoint. [WSC-3.1.7-1] The platform default implementation of this
method is to return a new instance of the endpoint class each time it is called. [WSC-3.1.7-2]
In this way, developers may deploy endpoints in such a way that only one instance of the endpoint class is
instantiated for all the client connections to the logical endpoints. In this case, developers are cautioned that
such a singleton instance of the endpoint class will have to program with concurrent calling threads in mind,
for example, if two different clients send a message at the same time.

August 5, 2014 Java WebSocket API 13

Chapter 3. Configuration

3.2 Client Configuration

In order to connect a websocket client endpoint to its corresponding websocket server endpoint, the im-
plementation requires configuration information. Aside from the list of encoders and decoders, the Java
WebSocket API needs the following attributes:

3.2.1 Subprotocols

The default client configuration uses the developer provided list of subprotocols, to send in order of pref-
erence, the names of the subprotocols it would like to use in the opening handshake it formulates. [WSC-
3.2.1-1]

3.2.2 Extensions

The default client configuration must use the developer provided list of extensions to send, in order of prefer-
ence, the extensions, including parameters, that it would like to use in the opening handshake it formulates.
[WSC-3.2.2-1]

3.2.3 Client Configuration Modification

Some clients may wish to adapt the way in which the client side formulates the opening handshake interac-
tion with the server. Developers may provide their own implementations of ClientEndpointConfig.Configurator
which override the default behavior of the underlying implementation in order to customize it to suit a par-
ticular applications needs.

14 Java WebSocket API August 5, 2014

 Chapter 4

Annotations

This section contains a full specification of the semantics of the annotations in the Java WebSocket API.

4.1 @ServerEndpoint

This class level annotation signifies that the Java class it decorates must be deployed by the implementation
as a websocket server endpoint and made available in the URI-space of the websocket implementation.
[WSC-4.1-1] The class must be public, concrete, and have a public no-args constructor. The class may or
may not be final, and may or may not have final methods.

4.1.1 value

The value attribute must be a Java string that is a partial URI or URI-template (level-1), with a leading
‘/’. For a definition of URI-templates, see [6]. The implementation uses the value attribute to deploy the
endpoint to the URI space of the websocket implementation. The implementation must treat the value as
relative to the root URI of the websocket implementation in determining a match against the request URI of
an incoming opening handshake request. [WSC-4.1.1-2] The semantics of matching for annotated endpoints
is the same as was defined in the previous chapter. The value attribute is mandatory; the implementation
must reject a missing or malformed path at deployment time [WSC-4.1.1-3].
For example,

1 @ServerEndpoint("/bookings/{guest-id}")
2 public class BookingServer {
3
4 @OnMessage
5 public void processBookingRequest(
6 @PathParam("guest-id") String guestID,
7 String message,
8 Session session) {
9 // process booking from the given guest here
10 }
11 }

In this case, a client will be able to connect to this endpoint with any of the URIs

August 5, 2014 Java WebSocket API 15

Chapter 4. Annotations

• /bookings/JohnSmith

• /bookings/SallyBrown

• /bookings/MadisonWatson

However, were the endpoint annotation to be @ServerEndpoint(”/bookings/SallyBrown”), then only a

client request to /bookings/SallyBrown would be able to connect to this websocket endpoint.
If URI-templates are used in the value attribute, the developer may retrieve the variable path segments using
the @PathParam annotation, as described below.
Applications that contain more than one annotated endpoint may inadvertently use the same relative URI.
The websocket implementation must reject such an application at deployment time with an informative error
message that there is a duplicate path that it cannot resolve. [WSC-4.1.1-4]
Applications may contain an endpoint mapped to a path that is an expanded form of a URI template that is
used by another endpoint in the same application. In this case, the application is valid. Please refer to the
previous chapter for a definition of how to resolve the best match in this type of situation.
Future versions of the specification may allow higher levels of URI-templates.

4.1.2 encoders

The encoders attribute contains a (possibly empty) list of Java classes that are to act as encoder components
for this endpoint. These classes must implement some form of the Encoder interface, and have public no-
arg constructors and be visible within the classpath of the application that this websocket endpoint is part
of. The implementation must create a new instance of each encoder per connection per endpoint which
guarantees no two threads are in the encoder at the same time. The implementation must attempt to encode
application objects of matching parametrized type as the encoder when they are attempted to be sent using
the RemoteEndpoint API [WSC-4.1.2-1].

4.1.3 decoders

The decoders attribute contains a (possibly empty) list of Java classes that are to act as decoder components
for this endpoint. These classes must implement some form of the Decoder interface, and have public
no-arg constructors and be visible within the classpath of the application that this websocket endpoint is
part of. The implementation must create a new instance of each encoder per connection per endpoint. The
implementation must attempt to decode websocket messages using the decoder in the list appropriate to the
native websocket message type and pass the message in decoded object form to the websocket endpoint
[WSC-4.1.3-1]. On Decoder implementations that have it, the implementation must use the willDecode()
method on the decoder to determine if the Decoder will match the incoming message [WSC-4.1.3-2]

4.1.4 subprotocols

The subprotocols parameter contains a (possibly empty) list of string names of the sub protocols that this
endpoint supports. The implementation must use this list in the opening handshake to negotiate the desired
subprotocol to use for the connection it establishes [WSC-4.1.4-1].

16 Java WebSocket API August 5, 2014

 4.2. @ClientEndpoint

4.1.5 configurator

The optional configurator attribute allows the developer to indicate that he would like the websocket imple-
mentation to use a developer provided implementation of ServerEndpointConfig.Configurator. If one is
supplied, the websocket implementation must use this when configuring the endpoint. [WSC-4.1.5-1] The
developer may use this technique to share state across all instances of the endpoint in addition to customizing
the opening handshake.

4.2 @ClientEndpoint

This class level annotation signifies that the Java class it decorates is to be deployed as a websocket client
endpoint that will connect to a websocket endpoint residing on a websocket server. The class must have a
public no-args constructor, and additionally may conform to one of the types listed in Chapter 7.

4.2.1 encoders

The encoders parameter contains a (possibly empty) list of Java classes that are to act as encoder components
for this endpoint. These classes must implement some form of the Encoder interface, and have public no-
arg constructors and be visible within the classpath of the application that this websocket endpoint is part
of. The implementation must create a new instance of each encoder per connection per endpoint which
guarantees no two threads are in the encoder at the same time. The implementation must attempt to encode
application objects of matching parametrized type as the encoder when they are attempted to be sent using
the RemoteEndpoint API [WSC-4.2.1-1].

4.2.2 decoders

The decoders parameter contains a (possibly empty) list of Java classes that are to act as decoder components
for this endpoint. These classes must implement some form of the Decoder interface, and have public no-
arg constructors and be visible within the classpath of the application that this websocket endpoint is part
of. The implementation must create a new instance of each encoder per connection per endpoint. The
implementation must attempt to decode websocket messages using the first appropriate decoder in the list
and pass the message in decoded object form to the websocket endpoint [WSC-4.2.2-1]. If the Decoder
implementation has the method, the implementation must use the willDecode() method on the decoder to
determine if the Decoder will match the incoming message [WSC-4.2.2-2]

4.2.3 configurator

The optional configurator attribute allows the developer to indicate that he would like the websocket im-
plementation to use a developer provided implementation of ClientEndpointConfig.Configurator. If one
is supplied, the websocket implementation must use this when configuring the endpoint. [4.2.3-1] The de-
veloper may use this technique to share state across all instances of the endpoint in addition to customizing
the opening handshake.

August 5, 2014 Java WebSocket API 17

 Chapter 4. Annotations

4.2.4 subprotocols

The subprotocols parameter contains a (possibly empty) list of string names of the sub protocols that this
endpoint is willing to support. The implementation must use this list in the opening handshake to negotiate
the desired subprotocol to use for the connection it establishes [WSC-4.2.4-1].

4.3 @PathParam

This annotation is used to annotate one or more parameters of methods on an annotated endpoint class
decorated with any of the annotations @OnMessage, @OnError, @OnOpen, @OnClose. The allowed
types for these parameters are String, any Java primitive type, or boxed version thereof. Any other type
annotated with this annotation is an error that the implementation must report at deployment time. [WSC-
4.3-1] The value attribute of this annotation must be present otherwise the implementation must throw an
error. [WSC-4.3-2] If the value attribute of this annotation matches the variable name of an element of
the URI-template used in the @ServerEndpoint annotation that annotates this annotated endpoint, then the
implementation must associate the value of the parameter it annotates with the value of the path segment
of the request URI to which the calling websocket frame is connected when the method is called. [WSC-
4.3-3] Otherwise, the value of the String parameter annotated by this annotation must be set to null by the
implementation. The association must follow these rules:
if the parameter is a String, the container must use the value of the path segment [WSC-4.3-4]
if the parameter is a Java primitive type or boxed version thereof, the container must use the path segment
string to construct the type with the same result as if it had used the public one argument String constructor
to obtain the boxed type, and reduced to its primitive type if necessary. [WSC-4.3-5]
If the container cannot decode the path segment appropriately to the annotated path parameter, then the
container must raise an DecodeException to the error handling method of the websocket containing the
path segment. [WSC-4.3-6]
For example,

1 @ServerEndpoint("/bookings/{guest-id}")
2 public class BookingServer {
3
4 @OnMessage
5 public void processBookingRequest(
6 @PathParam("guest-id") String guestID,
7 String message,
8 Session session) {
9 // process booking from the given guest here
10 }
11 }

In this example, if a client connects to this endpoint with the URI /bookings/JohnSmith, then the value of
the guestID parameter will be ”JohnSmith”.
Here is an example where the path parameter is an Integer:

1 @ServerEndpoint("/rewards/{vip-level}")
2 public class RewardServer {
3 @OnMessage

18 Java WebSocket API August 5, 2014

 4.4. @OnOpen

4 public void processReward(

5 @PathParam("vip-level") Integer vipLevel,
6 String message, Session session) {
7 // process reward here
8 }
9 }

4.4 @OnOpen

This annotation may be used on certain methods of a Java class annotated with @ServerEndpoint or
@ClientEndpoint. The annotation defines that the decorated method be called whenever a new client
has connected to this endpoint. The container notifies the method after the connection has been established
[WSC-4.4-1]. The decorated method can only have an optional Session parameter, an optional Endpoint-
Config parameter and zero to n String parameters annotated with a @PathParam annotation as parameters.
If the Session parameter is present, the implementation must pass in the newly created Session correspond-
ing to the new connection [WSC-4.4-2]. Any Java class using this annotation on a method that does not
follow these rules, or that uses this annotation on more than one method may not be deployed by the imple-
mentation and the error reported to the deployer. [WSC-4.4-3]

4.5 @OnClose

This annotation may be used on certain methods of a Java class annotated with @ServerEndpoint or
@ClientEndpoint. The annotation defines that the decorated method be called whenever a remote peer
is about to be disconnected from this endpoint, whether that process is initiated by the remote peer, by
the local container or by a call to session.close(). The container notifies the method before the connection
is brought down [WSC-4.5-1]. The decorated method can only have optional Session parameter, optional
CloseReason parameter and zero to n String parameters annotated with a @PathParam annotation as pa-
rameters. If the Session parameter is present, the implementation must pass in the about-to-be ended Session
corresponding to the connection [WSC-4.5-2]. If the method itself throws an error, the implementation must
pass this error to the onError() method of the endpoint together with the session [WSC-4.5-3].
Any Java class using this annotation on a method that does not follow these rules, or that uses this annotation
on more than one method may not be deployed by the implementation and the error reported to the deployer.
[WSC-4.5-4]

4.6 @OnError

This annotation may be used on certain methods of a Java class annotated with @ServerEndpoint or
@ClientEndpoint. The annotation defines that the decorated method be called whenever an error is gen-
erated on any of the connections to this endpoint. The decorated method can only have optional Session
parameter, mandatory Throwable parameter and zero to n String parameters annotated with a @Path-
Param annotation as parameters. If the Session parameter is present, the implementation must pass in the
Session in which the error occurred to the connection [WSC-4.6-1]. The container must pass the error as
the Throwable parameter to this method [WSC-4.6-2].
Any Java class using this annotation on a method that does not follow these rules, or that uses this annotation
on more than one method may not be deployed by the implementation and the error reported to the deployer.

August 5, 2014 Java WebSocket API 19

Chapter 4. Annotations

[WSC-4.6-3]

4.7 @OnMessage

This annotation may be used on certain methods of a Java class annotated with @ServerEndpoint or
@ClientEndpoint. The annotation defines that the decorated method be called whenever an incoming
message is received. The method it decorates may have a number of forms for handling text, binary or pong
messages, and for sending a message back immediately that are defined in detail in the api documentation
for @OnMessage.
Any method annotated with @OnMessage that does not conform to the forms defied therein is invalid. The
websocket implementation must not deploy such an endpoint and must raise a deployment error if an attempt
is made to deploy such an annotated endpoint. [WSC-4.7-1]
If the method uses a class equivalent of a Java primitive as a method parameter to handle whole text mes-
sages, the implementation must use the single String parameter constructor to attempt construct the object.
If the method uses a Java primitive as a method parameter to handle whole text messages, the implemen-
tation must attempt to construct its class equivalent as described above, and then convert it to its primitive
value. [WSC-4.7-2]
If the method uses a Java primitive as a return value, the implementation must construct the text message to
send using the standard Java string representation of the Java primitive. If the method uses a class equivalent
of a Java primitive as a return value, the implementation must construct the text message from the Java
primitive equivalent as just described. [WSC-4.7-3]
Each websocket endpoint may only have one message handling method for each of the native websocket
message formats: text, binary and pong. The websocket implementation must not deploy such an endpoint
and must raise a deployment error if an attempt is made to deploy such an annotated endpoint. [WSC-4.7-4]

4.7.1 maxMessageSize

The maxMessageSize attribute allows the developer to specify the maximum size of message in bytes that
the method it annotates will be able to process, or −1 to indicate that there is no maximum. The default is
−1.
If an incoming message exceeds the maximum message size, the implementation must formally close the
connection with a close code of 1009 (Too Big). [WSC-4.7.1-1]

4.8 WebSockets and Inheritance

The websocket annotation behaviors defined by this specification are not passed down the Java class inher-
itance hierarchy. They apply only to the Java class on which they are marked. For example, a Java class
that inherits from a Java class annotated with class level WebSocket annotations does not itself become an
annotated endpoint, unless it itself is annotated with a class level WebSocket annotation. Similarly, sub-
classes of an annotated endpoint may not use method level websocket annotations unless they themselves
use a class level websocket annotation. Subclasses that override methods annotated with websocket method
annotations do not obtain websocket callbacks unless those subclass methods themselves are marked with a
method level websocket annotation.

20 Java WebSocket API August 5, 2014

 4.8. WebSockets and Inheritance

Implementations should not deploy Java classes that mistakenly mix Java inheritance with websocket anno-
tations in these ways. [WSC-4.8.1]
Implementations that use archive scanning techniques to deploy endpoints on startup must filter out sub-
classes of annotated endpoints, in addition to other errent endpoint definitions such as annotated classes that
are non-public when they build the list of annotated endpoints to deploy. [WSC-4.8.2]

August 5, 2014 Java WebSocket API 21

Chapter 4. Annotations

22 Java WebSocket API August 5, 2014

 Chapter 5

Exception handling and Threading

5.1 Threading Considerations

Implementations of the WebSocket API may employ a variety of threading strategies in order to provide a
scalable implementation. The specification aims to allow a range of strategies. However, the implemen-
tation must fulfill certain threading requirements in order to provide the developer a consistent threading
environment for their applications.
Unless backed by a Java EE component with a different lifecycle (See Chapter 7), the container must use a
unique instance of the endpoint per peer. [WSC-5.1-1] In all cases, the implementation must not invoke an
endpoint instance with more than one thread per peer at a time. [WSC-5.1-2] The implementation may not
invoke the close method on an endpoint until after the open method has completed. [WSC-5.1-3]
This guarantees that a websocket endpoint instance is never called by more than one container thread at a
time per peer. [WSC-5.1-4]
If the implementation decides to process an incoming message in parts, it must ensure that the corresponding
onMessage() calls are called sequentially, and do not interleave either with parts of the same message or
with other messages [WSC-5.1.5].

5.2 Error Handling

There are three categories of errors (checked and unchecked Java exceptions) that this specification defines.

5.2.1 Deployment Errors

These are errors raised during the deployment of an application containing websocket endpoints. Some
of these errors arise as the result of a container malfunction during the deployment of the application. For
example, the container may not have sufficient computing resources to deploy the application as specified. In
this case, the container must provide an informative error message to the developer during the deployment
process. [WSC-5.2.1-1] Other errors arise as a result of a malformed websocket application. Chapter 4
provides several examples of websocket endpoints that are malformed. In such cases, the container must
provide an informative error message to the deployer during the deployment process. [WSC-5.2.1-2]
In both cases, a deployment error raised during the deployment process must halt the deployment of the
application, any well formed endpoints deployed prior to the error being raised must be removed from

August 5, 2014 Java WebSocket API 23

Chapter 5. Exception handling and Threading

service and no more websocket endpoints from that application may be deployed by the container, even if
they are valid. [WSC-5.2.1-3]
If the deployment error occurs under the programmatic control of the developer, for example, when using the
WebSocketContainer API to deploy a client endpoint, deployment errors must be reported by the container
to the developer by using an instance of the DeploymentException. [WSC-5.2.1-4] Containers may choose
the precise wording of the error message in such cases.
If the deployment error occurs while deployment is managed by the implementation, for example, as a result
of deploying a WAR file where the endpoints are deployed by the container as a result of scanning the WAR
file, the deployment error must be reported to the deployer by the implementation as part of the container
specific deployment process. [WSC-5.2.1-5]

5.2.2 Errors Originating in Websocket Application Code

All errors arising during the functioning of a websocket endpoint must be caught by the websocket imple-
mentation. [WSC-5.2.2-1] Examples of these errors include checked exceptions generated by Decoders
used by the endpoint, runtime errors generated in the message handling code used by the endpoint. If the
websocket endpoint has provided an error handling method, either by implementing the onError() method
in the case of programmatic endpoints, or by using the @OnError annotation in the case of annotated end-
points, the implementation must invoke the error handling method with the error. [WSC-5.2.2-2]
If the developer has not provided an error handling method on an endpoint that is generating errors, this
indicates to the implementation that the developer does not wish to handle such errors. In these cases, the
container must make this information available for later analysis, for example by logging it. [WSC-5.2.2-3]
If the error handling method of an endpoint itself is generating runtime errors, the container must make this
information available for later analysis. [WSC-5.2.2-4]

5.2.3 Errors Originating in the Container and/or Underlying Connection

A wide variety of runtime errors may occur during the functioning of an endpoint. These may including bro-
ken underlying connections, occasional communication errors handling incoming and outgoing messages,
or fatal errors communicating with a peer. Implementations or their administrators judging such errors to
be fatal to the correct functioning of the endpoint may close the endpoint connection, making an attempt
to informing both participants using the onClose() method. Containers judging such errors to be non-fatal
to the correct functioning of the endpoint may allow the endpoint to continue functioning, but must report
the error in message processing either as a checked exception returned by one of the send operations, or by
delivering a the SessionException to the endpoints error handling method, if present, or by logging the error
for later analysis. [WSC-5.2.3-1]

24 Java WebSocket API August 5, 2014

 Chapter 6

Packaging and Deployment

Java WebSocket applications are packaged using the usual conventions of the Java Platform.

6.1 Client Deployment on JDK

The class files for the websocket application and any application resources such as Java WebSocket client
applications are packaged as JAR files, along with any resources such as text or image files that it needs.
The client container is not required to automatically scan the JAR file for websocket client endpoints and
deploy them.
Obtaining a reference to the WebSocketContainer using the ContainerProvider class, the developer de-
ploys both programmatic endpoints and annotated endpoints using the connectToServer() APIs on the Web-
SocketContainer.

6.2 Application Deployment on Web Containers

The class files for the endpoints and any resources they need such as text or image files are packaged into the
Java EE-defined WAR file, either directly under WEB-INF/classes or packaged as a JAR file and located
under WEB-INF/lib.
Java EE containers are not required to support deployment of websocket endpoints if they are not packaged
in a WAR file as described above.
The Java WebSocket implementation must use the web container scanning mechanism defined in [Servlet
3.0] to find annotated and programmatic endpoints contained within the WAR file at deployment time.
[WSC-6.2-1] This is done by scanning for classes annotated with @ServerEndpoint and classes that ex-
tend Endpoint. See also section 4.8 for potential extra steps needed after the scan for annotated endpoints.
Further, the websocket implementation must use the websocket scanning mechanism to find implementa-
tions of the ServerApplicationConfig interface packaged within the WAR file (or in any of its sub-JAR
files). [WSC-6.2-2]
If scan of the WAR file locates one or more ServerApplicationConfig implementations, the websocket
implementation must instantiate each of the ServerApplicationConfig classes it found. For each one, it
must pass the results of the scan of the archive containing it (top level WAR or contained JAR) to its meth-
ods. [WSC-6.2-4] The set that is the union of all the results obtained by calling the getEndpointConfigs()

August 5, 2014 Java WebSocket API 25

Chapter 6. Packaging and Deployment

and getAnnotatedEndpointClasses() on the ServerApplicationConfig classes (that is to say, the anno-

tated endpoint classes and configuration objects for programmatic endpoints) is the set that the websocket
implementation must deploy. [WSC-6.2-5]
If the WAR file contains no ServerApplicationConfig implementations, it must deploy all the annotated
endpoints it located as a result of the scan. [WSC-6.2-3] Because programmatic endpoints cannot be de-
ployed without a corresponding ServerEndpointConfig, if there are no ServerApplicationConfig imple-
mentations to provide these configuration objects, no programmatic endpoints can be deployed.

Note: This means developers can easily deploy all the annotated endpoints in a WAR file by simply bundling
the class files for them into the WAR. This also means that programmatic endpoints cannot be deployed using
this scanning mechanism unless a suitable ServerApplicationConfig is supplied. This also means that the
developer can have precise control over which endpoints are to be deployed from a WAR file by providing
one or more ServerApplicationConfig implementation classes. This also allows the developer to limit a
potentially lengthy scanning process by excluding certain JAR files from the scan (see Servlet 3.0, section
8.2.1). This last case may be desirable in the case of a WAR file containing many JAR files that the developer
knows do not contain any websocket endpoints.

6.3 Application Deployment in Standalone Websocket Server Con-

tainers

This specification recommends standalone websocket server containers (i.e. those that do not include a
servlet container) locates any websocket server endpoints and ServerApplicationConfig classes in the
application bundle and deploys the set of all the server endpoints returned by the configuration classes.
However, standalone websocket server containers may employ other implementation techniques to deploy
endpoints if they wish.

6.4 Programmatic Server Deployment

This specification also defines a mechanism for deployment of server endpoints that does not depend on
Servlet container scanning of the application. Developers may deploy server endpoints programmatically
by using one of the addEndpoint methods of the ServerContainer interface. These methods are only
operational during the application deployment phase of an application. Specifically, as soon as any of the
server endpoints within the application have accepted an opening handshake request, the apis may not longer
be used. This restriction may be relaxed in a future version.
When running on the web container, the addEndpoint methods may be called from a javax.servlet.ServletContextListener
provided by the developer and configured in the deployment descriptor of the web application. The web-
socket implementation must make the ServerContainer instance corresponding to this application available
to the developer as a ServletContext attribute registered under the name javax.websocket.server.ServerContainer.
When running on a standalone container, the application deployment phase is undefined, so the developer
will need to utilize whatever proprietary deployment time hooks the particular container has to offer in order
to make a ServerContainer instance available to the developer at this time.
It is recommended that developers use either the programmatic deployment API, or base their application
on the scanning and ServerApplicationConfig mechanism, but not mix both methods. Developers can
suppress a deployment by scan of the endpoints in the WAR file by providing a ServerApplicationConfig
that returns empty sets from its methods.

26 Java WebSocket API August 5, 2014

 6.5. Websocket Server Paths

If however, the developer does mix both modes of deployment, it is possible in the case of annotated end-
points, for the same annotated endpoint to be submitted twice for deployment, once as a result of a scan of
the WAR file, and once by means of the developer calling the programmatic deployment API. In this case
of an attempt to deploy the same annotated endpoint class more than once, the websocket implementation
must only deploy the annotated endpoint once, and ignore the duplicate submission.

6.5 Websocket Server Paths

Websocket implementations that include server functionality must define a root or the URI space for web-
sockets. Called the the websocket root, it is the URI to which all the relative websocket paths in the same
application are relative. If the websocket server does not include the Servlet API, the websocket server may
choose websocket root itself. If the websocket server includes the Java ServletAPI, the websocket root must
be the same as the servlet context root of the web application. [WSC-6.4-1]

6.6 Platform Versions

The minimum versions of the Java platforms are:

• Java SE version 7, for the Java WebSocket client API [WSC-6.5-1].

• Java EE version 6, for the Java WebSocket server API [WSC-6.5-2].

August 5, 2014 Java WebSocket API 27

Chapter 6. Packaging and Deployment

28 Java WebSocket API August 5, 2014

 Chapter 7

Java EE Environment

7.1 Java EE Environment

When supported on the Java EE platform, there are some additional requirements to support websocket
applications.

7.1.1 Websocket Endpoints and Dependency Injection

Websocket endpoints running in the Java EE platform must have full dependency injection support as de-
scribed in the CDI specification [7] Websocket implementations part of the Java EE platform are required to
support field, method, and constructor injection using the javax.inject.Inject annotation into all websocket
endpoint classes, as well as the use of interceptors for these classes. [WSC-7.1.1-1]The details of this re-
quirement are laid out in the Java EE Platform Specification [8], section EE.5.2.5, and a useful guide for
implementations to meet the requirement is location in section EE.5.24.

7.2 Relationship with Http Session and Authenticated State

It is often useful for developers who embed websocket server endpoints into a larger web application to be
able to share information on a per client basis between the web resources (JSPs, JSFs, Servlets for example)
and the websocket endpoints servicing that client. Because websocket connections are initiated with an
http request, there is an association between the HttpSession under which a client is operating and any
websockets that are established within that HttpSession. The API allows access in the opening handshake
to the unique HttpSession corresponding to that same client. [WSC-7.2-1]
Similarly, if the opening handshake request is already authenticated with the server, the opening handshake
API allows the developer to query the user Principal of the request. If the connection is established with the
requesting client, the websocket implementation considers the user Principal for the associated websocket
Session to be the user Principal that was present on the opening handshake. [WSC-7.2-2]
In the case where a websocket endpoint is a protected resource in the web application (see Chapter 8), that
is to say, requires an authorized user to access it, then the websocket implementation must ensure that the
websocket endpoint does not remain connected to its peer after the underlying implementation has decided
the authenticated identity is no longer valid. [WSC-7.2-3] This may happen, for example, if the user logs out
of the containing web application, or if the authentication times out or is invalidated for some other reason.

August 5, 2014 Java WebSocket API 29

Chapter 7. Java EE Environment

In this situation, the websocket implementation must immediately close the connection using the websocket
close status code 1008. [WSC-7.2-3]
On the other hand, if the websocket endpoint is not a protected resource in the web application, then the user
identity under which an opening handshake established the connection may become invalid or change during
the operation of the websocket without the websocket implementation needing to close the connection.

30 Java WebSocket API August 5, 2014

 Chapter 8

Server Security

Websocket endpoints are secured using the web container security model. The goal of this is to make
it easy for a websocket developer to declare whether access to a websocket server endpoint needs to be
authenticated, and who can access it, and if it needs an encrypted connection or not. A websocket which is
mapped to a given ws:// URI (as described in Chapters 3 and 4) is protected in the deployment descriptor
with a listing to a http:// URI with same hostname, port and path since this is the URL of its opening
handshake. Accordingly, websocket developers may assign an authentication scheme, user roles granted
access and transport guarantee to their websocket endpoints.

8.1 Authentication of Websockets

This specification does not define a mechanism by which websockets themselves can be authenticated.
Rather, by building on the servlet defined security mechanism, a websocket that requires authentication
must rely on the opening handshake request that seeks to initiate a connection to be previously authenti-
cated. Typically, this will be performed by a Http authentication (perhaps basic or form-based) in the web
application containing the websocket prior to the opening handshake to the websocket.
If a client sends an unauthenticated opening handshake request for a websocket that is protected by the secu-
rity mechanism, the websocket implementation must return a 401 (Unauthorized) response to the opening
handshake request and may not initiate a websocket connection [WSC-8.1-1].

8.2 Authorization of Websockets

A websockets authorization may be set by adding a <security-constraint> element to the web.xml of the
web application in which it is packaged. The <url-pattern> used in the security constraint must be used
by the container to match the request URI of the opening handshake of the websocket [WSC-8.2-1]. The
implementation must interpret any http-method other than GET (or the default, missing) as not applying to
the websocket. [WSC-8.2-2]

8.3 Transport Guarantee

A transport guarantee of NONE must be interpreted by the container as allowing unencrypted ws:// connec-
tions to the websocket [WSC-8.3-1]. A transport guarantee of CONFIDENTIAL must be interpreted by

August 5, 2014 Java WebSocket API 31

 Chapter 8. Server Security

the implementation as only allowing access to the websocket over an encrypted (wss://) connection [WSC-
8.3-2] This may require a pre-authenticated request.

8.4 Example

This example snippet from a larger web.xml deployment descriptor shows a security constraint for a web-
socket endpoint. In the example, the websocket endpoint which matches on an incoming request URI
of ‘quotes/live’ relative to the context root of the containing web application is protected such that it
may only be accessed using wss://, and is available only to authenticated users who belong either to the
GOLD MEMBER or PLATINUM MEMBER roles.

1 <security-constraint>
2 <web-resource-collection>
3 <web-resource-name>
4 LiveQuoteWebSocket
5 </web-resource-name>
6 <description>
7 Security constraint for
8 live quote websocket endpoint
9 </description>
10 <url-pattern>/quotes/live</url-pattern>
11 <http-method>GET</http-method>
12 </web-resource-collection>
13 <auth-constraint>
14 <description>
15 definition of which roles
16 may access the quote endpoint
17 </description>
18 <role-name>GOLD_MEMBER</role-name>
19 <role-name>PLATINUM_MEMBER</role-name>
20 </auth-constraint>
21 <user-data-constraint>
22 <description>WSS required</description>
23 <transport-guarantee>
24 CONFIDENTIAL
25 </transport-guarantee>
26 </user-data-constraint>
27 </security-constraint>

32 Java WebSocket API August 5, 2014

 Appendix A

Changes Since 1.0 Final Release

• WEBSOCKET SPEC-226 Session.addMessageHandler(MessageHandler) cannot work with lambda

expressions.

August 5, 2014 Java WebSocket API 33

Appendix A. Changes Since 1.0 Final Release

34 Java WebSocket API August 5, 2014

 Appendix B

Changes Since EDR

Changes in v014 since v013

• WEBSOCKET SPEC-158 HandshakeRequest documentation

• WEBSOCKET SPEC-153 @OnClose and Endpoint.onClose() differences

• WEBSOCKET SPEC-116 WebSocketContainer.connectToServer ease of use / API change

• WEBSOCKET SPEC-114 Programmatic deployment of server endpoints

• WEBSOCKET SPEC-150 Encoder/Decoder lifecycle consistency between pe and ae’s

• WEBSOCKET SPEC-135 Improve modularity around client/server split

• WEBSOCKET SPEC-115 Pls revert to EndpointFactory instead of EndpointConfig scheme

• WEBSOCKET SPEC-79 Deployment on the server by instance

• WEBSOCKET SPEC-154 Incomplete javadoc for ContainerProvider#getContainer

• WEBSOCKET SPEC-157 Typo in ServerEndpointConfigurationBuilder javadocs

• WEBSOCKET SPEC-149 Refactor & rename: Make *Configuration interfaces abstract classes, and
have builders be member classes. Rename Configurators

• WEBSOCKET SPEC-156 ClientEndpointConfigBuilder creation

• WEBSOCKET SPEC-155 DefaultClientEndpointConfig cannot be subclassed

• WEBSOCKET SPEC-58 Thorough list of smaller API, javadoc, spec suggestions based on the EDR
draft

• WEBSOCKET SPEC-16 Which APIs are threadsafe ?

• WEBSOCKET SPEC-151 Clarify that primitive type encoder/decoder work with text messages

• WEBSOCKET SPEC-142 Remove Session#getId()

• WEBSOCKET SPEC-101 Programmatic MessageHandler registration

August 5, 2014 Java WebSocket API 35

Appendix B. Changes Since EDR

Changes in v013 since v012

• WEBSOCKET SPEC-82 @WebSocketEndpoint’s configuration attribute

• WEBSOCKET SPEC-132 RemoteEndpoint#setBatchingAllowed(boolean) should throw IOExcep-

tion

• WEBSOCKET SPEC-139 getNegotiatedSubprotocol(): not sure if we can return null

• WEBSOCKET SPEC-138 websockets api javadoc: include message handler registration for onOpen
method

• WEBSOCKET SPEC-69 Publish same programmatic endpoint type to many different paths

• WEBSOCKET SPEC-98 Consider a property bag on EndpointConfiguration instead of subclassing

for shared application state

• WEBSOCKET SPEC-126 ServerEndpointConfiguration.matchesURI

• WEBSOCKET SPEC-128 DefaultServerConfiguration - methods implementation - b12

• WEBSOCKET SPEC-140 Clarify relationship between WebSocketContainer#setMaxSessionIdleTimeout()

and Session#setTimeout()

• WEBSOCKET SPEC-133 DefaultServerConfiguration#getEndpointClass() should return Class<? ex-

tends Endpoint>

• WEBSOCKET SPEC-141 websockets api: how to pass instance to ServerEndPointConfiguration ?

• WEBSOCKET SPEC-103 DefaultServerConfiguration used in @WebSocketEndpoint

• WEBSOCKET SPEC-144 Discrepancy between URIs of programmatic and annotated endpoint

• WEBSOCKET SPEC-147 @WebSocketClose: javadoc not in sync with the Java API Web Socket
pdf document

• WEBSOCKET SPEC-145 Rename HandshakeRequest.getSession -¿ getHttpSession

• WEBSOCKET SPEC-143 ContainerProvider javadoc need to update the location of service provider

• WEBSOCKET SPEC-131 Consider merging RemoteEndpoint and Session

• WEBSOCKET SPEC-134 ContainerProvider#getWebSocketContainer()

• WEBSOCKET SPEC-88 CloseReason changes

• WEBSOCKET SPEC-136 Session.getRequestURI() . includes the query string ?

• WEBSOCKET SPEC-111 Missing WebSocketClient#configuration attribute

• WEBSOCKET SPEC-118 Scanning scheme forces creation of ServerEndpoinConfiguration class

even for vanilla endpoints

• WEBSOCKET SPEC-97 Consider using jax-rs MultiValueMap to represent Http headers in the hand-
shake request and response

• WEBSOCKET SPEC-137 An incoming message that is too big: should it cause the connection to
close ? Or should the implementation report the error to the endpoint and move on ?

36 Java WebSocket API August 5, 2014

 • WEBSOCKET SPEC-110 Rename SendHandler#setResult

• WEBSOCKET SPEC-9 API Usability: Consider API renaming, minor refactorizations for usability

Changes in v012 since v011/Public Draft

• WEBSOCKET SPEC-89 Extension unification

• WEBSOCKET SPEC-94 WebSocketEndpoint.configuration should be an optional parameter

• WEBSOCKET SPEC-84 Typo WebSocketResponse#getHeaders()

• WEBSOCKET SPEC-91 WebSocketOpen javadoc

• WEBSOCKET SPEC-86 PongMessage typo and formatting

• WEBSOCKET SPEC-95 Clarify @WebSocketOpen, @WebSocketClose, @WebSocketError can each

only annotate one method per annotated endpoint

• WEBSOCKET SPEC-52 Define inheritance semantics for annotations

• WEBSOCKET SPEC-75 Consider requiring BASIC and DIGEST authentication schemes in the client
container.

• WEBSOCKET SPEC-96 Allow Java primitives and boxed equivalents as message parameters to
@WebSocketMessage methods

• WEBSOCKET SPEC-119 WebSocketContainer can’t be a singleton

• WEBSOCKET SPEC-120 Allow multiple ClientContainers per VM

• WEBSOCKET SPEC-99 Define lifecycle and cardinality of encoders and decoders.

• WEBSOCKET SPEC-121 RemoteEndpoint#[sendPing()—sendPong()] should throw IOException

• WEBSOCKET SPEC-100 Clarify semantics of EJB SSB and Singletons and CDI managed beans -
as-websockets

• WEBSOCKET SPEC-85 Some DefaultClientConfiguration methods return ClientEndpointConfigu-

ration

• WEBSOCKET SPEC-102 CloseReason.CloseCodes

• WEBSOCKET SPEC-122 Behaviour of onMessage(some mutable object) not defined

• WEBSOCKET SPEC-127 Consider removing setBufferSize() on containers

• WEBSOCKET SPEC-130 Wrong javadoc for @WebSocketMessage return type

• WEBSOCKET SPEC-80 Semantics of undeploy of a websocket

• WEBSOCKET SPEC-53 Endpoint class qualifiers for @WebSocketEndpoint

• WEBSOCKET SPEC-117 Provide way to inform developers when connections timeout or close
(without close frames being sent)

August 5, 2014 Java WebSocket API 37

Appendix B. Changes Since EDR

• WEBSOCKET SPEC-81 Consider using servlet security annotations to configure authorization and
connection encryption

• WEBSOCKET SPEC-74 Consider scoping getOpenSessions() just to the endpoint

• WEBSOCKET SPEC-83 Define the portability semantics of ContainerProvider

• WEBSOCKET SPEC-93 ServerEndpointConfiguration#getEndpointClass() for annotated endpoints

• WEBSOCKET SPEC-92 Clarify javadoc on DecodeException

• WEBSOCKET SPEC-87 Session should extend Closeable

• WEBSOCKET SPEC-108 RemoteEndpoint#sendPing()/sendPong() data shouldn’t exceed 125 bytes

• WEBSOCKET SPEC-105 Extension parameters ordering

• WEBSOCKET SPEC-88 CloseReason changes

• WEBSOCKET SPEC-112 ServerApplicationConfiguration#getAnnotatedEndpointClasses(Set<Class>

scanned) using Class<?> instead of Class

• WEBSOCKET SPEC-104 Session - javadoc/error reporting

• WEBSOCKET SPEC-78 Specify extensions attribute in the annotation

• WEBSOCKET SPEC-72 Consider producing separate JAR files for client and server API bundles

• WEBSOCKET SPEC-113 Clarify websocket endpoints in EJB JARs do not need to be deployed

Changes since v011

• Editorial cleanups

Changes since v010

• Added batch mode to RemoteEndpoint

• many additions to javadocs and formatting/editorial improvements to specification document

Changes since v009

• New section on exception handling (5.2)

• New and (hopefully final!) package arrangement to suit the client/server split.

• Updated section on the relationship between web socket sessions, HttpSession and authenticated state
(7.2) and guidance for distributed implementations.

• Full and updated description on application deployment on web containers. This now features a new
ServerApplicationConfiguration class and removes programmatic server deployment.

38 Java WebSocket API August 5, 2014

 • ClientContainer/ServerContainer have now become one WebSocketContainer.

• Removed EndpointFactory, replaced with ability to get the (custom) EndpointConfiguration from the
onOpen method.

• New Extension interface to model the websocket-extension parameters sent in the opening handshake.

• Added ability to change the timeouts for async send operations.

• Removed getInactiveTime() on Session due to performance concerns.

• Added standard websocket handshake headers.

Changes since v008

• Restricted the number of MessageHandlers that can be registered per Session to one per native web-
socket message type: text, binary, pong.

• Added user property Map to Session.

• Loosened the restrictions on @WebSocketMessage method parameters: now these methods can take
any parameters that can be mapped to one of the MessageHandler types.

• Refactored Endpoint and EndpointConfiguration and added EndpointFactory so that Endpoint in-
stances can share state.

Changes between v008 and EDR (v006)

• WEBSOCKET SPEC-7

• WEBSOCKET SPEC-10

• WEBSOCKET SPEC-14

• WEBSOCKET SPEC-50

• WEBSOCKET SPEC-23

• WEBSOCKET SPEC-61

• WEBSOCKET SPEC-29

• WEBSOCKET SPEC-28

• WEBSOCKET SPEC-51

• WEBSOCKET SPEC-57

• WEBSOCKET SPEC-36

• WEBSOCKET SPEC-44

• WEBSOCKET SPEC-18

• WEBSOCKET SPEC-54

August 5, 2014 Java WebSocket API 39

Appendix B. Changes Since EDR

• WEBSOCKET SPEC-41

• WEBSOCKET SPEC-23

plus a large number of smaller tweaks and editorial improvements.

40 Java WebSocket API August 5, 2014

 Bibliography

[1] I. Fette and A. Melnikov. RFC 6455: The WebSocket Protocol. RFC, IETF, December 2011. See
http://www.ietf.org/rfc/rfc6455.txt.

[2] Ian Hickson. The WebSocket API. Note, W3C, December 2012. See
http://dev.w3.org/html5/websockets/.

[3] S. Bradner. RFC 2119: Keywords for use in RFCs to Indicate Requirement Levels. RFC, IETF, March
1997. See http://www.ietf.org/rfc/rfc2119.txt.

[4] Danny Coward. Java API for WebSocket. JSR, JCP, 2013. See http://jcp.org/en/jsr/detail?id=356.

[5] Expert group mailing list archive. Web site. See

http://java.net/projects/websocket-spec/lists/jsr356-experts/archive.

[6] J. Gregorio, R. Fielding, M. Hadley, M. Nottingham, and D. Orchard. RFC 6570: URI Template. RFC,
IETF, March 2012. See http://www.ietf.org/rfc/rfc6570.txt.

[7] Pete Muir. Contexts and Dependency Injection for Java EE. JSR, JCP, 2013. See
http://jcp.org/en/jsr/detail?id=347.

[8] Linda DeMichiel and Bill Shannon. Java Platform, Enterprise Edition 7 (Java EE 7) Specification.
JSR, JCP, 2013. See http://jcp.org/en/jsr/detail?id=342.

August 5, 2014 Java WebSocket API 41