├── spec ├── spec.pdf ├── styles │ ├── lineno.sty │ ├── macros.tex │ ├── jsrfrontstyle.tex │ ├── jsrmainstyle.tex │ └── jsr.sty ├── chapters │ ├── license___final.tex │ ├── license_final.tex │ ├── refs.tex │ ├── titlepage.tex │ ├── javaee.tex │ ├── security.tex │ ├── exception.tex │ ├── introduction.tex │ ├── packaging.tex │ ├── license.tex │ ├── license___eval.tex │ └── configuration.tex ├── references.bib └── spec.tex ├── README.md ├── api ├── etc │ └── config │ │ ├── copyright-exclude │ │ └── copyright.txt ├── client │ ├── src │ │ └── main │ │ │ └── java │ │ │ └── javax │ │ │ └── websocket │ │ │ ├── package-info.java │ │ │ ├── SendHandler.java │ │ │ ├── PongMessage.java │ │ │ ├── HandshakeResponse.java │ │ │ ├── OnOpen.java │ │ │ ├── OnError.java │ │ │ ├── DeploymentException.java │ │ │ ├── OnClose.java │ │ │ ├── SessionException.java │ │ │ ├── Extension.java │ │ │ ├── EncodeException.java │ │ │ ├── SendResult.java │ │ │ ├── ContainerProvider.java │ │ │ ├── EndpointConfig.java │ │ │ ├── ClientEndpoint.java │ │ │ ├── DefaultClientEndpointConfig.java │ │ │ ├── Decoder.java │ │ │ ├── MessageHandler.java │ │ │ ├── DecodeException.java │ │ │ ├── Encoder.java │ │ │ ├── OnMessage.java │ │ │ └── Endpoint.java │ └── pom.xml ├── server │ ├── src │ │ └── main │ │ │ └── java │ │ │ └── javax │ │ │ └── websocket │ │ │ └── server │ │ │ ├── package-info.java │ │ │ ├── PathParam.java │ │ │ ├── ServerApplicationConfig.java │ │ │ ├── ServerContainer.java │ │ │ ├── HandshakeRequest.java │ │ │ ├── ServerEndpoint.java │ │ │ └── DefaultServerEndpointConfig.java │ └── pom.xml └── pom.xml ├── CONTRIBUTING.md └── websocket-1.1-changes.txt /spec/spec.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/javaee/websocket-spec/HEAD/spec/spec.pdf -------------------------------------------------------------------------------- /spec/styles/lineno.sty: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/javaee/websocket-spec/HEAD/spec/styles/lineno.sty -------------------------------------------------------------------------------- /spec/chapters/license___final.tex: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/javaee/websocket-spec/HEAD/spec/chapters/license___final.tex -------------------------------------------------------------------------------- /spec/chapters/license_final.tex: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/javaee/websocket-spec/HEAD/spec/chapters/license_final.tex -------------------------------------------------------------------------------- /spec/chapters/refs.tex: -------------------------------------------------------------------------------- 1 | \raggedright 2 | \bibliographystyle{unsrt} 3 | \addcontentsline{toc}{chapter}{Bibliography} 4 | \bibliography{references} 5 | 6 | -------------------------------------------------------------------------------- /spec/styles/macros.tex: -------------------------------------------------------------------------------- 1 | \newtheorem{note}{Note}[chapter] 2 | \newcommand{\code}[1]{\texttt{\small #1}} 3 | \renewcommand\verbatimtabsize{4\relax} 4 | 5 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ⚠️ This project is now part of the EE4J initiative. This repository has been archived as all activities are now happening in the [corresponding Eclipse repository](https://github.com/eclipse-ee4j/websocket-api). 2 | -------------------------------------------------------------------------------- /api/etc/config/copyright-exclude: -------------------------------------------------------------------------------- 1 | .apt 2 | .args 3 | .bundle 4 | .class 5 | .exe 6 | .gif 7 | .gitignore 8 | .ico 9 | .iml 10 | .ipr 11 | .iws 12 | .jar 13 | .jks 14 | .jpg 15 | .js 16 | .json 17 | .mm 18 | .ods 19 | .png 20 | .project 21 | .sql 22 | .svg 23 | .war 24 | .zip 25 | .dat 26 | jaxb.index 27 | nb-configuration.xml 28 | nbactions.xml 29 | /MANIFEST.MF 30 | /META-INF/services/ 31 | /etc/config/copyright-exclude 32 | /etc/config/copyright.txt 33 | /LICENSE.html 34 | /LICENSE.txt -------------------------------------------------------------------------------- /spec/styles/jsrfrontstyle.tex: -------------------------------------------------------------------------------- 1 | % set up page styles for frontmatter, no page headers, normal footer 2 | \fancyhf{} 3 | \fancyfoot[CO,CE]{Java Web Socket API} 4 | \fancyfoot[LE,RO]{\thepage} 5 | \fancyfoot[RE,LO]{\today} 6 | \fancypagestyle{plain}{ 7 | \fancyhf{} 8 | \fancyfoot[CO,CE]{Java Web Socket API} 9 | \fancyfoot[LE,RO]{\thepage} 10 | \fancyfoot[RE,LO]{\today} 11 | \renewcommand{\footrulewidth}{0pt} 12 | \renewcommand{\headrulewidth}{0pt} 13 | } 14 | \renewcommand{\headrulewidth}{0pt} 15 | -------------------------------------------------------------------------------- /spec/chapters/titlepage.tex: -------------------------------------------------------------------------------- 1 | \begin{titlepage} 2 | \raggedleft 3 | 4 | \vspace*{60pt} 5 | 6 | {\Huge 7 | \textsf{Java\texttrademark\ API for WebSocket 8 | \vspace{10pt}}} 9 | 10 | \vspace{20pt} 11 | 12 | { 13 | \Large\textit{Version 1.1 Maintenance Release \\ 14 | \today} 15 | } 16 | 17 | \vspace{40pt} 18 | 19 | {\large Pavel\ Bucek\\ 20 | \vspace{10pt}Comments to: users@websocket-spec.java.net 21 | } 22 | 23 | \vspace{80pt} 24 | 25 | {\small\textit{Oracle Corporation\\ 26 | 500 Oracle Parkway, Redwood Shores, CA 94065 USA.} 27 | } 28 | \end{titlepage} 29 | -------------------------------------------------------------------------------- /spec/styles/jsrmainstyle.tex: -------------------------------------------------------------------------------- 1 | % set up page styles for mainmatter, page headers and normal footer 2 | \renewcommand{\chaptermark}[1]{ 3 | \markboth{\chaptername 4 | \ \thechapter.\ #1}{}} 5 | \renewcommand{\sectionmark}[1]{ 6 | \markright{\thesection.\ #1}{}} 7 | \fancyhf{} 8 | \fancyhead[RO]{\slshape \rightmark} 9 | \fancyhead[LE]{\slshape \leftmark} 10 | \fancyfoot[CO,CE]{Java WebSocket API} 11 | \fancyfoot[LE,RO]{\thepage} 12 | \fancyfoot[RE,LO]{\today} 13 | \fancypagestyle{plain}{ 14 | \fancyhf{} 15 | \fancyfoot[CO,CE]{Java WebSocket API} 16 | \fancyfoot[LE,RO]{\thepage} 17 | \fancyfoot[RE,LO]{\today} 18 | \renewcommand{\footrulewidth}{0pt} 19 | \renewcommand{\headrulewidth}{0pt} 20 | } 21 | \renewcommand{\headrulewidth}{0.4pt} 22 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | --- 4 | 5 | # Source Code Submissions 6 | We welcome your contributions and look forward to collaborating with you. We can only accept source code repository 7 | submissions from users who have signed and returned the Oracle 8 | Contributor Agreement. You will find details and the agreement to sign at this OTN web page: 9 | [Oracle Contributor Agreement](http://www.oracle.com/technetwork/community/oca-486395.html). 10 | 11 | # Other Contributions 12 | For all project Submissions other than source code repository contributions, the following also applies: Oracle does 13 | not claim ownership of Your Submissions. However, in order to fulfill 14 | the purposes of this project, You must give Oracle and all Users 15 | the right to post, access, discuss, use, publish, disseminate, and refine 16 | Your Submissions. 17 | 18 | In legalese: *You hereby grant to Oracle and all 19 | Users a royalty-free, perpetual, irrevocable, worldwide, non-exclusive, 20 | and fully sub-licensable right and license, under Your intellectual 21 | property rights, to reproduce, modify, adapt, publish, translate, create 22 | derivative works from, distribute, perform, display, and use Your 23 | Submissions (in whole or part) and to incorporate or implement them in 24 | other works in any form, media, or technology now known or later 25 | developed, all subject to the obligation to retain any copyright notices 26 | included in Your Submissions. All Users, Oracle, and their 27 | sublicensees are responsible for any modifications they make to the 28 | Submissions of others.* 29 | 30 | Copyright © 2017 Oracle and/or its affiliates. All rights reserved. 31 | -------------------------------------------------------------------------------- /api/etc/config/copyright.txt: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) YYYY Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | -------------------------------------------------------------------------------- /spec/references.bib: -------------------------------------------------------------------------------- 1 | 2 | @techreport{rfc6455, 3 | Author = {I. Fette and A. Melnikov}, 4 | Institution = {IETF}, 5 | Month = {December}, 6 | Note = {See http://www.ietf.org/rfc/rfc6455.txt}, 7 | Title = {{RFC} 6455: {The} {WebSocket} {Protocol}}, 8 | Type = {{RFC}}, 9 | Year = 2011} 10 | 11 | @techreport{websocketsw3c, 12 | Author = {Ian Hickson}, 13 | Institution = {W3C}, 14 | Month = {December}, 15 | Note = {See http://dev.w3.org/html5/websockets/}, 16 | Title = {{The} {WebSocket} {API}}, 17 | Type = {{Note}}, 18 | Year = 2012} 19 | 20 | @techreport{rfc2119, 21 | Author = {S. Bradner}, 22 | Institution = {IETF}, 23 | Month = {March}, 24 | Note = {See http://www.ietf.org/rfc/rfc2119.txt}, 25 | Title = {{RFC} 2119: {Keywords} for use in {RFCs} to {Indicate} {Requirement} {Levels}}, 26 | Type = {{RFC}}, 27 | Year = 1997} 28 | 29 | @techreport{rfc6570, 30 | Author = {J. Gregorio and R. Fielding and M. Hadley and M. Nottingham and D. Orchard}, 31 | Institution = {IETF}, 32 | Month = {March}, 33 | Note = {See http://www.ietf.org/rfc/rfc6570.txt}, 34 | Title = {{RFC} 6570: {URI} {Template}}, 35 | Type = {{RFC}}, 36 | Year = 2012} 37 | 38 | @techreport{mailinglist, 39 | Note = {See http://java.net/projects/websocket-spec/lists/jsr356-experts/archive}, 40 | Title = {{Expert} {group} {mailing} {list} {archive}}, 41 | Type = {Web Site}} 42 | 43 | @techreport{jsr342, 44 | Author = {Linda DeMichiel and Bill Shannon}, 45 | Institution = {JCP}, 46 | Note = {See http://jcp.org/en/jsr/detail?id=342}, 47 | Title = {{Java} {Platform}, {Enterprise Edition 7} {(Java EE 7)} {Specification}}, 48 | Type = {{JSR}}, 49 | Year = 2013} 50 | 51 | @techreport{jsr347, 52 | Author = {Pete Muir}, 53 | Institution = {JCP}, 54 | Note = {See http://jcp.org/en/jsr/detail?id=347}, 55 | Title = {{Contexts} and {Dependency} {Injection} for {Java} {EE}}, 56 | Type = {{JSR}}, 57 | Year = 2013} 58 | 59 | @techreport{jsr356, 60 | Author = {Danny Coward}, 61 | Institution = {JCP}, 62 | Note = {See http://jcp.org/en/jsr/detail?id=356}, 63 | Title = {Java {API} for {WebSocket}}, 64 | Type = {{JSR}}, 65 | Year = 2013} 66 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | 41 | /** 42 | * This package contains all the WebSocket APIs common to both the client 43 | * and server side. 44 | */ 45 | package javax.websocket; 46 | 47 | -------------------------------------------------------------------------------- /api/server/src/main/java/javax/websocket/server/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | 41 | /** 42 | * This package contains all the WebSocket APIs used only by server side 43 | * applications. 44 | */ 45 | package javax.websocket.server; 46 | 47 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/SendHandler.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | /** 43 | * A simple callback object for asynchronous sending of web socket messages. 44 | * 45 | * @author dannycoward 46 | */ 47 | public interface SendHandler { 48 | 49 | /** 50 | * Called once the message has been transmitted. 51 | * 52 | * @param result the result. 53 | */ 54 | void onResult(SendResult result); 55 | } 56 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/PongMessage.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | import java.nio.ByteBuffer; 43 | 44 | /** 45 | * The PongMessage interface represents a web socket pong. PongMessages may be received by using 46 | * a {@code MessageHandler.Basic}. The payload of the PongMessage is the application data sent by the peer. 47 | * 48 | * @author dannycoward 49 | */ 50 | public interface PongMessage { 51 | 52 | /** 53 | * The application data inside the pong message from the peer. 54 | * 55 | * @return the application data. 56 | */ 57 | ByteBuffer getApplicationData(); 58 | } 59 | -------------------------------------------------------------------------------- /spec/spec.tex: -------------------------------------------------------------------------------- 1 | \documentclass[11pt, dvips]{book} 2 | \usepackage[hyperref, thmmarks]{styles/ntheorem} 3 | \usepackage{framed} 4 | \usepackage{times} 5 | \usepackage{textcomp} 6 | \usepackage{tabularx} 7 | \usepackage{moreverb} 8 | \usepackage[pdftex]{graphicx} 9 | \usepackage{amssymb} 10 | \usepackage{float} 11 | \usepackage[dvips, 12 | pdftitle={Java API for WebSocket}, 13 | pdfauthor={Pavel Bucek, Oracle}, 14 | pdfsubject={Java API for WebSocket}, 15 | pdfkeywords={Java Web Services Websocket}, 16 | pdftex, 17 | colorlinks=true, 18 | linkcolor=black, 19 | citecolor=black, 20 | pdfstartview=FitH, 21 | letterpaper=true, 22 | bookmarksnumbered=true 23 | ]{hyperref} 24 | 25 | % set up page dimensions 26 | \textwidth = 6.5 in 27 | \textheight = 9.33 in 28 | \oddsidemargin = 0.0 in 29 | \evensidemargin = 0.0 in 30 | \topmargin = -0.75 in 31 | \headheight = 15pt 32 | \headsep = 0.33 in 33 | \parskip = 6pt 34 | \parindent = 0.0in 35 | \footskip=0.5in 36 | 37 | \usepackage{fancyhdr} 38 | \pagestyle{fancy} 39 | \usepackage{styles/jsr} 40 | \theoremstyle{plain} 41 | %\setlength{\theorempostskipamount}{0pt} 42 | \newtheorem{ednote}{Editors Note}[chapter] 43 | 44 | \theoremstyle{nonumberplain} 45 | \theoremindent0cm 46 | \theoremseparator{:} 47 | \newtheorem{nnnote}{Note}[chapter] 48 | 49 | %\usepackage[pagewise, right]{styles/lineno} 50 | %\usepackage[dvips]{changebar} 51 | \usepackage{longtable} 52 | 53 | 54 | %%% 55 | %%% TODAY 56 | %%% 57 | \renewcommand{\today}{August 5, 2014} 58 | 59 | \begin{document} 60 | 61 | \frontmatter 62 | \include{styles/macros} 63 | \include{styles/jsrfrontstyle} 64 | 65 | \include{chapters/titlepage} 66 | 67 | \cleardoublepage 68 | { 69 | \small 70 | %\include{chapters/license} 71 | \include{chapters/license___final} 72 | } 73 | 74 | \pdfbookmark[0]{Contents}{toc} 75 | \tableofcontents 76 | 77 | \mainmatter 78 | \include{styles/jsrmainstyle} 79 | 80 | %\linenumbers 81 | %\nochangebars 82 | 83 | \setcounter{secnumdepth}{4} 84 | 85 | \newcommand{\footnoteremember}[2]{\footnote{#2}\newcounter{#1}\setcounter{#1}{\value{footnote}}} 86 | \newcommand{\footnoterecall}[1]{\footnotemark[\value{#1}]} 87 | 88 | \include{chapters/introduction} 89 | \include{chapters/applications} 90 | \include{chapters/configuration} 91 | \include{chapters/annotations} 92 | \include{chapters/exception} 93 | \include{chapters/packaging} 94 | \include{chapters/javaee} 95 | \include{chapters/security} 96 | 97 | \appendix 98 | \renewcommand{\chaptermark}[1]{ 99 | \markboth{\appendixname 100 | \ \thechapter.\ #1}{}} 101 | 102 | \include{chapters/changes} 103 | 104 | \backmatter 105 | 106 | \include{chapters/refs} 107 | 108 | \end{document} 109 | -------------------------------------------------------------------------------- /api/client/pom.xml: -------------------------------------------------------------------------------- 1 | 2 | 41 | 42 | 43 | 4.0.0 44 | 45 | javax.websocket 46 | javax.websocket-all 47 | 1.1 48 | 49 | 50 | javax.websocket-client-api 51 | jar 52 | WebSocket client API 53 | JSR 356: Java API for WebSocket 54 | http://websocket-spec.java.net 55 | 56 | 57 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/HandshakeResponse.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | import java.util.List; 43 | import java.util.Map; 44 | 45 | /** 46 | * The handshake response represents the web socket-defined Http response 47 | * that is the response to the opening handshake request. 48 | * 49 | * @author dannycoward 50 | */ 51 | public interface HandshakeResponse { 52 | 53 | /** 54 | * The Sec-WebSocket-Accept header name. 55 | */ 56 | static final String SEC_WEBSOCKET_ACCEPT = "Sec-WebSocket-Accept"; 57 | 58 | /** 59 | * Return the list of Http headers sent by the web socket server. 60 | * 61 | * @return the http headers . 62 | */ 63 | Map> getHeaders(); 64 | } 65 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/OnOpen.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | import java.lang.annotation.ElementType; 43 | import java.lang.annotation.Retention; 44 | import java.lang.annotation.RetentionPolicy; 45 | import java.lang.annotation.Target; 46 | 47 | /** 48 | * This method level annotation can be used to decorate a Java method that wishes to be called when a new 49 | * web socket session is open. 50 | * 51 | *

The method may only take the following parameters:- 52 | *

57 | * 58 | *

The parameters may appear in any order. 59 | * 60 | * @author dannycoward 61 | */ 62 | @Retention(RetentionPolicy.RUNTIME) 63 | @Target(ElementType.METHOD) 64 | public @interface OnOpen { 65 | 66 | } 67 | -------------------------------------------------------------------------------- /spec/chapters/javaee.tex: -------------------------------------------------------------------------------- 1 | \chapter{Java EE Environment} 2 | \label{javaee} 3 | 4 | \section{Java EE Environment} 5 | 6 | When supported on the Java EE platform, there are some additional requirements to support websocket applications. 7 | 8 | \subsection{Websocket Endpoints and Dependency Injection} 9 | 10 | Websocket endpoints running in the Java EE platform must have full dependency injection support as described in the CDI specification \cite{jsr347} 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 requirement are laid out in the Java EE Platform Specification \cite{jsr342}, section EE.5.2.5, and a useful guide for implementations to meet the requirement is location in section EE.5.24. 11 | 12 | \section{Relationship with Http Session and Authenticated State} 13 | \label{javaee:httpsession} 14 | 15 | 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 \textbf{HttpSession}. The API allows access in the opening handshake to the unique \textbf{HttpSession} corresponding to that same client. [WSC-7.2-1] 16 | 17 | Similarly, if the opening handshake request is already authenticated with the server, the opening handshake API allows the developer to query the user \textbf{Principal} of the request. If the connection is established with the requesting client, the websocket implementation considers the user \textbf{Principal} for the associated websocket \textbf{Session} to be the user \textbf{Principal} that was present on the opening handshake. [WSC-7.2-2] 18 | 19 | In the case where a websocket endpoint is a protected resource in the web application (see Chapter \ref{security}), 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. In this situation, the websocket implementation must immediately close the connection using the websocket close status code $1008$. [WSC-7.2-3] 20 | 21 | 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. -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/OnError.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | import java.lang.annotation.ElementType; 43 | import java.lang.annotation.Retention; 44 | import java.lang.annotation.RetentionPolicy; 45 | import java.lang.annotation.Target; 46 | 47 | /** 48 | * This method level annotation can be used to decorate a Java method that wishes to be called in order 49 | * to handle errors. See {@link Endpoint#onError} for 50 | * a description of the different categories of error. 51 | * 52 | *

The method may only take the following parameters:- 53 | *

58 | * 59 | *

The parameters may appear in any order. 60 | * 61 | * @author dannycoward 62 | */ 63 | @Retention(RetentionPolicy.RUNTIME) 64 | @Target(ElementType.METHOD) 65 | public @interface OnError { 66 | 67 | } 68 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/DeploymentException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | /** 43 | * Checked exception indicating some kind of failure either to publish 44 | * an endpoint on its server, or a failure to connect a client to its server. 45 | * 46 | * @author dannycoward 47 | */ 48 | public class DeploymentException extends Exception { 49 | 50 | /** 51 | * Creates a deployment exception with the given reason for the deployment 52 | * failure. 53 | * 54 | * @param message the reason for the failure. 55 | */ 56 | public DeploymentException(String message) { 57 | super(message); 58 | } 59 | 60 | /** 61 | * Creates a deployment exception with the given reason for the deployment 62 | * failure and wrapped cause of the failure. 63 | * 64 | * @param message the reason for the failure. 65 | * @param cause the cause of the problem. 66 | */ 67 | public DeploymentException(String message, Throwable cause) { 68 | super(message, cause); 69 | } 70 | } 71 | -------------------------------------------------------------------------------- /spec/styles/jsr.sty: -------------------------------------------------------------------------------- 1 | \NeedsTeXFormat{LaTeX2e}[1996/06/01] 2 | \ProvidesPackage{styles/jsr}[2003/04/29 v1.0 (MJH)] 3 | 4 | \def\@chapter[#1]#2{\ifnum \c@secnumdepth >\m@ne 5 | \if@mainmatter 6 | \refstepcounter{chapter}% 7 | \typeout{\@chapapp\space\thechapter.}% 8 | \addcontentsline{toc}{chapter}% 9 | {\protect\numberline{\thechapter}#1}% 10 | \else 11 | \addcontentsline{toc}{chapter}{#1}% 12 | \fi 13 | \else 14 | \addcontentsline{toc}{chapter}{#1}% 15 | \fi 16 | \chaptermark{#1}% 17 | \addtocontents{lof}{\protect\addvspace{10\p@}}% 18 | \addtocontents{lot}{\protect\addvspace{10\p@}}% 19 | \if@twocolumn 20 | \@topnewpage[\@makechapterhead{#2}]% 21 | \else 22 | \@makechapterhead{#2}% 23 | \@afterheading 24 | \fi} 25 | \def\@makechapterhead#1{% 26 | \vspace*{50\p@}% 27 | {\parindent \z@ \raggedleft \sffamily 28 | \ifnum \c@secnumdepth >\m@ne 29 | \if@mainmatter 30 | \huge\bfseries \@chapapp\space \thechapter 31 | \par\nobreak 32 | \vskip 20\p@ 33 | \fi 34 | \fi 35 | \interlinepenalty\@M 36 | \Huge \bfseries #1\par\nobreak 37 | \vskip 40\p@ 38 | }} 39 | \def\@schapter#1{\if@twocolumn 40 | \@topnewpage[\@makeschapterhead{#1}]% 41 | \else 42 | \@makeschapterhead{#1}% 43 | \@afterheading 44 | \fi} 45 | \def\@makeschapterhead#1{% 46 | \vspace*{50\p@}% 47 | {\parindent \z@ \raggedleft 48 | \sffamily 49 | \interlinepenalty\@M 50 | \Huge \bfseries #1\par\nobreak 51 | \vskip 40\p@ 52 | }} 53 | 54 | \def\verbatim@font{\small\ttfamily} 55 | 56 | \renewcommand{\chapter}{\if@openright\cleardoublepage\else\clearpage\fi 57 | \thispagestyle{plain}% 58 | \global\@topnum\z@ 59 | \@afterindentfalse 60 | \secdef\@chapter\@schapter} 61 | \renewcommand{\section}{\@startsection {section}{1}{0pt}% 62 | {-3.5ex \@plus -1ex \@minus -.2ex}% 63 | {2.3ex \@plus.2ex}% 64 | {\sffamily\Large\bfseries}} 65 | 66 | \renewcommand{\subsection}{\@startsection{subsection}{2}{0pt}% 67 | {-3.25ex\@plus -1ex \@minus -.2ex}% 68 | {1.5ex \@plus .2ex}% 69 | {\sffamily\large\bfseries}} 70 | 71 | \renewcommand{\subsubsection}{\@startsection{subsubsection}{3}{0pt}% 72 | {-3.25ex\@plus -1ex \@minus -.2ex}% 73 | {1.5ex \@plus .2ex}% 74 | {\sffamily\normalsize\bfseries}} 75 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/OnClose.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | import java.lang.annotation.ElementType; 43 | import java.lang.annotation.Retention; 44 | import java.lang.annotation.RetentionPolicy; 45 | import java.lang.annotation.Target; 46 | 47 | /** 48 | * This method level annotation can be used to decorate a Java method that wishes 49 | * to be called when a web socket session is closing. 50 | * 51 | *

The method may only take the following parameters:- 52 | *

58 | * 59 | *

The parameters may appear in any order. See 60 | * {@link Endpoint#onClose} 61 | * for more details on how the session parameter may be used during method calls 62 | * annotated with this annotation. 63 | * 64 | * @author dannycoward 65 | */ 66 | @Retention(RetentionPolicy.RUNTIME) 67 | @Target(ElementType.METHOD) 68 | public @interface OnClose { 69 | 70 | } 71 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/SessionException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2017 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | 41 | package javax.websocket; 42 | 43 | /** 44 | * A SessionException represents a general exception type reporting problems 45 | * occurring on a websocket session. 46 | * 47 | * @author dannycoward 48 | */ 49 | public class SessionException extends Exception { 50 | private final Session session; 51 | private static final long serialVersionUID = 014; 52 | 53 | /** 54 | * Creates a new instance of this exception with the given message, 55 | * the wrapped cause of the exception and the session with which 56 | * the problem is associated. 57 | * 58 | * @param message a description of the problem 59 | * @param cause the error that caused the problem 60 | * @param session the session on which the problem occurred. 61 | */ 62 | 63 | public SessionException(String message, Throwable cause, Session session) { 64 | super(message, cause); 65 | this.session = session; 66 | } 67 | 68 | /** 69 | * Return the Session on which the problem occurred. 70 | * 71 | * @return the session 72 | */ 73 | 74 | public Session getSession() { 75 | return this.session; 76 | } 77 | } 78 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/Extension.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2017 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | 41 | package javax.websocket; 42 | 43 | import java.util.List; 44 | 45 | /** 46 | * A simple representation of a websocket extension as a name and map of extension parameters. 47 | * 48 | * @author dannycoward 49 | */ 50 | public interface Extension { 51 | 52 | /** 53 | * The name of the extension. 54 | * 55 | * @return the name of the extension. 56 | */ 57 | String getName(); 58 | 59 | /** 60 | * The extension parameters for this extension in the order 61 | * they appear in the http headers. 62 | * 63 | * @return The read-only Map of extension parameters belonging to this extension. 64 | */ 65 | List getParameters(); 66 | 67 | /** 68 | * This member interface defines a single websocket extension parameter. 69 | */ 70 | interface Parameter { 71 | /** 72 | * Return the name of the extension parameter. 73 | * 74 | * @return the name of the parameter. 75 | */ 76 | String getName(); 77 | 78 | /** 79 | * Return the value of the extension parameter. 80 | * 81 | * @return the value of the parameter. 82 | */ 83 | String getValue(); 84 | } 85 | } 86 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/EncodeException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | /** 43 | * A general exception that occurs when trying to encode a custom object to a string or binary message. 44 | * 45 | * @author dannycoward 46 | */ 47 | public class EncodeException extends Exception { 48 | private final Object object; 49 | private static final long serialVersionUID = 006; 50 | 51 | /** 52 | * Constructor with the object being encoded, and the reason why it failed to be. 53 | * 54 | * @param object the object that could not be encoded. 55 | * @param message the reason for the failure. 56 | */ 57 | public EncodeException(Object object, String message) { 58 | super(message); 59 | this.object = object; 60 | } 61 | 62 | 63 | /** 64 | * Constructor with the object being encoded, and the reason why it failed to be, and the cause. 65 | * 66 | * @param object the object that could not be encoded. 67 | * @param message the reason for the failure. 68 | * @param cause the cause of the problem. 69 | */ 70 | public EncodeException(Object object, String message, Throwable cause) { 71 | super(message, cause); 72 | this.object = object; 73 | } 74 | 75 | 76 | /** 77 | * Return the Object that could not be encoded. 78 | * 79 | * @return the object. 80 | */ 81 | public Object getObject() { 82 | return this.object; 83 | } 84 | } 85 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/SendResult.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | /** 43 | * The result of asynchronously sending a web socket message. A SendResult is either 44 | * ok indicating there was no problem, or is not OK in which case there was a problem 45 | * and it carries an exception to indicate what the problem was. 46 | * 47 | * @author dannycoward 48 | */ 49 | final public class SendResult { 50 | 51 | private final Throwable exception; 52 | private final boolean isOK; 53 | 54 | /** 55 | * Construct a SendResult carrying an exception. 56 | * 57 | * @param exception the exception causing a send failure. 58 | */ 59 | public SendResult(Throwable exception) { 60 | this.exception = exception; 61 | this.isOK = false; 62 | } 63 | 64 | /** 65 | * Construct a SendResult signifying a successful send carrying no exception. 66 | */ 67 | public SendResult() { 68 | this.exception = null; 69 | this.isOK = true; 70 | } 71 | 72 | /** 73 | * The problem sending the message. 74 | * 75 | * @return the problem or {@code null} if the send was successful. 76 | */ 77 | public Throwable getException() { 78 | return exception; 79 | } 80 | 81 | /** 82 | * Determines if this result is ok or not. 83 | * 84 | * @return whether the send was successful or not. 85 | */ 86 | public boolean isOK() { 87 | return this.isOK; 88 | } 89 | } 90 | -------------------------------------------------------------------------------- /spec/chapters/security.tex: -------------------------------------------------------------------------------- 1 | \chapter{Server Security} 2 | \label{security} 3 | 4 | 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 \textbf{ws://} URI (as described in Chapters \ref{configuration} and \ref{annotations}) is protected in the deployment descriptor with a listing to a \textbf{http://} URI with same hostname, port and path since this is the URL of its opening handshake. 5 | Accordingly, websocket developers may assign an authentication scheme, user roles granted access and transport guarantee to their websocket endpoints. 6 | 7 | \section{Authentication of Websockets} 8 | 9 | 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 authenticated. 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. 10 | 11 | If a client sends an unauthenticated opening handshake request for a websocket that is protected by the security mechanism, the websocket implementation must return a \textbf{401 (Unauthorized)} response to the opening handshake request and may not initiate a websocket connection [WSC-8.1-1]. 12 | 13 | \section{Authorization of Websockets} 14 | 15 | A websocket’s authorization may be set by adding a \textbf{$<$security-constraint$>$} element to the \textbf{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] 16 | 17 | \section{Transport Guarantee} 18 | 19 | A transport guarantee of \textbf{NONE} must be interpreted by the container as allowing unencrypted \textbf{ws://} connections to the websocket [WSC-8.3-1]. A transport guarantee of \textbf{CONFIDENTIAL} must be interpreted by the implementation as only allowing access to the websocket over an encrypted (\textbf{wss://}) connection [WSC-8.3-2] This may require a pre-authenticated request. 20 | 21 | \section{Example} 22 | 23 | This example snippet from a larger web.xml deployment descriptor shows a security constraint for a websocket endpoint. In the example, the websocket endpoint which matches on an incoming request URI of \textbf{`quotes/live'} relative to the context root of the containing web application is protected such that it may only be accessed using \textbf{wss://}, and is available only to authenticated users who belong either to the \textbf{GOLD\_MEMBER} or \textbf{PLATINUM\_MEMBER} roles. 24 | 25 | \begin{listing}{1} 26 | 27 | 28 | 29 | LiveQuoteWebSocket 30 | 31 | 32 | Security constraint for 33 | live quote websocket endpoint 34 | 35 | /quotes/live 36 | GET 37 | 38 | 39 | 40 | definition of which roles 41 | may access the quote endpoint 42 | 43 | GOLD_MEMBER 44 | PLATINUM_MEMBER 45 | 46 | 47 | WSS required 48 | 49 | CONFIDENTIAL 50 | 51 | 52 | 53 | \end{listing} 54 | -------------------------------------------------------------------------------- /api/server/src/main/java/javax/websocket/server/PathParam.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket.server; 41 | 42 | import java.lang.annotation.ElementType; 43 | import java.lang.annotation.Retention; 44 | import java.lang.annotation.RetentionPolicy; 45 | import java.lang.annotation.Target; 46 | 47 | /** 48 | * This annotation may be used to annotate method parameters on server endpoints 49 | * where a URI-template has been used in the path-mapping of the {@link ServerEndpoint} 50 | * annotation. The method parameter may be of type String, any Java primitive 51 | * type or any boxed version thereof. If a client URI matches the URI-template, 52 | * but the requested path parameter cannot be decoded, then the websocket's error 53 | * handler will be called. 54 | * 55 | *

For example:- 56 | * 


57 |  * @ServerEndpoint("/bookings/{guest-id}")
58 |  * public class BookingServer {
59 |  * 
60 |  *     @OnMessage
61 |  *     public void processBookingRequest(@PathParam("guest-id") String guestID, String message, Session session) {
62 |  *         // process booking from the given guest here
63 |  *     }
64 |  * }
65 |  *
66 | * 67 | *

For example:- 68 | * 


69 |  * @ServerEndpoint("/rewards/{vip-level}")
70 |  * public class RewardServer {
71 |  * 
72 |  *     @OnMessage
73 |  *     public void processReward(@PathParam("vip-level") Integer vipLevel, String message, Session session) {
74 |  *         // process reward here
75 |  *     }
76 |  * }
77 |  *
78 | * 79 | * @author dannycoward 80 | */ 81 | @Retention(RetentionPolicy.RUNTIME) 82 | @Target(ElementType.PARAMETER) 83 | public @interface PathParam { 84 | 85 | /** 86 | * The name of the variable used in the URI-template. If the name does 87 | * not match a path variable in the URI-template, the value of the method parameter 88 | * this annotation annotates is {@code null}. 89 | * 90 | * @return the name of the variable used in the URI-template. 91 | */ 92 | public String value(); 93 | } 94 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/ContainerProvider.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | import java.util.ServiceLoader; 43 | 44 | /** 45 | * Provider class that allows the developer to get a reference to 46 | * the implementation of the WebSocketContainer. 47 | * The provider class uses the 48 | * ServiceLoader 49 | * to load an implementation of ContainerProvider. Specifically, the fully qualified classname 50 | * of the container implementation of ContainerProvider must be listed in the 51 | * META-INF/services/javax.websocket.ContainerProvider file in the implementation JAR file. 52 | * 53 | * @author dannycoward 54 | */ 55 | public abstract class ContainerProvider { 56 | 57 | /** 58 | * Obtain a new instance of a WebSocketContainer. The method looks for the 59 | * ContainerProvider implementation class in the order listed in the META-INF/services/javax.websocket.ContainerProvider 60 | * file, returning the WebSocketContainer implementation from the ContainerProvider implementation 61 | * that is not {@code null}. 62 | * @return an implementation provided instance of type WebSocketContainer 63 | */ 64 | public static WebSocketContainer getWebSocketContainer() { 65 | WebSocketContainer wsc = null; 66 | for (ContainerProvider impl : ServiceLoader.load(ContainerProvider.class)) { 67 | wsc = impl.getContainer(); 68 | if (wsc != null) { 69 | return wsc; 70 | } 71 | } 72 | if (wsc == null) { 73 | throw new RuntimeException("Could not find an implementation class."); 74 | } else { 75 | throw new RuntimeException("Could not find an implementation class with a non-null WebSocketContainer."); 76 | } 77 | } 78 | 79 | /** 80 | * Load the container implementation. 81 | * @return the implementation class 82 | */ 83 | protected abstract WebSocketContainer getContainer(); 84 | } 85 | 86 | 87 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/EndpointConfig.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | import java.util.List; 43 | import java.util.Map; 44 | 45 | /** 46 | * The endpoint configuration contains all the information needed during the handshake process 47 | * for this end point. All endpoints specify, for example, a URI. In the case of a server endpoint, 48 | * the URI signifies the URI to which the endpoint will be mapped. In the case of a client application 49 | * the URI signifies the URI of the server to which the client endpoint will attempt to connect. 50 | * 51 | * @author dannycoward 52 | */ 53 | public interface EndpointConfig { 54 | 55 | /** 56 | * Return the Encoder implementation classes configured. These 57 | * will be instantiated by the container to encode custom objects passed into 58 | * the send() methods on remote endpoints. 59 | * 60 | * @return the encoder implementation classes, an empty list if none. 61 | */ 62 | List> getEncoders(); 63 | 64 | /** 65 | * Return the Decoder implementation classes configured. These 66 | * will be instantiated by the container to decode incoming messages 67 | * into the expected custom objects on {@link MessageHandler.Whole#onMessage(Object)} 68 | * callbacks. 69 | * 70 | * @return the decoder implementation classes, the empty list if none. 71 | */ 72 | List> getDecoders(); 73 | 74 | /** 75 | * This method returns a modifiable Map that the developer may use to store application 76 | * specific information relating to the endpoint that uses this 77 | * configuration instance. Web socket applications running on distributed 78 | * implementations of the web container should make any application 79 | * specific objects stored here java.io.Serializable, or the object may 80 | * not be recreated after a failover. 81 | * 82 | * @return a modifiable Map of application data. 83 | */ 84 | Map getUserProperties(); 85 | } 86 | -------------------------------------------------------------------------------- /api/server/src/main/java/javax/websocket/server/ServerApplicationConfig.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket.server; 41 | 42 | import java.util.Set; 43 | import javax.websocket.Endpoint; 44 | 45 | /** 46 | * Developers include implementations of ServerApplicationConfig in an archive containing 47 | * websocket endpoints (WAR file, or JAR file within the WAR file) in order to specify the websocket 48 | * endpoints within the archive the implementation must deploy. There is a separate 49 | * method for programmatic endpoints and for annotated endpoints. 50 | * 51 | * @author dannycoward 52 | */ 53 | public interface ServerApplicationConfig { 54 | 55 | /** 56 | * Return a set of ServerEndpointConfig instances that the server container 57 | * will use to deploy the programmatic endpoints. The set of Endpoint classes passed in to this method is 58 | * the set obtained by scanning the archive containing the implementation 59 | * of this ServerApplicationConfig. This set passed in 60 | * may be used the build the set of ServerEndpointConfig instances 61 | * to return to the container for deployment. 62 | * 63 | * @param endpointClasses the set of all the Endpoint classes in the archive containing 64 | * the implementation of this interface. 65 | * @return the non-null set of ServerEndpointConfig s to deploy on the server, using the empty set to 66 | * indicate none. 67 | */ 68 | public Set getEndpointConfigs(Set> endpointClasses); 69 | 70 | /** 71 | * Return a set of annotated endpoint classes that the server container 72 | * must deploy. The set of classes passed in to this method is 73 | * the set obtained by scanning the archive containing the implementation 74 | * of this interface. Therefore, this set passed in contains all the annotated endpoint classes 75 | * in the JAR or WAR file containing the implementation of this interface. This set passed in 76 | * may be used the build the set to return to the container for deployment. 77 | * 78 | * @param scanned the set of all the annotated endpoint classes in the archive containing 79 | * the implementation of this interface. 80 | * @return the non-null set of annotated endpoint classes to deploy on the server, using the empty 81 | * set to indicate none. 82 | */ 83 | Set> getAnnotatedEndpointClasses(Set> scanned); 84 | } 85 | -------------------------------------------------------------------------------- /api/server/src/main/java/javax/websocket/server/ServerContainer.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket.server; 41 | 42 | import javax.websocket.*; 43 | /** 44 | * The ServerContainer is the specialized view of the WebSocketContainer available 45 | * in server-side deployments. There is one ServerContainer instance per 46 | * websocket application. The ServerContainer holds the methods to be able to 47 | * register server endpoints during the initialization phase of the application. 48 | *

For websocket enabled web containers, developers may 49 | * obtain a reference to the ServerContainer instance by retrieving it as an 50 | * attribute named javax.websocket.server.ServerContainer on the 51 | * ServletContext. This way, the registration methods held on this interface 52 | * may be called to register server endpoints from a ServletContextListener 53 | * during the deployment of the WAR file containing the endpoint. 54 | *

55 | *

WebSocket 56 | * implementations that run outside the web container may have other means 57 | * by which to provide a ServerContainer instance to the developer at application 58 | * deployment time. 59 | *

60 | *

Once the 61 | * application deployment phase is complete, and the websocket application has 62 | * begun accepting incoming connections, the registration methods may no 63 | * longer be called. 64 | * 65 | * @author dannycoward 66 | */ 67 | public interface ServerContainer extends WebSocketContainer { 68 | 69 | /** 70 | * Deploys the given annotated endpoint into this ServerContainer during the 71 | * initialization phase of deploying the application. 72 | * 73 | * @param endpointClass the class of the annotated endpoint 74 | * @throws DeploymentException if the annotated endpoint was badly formed. 75 | * @throws IllegalStateException if the containing websocket application has already 76 | * been deployed. 77 | */ 78 | public void addEndpoint(Class endpointClass) throws DeploymentException; 79 | /** 80 | * 81 | * @param serverConfig the configuration instance representing the logical endpoint 82 | * that will be registered. 83 | * @throws DeploymentException if the endpoint was badly formed. 84 | * @throws IllegalStateException if the containing websocket application has already 85 | * been deployed. 86 | */ 87 | public void addEndpoint(ServerEndpointConfig serverConfig) throws DeploymentException; 88 | 89 | } 90 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/ClientEndpoint.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | import java.lang.annotation.ElementType; 43 | import java.lang.annotation.Retention; 44 | import java.lang.annotation.RetentionPolicy; 45 | import java.lang.annotation.Target; 46 | 47 | /** 48 | * The ClientEndpoint annotation a class level annotation is used to denote that a POJO 49 | * is a web socket client and can be deployed as such. Similar to 50 | * {@link javax.websocket.server.ServerEndpoint}, POJOs that are 51 | * annotated with this annotation can have methods that, using the web socket method level annotations, 52 | * are web socket lifecycle methods. 53 | *

54 | * For example: 55 | * 


 56 |  * @ClientEndpoint(subprotocols="chat")
 57 |  * public class HelloServer {
 58 |  *
 59 |  *     @OnMessage
 60 |  *     public void processMessageFromServer(String message, Session session) {
 61 |  *         System.out.println("Message came from the server ! " + message);
 62 |  *     }
 63 |  *
 64 |  * }
 65 |  *
66 | * 67 | * @author dannycoward 68 | */ 69 | 70 | @Retention(RetentionPolicy.RUNTIME) 71 | @Target(ElementType.TYPE) 72 | public @interface ClientEndpoint { 73 | 74 | /** 75 | * The names of the subprotocols this client supports. 76 | * 77 | * @return the array of names of the subprotocols. 78 | */ 79 | String[] subprotocols() default {}; 80 | 81 | /** 82 | * The array of Java classes that are to act as Decoders for messages coming into 83 | * the client. 84 | * 85 | * @return the array of decoders. 86 | */ 87 | Class[] decoders() default {}; 88 | 89 | /** 90 | * The array of Java classes that are to act as Encoders for messages sent by the client. 91 | * 92 | * @return the array of decoders. 93 | */ 94 | Class[] encoders() default {}; 95 | 96 | /** 97 | * An optional custom configurator class that the developer would like to use 98 | * to provide custom configuration of new instances of this endpoint. The implementation 99 | * creates a new instance of the configurator per logical endpoint. 100 | * 101 | * @return the custom configurator class, or ClientEndpointConfigurator.class 102 | * if none was provided in the annotation. 103 | */ 104 | public Class configurator() default ClientEndpointConfig.Configurator.class; 105 | } 106 | -------------------------------------------------------------------------------- /api/server/src/main/java/javax/websocket/server/HandshakeRequest.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket.server; 41 | 42 | import java.net.URI; 43 | import java.security.Principal; 44 | import java.util.List; 45 | import java.util.Map; 46 | 47 | /** 48 | * The handshake request represents the web socket defined Http GET request 49 | * for the opening handshake of a web socket session. 50 | * 51 | * @author dannycoward 52 | */ 53 | public interface HandshakeRequest { 54 | /** 55 | * The Sec-WebSocket-Key header name 56 | */ 57 | static String SEC_WEBSOCKET_KEY = "Sec-WebSocket-Key"; 58 | /** 59 | * The Sec-WebSocket-Protocol header name 60 | */ 61 | static String SEC_WEBSOCKET_PROTOCOL = "Sec-WebSocket-Protocol"; 62 | /** 63 | * The Sec-WebSocket-Version header name 64 | */ 65 | static String SEC_WEBSOCKET_VERSION = "Sec-WebSocket-Version"; 66 | /** 67 | * The Sec-WebSocket-Extensions header name 68 | */ 69 | static String SEC_WEBSOCKET_EXTENSIONS = "Sec-WebSocket-Extensions"; 70 | 71 | /** 72 | * Return the read only Map of Http Headers that came with the handshake request. The header names 73 | * are case insensitive. 74 | * 75 | * @return the list of headers. 76 | */ 77 | Map> getHeaders(); 78 | 79 | /** 80 | * Return the authenticated user or {@code null} if no user is authenticated 81 | * for this handshake. 82 | * 83 | * @return the user principal. 84 | */ 85 | Principal getUserPrincipal(); 86 | 87 | /** 88 | * Return the request URI of the handshake request. 89 | * 90 | * @return the request uri of the handshake request. 91 | */ 92 | URI getRequestURI(); 93 | 94 | /** 95 | * Checks whether the current user is in the given role. Roles and role 96 | * membership can be defined using deployment descriptors of the containing 97 | * WAR file, if running in a Java EE web container. If the user has 98 | * not been authenticated, the method returns {@code false}. 99 | * 100 | * @param role the role being checked. 101 | * @return whether the authenticated user is in the role, or false if the user has not 102 | * been authenticated. 103 | */ 104 | boolean isUserInRole(String role); 105 | 106 | /** 107 | * Return a reference to the HttpSession that the web socket handshake that 108 | * started this conversation was part of, if the implementation 109 | * is part of a Java EE web container. 110 | * 111 | * @return the http session or {@code null} if either the websocket 112 | * implementation is not part of a Java EE web container, or there is 113 | * no HttpSession associated with the opening handshake request. 114 | */ 115 | Object getHttpSession(); 116 | 117 | /** 118 | * Return the request parameters associated with the request. 119 | * 120 | * @return the unmodifiable map of the request parameters. 121 | */ 122 | Map> getParameterMap(); 123 | 124 | /** 125 | * Return the query string associated with the request. 126 | * 127 | * @return the query string. 128 | */ 129 | String getQueryString(); 130 | } 131 | -------------------------------------------------------------------------------- /spec/chapters/exception.tex: -------------------------------------------------------------------------------- 1 | \chapter{Exception handling and Threading} 2 | 3 | \section{Threading Considerations} 4 | 5 | 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 implementation must fulfill certain threading requirements in order to provide the developer a consistent threading environment for their applications. 6 | 7 | Unless backed by a Java EE component with a different lifecycle (See Chapter \ref{javaee}), 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] 8 | 9 | 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] 10 | 11 | If the implementation decides to process an incoming message in parts, it must ensure that the corresponding \textbf{onMessage()} calls are called sequentially, and do not interleave either with parts of the same message or with other messages [WSC-5.1.5]. 12 | 13 | 14 | \section{Error Handling} 15 | \label{exception:error} 16 | 17 | There are three categories of errors (checked and unchecked Java exceptions) that this specification defines. 18 | 19 | \subsection{Deployment Errors} 20 | 21 | 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 \ref{annotations} 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] 22 | 23 | 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 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] 24 | 25 | 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. 26 | 27 | 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] 28 | 29 | \subsection{Errors Originating in Websocket Application Code} 30 | 31 | All errors arising during the functioning of a websocket endpoint must be caught by the websocket implementation. [WSC-5.2.2-1] Examples of these errors include checked exceptions generated by \textbf{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 \textbf{onError()} method in the case of programmatic endpoints, or by using the @OnError annotation in the case of annotated endpoints, the implementation must invoke the error handling method with the error. [WSC-5.2.2-2] 32 | 33 | 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] 34 | 35 | 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] 36 | 37 | \subsection{Errors Originating in the Container and/or Underlying Connection} 38 | 39 | A wide variety of runtime errors may occur during the functioning of an endpoint. These may including broken 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 \textbf{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 endpoint’s error handling method, if present, or by logging the error for later analysis. [WSC-5.2.3-1] 40 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/DefaultClientEndpointConfig.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | import java.util.Collections; 43 | import java.util.HashMap; 44 | import java.util.List; 45 | import java.util.Map; 46 | 47 | /** 48 | * The DefaultClientEndpointConfig is a concrete implementation of a client configuration. 49 | * 50 | * @author dannycoward 51 | */ 52 | final class DefaultClientEndpointConfig implements ClientEndpointConfig { 53 | private List preferredSubprotocols; 54 | private List extensions; 55 | private List> encoders; 56 | private List> decoders; 57 | private Map userProperties = new HashMap(); 58 | private ClientEndpointConfig.Configurator clientEndpointConfigurator; 59 | 60 | 61 | DefaultClientEndpointConfig( 62 | List preferredSubprotocols, 63 | List extensions, 64 | List> encoders, 65 | List> decoders, 66 | ClientEndpointConfig.Configurator clientEndpointConfigurator) { 67 | this.preferredSubprotocols = Collections.unmodifiableList(preferredSubprotocols); 68 | this.extensions = Collections.unmodifiableList(extensions); 69 | this.encoders = Collections.unmodifiableList(encoders); 70 | this.decoders = Collections.unmodifiableList(decoders); 71 | this.clientEndpointConfigurator = clientEndpointConfigurator; 72 | } 73 | 74 | /** 75 | * Return the protocols, in order of preference, favorite first, that this client would 76 | * like to use for its sessions. 77 | * 78 | * @return the preferred subprotocols. 79 | */ 80 | @Override 81 | public List getPreferredSubprotocols() { 82 | return this.preferredSubprotocols; 83 | } 84 | 85 | 86 | 87 | /** 88 | * Return the extensions, in order of preference, favorite first, that this client would 89 | * like to use for its sessions. 90 | * 91 | * @return the (unmodifiable) extension list. 92 | */ 93 | @Override 94 | public List getExtensions() { 95 | return this.extensions; 96 | } 97 | 98 | 99 | 100 | /** 101 | * Return the (unmodifiable) list of encoders this client will use. 102 | * 103 | * @return the encoder list. 104 | */ 105 | @Override 106 | public List> getEncoders() { 107 | return this.encoders; 108 | } 109 | 110 | 111 | 112 | /** 113 | * Return the (unmodifiable) list of decoders this client will use. 114 | * 115 | * @return the decoders to use. 116 | */ 117 | @Override 118 | public List> getDecoders() { 119 | return this.decoders; 120 | } 121 | 122 | 123 | /** 124 | * Editable map of user properties. 125 | */ 126 | @Override 127 | public final Map getUserProperties() { 128 | return this.userProperties; 129 | } 130 | 131 | @Override 132 | public ClientEndpointConfig.Configurator getConfigurator() { 133 | return this.clientEndpointConfigurator; 134 | } 135 | 136 | 137 | } 138 | -------------------------------------------------------------------------------- /spec/chapters/introduction.tex: -------------------------------------------------------------------------------- 1 | \chapter{Introduction} 2 | 3 | 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: 4 | 5 | \begin{itemize} 6 | \item The WebSocket Protocol specification \cite{rfc6455} 7 | \item The WebSocket API for JavaScript \cite{websocketsw3c} 8 | \end{itemize} 9 | 10 | \section{Purpose of this document} 11 | \label{purpose} 12 | 13 | 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. 14 | 15 | 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. 16 | 17 | \section{Goals of the Specification} 18 | 19 | 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. 20 | 21 | \section{Terminology used throughout the Specification} 22 | 23 | \begin{description} 24 | 25 | \item[endpoint] A websocket endpoint is a Java component that represents one side of a sequence of websocket interactions between two connected peers. 26 | 27 | \item[connection] A websocket connection is the networking connection between the two endpoints which are interacting using the websocket protocol. 28 | 29 | \item[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. 30 | 31 | \item[session] The term websocket session is used to represent a sequence of websocket interactions between an endpoint and a single peer. 32 | 33 | \item[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. 34 | 35 | \end{description} 36 | 37 | \section{Specification Conventions} 38 | 39 | 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 \cite{rfc2119}. 40 | 41 | 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 requirement, for example ‘WSC-12’. 42 | 43 | Java code and sample data fragments are formatted as shown in figure \ref{ex1}: 44 | 45 | \begin{figure}[hbtp] 46 | \caption{Example Java Code} 47 | \label{ex1} 48 | \begin{listing}{1} 49 | package com.example.hello; 50 | 51 | public class Hello { 52 | public static void main(String args[]) { 53 | System.out.println("Hello World"); 54 | } 55 | }\end{listing} 56 | \end{figure} 57 | 58 | URIs of the general form `http://example.org/...' and `http://example.com/...' represent application or context-dependent URIs. 59 | 60 | 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. 61 | 62 | \begin{nnnote*} 63 | This is a note. 64 | \end{nnnote*} 65 | 66 | \section{Expert Group Members} 67 | \label{expert_group} 68 | 69 | This specification was developed in the Java Community Process as part of JSR 356 \cite{jsr356}. 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 \cite{mailinglist}. The following are the expert group members: 70 | 71 | \begin{list}{$-$}{\parsep 0em \labelwidth 0em} 72 | \item Jean-Francois Arcand (Individual Member) 73 | \item Greg Wilkins (Intalio) 74 | \item Scott Ferguson (Caucho Technology, Inc) 75 | \item Joe Walnes (DRW Holdings, LLC) 76 | \item Minehiko IIDA (Fujitsu Limited) 77 | \item Wenbo Zhu (Google Inc.) 78 | \item Bill Wigger (IBM) 79 | \item Justin Lee (Individual Member) 80 | \item Danny Coward (Oracle) 81 | \item Rémy Maucherat (RedHat) 82 | \item Moon Namkoong (TmaxSoft, Inc.) 83 | \item Mark Thomas (VMware) 84 | \item Wei Chen (Voxeo Corporation) 85 | \item Rossen Stoyanchev (VMware) 86 | \end{list} 87 | 88 | \section{Acknowledgements} 89 | \label{acks} 90 | 91 | During the development of this specification we received many review comments, feedback and suggestions. Thanks in particular to: Jitendra Kotamraju, Martin Matula, \v{S}t\v{e}p\'an Kop\v{r}iva, Dhiru Panday, Jondean Healey, Joakim Erdfelt, Dianne Jiao, Michal \v{C}onos and Jan \v{S}upol. 92 | -------------------------------------------------------------------------------- /api/server/src/main/java/javax/websocket/server/ServerEndpoint.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket.server; 41 | 42 | import java.lang.annotation.ElementType; 43 | import java.lang.annotation.Retention; 44 | import java.lang.annotation.RetentionPolicy; 45 | import java.lang.annotation.Target; 46 | import javax.websocket.Decoder; 47 | import javax.websocket.Encoder; 48 | 49 | /** 50 | * This class level annotation declares that the class it decorates 51 | * is a web socket endpoint that will be deployed and made available in the URI-space 52 | * of a web socket server. The annotation allows the developer to 53 | * define the URL (or URI template) which this endpoint will be published, and other 54 | * important properties of the endpoint to the websocket runtime, such as the encoders 55 | * it uses to send messages. 56 | * 57 | *

The annotated class 58 | * must have a public no-arg constructor. 59 | * 60 | *

For example: 61 | * 


 62 |  * @ServerEndpoint("/hello");
 63 |  * public class HelloServer {
 64 |  *
 65 |  *     @OnMessage
 66 |  *     public void processGreeting(String message, Session session) {
 67 |  *         System.out.println("Greeting received:" + message);
 68 |  *     }
 69 |  *
 70 |  * }
 71 |  *
72 | * 73 | * @author dannycoward 74 | */ 75 | @Retention(RetentionPolicy.RUNTIME) 76 | @Target(ElementType.TYPE) 77 | public @interface ServerEndpoint { 78 | 79 | /** 80 | * The URI or URI-template, level-1 (See RFC 6570) where the endpoint will be deployed. The URI us relative to the 81 | * root of the web socket container and must begin with a leading "/". Trailing "/"'s are ignored. Examples: 82 | * 

 83 |      * @ServerEndpoint("/chat")
 84 |      * @ServerEndpoint("/chat/{user}")
 85 |      * @ServerEndpoint("/booking/{privilege-level}")
 86 |      *
87 | * 88 | * @return the URI or URI-template 89 | */ 90 | public String value(); 91 | 92 | /** 93 | * The ordered array of web socket protocols this endpoint supports. 94 | * For example, {"superchat", "chat"}. 95 | * 96 | * @return the subprotocols. 97 | */ 98 | public String[] subprotocols() default {}; 99 | 100 | /** 101 | * The ordered array of decoder classes this endpoint will use. For example, 102 | * if the developer has provided a MysteryObject decoder, this endpoint will be able to 103 | * receive MysteryObjects as web socket messages. The websocket runtime will use the first 104 | * decoder in the list able to decode a message, ignoring the remaining decoders. 105 | * 106 | * @return the decoders. 107 | */ 108 | public Class[] decoders() default {}; 109 | 110 | /** 111 | * The ordered array of encoder classes this endpoint will use. For example, 112 | * if the developer has provided a MysteryObject encoder, this class will be able to 113 | * send web socket messages in the form of MysteryObjects. The websocket runtime will use the first 114 | * encoder in the list able to encode a message, ignoring the remaining encoders. 115 | * 116 | * @return the encoders. 117 | */ 118 | public Class[] encoders() default {}; 119 | 120 | 121 | /** 122 | * The optional custom configurator class that the developer would like to use 123 | * to further configure new instances of this endpoint. If no configurator 124 | * class is provided, the implementation uses its own. The implementation 125 | * creates a new instance of the configurator per logical endpoint. 126 | * 127 | * @return the custom configuration class, or ServerEndpointConfig.Configurator.class 128 | * if none was set in the annotation. 129 | */ 130 | public Class configurator() default ServerEndpointConfig.Configurator.class; 131 | } 132 | -------------------------------------------------------------------------------- /websocket-1.1-changes.txt: -------------------------------------------------------------------------------- 1 | Java API for WebSocket 1.1 2 | ========================== 3 | 4 | (Updated May 21, 2014) 5 | 6 | Following is a description of the additions to the WebSocket 7 | API introduced in Java API for WebSocket 1.1. The values in 8 | parentheses are bug numbers; you can find more information 9 | about the bug reports at: 10 | 11 | https://java.net/jira/browse/WEBSOCKET_SPEC 12 | 13 | Please send comments and feedback to users@websocket-spec.java.net. 14 | 15 | =================================================================== 16 | 17 | 1. Session.addMessageHandler(MessageHandler) cannot work with lambda 18 | expressions (WEBSOCKET_SPEC-226) 19 | ------------------------------------ 20 | 21 | The method "Session.addMessageHandler(MessageHandler)" forces implementations 22 | to get the generic type of the message handler instance. The problem is that this 23 | information is not always available - for example for lambda expressions 24 | (MessageHandler is interface with only one method, thus can be replaced with 25 | lambda). There are other cases where this method does not work and any generics 26 | expert will confirm that this is not correctly defined; basically whenever 27 | there is no info in the class file for supplied argument, it cannot work. 28 | 29 | The solution is to add methods to register all extensions of the MessageHandler 30 | interface (there are two: MessageHandler.Partial and 31 | MessageHandler.Whole) with an additional parameter representing the handled type. 32 | A possible drawback is that this solution limits types to those expressible by 33 | a class object - for example, types with a generic parameter cannot be represented 34 | like this (we cannot do List.class). Currently there is no good 35 | alternative to this cleanly in Java, but it can still be worked around by 36 | creating a wrapper class such as: 37 | 38 | public class MyStringList implements List { 39 | ... 40 | } 41 | 42 | and declaring a message handler that uses it: 43 | 44 | public class MyMessageHandler implements MessageHandler.Whole { 45 | ... 46 | } 47 | 48 | which can be registered as: 49 | 50 | session.addMessageHandler(MyStringList.class, new MyMessageHandler()); 51 | 52 | Added methods: 53 | /** 54 | * Register to handle to incoming messages in this conversation. A maximum of one message handler per 55 | * native websocket message type (text, binary, pong) may be added to each Session. I.e. a maximum 56 | * of one message handler to handle incoming text messages a maximum of one message handler for 57 | * handling incoming binary messages, and a maximum of one for handling incoming pong 58 | * messages. For further details of which message handlers handle which of the native websocket 59 | * message types please see {@link MessageHandler.Whole} and {@link MessageHandler.Partial}. 60 | * Adding more than one of any one type will result in a runtime exception. 61 | * 62 | * @param clazz type of the message processed by message handler to be registered. 63 | * @param handler whole message handler to be added. 64 | * @throws IllegalStateException if there is already a MessageHandler registered for the same native 65 | * websocket message type as this handler. 66 | */ 67 | public void addMessageHandler(Class clazz, MessageHandler.Whole handler); 68 | 69 | /** 70 | * Register to handle to incoming messages in this conversation. A maximum of one message handler per 71 | * native websocket message type (text, binary, pong) may be added to each Session. I.e. a maximum 72 | * of one message handler to handle incoming text messages a maximum of one message handler for 73 | * handling incoming binary messages, and a maximum of one for handling incoming pong 74 | * messages. For further details of which message handlers handle which of the native websocket 75 | * message types please see {@link MessageHandler.Whole} and {@link MessageHandler.Partial}. 76 | * Adding more than one of any one type will result in a runtime exception. 77 | * 78 | * 79 | * @param clazz type of the message processed by message handler to be registered. 80 | * @param handler partial message handler to be added. 81 | * @throws IllegalStateException if there is already a MessageHandler registered for the same native 82 | * websocket message type as this handler. 83 | */ 84 | public void addMessageHandler(Class clazz, MessageHandler.Partial handler); 85 | 86 | Existing Session.addMessageHandler(MessageHandler) method is kept for backwards compatibility, but 87 | last paragraph is added to its javadoc ("This method is not safe..."): 88 | 89 | /** 90 | * Register to handle to incoming messages in this conversation. A maximum of one message handler per 91 | * native websocket message type (text, binary, pong) may be added to each Session. I.e. a maximum 92 | * of one message handler to handle incoming text messages a maximum of one message handler for 93 | * handling incoming binary messages, and a maximum of one for handling incoming pong 94 | * messages. For further details of which message handlers handle which of the native websocket 95 | * message types please see {@link MessageHandler.Whole} and {@link MessageHandler.Partial}. 96 | * Adding more than one of any one type will result in a runtime exception. 97 | *

98 | * This method is not safe to use unless you are providing anonymous class derived directly 99 | * from {@link javax.websocket.MessageHandler.Whole} or {@link javax.websocket.MessageHandler.Partial}. 100 | * Please consider using 101 | * {@link #addMessageHandler(Class, javax.websocket.MessageHandler.Whole)} or 102 | * {@link #addMessageHandler(Class, javax.websocket.MessageHandler.Partial)}. 103 | * 104 | * @param handler the MessageHandler to be added. 105 | * @throws IllegalStateException if there is already a MessageHandler registered for the same native 106 | * websocket message type as this handler. 107 | */ 108 | void addMessageHandler(MessageHandler handler) throws IllegalStateException; 109 | 110 | 111 | 112 | 113 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/Decoder.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | import java.io.IOException; 43 | import java.io.InputStream; 44 | import java.io.Reader; 45 | import java.nio.ByteBuffer; 46 | 47 | /** 48 | * The Decoder interface holds member interfaces that define how a developer can provide 49 | * the web socket container a way web socket messages into developer defined custom objects. 50 | * The websocket implementation creates a new instance of the decoder per endpoint 51 | * instance per connection. 52 | * The lifecycle of the Decoder instance is governed by the container calls to the 53 | * {@link Decoder#init(javax.websocket.EndpointConfig)} and {@link Decoder#destroy() } 54 | * methods. 55 | * 56 | * @author dannycoward 57 | */ 58 | public interface Decoder { 59 | 60 | /** 61 | * This method is called with the endpoint configuration object of the 62 | * endpoint this decoder is intended for when 63 | * it is about to be brought into service. 64 | * 65 | * @param config the endpoint configuration object when being brought into 66 | * service 67 | */ 68 | void init(EndpointConfig config); 69 | 70 | /** 71 | * This method is called when the decoder is about to be removed 72 | * from service in order that any resources the encoder used may 73 | * be closed gracefully. 74 | */ 75 | void destroy(); 76 | 77 | /** 78 | * This interface defines how a custom object (of type T) is decoded from a web socket message in 79 | * the form of a byte buffer. 80 | */ 81 | interface Binary extends Decoder { 82 | 83 | /** 84 | * Decode the given bytes into an object of type T. 85 | * 86 | * @param bytes the bytes to be decoded. 87 | * @return the decoded object. 88 | */ 89 | T decode(ByteBuffer bytes) throws DecodeException; 90 | 91 | /** 92 | * Answer whether the given bytes can be decoded into an object of type T. 93 | * 94 | * @param bytes the bytes to be decoded. 95 | * @return whether or not the bytes can be decoded by this decoder. 96 | */ 97 | boolean willDecode(ByteBuffer bytes); 98 | 99 | } 100 | 101 | /** 102 | * This interface defines how a custom object is decoded from a web socket message in 103 | * the form of a binary stream. 104 | */ 105 | interface BinaryStream extends Decoder { 106 | 107 | /** 108 | * Decode the given bytes read from the input stream into an object of type T. 109 | * 110 | * @param is the input stream carrying the bytes. 111 | * @return the decoded object. 112 | */ 113 | T decode(InputStream is) throws DecodeException, IOException; 114 | 115 | 116 | } 117 | 118 | /** 119 | * This interface defines how a custom object is decoded from a web socket message in 120 | * the form of a string. 121 | */ 122 | interface Text extends Decoder { 123 | /** 124 | * Decode the given String into an object of type T. 125 | * 126 | * @param s string to be decoded. 127 | * @return the decoded message as an object of type T 128 | */ 129 | T decode(String s) throws DecodeException; 130 | 131 | /** 132 | * Answer whether the given String can be decoded into an object of type T. 133 | * 134 | * @param s the string being tested for decodability. 135 | * @return whether this decoder can decoded the supplied string. 136 | */ 137 | boolean willDecode(String s); 138 | 139 | 140 | } 141 | 142 | /** 143 | * This interface defines how a custom object of type T is decoded from a web socket message in 144 | * the form of a character stream. 145 | */ 146 | interface TextStream extends Decoder { 147 | /** 148 | * Reads the websocket message from the implementation provided 149 | * Reader and decodes it into an instance of the supplied object type. 150 | * 151 | * @param reader the reader from which to read the web socket message. 152 | * @return the instance of the object that is the decoded web socket message. 153 | */ 154 | T decode(Reader reader) throws DecodeException, IOException; 155 | 156 | } 157 | } 158 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/MessageHandler.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | 43 | /** 44 | * Developers implement MessageHandlers in order to receive incoming messages 45 | * during a web socket conversation. 46 | * Each web socket session uses no more than one thread at a time to call its MessageHandlers. This means 47 | * that, provided each message handler instance is used to handle messages for one web socket session, at most 48 | * one thread at a time can be calling any of its methods. Developers who wish to handle messages from multiple 49 | * clients within the same message handlers may do so by adding the same instance as a handler on each of the Session 50 | * objects for the clients. In that case, they will need to code with the possibility of their MessageHandler 51 | * being called concurrently by multiple threads, each one arising from a different client session. 52 | * 53 | *

See {@link Endpoint} for a usage example. 54 | * 55 | * @author dannycoward 56 | */ 57 | public interface MessageHandler { 58 | 59 | /** 60 | * This kind of handler is notified by the container on arrival of a complete message. If the message is received in parts, 61 | * the container buffers it until it is has been fully received before this method is called. 62 | * 63 | *

For handling incoming text messages, the allowed types for T are 64 | *

    65 | *
  • {@link java.lang.String}
    • 66 | *
  • {@link java.io.Reader}
    • 67 | *
  • any developer object for which there is a corresponding {@link Decoder.Text} or 68 | * {@link Decoder.TextStream} configured
    • 69 | *
70 | * 71 | *

For handling incoming binary messages, the allowed types for T are 72 | *

    73 | *
  • {@link java.nio.ByteBuffer}
    • 74 | *
  • byte[]
    • 75 | *
  • {@link java.io.InputStream}
    • 76 | *
  • any developer object for which there is a corresponding {@link Decoder.Binary} or 77 | * {@link Decoder.BinaryStream} configured 78 | *
79 | * 80 | *

For handling incoming pong messages, the type of T is {@link PongMessage} 81 | * 82 | *

Developers should not continue to reference message objects of type {@link java.io.Reader}, {@link java.nio.ByteBuffer} 83 | * or {@link java.io.InputStream} after the completion of the onMessage() call, since they 84 | * may be recycled by the implementation. 85 | * 86 | * @param The type of the message object that this MessageHandler will consume. 87 | */ 88 | interface Whole extends MessageHandler { 89 | 90 | /** 91 | * Called when the message has been fully received. 92 | * 93 | * @param message the message data. 94 | */ 95 | void onMessage(T message); 96 | } 97 | 98 | /** 99 | * This kind of handler is notified by the implementation as it becomes ready 100 | * to deliver parts of a whole message. 101 | * 102 | *

For handling parts of text messages, the type T is {@link java.lang.String} 103 | * 104 | *

For handling parts of binary messages, the allowable types for T are 105 | *

    106 | *
  • {@link java.nio.ByteBuffer}
    • 107 | *
  • byte[]
    • 108 | *
109 | * 110 | *

Developers should not continue to reference message objects of type {@link java.nio.ByteBuffer} 111 | * after the completion of the onMessage() call, since they 112 | * may be recycled by the implementation. 113 | * 114 | *

Note: Implementations may choose their own schemes for delivering large messages in smaller parts through this API. These 115 | * schemes may or may not bear a relationship to the underlying websocket dataframes in which the message 116 | * is received off the wire. 117 | * 118 | * @param The type of the object that represent pieces of the incoming message that this MessageHandler will consume. 119 | */ 120 | interface Partial extends MessageHandler { 121 | 122 | /** 123 | * Called when the next part of a message has been fully received. 124 | * 125 | * @param partialMessage the partial message data. 126 | * @param last flag to indicate if this partialMessage is the last of the whole message being delivered. 127 | */ 128 | void onMessage(T partialMessage, boolean last); 129 | } 130 | } 131 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/DecodeException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | import java.nio.ByteBuffer; 43 | 44 | /** 45 | * A general exception that occurs when trying to decode a custom object from a text or binary message. 46 | * 47 | * @author dannycoward 48 | */ 49 | public class DecodeException extends Exception { 50 | private final ByteBuffer bb; 51 | private final String encodedString; 52 | private static final long serialVersionUID = 006; 53 | 54 | /** 55 | * Constructor with the binary data that could not be decoded, and the 56 | * reason why it failed to be, and the cause. The buffer may represent the 57 | * whole message, or the part of the message most relevant to the decoding 58 | * error, depending whether the application is using one 59 | * of the streaming methods or not. 60 | * 61 | * @param bb the byte buffer containing the (part of) the message that 62 | * could not be decoded. 63 | * @param message the reason for the failure. 64 | * @param cause the cause of the error. 65 | */ 66 | public DecodeException(ByteBuffer bb, String message, Throwable cause) { 67 | super(message, cause); 68 | this.encodedString = null; 69 | this.bb = bb; 70 | } 71 | 72 | /** 73 | * Constructor with the text data that could not be decoded, and the reason 74 | * why it failed to be, and the cause. The encoded string may represent the whole message, 75 | * or the part of the message most relevant to the decoding error, depending 76 | * whether the application is using one 77 | * of the streaming methods or not. 78 | * 79 | * @param encodedString the string representing the (part of) the message that could not be decoded. 80 | * @param message the reason for the failure. 81 | * @param cause the cause of the error. 82 | */ 83 | public DecodeException(String encodedString, String message, Throwable cause) { 84 | super(message, cause); 85 | this.encodedString = encodedString; 86 | this.bb = null; 87 | } 88 | 89 | /** 90 | * Constructs a DecodedException with the given ByteBuffer that cannot 91 | * be decoded, and reason why. The buffer may represent the 92 | * whole message, or the part of the message most relevant to the decoding 93 | * error, depending whether the application is using one 94 | * of the streaming methods or not. 95 | * 96 | * @param bb the byte buffer containing the (part of) the message that 97 | * could not be decoded. 98 | * @param message the reason for the failure. 99 | */ 100 | public DecodeException(ByteBuffer bb, String message) { 101 | super(message); 102 | this.encodedString = null; 103 | this.bb = bb; 104 | } 105 | 106 | /** 107 | * Constructs a DecodedException with the given encoded string that cannot 108 | * be decoded, and reason why. The encoded string may represent the whole message, 109 | * or the part of the message most relevant to the decoding error, depending 110 | * whether the application is using one 111 | * of the streaming methods or not. 112 | * 113 | * @param encodedString the string representing the (part of) the message that 114 | * could not be decoded. 115 | * @param message the reason for the failure. 116 | */ 117 | public DecodeException(String encodedString, String message) { 118 | super(message); 119 | this.encodedString = encodedString; 120 | this.bb = null; 121 | } 122 | 123 | /** 124 | * Return the ByteBuffer containing either the whole message, or the partial message, that 125 | * could not be decoded, or {@code null} if 126 | * this exception arose from a failure to decode a text message. 127 | * 128 | * @return the binary data not decoded or {@code null} for text message failures. 129 | */ 130 | public ByteBuffer getBytes() { 131 | return this.bb; 132 | } 133 | 134 | /** 135 | * Return the encoded string that is either the whole message, or the partial 136 | * message that could not be decoded, or {@code null} if 137 | * this exception arose from a failure to decode a binary message.. 138 | * 139 | * @return the text not decoded or {@code null} for binary message failures. 140 | */ 141 | public String getText() { 142 | return this.encodedString; 143 | } 144 | } 145 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/Encoder.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | import java.io.IOException; 43 | import java.io.OutputStream; 44 | import java.io.Writer; 45 | import java.nio.ByteBuffer; 46 | 47 | /** 48 | * The Encoder interface defines how developers can provide a way to convert 49 | * their custom objects into web socket messages. The Encoder interface contains 50 | * subinterfaces that allow encoding algorithms to encode custom objects to: text, 51 | * binary data, character stream and write to an output stream. 52 | * The websocket implementation creates a new instance of the encoder per 53 | * endpoint instance per connection. This means that each encoder instance has 54 | * at most one calling thread at a time. 55 | * The lifecycle of the Encoder instance is governed by the container calls to the 56 | * {@link Encoder#init(javax.websocket.EndpointConfig)} and {@link Encoder#destroy() } 57 | * methods. 58 | * 59 | * @author dannycoward 60 | */ 61 | public interface Encoder { 62 | 63 | /** 64 | * This method is called with the endpoint configuration object of the 65 | * endpoint this encoder is intended for when 66 | * it is about to be brought into service. 67 | * 68 | * @param config the endpoint configuration object when being brought into 69 | * service 70 | */ 71 | void init(EndpointConfig config); 72 | 73 | /** 74 | * This method is called when the encoder is about to be removed 75 | * from service in order that any resources the encoder used may 76 | * be closed gracefully. 77 | */ 78 | void destroy(); 79 | 80 | /** 81 | * This interface defines how to provide a way to convert a custom 82 | * object into a text message. 83 | * 84 | * @param The type of the custom developer object that this Encoder can encode into a String. 85 | */ 86 | interface Text extends Encoder { 87 | /** 88 | * Encode the given object into a String. 89 | * 90 | * @param object the object being encoded. 91 | * @return the encoded object as a string. 92 | */ 93 | String encode(T object) throws EncodeException; 94 | 95 | } 96 | 97 | /** 98 | * This interface may be implemented by encoding algorithms 99 | * that want to write the encoded object to a character stream. 100 | * 101 | * @param the type of the object this encoder can encode to a CharacterStream. 102 | */ 103 | interface TextStream extends Encoder { 104 | /** 105 | * Encode the given object to a character stream writing it 106 | * to the supplied Writer. Implementations of this method may use the EncodeException 107 | * to indicate a failure to convert the supplied object to an encoded form, and may 108 | * use the IOException to indicate a failure to write the data to the supplied 109 | * stream. 110 | * 111 | * @param object the object to be encoded. 112 | * @param writer the writer provided by the web socket runtime to write the encoded data. 113 | * @throws EncodeException if there was an error encoding the object due to its state. 114 | * @throws IOException if there was an exception writing to the writer. 115 | */ 116 | void encode(T object, Writer writer) throws EncodeException, IOException; 117 | } 118 | 119 | /** 120 | * This interface defines how to provide a way to convert a custom 121 | * object into a binary message. 122 | * 123 | * @param The type of the custom object that this Encoder can encoder to a ByteBuffer. 124 | */ 125 | interface Binary extends Encoder { 126 | /** 127 | * Encode the given object into a byte array. 128 | * 129 | * @param object the object being encoded. 130 | * @return the binary data. 131 | */ 132 | ByteBuffer encode(T object) throws EncodeException; 133 | } 134 | 135 | /** 136 | * This interface may be implemented by encoding algorithms 137 | * that want to write the encoded object to a binary stream. 138 | * 139 | * @param the type of the object this encoder can encode. 140 | */ 141 | interface BinaryStream extends Encoder { 142 | /** 143 | * Encode the given object into a binary stream written to the 144 | * implementation provided OutputStream. 145 | * 146 | * @param object the object being encoded. 147 | * @param os the output stream where the encoded data is written. 148 | */ 149 | void encode(T object, OutputStream os) throws EncodeException, IOException; 150 | } 151 | } 152 | -------------------------------------------------------------------------------- /api/server/src/main/java/javax/websocket/server/DefaultServerEndpointConfig.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket.server; 41 | 42 | import java.util.Collections; 43 | import java.util.HashMap; 44 | import java.util.List; 45 | import java.util.Map; 46 | import javax.websocket.Decoder; 47 | import javax.websocket.Encoder; 48 | import javax.websocket.Endpoint; 49 | import javax.websocket.Extension; 50 | 51 | 52 | /** 53 | * The DefaultServerEndpointConfig is a concrete class that embodies all the configuration 54 | * parameters for an endpoint that is to be published as a server endpoint. Developers may 55 | * subclass this class in order to override the configuration behavior. 56 | * 57 | * @author dannycoward 58 | */ 59 | final class DefaultServerEndpointConfig implements ServerEndpointConfig { 60 | private String path; 61 | private Class endpointClass; 62 | private List subprotocols; 63 | private List extensions; 64 | private List> encoders; 65 | private List> decoders; 66 | private Map userProperties = new HashMap(); 67 | private ServerEndpointConfig.Configurator serverEndpointConfigurator; 68 | 69 | 70 | // The builder ensures nothing except configurator can be {@code null}. 71 | DefaultServerEndpointConfig(Class endpointClass, 72 | String path, 73 | List subprotocols, 74 | List extensions, 75 | List> encoders, 76 | List> decoders, 77 | ServerEndpointConfig.Configurator serverEndpointConfigurator) { 78 | this.path = path; 79 | this.endpointClass = endpointClass; 80 | this.subprotocols = Collections.unmodifiableList(subprotocols); 81 | this.extensions = Collections.unmodifiableList(extensions); 82 | this.encoders = Collections.unmodifiableList(encoders); 83 | this.decoders = Collections.unmodifiableList(decoders); 84 | if (serverEndpointConfigurator == null) { 85 | this.serverEndpointConfigurator = ServerEndpointConfig.Configurator.fetchContainerDefaultConfigurator(); 86 | } else{ 87 | this.serverEndpointConfigurator = serverEndpointConfigurator; 88 | } 89 | } 90 | 91 | /** 92 | * Returns the class of the Endpoint that this configuration configures. 93 | * 94 | * @return the class of the Endpoint. 95 | */ 96 | @Override 97 | public Class getEndpointClass() { 98 | return this.endpointClass; 99 | } 100 | 101 | 102 | /** 103 | * Creates a server configuration with the given path 104 | * 105 | * @param path the URI or URI template. 106 | */ 107 | DefaultServerEndpointConfig(Class endpointClass, String path) { 108 | this.path = path; 109 | this.endpointClass = endpointClass; 110 | } 111 | 112 | /** 113 | * Return the Encoder implementation classes configured. These 114 | * will be used by the container to encode outgoing messages. 115 | * 116 | * @return the encoder implementation classes, in an unmodifiable list, empty if there are none. 117 | */ 118 | @Override 119 | public List> getEncoders() { 120 | return this.encoders; 121 | } 122 | 123 | /** 124 | * Return the Decoder implementation classes configured. These 125 | * will be used by the container to decode incoming messages 126 | * into the expected custom objects on MessageHandler 127 | * callbacks. 128 | * 129 | * @return the decoder implementation classes, in an unmodifiable list. 130 | */ 131 | @Override 132 | public List> getDecoders() { 133 | return this.decoders; 134 | } 135 | 136 | /** 137 | * Return the path of this server configuration. The path is a relative URI 138 | * or URI-template. 139 | * 140 | * @return the path 141 | */ 142 | @Override 143 | public String getPath() { 144 | return path; 145 | } 146 | 147 | 148 | /** 149 | * Return the ServerEndpointConfigurator 150 | * @return the ServerEndpointConfigurator 151 | */ 152 | @Override 153 | public ServerEndpointConfig.Configurator getConfigurator() { 154 | return this.serverEndpointConfigurator; 155 | } 156 | 157 | /** 158 | * Editable map of user properties. 159 | */ 160 | @Override 161 | public final Map getUserProperties() { 162 | return this.userProperties; 163 | } 164 | 165 | @Override 166 | public final List getSubprotocols() { 167 | return this.subprotocols; 168 | } 169 | 170 | @Override 171 | public final List getExtensions() { 172 | return this.extensions; 173 | } 174 | 175 | } 176 | -------------------------------------------------------------------------------- /spec/chapters/packaging.tex: -------------------------------------------------------------------------------- 1 | \chapter{Packaging and Deployment} 2 | 3 | Java WebSocket applications are packaged using the usual conventions of the Java Platform. 4 | 5 | \section{Client Deployment on JDK} 6 | 7 | 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. 8 | 9 | The client container is not required to automatically scan the JAR file for websocket client endpoints and deploy them. 10 | 11 | Obtaining a reference to the \textbf{WebSocketContainer} using the \textbf{ContainerProvider} class, the developer deploys both programmatic endpoints and annotated endpoints using the \textbf{connectToServer()} APIs on the \textbf{WebSocketContainer}. 12 | 13 | \section{Application Deployment on Web Containers} 14 | 15 | 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 \textbf{WEB-INF/classes} or packaged as a JAR file and located under \textbf{WEB-INF/lib}. 16 | 17 | Java EE containers are not required to support deployment of websocket endpoints if they are not packaged in a WAR file as described above. 18 | 19 | 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 \textbf{@ServerEndpoint} and classes that extend \textbf{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 implementations of the \textbf{ServerApplicationConfig} interface packaged within the WAR file (or in any of its sub-JAR files). [WSC-6.2-2] 20 | 21 | If scan of the WAR file locates one or more \textbf{ServerApplicationConfig} implementations, the websocket implementation must instantiate each of the \textbf{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 methods. [WSC-6.2-4] The set that is the union of all the results obtained by calling the \textbf{getEndpointConfigs()} and \textbf{getAnnotatedEndpointClasses()} on the \textbf{ServerApplicationConfig} classes (that is to say, the annotated endpoint classes and configuration objects for programmatic endpoints) is the set that the websocket implementation must deploy. [WSC-6.2-5] 22 | 23 | If the WAR file contains no \textbf{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 deployed without a corresponding \textbf{ServerEndpointConfig}, if there are no \textbf{ServerApplicationConfig} implementations to provide these configuration objects, no programmatic endpoints can be deployed. 24 | 25 | \begin{nnnote} 26 | 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 \textbf{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 \textbf{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. 27 | \end{nnnote} 28 | 29 | \section{Application Deployment in Standalone Websocket Server Containers} 30 | 31 | This specification recommends standalone websocket server containers (i.e. those that do not include a servlet container) locates any websocket server endpoints and \textbf{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. 32 | 33 | \section{Programmatic Server Deployment} 34 | 35 | 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 \textbf{addEndpoint} methods of the \textbf{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. 36 | 37 | When running on the web container, the \textbf{addEndpoint} methods may be called from a \textbf{javax.servlet.ServletContextListener} provided by the developer and configured in the deployment descriptor of the web application. The websocket implementation must make the \textbf{ServerContainer} instance corresponding to this application available to the developer as a \textbf{ServletContext} attribute registered under the name \textbf{javax.websocket.server.ServerContainer}. 38 | 39 | 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 \textbf{ServerContainer} instance available to the developer at this time. 40 | 41 | It is recommended that developers use either the programmatic deployment API, or base their application on the scanning and \textbf{ServerApplicationConfig} mechanism, but not mix both methods. Developers can suppress a deployment by scan of the endpoints in the WAR file by providing a \textbf{ServerApplicationConfig} that returns empty sets from its methods. 42 | 43 | If however, the developer does mix both modes of deployment, it is possible in the case of annotated endpoints, 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. 44 | 45 | \section{Websocket Server Paths} 46 | 47 | Websocket implementations that include server functionality must define a root or the URI space for websockets. 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] 48 | 49 | \section{Platform Versions} 50 | 51 | The minimum versions of the Java platforms are: 52 | 53 | \begin{itemize} 54 | \item Java SE version 7, for the Java WebSocket client API [WSC-6.5-1]. 55 | \item Java EE version 6, for the Java WebSocket server API [WSC-6.5-2]. 56 | \end{itemize} 57 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/OnMessage.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | import java.lang.annotation.ElementType; 43 | import java.lang.annotation.Retention; 44 | import java.lang.annotation.RetentionPolicy; 45 | import java.lang.annotation.Target; 46 | 47 | /** 48 | * This method level annotation can be used to make a Java method receive incoming web socket messages. Each websocket 49 | * endpoint may only have one message handling method for each of the native websocket message formats: text, binary and pong. Methods 50 | * using this annotation are allowed to have 51 | * parameters of types described below, otherwise the container will generate an error at deployment time. 52 | *

The allowed parameters are: 53 | *

    54 | *
  1. Exactly one of any of the following choices 55 | *
      56 | *
    • if the method is handling text messages: 57 | *
        58 | *
      • {@link java.lang.String} to receive the whole message
        • 59 | *
      • Java primitive or class equivalent to receive the whole message converted to that type
        • 60 | *
      • String and boolean pair to receive the message in parts
        • 61 | *
      • {@link java.io.Reader} to receive the whole message as a blocking stream
        • 62 | *
      • any object parameter for which the endpoint has a text decoder ({@link Decoder.Text} or 63 | * {@link Decoder.TextStream}).
        • 64 | *
      65 | *
      • 66 | *
    • if the method is handling binary messages: 67 | *
        68 | *
      • byte[] or {@link java.nio.ByteBuffer} to receive the whole message
        • 69 | *
      • byte[] and boolean pair, or {@link java.nio.ByteBuffer} and boolean pair to receive the message in parts
        • 70 | *
      • {@link java.io.InputStream} to receive the whole message as a blocking stream
        • 71 | *
      • any object parameter for which the endpoint has a binary decoder ({@link Decoder.Binary} or 72 | * {@link Decoder.BinaryStream}).
        • 73 | *
      74 | *
      • 75 | *
    • if the method is handling pong messages: 76 | *
        77 | *
      • {@link PongMessage} for handling pong messages
        • 78 | *
      79 | *
      • 80 | *
    81 | *
    2. 82 | *
  2. and Zero to n String or Java primitive parameters 83 | * annotated with the {@link javax.websocket.server.PathParam} annotation for server endpoints.
    3. 84 | *
  3. and an optional {@link Session} parameter
    4. 85 | *
86 | *

87 | * The parameters may be listed in any order. 88 | * 89 | *

The method may have a non-void return type, in which case the web socket 90 | * runtime must interpret this as a web socket message to return to the peer. 91 | * The allowed data types for this return type, other than void, are String, 92 | * ByteBuffer, byte[], any Java primitive or class equivalent, and anything for 93 | * which there is an encoder. If the method uses a Java primitive as a return 94 | * value, the implementation must construct the text message to send using the 95 | * standard Java string representation of the Java primitive unless there developer 96 | * provided encoder for the type configured for this endpoint, in which 97 | * case that encoder must be used. If the method uses 98 | * a class equivalent of a Java primitive as a return value, the implementation 99 | * must construct the text message from the Java primitive equivalent as 100 | * described above. 101 | * 102 | *

Developers should 103 | * note that if developer closes the session during the invocation of a method with a return type, the method will complete but the 104 | * return value will not be delivered to the remote endpoint. The send failure will be passed back into the endpoint's error handling method. 105 | * 106 | *

For example: 107 | * 


108 |  * @OnMessage
109 |  * public void processGreeting(String message, Session session) {
110 |  *     System.out.println("Greeting received:" + message);
111 |  * }
112 |  *
113 | * For example: 114 | * 

115 |  * @OnMessage
116 |  * public void processUpload(byte[] b, boolean last, Session session) {
117 |  *     // process partial data here, which check on last to see if these is more on the way
118 |  * }
119 |  *
120 | * Developers should not continue to reference message objects of type {@link java.io.Reader}, {@link java.nio.ByteBuffer} 121 | * or {@link java.io.InputStream} after the annotated method has completed, since they 122 | * may be recycled by the implementation. 123 | * 124 | * @author dannycoward 125 | */ 126 | @Retention(RetentionPolicy.RUNTIME) 127 | @Target(ElementType.METHOD) 128 | public @interface OnMessage { 129 | 130 | /** 131 | * Specifies the maximum size of message in bytes that the method 132 | * this annotates will be able to process, or -1 to indicate 133 | * that there is no maximum. The default is -1. This attribute only 134 | * applies when the annotation is used to process whole messages, not to 135 | * those methods that process messages in parts or use a stream or reader 136 | * parameter to handle the incoming message. 137 | * If the incoming whole message exceeds this limit, then the implementation 138 | * generates an error and closes the connection using the reason that 139 | * the message was too big. 140 | * 141 | * @return the maximum size in bytes. 142 | */ 143 | public long maxMessageSize() default -1; 144 | } 145 | -------------------------------------------------------------------------------- /api/client/src/main/java/javax/websocket/Endpoint.java: -------------------------------------------------------------------------------- 1 | /* 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 3 | * 4 | * Copyright (c) 2012-2017 Oracle and/or its affiliates. All rights reserved. 5 | * 6 | * The contents of this file are subject to the terms of either the GNU 7 | * General Public License Version 2 only ("GPL") or the Common Development 8 | * and Distribution License("CDDL") (collectively, the "License"). You 9 | * may not use this file except in compliance with the License. You can 10 | * obtain a copy of the License at 11 | * http://glassfish.java.net/public/CDDL+GPL_1_1.html 12 | * or packager/legal/LICENSE.txt. See the License for the specific 13 | * language governing permissions and limitations under the License. 14 | * 15 | * When distributing the software, include this License Header Notice in each 16 | * file and include the License file at packager/legal/LICENSE.txt. 17 | * 18 | * GPL Classpath Exception: 19 | * Oracle designates this particular file as subject to the "Classpath" 20 | * exception as provided by Oracle in the GPL Version 2 section of the License 21 | * file that accompanied this code. 22 | * 23 | * Modifications: 24 | * If applicable, add the following below the License Header, with the fields 25 | * enclosed by brackets [] replaced by your own identifying information: 26 | * "Portions Copyright [year] [name of copyright owner]" 27 | * 28 | * Contributor(s): 29 | * If you wish your version of this file to be governed by only the CDDL or 30 | * only the GPL Version 2, indicate your decision by adding "[Contributor] 31 | * elects to include this software in this distribution under the [CDDL or GPL 32 | * Version 2] license." If you don't indicate a single choice of license, a 33 | * recipient has the option to distribute your version of this file under 34 | * either the CDDL, the GPL Version 2 or to extend the choice of license to 35 | * its licensees as provided above. However, if you add GPL Version 2 code 36 | * and therefore, elected the GPL Version 2 license, then the option applies 37 | * only if the new code is made subject to such option by the copyright 38 | * holder. 39 | */ 40 | package javax.websocket; 41 | 42 | 43 | /** 44 | * The Web Socket Endpoint represents an object that can handle websocket conversations. 45 | * Developers may extend this class in order to implement a programmatic websocket 46 | * endpoint. The Endpoint class holds lifecycle methods that may be 47 | * overridden to intercept websocket open, error and close events. By implementing 48 | * the {@link Endpoint#onOpen(javax.websocket.Session, javax.websocket.EndpointConfig) onOpen} method, the programmatic endpoint gains access to the {@link Session} object, 49 | * to which the developer may add {@link MessageHandler} implementations in order to 50 | * intercept incoming websocket messages. Each instance 51 | * of a websocket endpoint is guaranteed not to be called by more than one thread 52 | * at a time per active connection. 53 | * 54 | *

If deployed as a client endpoint, it will be instantiated once for the 55 | * single connection to the server. 56 | * 57 | *

When deployed as a server endpoint, the implementation uses the 58 | * {@link javax.websocket.server.ServerEndpointConfig.Configurator#getEndpointInstance} 59 | * method to obtain the 60 | * endpoint instance it will use for each new client connection. If the developer uses 61 | * the default {@link javax.websocket.server.ServerEndpointConfig.Configurator}, 62 | * there will be precisely one 63 | * endpoint instance per active client connection. Consequently, in this typical 64 | * case, when implementing/overriding the methods of Endpoint, the developer is 65 | * guaranteed that there will be at most one thread calling each endpoint instance 66 | * at a time. 67 | * 68 | *

If the developer provides a custom {@link javax.websocket.server.ServerEndpointConfig.Configurator} 69 | * which overrides the default policy for endpoint instance creation, for example, 70 | * using a single Endpoint instance for multiple client connections, the developer 71 | * may need to write code that can execute concurrently. 72 | * 73 | *

Here is an example of a simple endpoint that echoes any incoming text message back to the sender. 74 | * 


 75 |  * public class EchoServer extends Endpoint {
 76 |  *
 77 |  *     public void onOpen(Session session, EndpointConfig config) {
 78 |  *         final RemoteEndpoint remote = session.getBasicRemote();
 79 |  *         session.addMessageHandler(String.class, new MessageHandler.Whole<String>() {
 80 |  *             public void onMessage(String text) {
 81 |  *                 try {
 82 |  *                     remote.sendString("Got your message (" + text + "). Thanks !");
 83 |  *                 } catch (IOException ioe) {
 84 |  *                     // handle send failure here
 85 |  *                 }
 86 |  *             }
 87 |  *         });
 88 |  *     }
 89 |  *
 90 |  * }
 91 |  *
92 | * 93 | * @author dannycoward 94 | */ 95 | public abstract class Endpoint { 96 | 97 | /** 98 | * Developers must implement this method to be notified when a new conversation has 99 | * just begun. 100 | * 101 | * @param session the session that has just been activated. 102 | * @param config the configuration used to configure this endpoint. 103 | */ 104 | public abstract void onOpen(Session session, EndpointConfig config); 105 | 106 | /** 107 | * This method is called immediately prior to the session with the remote 108 | * peer being closed. It is called whether the session is being closed 109 | * because the remote peer initiated a close and sent a close frame, or 110 | * whether the local websocket container or this endpoint requests to close 111 | * the session. The developer may take this last opportunity to retrieve 112 | * session attributes such as the ID, or any application data it holds before 113 | * it becomes unavailable after the completion of the method. Developers should 114 | * not attempt to modify the session from within this method, or send new 115 | * messages from this call as the underlying 116 | * connection will not be able to send them at this stage. 117 | * 118 | * @param session the session about to be closed. 119 | * @param closeReason the reason the session was closed. 120 | */ 121 | public void onClose(Session session, CloseReason closeReason) { 122 | } 123 | 124 | /** 125 | * Developers may implement this method when the web socket session 126 | * creates some kind of error that is not modeled in the web socket protocol. This may for example 127 | * be a notification that an incoming message is too big to handle, or that the incoming message could not be encoded. 128 | * 129 | *

There are a number of categories of exception that this method is (currently) defined to handle: 130 | *

    131 | *
  • connection problems, for example, a socket failure that occurs before 132 | * the web socket connection can be formally closed. These are modeled as 133 | * {@link SessionException}s
    • 134 | *
  • runtime errors thrown by developer created message handlers calls.
    • 135 | *
  • conversion errors encoding incoming messages before any message handler has been called. These 136 | * are modeled as {@link DecodeException}s
    • 137 | *
138 | * 139 | * @param session the session in use when the error occurs. 140 | * @param thr the throwable representing the problem. 141 | */ 142 | public void onError(Session session, Throwable thr) { 143 | } 144 | } 145 | -------------------------------------------------------------------------------- /spec/chapters/license.tex: -------------------------------------------------------------------------------- 1 | \begin{flushleft} 2 | 3 | {\bfseries JSR 356 Java\texttrademark\ API for WebSocket (\lq\lq Specification\rq\rq)\\ 4 | Version: 1.1 \\ 5 | Status: Maintenance Draft Review \\ 6 | Release: \today\\ 7 | Copyright 2011-2014 Oracle America, Inc. (``Oracle'') \\ 8 | 500 Oracle Parkway, Redwood Shores, California 94065, U.S.A\\ 9 | All rights reserved. 10 | } 11 | 12 | \mbox{}\\ 13 | 14 | {\bfseries NOTICE} 15 | 16 | The Specification is protected by copyright and the information described therein may be protected by one or more U.S. patents, foreign patents, or pending applications. Except as provided under the following license, no part of the Specification may be reproduced in any form by any means without the prior written authorization of Oracle America, Inc. (``Oracle'') and its licensors, if any. Any use of the Specification and the information described therein will be governed by the terms and conditions of this Agreement. 17 | 18 | Subject to the terms and conditions of this license, including your compliance with Paragraphs 1 and 2 below, Oracle hereby grants you a fully-paid, non-exclusive, non-transferable, limited license (without the right to sublicense) under Oracle's intellectual property rights to: 19 | 20 | 1.Review the Specification for the purposes of evaluation. This includes: (i) developing implementations of the Specification for your internal, non-commercial use; (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 Technology. 21 | 22 | 2.Distribute implementations of the Specification to third parties for their testing and evaluation use, provided that any such implementation: 23 | (i) 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; 24 | (ii) is clearly and prominently marked with the word ``UNTESTED'' or ``EARLY ACCESS'' or ``INCOMPATIBLE'' or ``UNSTABLE'' or ``BETA'' in any list of available builds and in proximity to every link initiating its download, where the list or link is under Licensee's control; and 25 | (iii) includes the following notice: 26 | ``This is an implementation of an early-draft specification developed under the Java Community Process (JCP) and is made available for testing and evaluation purposes only. The code is not compatible with any specification of the JCP.'' 27 | The grant set forth above concerning your distribution of implementations of the specification is contingent upon your agreement to terminate development and distribution of your ``early draft'' implementation as soon as feasible following final completion of the specification. If you fail to do so, the foregoing grant shall be considered null and void. 28 | No provision of this Agreement shall be understood to restrict your ability to make and distribute to third parties applications written to the Specification. 29 | Other than this limited license, you acquire no right, title or interest in or to the Specification or any other Oracle intellectual property, and the Specification may only be used in accordance with the license terms set forth herein. This license will expire on the earlier of: (a) two (2) years from the date of Release listed above; (b) the date on which the final version of the Specification is publicly released; or (c) the date on which the Java Specification Request (JSR) to which the Specification corresponds is withdrawn. In addition, this license will terminate immediately without notice from Oracle if you fail to comply with any provision of this license. Upon termination, you must cease use of or destroy the Specification. 30 | ``Licensor Name Space'' means the public class or interface declarations whose names begin with ``java'', ``javax'', ``com.oracle'' or their equivalents in any subsequent naming convention adopted by Oracle through the Java Community Process, or any recognized successors or replacements thereof. 31 | 32 | {\bfseries TRADEMARKS} 33 | 34 | No right, title, or interest in or to any trademarks, service marks, or trade names of Oracle or Oracle's licensors is granted hereunder. Oracle, the Oracle logo, Java are trademarks or registered trademarks of Oracle USA, Inc. in the U.S. and other countries. 35 | 36 | {\bfseries DISCLAIMER OF WARRANTIES} 37 | 38 | THE SPECIFICATION IS PROVIDED ``AS IS'' AND IS EXPERIMENTAL AND MAY CONTAIN DEFECTS OR DEFICIENCIES WHICH CANNOT OR WILL NOT BE CORRECTED BY ORACLE. ORACLE MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT THAT THE CONTENTS OF THE SPECIFICATION ARE 39 | SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not represent any commitment to release or implement any portion of the Specification in any product. 40 | 41 | THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW VERSIONS OF THE SPECIFICATION, IF ANY. ORACLE MAY MAKE IMPROVEMENTS AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THE SPECIFICATION AT ANY TIME. Any use of such changes in the Specification will be governed by the then-current license for the applicable version of the Specification. 42 | 43 | {\bfseries LIMITATION OF LIABILITY} 44 | 45 | TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL ORACLE 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 TO ANY FURNISHING, PRACTICING, MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF ORACLE AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 46 | 47 | You will hold Oracle (and its licensors) harmless from any claims based on your use of the Specification for any purposes other than the limited right of evaluation as described above, and from any claims that later versions or releases of any Specification furnished to you are incompatible with the Specification provided to you under this license. 48 | 49 | {\bfseries RESTRICTED RIGHTS LEGEND} 50 | 51 | If this Software 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). 52 | 53 | {\bfseries REPORT} 54 | 55 | You may wish to report any ambiguities, inconsistencies or inaccuracies you may find in connection with your evaluation of the Specification (``Feedback''). To the extent that you provide Oracle with any Feedback, you hereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential basis, and (ii) grant Oracle 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 related to the Specification and future versions, implementations, and test suites thereof. 56 | 57 | {\bfseries GENERAL TERMS} 58 | 59 | 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. 60 | 61 | 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. 62 | 63 | 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. 64 | 65 | \end{flushleft} 66 | -------------------------------------------------------------------------------- /spec/chapters/license___eval.tex: -------------------------------------------------------------------------------- 1 | \begin{flushleft} 2 | 3 | {\bfseries JSR 356 Java\texttrademark\ API for WebSocket (\lq\lq Specification\rq\rq)\\ 4 | Version: 1.1 \\ 5 | Status: Maintenance Draft Review \\ 6 | Release: \today\\ 7 | Copyright 2011-2014 Oracle America, Inc. (``Oracle'') \\ 8 | 500 Oracle Parkway, Redwood Shores, California 94065, U.S.A\\ 9 | All rights reserved. 10 | } 11 | 12 | \mbox{}\\ 13 | 14 | {\bfseries NOTICE} 15 | 16 | The Specification is protected by copyright and the information described therein may be protected by one or more U.S. patents, foreign patents, or pending applications. Except as provided under the following license, no part of the Specification may be reproduced in any form by any means without the prior written authorization of Oracle America, Inc. (``Oracle'') and its licensors, if any. Any use of the Specification and the information described therein will be governed by the terms and conditions of this Agreement. 17 | 18 | Subject to the terms and conditions of this license, including your compliance with Paragraphs 1 and 2 below, Oracle hereby grants you a fully-paid, non-exclusive, non-transferable, limited license (without the right to sublicense) under Oracle's intellectual property rights to: 19 | 20 | 1.Review the Specification for the purposes of evaluation. This includes: (i) developing implementations of the Specification for your internal, non-commercial use; (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 Technology. 21 | 22 | 2.Distribute implementations of the Specification to third parties for their testing and evaluation use, provided that any such implementation: 23 | (i) 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; 24 | (ii) is clearly and prominently marked with the word ``UNTESTED'' or ``EARLY ACCESS'' or ``INCOMPATIBLE'' or ``UNSTABLE'' or ``BETA'' in any list of available builds and in proximity to every link initiating its download, where the list or link is under Licensee's control; and 25 | (iii) includes the following notice: 26 | ``This is an implementation of an early-draft specification developed under the Java Community Process (JCP) and is made available for testing and evaluation purposes only. The code is not compatible with any specification of the JCP.'' 27 | The grant set forth above concerning your distribution of implementations of the specification is contingent upon your agreement to terminate development and distribution of your ``early draft'' implementation as soon as feasible following final completion of the specification. If you fail to do so, the foregoing grant shall be considered null and void. 28 | No provision of this Agreement shall be understood to restrict your ability to make and distribute to third parties applications written to the Specification. 29 | Other than this limited license, you acquire no right, title or interest in or to the Specification or any other Oracle intellectual property, and the Specification may only be used in accordance with the license terms set forth herein. This license will expire on the earlier of: (a) two (2) years from the date of Release listed above; (b) the date on which the final version of the Specification is publicly released; or (c) the date on which the Java Specification Request (JSR) to which the Specification corresponds is withdrawn. In addition, this license will terminate immediately without notice from Oracle if you fail to comply with any provision of this license. Upon termination, you must cease use of or destroy the Specification. 30 | ``Licensor Name Space'' means the public class or interface declarations whose names begin with ``java'', ``javax'', ``com.oracle'' or their equivalents in any subsequent naming convention adopted by Oracle through the Java Community Process, or any recognized successors or replacements thereof. 31 | 32 | {\bfseries TRADEMARKS} 33 | 34 | No right, title, or interest in or to any trademarks, service marks, or trade names of Oracle or Oracle's licensors is granted hereunder. Oracle, the Oracle logo, Java are trademarks or registered trademarks of Oracle USA, Inc. in the U.S. and other countries. 35 | 36 | {\bfseries DISCLAIMER OF WARRANTIES} 37 | 38 | THE SPECIFICATION IS PROVIDED ``AS IS'' AND IS EXPERIMENTAL AND MAY CONTAIN DEFECTS OR DEFICIENCIES WHICH CANNOT OR WILL NOT BE CORRECTED BY ORACLE. ORACLE MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT THAT THE CONTENTS OF THE SPECIFICATION ARE 39 | SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not represent any commitment to release or implement any portion of the Specification in any product. 40 | 41 | THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW VERSIONS OF THE SPECIFICATION, IF ANY. ORACLE MAY MAKE IMPROVEMENTS AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THE SPECIFICATION AT ANY TIME. Any use of such changes in the Specification will be governed by the then-current license for the applicable version of the Specification. 42 | 43 | {\bfseries LIMITATION OF LIABILITY} 44 | 45 | TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL ORACLE 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 TO ANY FURNISHING, PRACTICING, MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF ORACLE AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 46 | 47 | You will hold Oracle (and its licensors) harmless from any claims based on your use of the Specification for any purposes other than the limited right of evaluation as described above, and from any claims that later versions or releases of any Specification furnished to you are incompatible with the Specification provided to you under this license. 48 | 49 | {\bfseries RESTRICTED RIGHTS LEGEND} 50 | 51 | If this Software 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). 52 | 53 | {\bfseries REPORT} 54 | 55 | You may wish to report any ambiguities, inconsistencies or inaccuracies you may find in connection with your evaluation of the Specification (``Feedback''). To the extent that you provide Oracle with any Feedback, you hereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential basis, and (ii) grant Oracle 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 related to the Specification and future versions, implementations, and test suites thereof. 56 | 57 | {\bfseries GENERAL TERMS} 58 | 59 | 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. 60 | 61 | 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. 62 | 63 | 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. 64 | 65 | \end{flushleft} 66 | -------------------------------------------------------------------------------- /api/server/pom.xml: -------------------------------------------------------------------------------- 1 | 2 | 41 | 42 | 43 | 4.0.0 44 | 45 | javax.websocket 46 | javax.websocket-all 47 | 1.1 48 | 49 | 50 | javax.websocket-api 51 | bundle 52 | WebSocket server API 53 | JSR 356: Java API for WebSocket 54 | http://websocket-spec.java.net 55 | 56 | 57 | 58 | 59 | org.glassfish.build 60 | spec-version-maven-plugin 61 | 62 | 63 | false 64 | api 65 | ${spec_version} 66 | 67 | ${spec_impl_version} 68 | ${api_package} 69 | 70 | 71 | 72 | 73 | 74 | 75 | set-spec-properties 76 | check-module 77 | 78 | 79 | 80 | 81 | 82 | 88 | 89 | org.apache.felix 90 | maven-bundle-plugin 91 | 2.3.7 92 | true 93 | 94 | 95 | ${spec.bundle.version} 96 | ${spec.bundle.symbolic-name} 97 | ${spec.extension.name} 98 | ${spec.implementation.version} 99 | ${spec.specification.version} 100 | ${packages.export} 101 | 102 | 103 | 104 | 105 | org.apache.maven.plugins 106 | maven-source-plugin 107 | 108 | true 109 | 110 | 111 | 112 | org.apache.maven.plugins 113 | maven-resources-plugin 114 | 115 | 116 | sources-as-resources 117 | package 118 | 119 | copy-resources 120 | 121 | 122 | 123 | 124 | src/main/java 125 | 126 | 127 | ${project.build.directory}/sources 128 | 129 | 130 | 131 | 132 | 133 | org.apache.maven.plugins 134 | maven-dependency-plugin 135 | 136 | 137 | unpack-client-sources 138 | package 139 | 140 | unpack 141 | 142 | 143 | 144 | 145 | javax.websocket 146 | javax.websocket-client-api 147 | ${project.version} 148 | sources 149 | false 150 | ${project.build.directory}/sources 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | org.apache.maven.plugins 159 | maven-jar-plugin 160 | 161 | 162 | attach-source-jar 163 | 164 | jar 165 | 166 | 167 | sources 168 | ${project.build.directory}/sources 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | javax.websocket 178 | javax.websocket-client-api 179 | ${project.version} 180 | true 181 | 182 | 183 | 184 | -------------------------------------------------------------------------------- /spec/chapters/configuration.tex: -------------------------------------------------------------------------------- 1 | \chapter{Configuration} 2 | \label{configuration} 3 | 4 | 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. 5 | 6 | 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] 7 | 8 | Here follows the definition of the server-specific and client-specific configuration options. 9 | 10 | \section{Server Configurations} 11 | \label{serverconfig} 12 | 13 | In order to deploy a programmatic endpoint into the URI space available for client connections, the container requires a \textbf{ServerEndpointConfig} instance. This object holds configuration data and the default implementation 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 \textbf{ServerEndpointConfig.Configurator} implementation with the \textbf{ServerEndpointConfig}. [WSC-3.1-1] 14 | 15 | These operations are laid out below. 16 | 17 | \subsection{URI Mapping} 18 | 19 | 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] 20 | 21 | An application that contains multiple endpoint paths that are the same relative URI is not a valid application. An application that contains multiple endpoint paths that are equivalent URI-templates is not a valid application. [WSC-3.1.1-2] 22 | 23 | However, it is possible for an incoming URI in an opening handshake request theoretically to match more than one endpoint path. For example, consider the following case:- 24 | 25 | incoming URI: "/a/b" 26 | 27 | endpoint A is mapped to "/a/b" 28 | 29 | endpoint B is mapped to /a/\{customer-name\} 30 | 31 | 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] 32 | 33 | 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. 34 | 35 | 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. 36 | 37 | 38 | Examples 39 | 40 | i) suppose an endpoint has path /a/b/, the only incoming URI that matches this is /a/b/ 41 | 42 | 43 | ii) suppose an endpoint is mapped to /a/\{var\} 44 | 45 | incoming URIs that do match: /a/b (with var=b), /a/apple (with var=apple) 46 | 47 | 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.) 48 | 49 | 50 | iii) suppose we have three endpoints and their paths: 51 | 52 | endpoint A: /a/\{var\}/c 53 | 54 | endpoint B: /a/b/c 55 | 56 | endpoint C: /a/\{var1\}/\{var2\} 57 | 58 | incoming URI: a/b/c matches B, not A or C, because an exact match is preferred. 59 | 60 | incoming URI: a/d/c matches A with variable var=d, because an exact matching segment is preferred over a variable segment 61 | 62 | incoming URI: a/x/y/ matches C, with var1=x, var2=y 63 | 64 | 65 | iv) suppose we have two endpoints 66 | 67 | endpoint A: /\{var1\}/d 68 | 69 | endpoint B: /b/\{var2\} 70 | 71 | incoming URI: /b/d matches B with var2=d, not A with var1=b because the matching process works from left to right. 72 | 73 | 74 | The implementation must not establish the connection unless there is a match. [WSC-3.1.1-4] 75 | 76 | \subsection{Subprotocol Negotiation} 77 | 78 | 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] 79 | 80 | \subsection{Extension Modification} 81 | 82 | 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] 83 | 84 | \subsection{Origin Check} 85 | 86 | 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] 87 | 88 | \subsection{Handshake Modification} 89 | 90 | The default server configuration makes no modification of the opening handshake process other than that described above. [WSC-3.1.5-1] 91 | 92 | 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 \textbf{ServerEndpointConfig.Configurator}. 93 | 94 | 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 \textbf{modifyHandshake()} method on the \textbf{ServerEndpointConfig.Configurator}, wherein they have full access to the \textbf{HandshakeRequest} and \textbf{HandshakeResponse} of the handshake. 95 | 96 | \subsection{Custom State or Processing Across Server Endpoint Instances} 97 | 98 | The developer may also implement \textbf{ServerEndpointConfig.Configurator} in order to hold custom application state or methods for other kinds of application specific processing that is accessible from all \textbf{Endpoint} instances of the same logical endpoint via the \textbf{EndpointConfig} object. 99 | 100 | \subsection{Customizing Endpoint Creation} 101 | \label{configuration:creation} 102 | 103 | The developer may control the creation of endpoint instances by supplying a \textbf{ServerEndpointConfig.Configurator} object that overrides the \textbf{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] 104 | 105 | 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. 106 | 107 | \section{Client Configuration} 108 | 109 | In order to connect a websocket client endpoint to its corresponding websocket server endpoint, the implementation requires configuration information. Aside from the list of encoders and decoders, the Java WebSocket API needs the following attributes: 110 | 111 | \subsection{Subprotocols} 112 | 113 | The default client configuration uses the developer provided list of subprotocols, to send in order of preference, the names of the subprotocols it would like to use in the opening handshake it formulates. [WSC-3.2.1-1] 114 | 115 | \subsection{Extensions} 116 | 117 | The default client configuration must use the developer provided list of extensions to send, in order of preference, the extensions, including parameters, that it would like to use in the opening handshake it formulates. [WSC-3.2.2-1] 118 | 119 | \subsection{Client Configuration Modification} 120 | 121 | Some clients may wish to adapt the way in which the client side formulates the opening handshake interaction 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 particular application’s needs. 122 | -------------------------------------------------------------------------------- /api/pom.xml: -------------------------------------------------------------------------------- 1 | 2 | 41 | 42 | 43 | 4.0.0 44 | 45 | net.java 46 | jvnet-parent 47 | 5 48 | 49 | 50 | javax.websocket 51 | javax.websocket-all 52 | pom 53 | 57 | 1.1 58 | WebSocket API 59 | JSR 356: Java API for WebSocket 60 | http://websocket-spec.java.net 61 | 62 | 63 | scm:git:git://java.net/websocket-spec~code 64 | scm:git:ssh://git.java.net/websocket-spec~code 65 | https://java.net/projects/websocket-spec/sources/code/show 66 | 1.1 67 | 68 | 69 | 70 | 71 | 72 | Dual license consisting of the CDDL v1.1 and GPL v2 73 | 74 | https://glassfish.java.net/public/CDDL+GPL_1_1.html 75 | repo 76 | 77 | 78 | 79 | 80 | Oracle 81 | http://www.oracle.com 82 | 83 | 84 | 85 | 86 | pavel_bucek 87 | Pavel Bucek 88 | Oracle 89 | 90 | developer 91 | 92 | 93 | 94 | 95 | 96 | 97 | Jitendra Kotamraju 98 | http://weblogs.java.net/blog/jitu 99 | 100 | 101 | Danny Coward 102 | Oracle 103 | 104 | developer 105 | 106 | 107 | 108 | Stepan Kopriva 109 | 110 | 111 | 112 | 113 | javax.websocket 114 | 1.1 115 | 116 | 1.1 117 | 1.1 118 | javax.websocket.* 119 | 120 | 121 | 122 | 123 | 124 | org.apache.maven.plugins 125 | maven-compiler-plugin 126 | 2.5.1 127 | 128 | 1.6 129 | 1.6 130 | 131 | 132 | 133 | org.glassfish.copyright 134 | glassfish-copyright-maven-plugin 135 | 1.46 136 | 137 | etc/config/copyright-exclude 138 | 139 | git 140 | 141 | off 142 | 143 | true 144 | 145 | true 146 | 147 | false 148 | 149 | false 150 | etc/config/copyright.txt 151 | 152 | 153 | 154 | org.apache.maven.plugins 155 | maven-release-plugin 156 | 2.3.2 157 | 158 | forked-path 159 | false 160 | ${release.arguments} 161 | 162 | 163 | 164 | org.apache.maven.plugins 165 | maven-source-plugin 166 | 2.1.2 167 | 168 | 169 | attach-sources 170 | verify 171 | 172 | jar-no-fork 173 | 174 | 175 | 176 | 177 | 178 | org.apache.maven.plugins 179 | maven-javadoc-plugin 180 | 2.8.1 181 | 182 | ${project.parent.basedir}/src/main/javadoc 183 | 184 | 185 | WebSocket Packages 186 | javax.websocket* 187 | 188 | 189 | 190 | Oracle 192 | and/or its affiliates. All Rights Reserved. 193 | Use is subject to 194 | license terms. 195 |
Comments to : users@websocket-spec.java.net 196 | ]]> 197 | 198 | 199 | http://docs.oracle.com/javase/6/docs/api/ 200 | 201 | true 202 | 203 | 204 | 205 | 206 | attach-javadocs 207 | 208 | jar 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | org.apache.maven.plugins 218 | maven-jar-plugin 219 | 2.4 220 | 221 | 222 | org.apache.maven.plugins 223 | maven-dependency-plugin 224 | 2.6 225 | 226 | 227 | org.apache.maven.plugins 228 | maven-resources-plugin 229 | 2.6 230 | 231 | 232 | org.glassfish.build 233 | spec-version-maven-plugin 234 | 1.2 235 | 236 | 237 | 238 | 239 | 240 | 241 | client 242 | server 243 | 244 | 245 | --------------------------------------------------------------------------------