Index: 3rdParty_sources/versions.txt =================================================================== diff -u -r345648e21e2c2b088c907ed812175477dd9b78f2 -rec3c5a5adbf38c525b3d3f2aec05af3f78f3968f --- 3rdParty_sources/versions.txt (.../versions.txt) (revision 345648e21e2c2b088c907ed812175477dd9b78f2) +++ 3rdParty_sources/versions.txt (.../versions.txt) (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -54,4 +54,6 @@ xmltooling 1.4.0 -XStream 1.5.0 \ No newline at end of file +XStream 1.5.0 + +websocket api_1.1_spec-1.1.0.Final \ No newline at end of file Index: 3rdParty_sources/websocket/javax/websocket/ClientEndpoint.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/ClientEndpoint.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/ClientEndpoint.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,105 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * The ClientEndpoint annotation a class level annotation is used to denote that a POJO + * is a web socket client and can be deployed as such. Similar to + * {@link javax.websocket.server.ServerEndpoint}, POJOs that are + * annotated with this annotation can have methods that, using the web socket method level annotations, + * are web socket lifecycle methods. + *

+ * For example: + * 


+ * @ClientEndpoint(subprotocols="chat")
+ * public class HelloServer {
+ *
+ *     @OnMessage
+ *     public void processMessageFromServer(String message, Session session) {
+ *         System.out.println("Message came from the server ! " + message);
+ *     }
+ *
+ * }
+ *
+ * + * @author dannycoward + */ + +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.TYPE) +public @interface ClientEndpoint { + + /** + * The names of the subprotocols this client supports. + * + * @return the array of names of the subprotocols. + */ + String[] subprotocols() default {}; + + /** + * The array of Java classes that are to act as Decoders for messages coming into + * the client. + * + * @return the array of decoders. + */ + Class[] decoders() default {}; + + /** + * The array of Java classes that are to act as Encoders for messages sent by the client. + * + * @return the array of decoders. + */ + Class[] encoders() default {}; + + /** + * An optional custom configurator class that the developer would like to use + * to provide custom configuration of new instances of this endpoint. The implementation + * creates a new instance of the configurator per logical endpoint. + * + * @return the custom configurator class, or ClientEndpointConfigurator.class + * if none was provided in the annotation. + */ + public Class configurator() default ClientEndpointConfig.Configurator.class; +} Index: 3rdParty_sources/websocket/javax/websocket/ClientEndpointConfig.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/ClientEndpointConfig.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/ClientEndpointConfig.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,253 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; +import java.util.Map; + +/** + * The ClientEndpointConfig is a special kind of endpoint configuration object that contains + * web socket configuration information specific only to client endpoints. Developers deploying + * programmatic client endpoints can create instances of this configuration by + * using a {@link ClientEndpointConfig.Builder}. Developers can override some + * of the configuration operations by providing an implementation of + * {@link ClientEndpointConfig.Configurator}. + * + * @author dannycoward + */ +public interface ClientEndpointConfig extends EndpointConfig { + + + /** + * Return the ordered list of sub protocols a client endpoint would like to use, + * in order of preference, favorite first that this client would + * like to use for its sessions. + * This list is used to generate the Sec-WebSocket-Protocol header in the opening + * handshake for clients using this configuration. The first protocol name is the most preferred. + * See Client Opening Handshake. + * + * @return the list of the preferred subprotocols, the empty list if there are none + */ + List getPreferredSubprotocols(); + + /** + * Return the extensions, in order of preference, favorite first, that this client would + * like to use for its sessions. These are the extensions that will + * be used to populate the Sec-WebSocket-Extensions header in the opening handshake for clients + * using this configuration. The first extension in the list is the most preferred extension. + * See Negotiating Extensions. + * + * @return the list of extensions, the empty list if there are none. + */ + List getExtensions(); + + + /** + * Return the custom configurator for this configuration. If the developer + * did not provide one, the platform default configurator is returned. + * + * @return the configurator in use with this configuration. + */ + public ClientEndpointConfig.Configurator getConfigurator(); + + /** + * The Configurator class may be extended by developers who want to + * provide custom configuration algorithms, such as intercepting the opening handshake, or + * providing arbitrary methods and algorithms that can be accessed from each endpoint + * instance configured with this configurator. + + */ + public class Configurator { + + /** + * This method is called by the implementation after it has formulated the handshake + * request that will be used to initiate the connection to the server, but before it has + * sent any part of the request. This allows the developer to inspect and modify the + * handshake request headers prior to the start of the handshake interaction. + * + * @param headers the mutable map of handshake request headers the implementation is about to send to + * start the handshake interaction. + */ + public void beforeRequest(Map> headers) { + + } + + /** + * This method is called by the implementation after it has received a handshake response + * from the server as a result of a handshake interaction it initiated. The developer may implement + * this method in order to inspect the returning handshake response. + * + * @param hr the handshake response sent by the server. + */ + public void afterResponse(HandshakeResponse hr) { + + } + } + + /** + * The ClientEndpointConfig.Builder is a class used for creating + * {@link ClientEndpointConfig} objects for the purposes of + * deploying a client endpoint. + * Here are some examples: + * Building a plain configuration with no encoders, decoders, subprotocols or extensions. + * + * ClientEndpointConfig cec = ClientEndpointConfig.Builder.create().build(); + * + * + * Building a configuration with no subprotocols and a custom configurator. + * 

+    * ClientEndpointConfig customCec = ClientEndpointConfig.Builder.create()
+    *         .preferredSubprotocols(mySubprotocols)
+    *         .configurator(new MyClientConfigurator())
+    *         .build();
+    *
+ * + * + * @author dannycoward + */ + public final class Builder { + private List preferredSubprotocols = Collections.emptyList(); + private List extensions = Collections.emptyList(); + private List> encoders = Collections.emptyList(); + private List> decoders = Collections.emptyList(); + private ClientEndpointConfig.Configurator clientEndpointConfigurator = new ClientEndpointConfig.Configurator() { + + }; + + // use create() + private Builder() { + } + + /** + * Creates a new builder object with no subprotocols, extensions, encoders, + * decoders and a {@code null} configurator. + * + * @return a new builder object. + */ + public static ClientEndpointConfig.Builder create() { + return new ClientEndpointConfig.Builder(); + } + + /** + * Builds a configuration object using the attributes set + * on this builder. + * + * @return a new configuration object. + */ + public ClientEndpointConfig build() { + return new DefaultClientEndpointConfig( + Collections.unmodifiableList(this.preferredSubprotocols), + Collections.unmodifiableList(this.extensions), + Collections.unmodifiableList(this.encoders), + Collections.unmodifiableList(this.decoders), + this.clientEndpointConfigurator); + } + + + + /** + * Sets the configurator object for the configuration this builder will build. + * + * @param clientEndpointConfigurator the configurator + * @return the builder instance + */ + public ClientEndpointConfig.Builder configurator(ClientEndpointConfig.Configurator clientEndpointConfigurator) { + this.clientEndpointConfigurator = clientEndpointConfigurator; + return this; + } + + + /** + * Set the preferred sub protocols for the configuration this builder will build. The + * list is treated in order of preference, favorite first, that this client would + * like to use for its sessions. + * + * @param preferredSubprotocols the preferred subprotocol names. + * @return the builder instance + */ + public ClientEndpointConfig.Builder preferredSubprotocols(List preferredSubprotocols) { + this.preferredSubprotocols = (preferredSubprotocols == null) ? new ArrayList() : preferredSubprotocols; + return this; + } + + + /** + * Set the extensions for the configuration this builder will build. The + * list is treated in order of preference, favorite first, that the + * client would like to use for its sessions. + * + * @param extensions the extensions + * @return the builder instance + */ + public ClientEndpointConfig.Builder extensions(List extensions) { + this.extensions = (extensions == null) ? new ArrayList() : extensions; + return this; + } + + /** + * Assign the list of encoder implementation classes the client will use. + * + * @param encoders the encoder implementation classes + * @return the builder instance + */ + public ClientEndpointConfig.Builder encoders(List> encoders) { + this.encoders = (encoders == null) ? new ArrayList>() : encoders; + return this; + } + + /** + * Assign the list of decoder implementation classes the client will use. + * + * @param decoders the decoder implementation classes + * @return this builder instance + */ + public ClientEndpointConfig.Builder decoders(List> decoders) { + this.decoders = (decoders == null) ? new ArrayList>() : decoders; + return this; + } + + + } + +} + + Index: 3rdParty_sources/websocket/javax/websocket/CloseReason.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/CloseReason.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/CloseReason.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,300 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.io.UnsupportedEncodingException; + +/** + * A class encapsulating the reason why a web socket has been closed, or why it is being asked to + * close. Note the acceptable uses of codes and reason phrase are defined in more detail by + * RFC 6455. + * + * @author dannycoward + */ +public class CloseReason { + + private final CloseReason.CloseCode closeCode; + private final String reasonPhrase; + + /** + * Creates a reason for closing a web socket connection with the given + * code and reason phrase. + * + * @param closeCode the close code, may not be {@code null} + * @param reasonPhrase the reason phrase, may be {@code null}. + */ + public CloseReason(CloseReason.CloseCode closeCode, String reasonPhrase) { + if (closeCode == null) { + throw new IllegalArgumentException("closeCode cannot be null"); + } + + try { + if (reasonPhrase != null && reasonPhrase.getBytes("UTF-8").length > 123) { + throw new IllegalArgumentException("Reason Phrase cannot exceed 123 UTF-8 encoded bytes: " + reasonPhrase); + } + } catch (UnsupportedEncodingException uee) { + throw new IllegalStateException(uee); + } + this.closeCode = closeCode; + this.reasonPhrase = "".equals(reasonPhrase) ? null : reasonPhrase; + } + + /** + * The Close code associated with this CloseReason. + * + * @return the close code. + */ + public CloseReason.CloseCode getCloseCode() { + return this.closeCode; + } + + /** + * The reason phrase associated with this CloseReason. + * + * @return the reason phrase. If there is no reason phrase, this returns + * the empty string + */ + public String getReasonPhrase() { + return (this.reasonPhrase == null) ? "" : this.reasonPhrase; + } + + /** + * Converts the CloseReason to a debug-friendly string. The exact format + * is not defined by the specification and may change in future releases. + * + * @return A String representation of this CloseReason + */ + public String toString() { + return (this.reasonPhrase == null) ? + "CloseReason[" + this.closeCode.getCode() + "]" : + "CloseReason[" + this.closeCode.getCode() + "," + reasonPhrase + "]"; + } + + + /** + * A marker interface for the close codes. This interface may be + * implemented by enumerations that contain web socket close codes, for + * example enumerations that contain all the in use close codes as of + * web socket 1.0, or an enumeration that contains close codes + * that are currently reserved for special use by the web socket + * specification. + */ + public interface CloseCode { + /** + * Returns the code number, for example the integer '1000' for normal closure. + * + * @return the code number + */ + int getCode(); + } + + /** + * An Enumeration of status codes for a web socket close that + * are defined in the specification. + */ + public enum CloseCodes implements CloseReason.CloseCode { + + + /** + * 1000 indicates a normal closure, meaning that the purpose for + * which the connection was established has been fulfilled. + */ + NORMAL_CLOSURE(1000), + /** + * 1001 indicates that an endpoint is "going away", such as a server + * going down or a browser having navigated away from a page. + */ + GOING_AWAY(1001), + /** + * 1002 indicates that an endpoint is terminating the connection due + * to a protocol error. + */ + PROTOCOL_ERROR(1002), + /** + * 1003 indicates that an endpoint is terminating the connection + * because it has received a type of data it cannot accept (e.g., an + * endpoint that understands only text data MAY send this if it + * receives a binary message). + */ + CANNOT_ACCEPT(1003), + /** + * Reserved. The specific meaning might be defined in the future. + */ + RESERVED(1004), + /** + * 1005 is a reserved value and MUST NOT be set as a status code in a + * Close control frame by an endpoint. It is designated for use in + * applications expecting a status code to indicate that no status + * code was actually present. + */ + NO_STATUS_CODE(1005), + /** + * 1006 is a reserved value and MUST NOT be set as a status code in a + * Close control frame by an endpoint. It is designated for use in + * applications expecting a status code to indicate that the + * connection was closed abnormally, e.g., without sending or + * receiving a Close control frame. + */ + CLOSED_ABNORMALLY(1006), + /** + * 1007 indicates that an endpoint is terminating the connection + * because it has received data within a message that was not + * consistent with the type of the message (e.g., non-UTF-8 + * data within a text message). + */ + NOT_CONSISTENT(1007), + /** + * 1008 indicates that an endpoint is terminating the connection + * because it has received a message that violates its policy. This + * is a generic status code that can be returned when there is no + * other more suitable status code (e.g., 1003 or 1009) or if there + * is a need to hide specific details about the policy. + */ + VIOLATED_POLICY(1008), + /** + * 1009 indicates that an endpoint is terminating the connection + * because it has received a message that is too big for it to + * process. + */ + TOO_BIG(1009), + /** + * 1010 indicates that an endpoint (client) is terminating the + * connection because it has expected the server to negotiate one or + * more extension, but the server didn't return them in the response + * message of the WebSocket handshake. The list of extensions that + * are needed SHOULD appear in the /reason/ part of the Close frame. + * Note that this status code is not used by the server, because it + * can fail the WebSocket handshake instead. + */ + NO_EXTENSION(1010), + /** + * 1011 indicates that a server is terminating the connection because + * it encountered an unexpected condition that prevented it from + * fulfilling the request. + */ + UNEXPECTED_CONDITION(1011), + /** + * 1012 indicates that the service will be restarted. + */ + SERVICE_RESTART(1012), + /** + * 1013 indicates that the service is experiencing overload + */ + TRY_AGAIN_LATER(1013), + /** + * 1015 is a reserved value and MUST NOT be set as a status code in a + * Close control frame by an endpoint. It is designated for use in + * applications expecting a status code to indicate that the + * connection was closed due to a failure to perform a TLS handshake + * (e.g., the server certificate can't be verified). + */ + TLS_HANDSHAKE_FAILURE(1015); + + /** + * Creates a CloseCode from the given int code number. This method throws + * an IllegalArgumentException if the int is not one of the + * + * @param code the integer code number + * @return a new CloseCode with the given code number + * @throws IllegalArgumentException if the code is not a valid close code + */ + public static CloseReason.CloseCode getCloseCode(final int code) { + if (code < 1000 || code > 4999) { + throw new IllegalArgumentException("Invalid code: " + code); + } + switch (code) { + case 1000: + return CloseReason.CloseCodes.NORMAL_CLOSURE; + case 1001: + return CloseReason.CloseCodes.GOING_AWAY; + case 1002: + return CloseReason.CloseCodes.PROTOCOL_ERROR; + case 1003: + return CloseReason.CloseCodes.CANNOT_ACCEPT; + case 1004: + return CloseReason.CloseCodes.RESERVED; + case 1005: + return CloseReason.CloseCodes.NO_STATUS_CODE; + case 1006: + return CloseReason.CloseCodes.CLOSED_ABNORMALLY; + case 1007: + return CloseReason.CloseCodes.NOT_CONSISTENT; + case 1008: + return CloseReason.CloseCodes.VIOLATED_POLICY; + case 1009: + return CloseReason.CloseCodes.TOO_BIG; + case 1010: + return CloseReason.CloseCodes.NO_EXTENSION; + case 1011: + return CloseReason.CloseCodes.UNEXPECTED_CONDITION; + case 1012: + return CloseReason.CloseCodes.SERVICE_RESTART; + case 1013: + return CloseReason.CloseCodes.TRY_AGAIN_LATER; + case 1015: + return CloseReason.CloseCodes.TLS_HANDSHAKE_FAILURE; + } + return new CloseReason.CloseCode() { + @Override + public int getCode() { + return code; + } + }; + + } + + CloseCodes(int code) { + this.code = code; + } + + /** + * Return the code number of this status code. + * + * @return the code. + */ + @Override + public int getCode() { + return code; + } + + private int code; + } +} + Index: 3rdParty_sources/websocket/javax/websocket/ContainerProvider.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/ContainerProvider.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/ContainerProvider.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,86 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.util.ServiceLoader; + +/** + * Provider class that allows the developer to get a reference to + * the implementation of the WebSocketContainer. + * The provider class uses the + * ServiceLoader + * to load an implementation of ContainerProvider. Specifically, the fully qualified classname + * of the container implementation of ContainerProvider must be listed in the + * META-INF/services/javax.websocket.ContainerProvider file in the implementation JAR file. + * + * @author dannycoward + */ +public abstract class ContainerProvider { + + /** + * Obtain a new instance of a WebSocketContainer. The method looks for the + * ContainerProvider implementation class in the order listed in the META-INF/services/javax.websocket.ContainerProvider + * file, returning the WebSocketContainer implementation from the ContainerProvider implementation + * that is not {@code null}. + * @return an implementation provided instance of type WebSocketContainer + */ + public static WebSocketContainer getWebSocketContainer() { + WebSocketContainer wsc = null; + for (ContainerProvider impl : ServiceLoader.load(ContainerProvider.class)) { + wsc = impl.getContainer(); + if (wsc != null) { + return wsc; + } + } + if (wsc == null) { + throw new RuntimeException("Could not find an implementation class."); + } else { + throw new RuntimeException("Could not find an implementation class with a non-null WebSocketContainer."); + } + } + + /** + * Load the container implementation. + * @return the implementation class + */ + protected abstract WebSocketContainer getContainer(); +} + + Index: 3rdParty_sources/websocket/javax/websocket/DecodeException.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/DecodeException.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/DecodeException.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,144 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.nio.ByteBuffer; + +/** + * A general exception that occurs when trying to decode a custom object from a text or binary message. + * + * @author dannycoward + */ +public class DecodeException extends Exception { + private final ByteBuffer bb; + private final String encodedString; + private static final long serialVersionUID = 006; + + /** + * Constructor with the binary data that could not be decoded, and the + * reason why it failed to be, and the cause. The buffer may represent the + * whole message, or the part of the message most relevant to the decoding + * error, depending whether the application is using one + * of the streaming methods or not. + * + * @param bb the byte buffer containing the (part of) the message that + * could not be decoded. + * @param message the reason for the failure. + * @param cause the cause of the error. + */ + public DecodeException(ByteBuffer bb, String message, Throwable cause) { + super(message, cause); + this.encodedString = null; + this.bb = bb; + } + + /** + * Constructor with the text data that could not be decoded, and the reason + * why it failed to be, and the cause. The encoded string may represent the whole message, + * or the part of the message most relevant to the decoding error, depending + * whether the application is using one + * of the streaming methods or not. + * + * @param encodedString the string representing the (part of) the message that could not be decoded. + * @param message the reason for the failure. + * @param cause the cause of the error. + */ + public DecodeException(String encodedString, String message, Throwable cause) { + super(message, cause); + this.encodedString = encodedString; + this.bb = null; + } + + /** + * Constructs a DecodedException with the given ByteBuffer that cannot + * be decoded, and reason why. The buffer may represent the + * whole message, or the part of the message most relevant to the decoding + * error, depending whether the application is using one + * of the streaming methods or not. + * + * @param bb the byte buffer containing the (part of) the message that + * could not be decoded. + * @param message the reason for the failure. + */ + public DecodeException(ByteBuffer bb, String message) { + super(message); + this.encodedString = null; + this.bb = bb; + } + + /** + * Constructs a DecodedException with the given encoded string that cannot + * be decoded, and reason why. The encoded string may represent the whole message, + * or the part of the message most relevant to the decoding error, depending + * whether the application is using one + * of the streaming methods or not. + * + * @param encodedString the string representing the (part of) the message that + * could not be decoded. + * @param message the reason for the failure. + */ + public DecodeException(String encodedString, String message) { + super(message); + this.encodedString = encodedString; + this.bb = null; + } + + /** + * Return the ByteBuffer containing either the whole message, or the partial message, that + * could not be decoded, or {@code null} if + * this exception arose from a failure to decode a text message. + * + * @return the binary data not decoded or {@code null} for text message failures. + */ + public ByteBuffer getBytes() { + return this.bb; + } + + /** + * Return the encoded string that is either the whole message, or the partial + * message that could not be decoded, or {@code null} if + * this exception arose from a failure to decode a binary message.. + * + * @return the text not decoded or {@code null} for binary message failures. + */ + public String getText() { + return this.encodedString; + } +} Index: 3rdParty_sources/websocket/javax/websocket/Decoder.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/Decoder.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/Decoder.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,157 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.io.IOException; +import java.io.InputStream; +import java.io.Reader; +import java.nio.ByteBuffer; + +/** + * The Decoder interface holds member interfaces that define how a developer can provide + * the web socket container a way web socket messages into developer defined custom objects. + * The websocket implementation creates a new instance of the decoder per endpoint + * instance per connection. + * The lifecycle of the Decoder instance is governed by the container calls to the + * {@link Decoder#init(javax.websocket.EndpointConfig)} and {@link Decoder#destroy() } + * methods. + * + * @author dannycoward + */ +public interface Decoder { + + /** + * This method is called with the endpoint configuration object of the + * endpoint this decoder is intended for when + * it is about to be brought into service. + * + * @param config the endpoint configuration object when being brought into + * service + */ + void init(EndpointConfig config); + + /** + * This method is called when the decoder is about to be removed + * from service in order that any resources the encoder used may + * be closed gracefully. + */ + void destroy(); + + /** + * This interface defines how a custom object (of type T) is decoded from a web socket message in + * the form of a byte buffer. + */ + interface Binary extends Decoder { + + /** + * Decode the given bytes into an object of type T. + * + * @param bytes the bytes to be decoded. + * @return the decoded object. + */ + T decode(ByteBuffer bytes) throws DecodeException; + + /** + * Answer whether the given bytes can be decoded into an object of type T. + * + * @param bytes the bytes to be decoded. + * @return whether or not the bytes can be decoded by this decoder. + */ + boolean willDecode(ByteBuffer bytes); + + } + + /** + * This interface defines how a custom object is decoded from a web socket message in + * the form of a binary stream. + */ + interface BinaryStream extends Decoder { + + /** + * Decode the given bytes read from the input stream into an object of type T. + * + * @param is the input stream carrying the bytes. + * @return the decoded object. + */ + T decode(InputStream is) throws DecodeException, IOException; + + + } + + /** + * This interface defines how a custom object is decoded from a web socket message in + * the form of a string. + */ + interface Text extends Decoder { + /** + * Decode the given String into an object of type T. + * + * @param s string to be decoded. + * @return the decoded message as an object of type T + */ + T decode(String s) throws DecodeException; + + /** + * Answer whether the given String can be decoded into an object of type T. + * + * @param s the string being tested for decodability. + * @return whether this decoder can decoded the supplied string. + */ + boolean willDecode(String s); + + + } + + /** + * This interface defines how a custom object of type T is decoded from a web socket message in + * the form of a character stream. + */ + interface TextStream extends Decoder { + /** + * Reads the websocket message from the implementation provided + * Reader and decodes it into an instance of the supplied object type. + * + * @param reader the reader from which to read the web socket message. + * @return the instance of the object that is the decoded web socket message. + */ + T decode(Reader reader) throws DecodeException, IOException; + + } +} Index: 3rdParty_sources/websocket/javax/websocket/DefaultClientEndpointConfig.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/DefaultClientEndpointConfig.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/DefaultClientEndpointConfig.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,137 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.util.Collections; +import java.util.HashMap; +import java.util.List; +import java.util.Map; + +/** + * The DefaultClientEndpointConfig is a concrete implementation of a client configuration. + * + * @author dannycoward + */ + final class DefaultClientEndpointConfig implements ClientEndpointConfig { + private List preferredSubprotocols; + private List extensions; + private List> encoders; + private List> decoders; + private Map userProperties = new HashMap(); + private ClientEndpointConfig.Configurator clientEndpointConfigurator; + + + DefaultClientEndpointConfig( + List preferredSubprotocols, + List extensions, + List> encoders, + List> decoders, + ClientEndpointConfig.Configurator clientEndpointConfigurator) { + this.preferredSubprotocols = Collections.unmodifiableList(preferredSubprotocols); + this.extensions = Collections.unmodifiableList(extensions); + this.encoders = Collections.unmodifiableList(encoders); + this.decoders = Collections.unmodifiableList(decoders); + this.clientEndpointConfigurator = clientEndpointConfigurator; + } + + /** + * Return the protocols, in order of preference, favorite first, that this client would + * like to use for its sessions. + * + * @return the preferred subprotocols. + */ + @Override + public List getPreferredSubprotocols() { + return this.preferredSubprotocols; + } + + + + /** + * Return the extensions, in order of preference, favorite first, that this client would + * like to use for its sessions. + * + * @return the (unmodifiable) extension list. + */ + @Override + public List getExtensions() { + return this.extensions; + } + + + + /** + * Return the (unmodifiable) list of encoders this client will use. + * + * @return the encoder list. + */ + @Override + public List> getEncoders() { + return this.encoders; + } + + + + /** + * Return the (unmodifiable) list of decoders this client will use. + * + * @return the decoders to use. + */ + @Override + public List> getDecoders() { + return this.decoders; + } + + + /** + * Editable map of user properties. + */ + @Override + public final Map getUserProperties() { + return this.userProperties; + } + + @Override + public ClientEndpointConfig.Configurator getConfigurator() { + return this.clientEndpointConfigurator; + } + + +} Index: 3rdParty_sources/websocket/javax/websocket/DeploymentException.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/DeploymentException.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/DeploymentException.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,70 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +/** + * Checked exception indicating some kind of failure either to publish + * an endpoint on its server, or a failure to connect a client to its server. + * + * @author dannycoward + */ +public class DeploymentException extends Exception { + + /** + * Creates a deployment exception with the given reason for the deployment + * failure. + * + * @param message the reason for the failure. + */ + public DeploymentException(String message) { + super(message); + } + + /** + * Creates a deployment exception with the given reason for the deployment + * failure and wrapped cause of the failure. + * + * @param message the reason for the failure. + * @param cause the cause of the problem. + */ + public DeploymentException(String message, Throwable cause) { + super(message, cause); + } +} Index: 3rdParty_sources/websocket/javax/websocket/EncodeException.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/EncodeException.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/EncodeException.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,84 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +/** + * A general exception that occurs when trying to encode a custom object to a string or binary message. + * + * @author dannycoward + */ +public class EncodeException extends Exception { + private final Object object; + private static final long serialVersionUID = 006; + + /** + * Constructor with the object being encoded, and the reason why it failed to be. + * + * @param object the object that could not be encoded. + * @param message the reason for the failure. + */ + public EncodeException(Object object, String message) { + super(message); + this.object = object; + } + + + /** + * Constructor with the object being encoded, and the reason why it failed to be, and the cause. + * + * @param object the object that could not be encoded. + * @param message the reason for the failure. + * @param cause the cause of the problem. + */ + public EncodeException(Object object, String message, Throwable cause) { + super(message, cause); + this.object = object; + } + + + /** + * Return the Object that could not be encoded. + * + * @return the object. + */ + public Object getObject() { + return this.object; + } +} Index: 3rdParty_sources/websocket/javax/websocket/Encoder.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/Encoder.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/Encoder.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,151 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.io.IOException; +import java.io.OutputStream; +import java.io.Writer; +import java.nio.ByteBuffer; + +/** + * The Encoder interface defines how developers can provide a way to convert + * their custom objects into web socket messages. The Encoder interface contains + * subinterfaces that allow encoding algorithms to encode custom objects to: text, + * binary data, character stream and write to an output stream. + * The websocket implementation creates a new instance of the encoder per + * endpoint instance per connection. This means that each encoder instance has + * at most one calling thread at a time. + * The lifecycle of the Encoder instance is governed by the container calls to the + * {@link Encoder#init(javax.websocket.EndpointConfig)} and {@link Encoder#destroy() } + * methods. + * + * @author dannycoward + */ +public interface Encoder { + + /** + * This method is called with the endpoint configuration object of the + * endpoint this encoder is intended for when + * it is about to be brought into service. + * + * @param config the endpoint configuration object when being brought into + * service + */ + void init(EndpointConfig config); + + /** + * This method is called when the encoder is about to be removed + * from service in order that any resources the encoder used may + * be closed gracefully. + */ + void destroy(); + + /** + * This interface defines how to provide a way to convert a custom + * object into a text message. + * + * @param The type of the custom developer object that this Encoder can encode into a String. + */ + interface Text extends Encoder { + /** + * Encode the given object into a String. + * + * @param object the object being encoded. + * @return the encoded object as a string. + */ + String encode(T object) throws EncodeException; + + } + + /** + * This interface may be implemented by encoding algorithms + * that want to write the encoded object to a character stream. + * + * @param the type of the object this encoder can encode to a CharacterStream. + */ + interface TextStream extends Encoder { + /** + * Encode the given object to a character stream writing it + * to the supplied Writer. Implementations of this method may use the EncodeException + * to indicate a failure to convert the supplied object to an encoded form, and may + * use the IOException to indicate a failure to write the data to the supplied + * stream. + * + * @param object the object to be encoded. + * @param writer the writer provided by the web socket runtime to write the encoded data. + * @throws EncodeException if there was an error encoding the object due to its state. + * @throws IOException if there was an exception writing to the writer. + */ + void encode(T object, Writer writer) throws EncodeException, IOException; + } + + /** + * This interface defines how to provide a way to convert a custom + * object into a binary message. + * + * @param The type of the custom object that this Encoder can encoder to a ByteBuffer. + */ + interface Binary extends Encoder { + /** + * Encode the given object into a byte array. + * + * @param object the object being encoded. + * @return the binary data. + */ + ByteBuffer encode(T object) throws EncodeException; + } + + /** + * This interface may be implemented by encoding algorithms + * that want to write the encoded object to a binary stream. + * + * @param the type of the object this encoder can encode. + */ + interface BinaryStream extends Encoder { + /** + * Encode the given object into a binary stream written to the + * implementation provided OutputStream. + * + * @param object the object being encoded. + * @param os the output stream where the encoded data is written. + */ + void encode(T object, OutputStream os) throws EncodeException, IOException; + } +} Index: 3rdParty_sources/websocket/javax/websocket/Endpoint.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/Endpoint.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/Endpoint.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,144 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + + +/** + * The Web Socket Endpoint represents an object that can handle websocket conversations. + * Developers may extend this class in order to implement a programmatic websocket + * endpoint. The Endpoint class holds lifecycle methods that may be + * overridden to intercept websocket open, error and close events. By implementing + * the {@link Endpoint#onOpen(javax.websocket.Session, javax.websocket.EndpointConfig) onOpen} method, the programmatic endpoint gains access to the {@link Session} object, + * to which the developer may add {@link MessageHandler} implementations in order to + * intercept incoming websocket messages. Each instance + * of a websocket endpoint is guaranteed not to be called by more than one thread + * at a time per active connection. + * + *

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

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

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

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


+ * public class EchoServer extends Endpoint {
+ *
+ *     public void onOpen(Session session, EndpointConfig config) {
+ *         final RemoteEndpoint remote = session.getBasicRemote();
+ *         session.addMessageHandler(String.class, new MessageHandler.Whole<String>() {
+ *             public void onMessage(String text) {
+ *                 try {
+ *                     remote.sendString("Got your message (" + text + "). Thanks !");
+ *                 } catch (IOException ioe) {
+ *                     // handle send failure here
+ *                 }
+ *             }
+ *         });
+ *     }
+ *
+ * }
+ *
+ * + * @author dannycoward + */ +public abstract class Endpoint { + + /** + * Developers must implement this method to be notified when a new conversation has + * just begun. + * + * @param session the session that has just been activated. + * @param config the configuration used to configure this endpoint. + */ + public abstract void onOpen(Session session, EndpointConfig config); + + /** + * This method is called immediately prior to the session with the remote + * peer being closed. It is called whether the session is being closed + * because the remote peer initiated a close and sent a close frame, or + * whether the local websocket container or this endpoint requests to close + * the session. The developer may take this last opportunity to retrieve + * session attributes such as the ID, or any application data it holds before + * it becomes unavailable after the completion of the method. Developers should + * not attempt to modify the session from within this method, or send new + * messages from this call as the underlying + * connection will not be able to send them at this stage. + * + * @param session the session about to be closed. + * @param closeReason the reason the session was closed. + */ + public void onClose(Session session, CloseReason closeReason) { + } + + /** + * Developers may implement this method when the web socket session + * creates some kind of error that is not modeled in the web socket protocol. This may for example + * be a notification that an incoming message is too big to handle, or that the incoming message could not be encoded. + * + *

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

    + *
  • connection problems, for example, a socket failure that occurs before + * the web socket connection can be formally closed. These are modeled as + * {@link SessionException}s
    • + *
  • runtime errors thrown by developer created message handlers calls.
    • + *
  • conversion errors encoding incoming messages before any message handler has been called. These + * are modeled as {@link DecodeException}s
    • + *
+ * + * @param session the session in use when the error occurs. + * @param thr the throwable representing the problem. + */ + public void onError(Session session, Throwable thr) { + } +} Index: 3rdParty_sources/websocket/javax/websocket/EndpointConfig.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/EndpointConfig.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/EndpointConfig.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,85 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.util.List; +import java.util.Map; + +/** + * The endpoint configuration contains all the information needed during the handshake process + * for this end point. All endpoints specify, for example, a URI. In the case of a server endpoint, + * the URI signifies the URI to which the endpoint will be mapped. In the case of a client application + * the URI signifies the URI of the server to which the client endpoint will attempt to connect. + * + * @author dannycoward + */ +public interface EndpointConfig { + + /** + * Return the Encoder implementation classes configured. These + * will be instantiated by the container to encode custom objects passed into + * the send() methods on remote endpoints. + * + * @return the encoder implementation classes, an empty list if none. + */ + List> getEncoders(); + + /** + * Return the Decoder implementation classes configured. These + * will be instantiated by the container to decode incoming messages + * into the expected custom objects on {@link MessageHandler.Whole#onMessage(Object)} + * callbacks. + * + * @return the decoder implementation classes, the empty list if none. + */ + List> getDecoders(); + + /** + * This method returns a modifiable Map that the developer may use to store application + * specific information relating to the endpoint that uses this + * configuration instance. Web socket applications running on distributed + * implementations of the web container should make any application + * specific objects stored here java.io.Serializable, or the object may + * not be recreated after a failover. + * + * @return a modifiable Map of application data. + */ + Map getUserProperties(); +} Index: 3rdParty_sources/websocket/javax/websocket/Extension.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/Extension.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/Extension.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,49 @@ +/* + * To change this template, choose Tools | Templates + * and open the template in the editor. + */ +package javax.websocket; + +import java.util.List; + +/** + * A simple representation of a websocket extension as a name and map of extension parameters. + * + * @author dannycoward + */ +public interface Extension { + + /** + * The name of the extension. + * + * @return the name of the extension. + */ + String getName(); + + /** + * The extension parameters for this extension in the order + * they appear in the http headers. + * + * @return The read-only Map of extension parameters belonging to this extension. + */ + List getParameters(); + + /** + * This member interface defines a single websocket extension parameter. + */ + interface Parameter { + /** + * Return the name of the extension parameter. + * + * @return the name of the parameter. + */ + String getName(); + + /** + * Return the value of the extension parameter. + * + * @return the value of the parameter. + */ + String getValue(); + } +} Index: 3rdParty_sources/websocket/javax/websocket/HandshakeResponse.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/HandshakeResponse.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/HandshakeResponse.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,64 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.util.List; +import java.util.Map; + +/** + * The handshake response represents the web socket-defined Http response + * that is the response to the opening handshake request. + * + * @author dannycoward + */ +public interface HandshakeResponse { + + /** + * The Sec-WebSocket-Accept header name. + */ + static final String SEC_WEBSOCKET_ACCEPT = "Sec-WebSocket-Accept"; + + /** + * Return the list of Http headers sent by the web socket server. + * + * @return the http headers . + */ + Map> getHeaders(); +} Index: 3rdParty_sources/websocket/javax/websocket/MessageHandler.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/MessageHandler.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/MessageHandler.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,130 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + + +/** + * Developers implement MessageHandlers in order to receive incoming messages + * during a web socket conversation. + * Each web socket session uses no more than one thread at a time to call its MessageHandlers. This means + * that, provided each message handler instance is used to handle messages for one web socket session, at most + * one thread at a time can be calling any of its methods. Developers who wish to handle messages from multiple + * clients within the same message handlers may do so by adding the same instance as a handler on each of the Session + * objects for the clients. In that case, they will need to code with the possibility of their MessageHandler + * being called concurrently by multiple threads, each one arising from a different client session. + * + *

See {@link Endpoint} for a usage example. + * + * @author dannycoward + */ +public interface MessageHandler { + + /** + * This kind of handler is notified by the container on arrival of a complete message. If the message is received in parts, + * the container buffers it until it is has been fully received before this method is called. + * + *

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

    + *
  • {@link java.lang.String}
    • + *
  • {@link java.io.Reader}
    • + *
  • any developer object for which there is a corresponding {@link Decoder.Text} or + * {@link Decoder.TextStream} configured
    • + *
+ * + *

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

    + *
  • {@link java.nio.ByteBuffer}
    • + *
  • byte[]
    • + *
  • {@link java.io.InputStream}
    • + *
  • any developer object for which there is a corresponding {@link Decoder.Binary} or + * {@link Decoder.BinaryStream} configured + *
+ * + *

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

Developers should not continue to reference message objects of type {@link java.io.Reader}, {@link java.nio.ByteBuffer} + * or {@link java.io.InputStream} after the completion of the onMessage() call, since they + * may be recycled by the implementation. + * + * @param The type of the message object that this MessageHandler will consume. + */ + interface Whole extends MessageHandler { + + /** + * Called when the message has been fully received. + * + * @param message the message data. + */ + void onMessage(T message); + } + + /** + * This kind of handler is notified by the implementation as it becomes ready + * to deliver parts of a whole message. + * + *

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

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

    + *
  • {@link java.nio.ByteBuffer}
    • + *
  • byte[]
    • + *
+ * + *

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

Note: Implementations may choose their own schemes for delivering large messages in smaller parts through this API. These + * schemes may or may not bear a relationship to the underlying websocket dataframes in which the message + * is received off the wire. + * + * @param The type of the object that represent pieces of the incoming message that this MessageHandler will consume. + */ + interface Partial extends MessageHandler { + + /** + * Called when the next part of a message has been fully received. + * + * @param partialMessage the partial message data. + * @param last flag to indicate if this partialMessage is the last of the whole message being delivered. + */ + void onMessage(T partialMessage, boolean last); + } +} Index: 3rdParty_sources/websocket/javax/websocket/OnClose.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/OnClose.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/OnClose.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,70 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * This method level annotation can be used to decorate a Java method that wishes + * to be called when a web socket session is closing. + * + *

The method may only take the following parameters:- + *

    + *
  • optional {@link Session} parameter
    • + *
  • optional {@link CloseReason} parameter
    • + *
  • Zero to n String parameters annotated with the {@link javax.websocket.server.PathParam} + * annotation.
    • + *
+ * + *

The parameters may appear in any order. See + * {@link Endpoint#onClose} + * for more details on how the session parameter may be used during method calls + * annotated with this annotation. + * + * @author dannycoward + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +public @interface OnClose { + +} Index: 3rdParty_sources/websocket/javax/websocket/OnError.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/OnError.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/OnError.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,67 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * This method level annotation can be used to decorate a Java method that wishes to be called in order + * to handle errors. See {@link Endpoint#onError} for + * a description of the different categories of error. + * + *

The method may only take the following parameters:- + *

    + *
  • optional {@link Session} parameter
    • + *
  • a {@link java.lang.Throwable} parameter
    • + *
  • Zero to n String parameters annotated with the {@link javax.websocket.server.PathParam} annotation
    • + *
+ * + *

The parameters may appear in any order. + * + * @author dannycoward + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +public @interface OnError { + +} Index: 3rdParty_sources/websocket/javax/websocket/OnMessage.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/OnMessage.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/OnMessage.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,144 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * This method level annotation can be used to make a Java method receive incoming web socket messages. Each websocket + * endpoint may only have one message handling method for each of the native websocket message formats: text, binary and pong. Methods + * using this annotation are allowed to have + * parameters of types described below, otherwise the container will generate an error at deployment time. + *

The allowed parameters are: + *

    + *
  1. Exactly one of any of the following choices + *
      + *
    • if the method is handling text messages: + *
        + *
      • {@link java.lang.String} to receive the whole message
        • + *
      • Java primitive or class equivalent to receive the whole message converted to that type
        • + *
      • String and boolean pair to receive the message in parts
        • + *
      • {@link java.io.Reader} to receive the whole message as a blocking stream
        • + *
      • any object parameter for which the endpoint has a text decoder ({@link Decoder.Text} or + * {@link Decoder.TextStream}).
        • + *
      + *
      • + *
    • if the method is handling binary messages: + *
        + *
      • byte[] or {@link java.nio.ByteBuffer} to receive the whole message
        • + *
      • byte[] and boolean pair, or {@link java.nio.ByteBuffer} and boolean pair to receive the message in parts
        • + *
      • {@link java.io.InputStream} to receive the whole message as a blocking stream
        • + *
      • any object parameter for which the endpoint has a binary decoder ({@link Decoder.Binary} or + * {@link Decoder.BinaryStream}).
        • + *
      + *
      • + *
    • if the method is handling pong messages: + *
        + *
      • {@link PongMessage} for handling pong messages
        • + *
      + *
      • + *
    + *
    2. + *
  2. and Zero to n String or Java primitive parameters + * annotated with the {@link javax.websocket.server.PathParam} annotation for server endpoints.
    3. + *
  3. and an optional {@link Session} parameter
    4. + *
+ *

+ * The parameters may be listed in any order. + * + *

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

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

For example: + * 


+ * @OnMessage
+ * public void processGreeting(String message, Session session) {
+ *     System.out.println("Greeting received:" + message);
+ * }
+ *
+ * For example: + * 

+ * @OnMessage
+ * public void processUpload(byte[] b, boolean last, Session session) {
+ *     // process partial data here, which check on last to see if these is more on the way
+ * }
+ *
+ * Developers should not continue to reference message objects of type {@link java.io.Reader}, {@link java.nio.ByteBuffer} + * or {@link java.io.InputStream} after the annotated method has completed, since they + * may be recycled by the implementation. + * + * @author dannycoward + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +public @interface OnMessage { + + /** + * Specifies the maximum size of message in bytes that the method + * this annotates will be able to process, or -1 to indicate + * that there is no maximum. The default is -1. This attribute only + * applies when the annotation is used to process whole messages, not to + * those methods that process messages in parts or use a stream or reader + * parameter to handle the incoming message. + * If the incoming whole message exceeds this limit, then the implementation + * generates an error and closes the connection using the reason that + * the message was too big. + * + * @return the maximum size in bytes. + */ + public long maxMessageSize() default -1; +} Index: 3rdParty_sources/websocket/javax/websocket/OnOpen.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/OnOpen.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/OnOpen.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,66 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * This method level annotation can be used to decorate a Java method that wishes to be called when a new + * web socket session is open. + * + *

The method may only take the following parameters:- + *

    + *
  • optional {@link Session} parameter
    • + *
  • optional {@link EndpointConfig} parameter
    • + *
  • Zero to n String parameters annotated with the {@link javax.websocket.server.PathParam} annotation.
    • + *
+ * + *

The parameters may appear in any order. + * + * @author dannycoward + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +public @interface OnOpen { + +} Index: 3rdParty_sources/websocket/javax/websocket/PongMessage.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/PongMessage.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/PongMessage.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,58 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.nio.ByteBuffer; + +/** + * The PongMessage interface represents a web socket pong. PongMessages may be received by using + * a {@code MessageHandler.Basic}. The payload of the PongMessage is the application data sent by the peer. + * + * @author dannycoward + */ +public interface PongMessage { + + /** + * The application data inside the pong message from the peer. + * + * @return the application data. + */ + ByteBuffer getApplicationData(); +} Index: 3rdParty_sources/websocket/javax/websocket/RemoteEndpoint.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/RemoteEndpoint.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/RemoteEndpoint.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,356 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.io.IOException; +import java.io.OutputStream; +import java.io.Writer; +import java.nio.ByteBuffer; +import java.util.concurrent.Future; + +/** + * The RemoteEndpoint object is supplied by the container and represents the + * 'other end' or peer of the Web Socket conversation. Instances of the RemoteEndpoint + * are obtained from the Session using {@link Session#getBasicRemote()} or + * {@link Session#getAsyncRemote()}. + * Objects of this kind include numerous ways to send web socket messages. There + * are two kinds of RemoteEndpoint objects: RemoteEndpoint.Basic for synchronous + * sending of websocket messages, and RemoteEndpoint.Async for sending messages + * asynchronously. + * + *

There is no guarantee of the successful delivery of a web socket message to + * the peer, but if the action of sending a message causes an error known to + * the container, the API throws it. + * RemoteEndpoints include a variety of ways to send messages: by whole message, + * in parts, and in various data formats including websocket pings and pongs. + * + *

Implementations + * may or may not support batching of messages. More detail of the expected semantics + * of implementations that do support batching are laid out in {@link RemoteEndpoint#setBatchingAllowed(boolean)}. + * + *

Note: Implementations may choose their own schemes for sending large messages in smaller parts. These + * schemes may or may not bear a relationship to the underlying websocket dataframes in which the message + * is ultimately sent on the wire. + * + *

If the underlying connection is closed and methods on the RemoteEndpoint are attempted to be called, they will + * result in an error being generated. For the methods that send messages, this will be an IOException, for the methods + * that alter configuration of the endpoint, this will be runtime IllegalArgumentExceptions. + * @author dannycoward + */ +public interface RemoteEndpoint { + + /** + * Indicate to the implementation that it is allowed to batch outgoing messages + * before sending. Not all implementations support batching of outgoing messages. + * The default mode for RemoteEndpoints is false. If the developer + * has indicated that batching of outgoing + * messages is permitted, then the developer must call flushBatch() in order to be + * sure that all the messages passed into the send methods of this RemoteEndpoint + * are sent. + * When batching is allowed, the implementations send operations are considered + * to have completed if the message has been written to the local batch, in + * the case when there is still room in the batch for the message, and are considered + * to have completed if the batch has been send to the peer and the remainder + * written to the new batch, in the case when + * writing the message causes the batch to need to be sent. The blocking + * and asynchronous send methods use this notion of completion in order + * to complete blocking calls, notify SendHandlers and complete Futures respectively. + * When batching is allowed, if the developer has called send methods + * on this RemoteEndpoint without calling flushBatch(), then the implementation + * may not have sent all the messages the developer has asked to be sent. If + * the parameter value is false and the implementation has a batch of unsent messages, + * then the implementation must immediately send the batch of unsent messages. + * + * @param allowed whether the implementation is allowed to batch messages. + * @throws IOException if batching is being disabled and there are unsent messages + * this error may be thrown as the implementation sends the batch of unsent messages if + * there is a problem. + */ + void setBatchingAllowed(boolean allowed) throws IOException; + + /** + * Return whether the implementation is allowed to batch outgoing messages + * before sending. The default mode for RemoteEndpoints is false. The value + * may be changed by calling {@link #setBatchingAllowed(boolean) setBatchingAllowed}. + */ + boolean getBatchingAllowed(); + + /** + * This method is only used when batching is allowed for this RemoteEndpint. Calling + * this method forces the implementation to send any unsent messages it has been batching. + */ + void flushBatch() throws IOException; + + /** + * Send a Ping message containing the given application data to the remote endpoint. The corresponding Pong message may be picked + * up using the MessageHandler.Pong handler. + * + * @param applicationData the data to be carried in the ping request. + * @throws IOException if the ping failed to be sent + * @throws IllegalArgumentException if the applicationData exceeds the maximum allowed payload of 125 bytes + */ + void sendPing(ByteBuffer applicationData) throws IOException, IllegalArgumentException; + + /** + * Allows the developer to send an unsolicited Pong message containing the given application + * data in order to serve as a unidirectional + * heartbeat for the session. + * + * @param applicationData the application data to be carried in the pong response. + * @throws IOException if the pong failed to be sent + * @throws IllegalArgumentException if the applicationData exceeds the maximum allowed payload of 125 bytes + */ + void sendPong(ByteBuffer applicationData) throws IOException, IllegalArgumentException; + + /** + * This representation of the peer of a web socket conversation has the ability + * to send messages asynchronously. The point of completion of the send is + * defined when all the supplied data has been written to the underlying connection. + * The completion handlers for the asynchronous methods are always called with + * a different thread from that which initiated the send. + */ + interface Async extends RemoteEndpoint { + + /** + * Return the number of milliseconds the implementation will timeout + * attempting to send a websocket message. A non-positive number indicates + * the implementation will not timeout attempting to send a websocket message + * asynchronously. This value overrides the default value assigned in the + * WebSocketContainer. + * + * @return the timeout time in milliseconds. + */ + long getSendTimeout(); + + /** + * Sets the number of milliseconds the implementation will timeout + * attempting to send a websocket message. A non-positive number indicates + * the implementation will not timeout attempting to send a websocket message + * asynchronously. This value overrides the default value assigned in the + * WebSocketContainer. + * + * @param timeoutmillis The number of milliseconds this RemoteEndpoint will wait before timing out + * an incomplete asynchronous message send. + */ + void setSendTimeout(long timeoutmillis); + + /** + * Initiates the asynchronous transmission of a text message. This method returns before the message + * is transmitted. Developers provide a callback to be notified when the message has been + * transmitted. Errors + * in transmission are given to the developer in the SendResult object. + * + * @param text the text being sent. + * @param handler the handler which will be notified of progress. + * @throws IllegalArgumentException if the text or the handler is {@code null}. + */ + void sendText(String text, SendHandler handler); + + /** + * Initiates the asynchronous transmission of a text message. This method + * returns before the message is transmitted. Developers use the + * returned Future object to track progress of the transmission. The + * Future's get() method returns {@code null} upon successful completion. Errors + * in transmission are wrapped in the {@link java.util.concurrent.ExecutionException} + * thrown when querying the Future object. + * + * @param text the text being sent. + * @return the Future object representing the send operation. + * @throws IllegalArgumentException if the text is {@code null}. + */ + Future sendText(String text); + + /** + * Initiates the asynchronous transmission of a binary message. This method returns before the message + * is transmitted. Developers use the returned Future object to track progress of the transmission. The + * Future's get() method returns {@code null} upon successful completion. Errors + * in transmission are wrapped in the {@link java.util.concurrent.ExecutionException} + * thrown when querying the Future object. + * + * @param data the data being sent. + * @return the Future object representing the send operation. + * @throws IllegalArgumentException if the data is {@code null}. + */ + Future sendBinary(ByteBuffer data); + + /** + * Initiates the asynchronous transmission of a binary message. This method returns before the message + * is transmitted. Developers provide a callback to be notified when the message has been + * transmitted. Errors in transmission are given to the developer in the SendResult object. + * + * @param data the data being sent, must not be {@code null}. + * @param handler the handler that will be notified of progress, must not be {@code null}. + * @throws IllegalArgumentException if either the data or the handler are {@code null}. + */ + void sendBinary(ByteBuffer data, SendHandler handler); + + /** + * Initiates the asynchronous transmission of a custom developer object. + * The developer will have provided an encoder for this object + * type in the endpoint configuration. Containers will by default be able + * to encode java primitive types and their object equivalents, otherwise + * the developer must have provided an encoder for the object type in the + * endpoint configuration. Progress may be tracked using the Future object. + * The Future's get() methods return {@code null} upon successful completion. Errors + * in transmission are wrapped in the {@link java.util.concurrent.ExecutionException} + * thrown when querying the Future object. + * + * @param data the object being sent. + * @return the Future object representing the send operation. + * @throws IllegalArgumentException if the data is {@code null}. + + */ + Future sendObject(Object data); + + /** + * Initiates the asynchronous transmission of a custom developer object. + * Containers will by default be able to encode java primitive types and + * their object equivalents, otherwise the developer must have provided an encoder + * for the object type in the endpoint configuration. Developers + * are notified when transmission is complete through the supplied callback object. + * + * @param data the object being sent. + * @param handler the handler that will be notified of progress, must not be {@code null}. + * @throws IllegalArgumentException if either the data or the handler are {@code null}. + */ + void sendObject(Object data, SendHandler handler); + + } + + /** + * This representation of the peer of a web socket conversation has the ability + * to send messages synchronously. The point of completion of the send is + * defined when all the supplied data has been written to the underlying connection. + * The methods for sending messages on the RemoteEndpoint.Basic block until this + * point of completion is reached, except for {@link RemoteEndpoint.Basic#getSendStream() getSendStream} + * and {@link RemoteEndpoint.Basic#getSendWriter() getSendWriter} which present + * traditional blocking I/O streams to write messages. + * + *

If the websocket connection underlying this RemoteEndpoint is busy sending a message when a call is made + * to send another one, for example if two threads attempt to call a send method + * concurrently, or if a developer attempts to send a new message while in the + * middle of sending an existing one, the send method called while + * the connection is already busy may throw an {@link java.lang.IllegalStateException}. + */ + + interface Basic extends RemoteEndpoint { + + /** + * Send a text message, blocking until all of the message has been transmitted. + * + * @param text the message to be sent. + * @throws IOException if there is a problem delivering the message. + * @throws IllegalArgumentException if the text is {@code null}. + */ + void sendText(String text) throws IOException; + + /** + * Send a binary message, returning when all of the message has been transmitted. + * + * @param data the message to be sent. + * @throws IOException if there is a problem delivering the message. + * @throws IllegalArgumentException if the data is {@code null}. + + */ + void sendBinary(ByteBuffer data) throws IOException; + + /** + * Send a text message in parts, blocking until all of the message has been transmitted. The runtime + * reads the message in order. Non-final parts of the message are sent with isLast set to false. The final part + * must be sent with isLast set to true. + * + * @param partialMessage the parts of the message being sent. + * @param isLast Whether the partial message being sent is the last part of the message. + * @throws IOException if there is a problem delivering the message fragment. + * @throws IllegalArgumentException if the partialMessage is {@code null}. + */ + void sendText(String partialMessage, boolean isLast) throws IOException; + + /** + * Send a binary message in parts, blocking until all of the message has been transmitted. The runtime + * reads the message in order. Non-final parts are sent with isLast set to false. The final piece + * must be sent with isLast set to true. + * + * @param partialByte the part of the message being sent. + * @param isLast Whether the partial message being sent is the last part of the message. + * @throws IOException if there is a problem delivering the partial message. + * @throws IllegalArgumentException if the partialByte is {@code null}. + */ + void sendBinary(ByteBuffer partialByte, boolean isLast) throws IOException; // or Iterable + + /** + * Opens an output stream on which a binary message may be sent. The developer must close the output stream in order + * to indicate that the complete message has been placed into the output stream. + * + * @return the output stream to which the message will be written. + * @throws IOException if there is a problem obtaining the OutputStream to write the binary message. + */ + OutputStream getSendStream() throws IOException; + + /** + * Opens an character stream on which a text message may be sent. The developer must close the writer in order + * to indicate that the complete message has been placed into the character stream. + * + * @return the writer to which the message will be written. + * @throws IOException if there is a problem obtaining the Writer to write the text message. + */ + Writer getSendWriter() throws IOException; + + /** + * Sends a custom developer object, blocking until it has been transmitted. + * Containers will by default be able to encode java primitive types and + * their object equivalents, otherwise the developer must have provided an encoder + * for the object type in the endpoint configuration. A developer-provided + * encoder for a Java primitive type overrides the container default + * encoder. + * + * @param data the object to be sent. + * @throws IOException if there is a communication error sending the message object. + * @throws EncodeException if there was a problem encoding the message object into the form of a native websocket message. + * @throws IllegalArgumentException if the data parameter is {@code null} + */ + void sendObject(Object data) throws IOException, EncodeException; + } + + + + +} + Index: 3rdParty_sources/websocket/javax/websocket/SendHandler.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/SendHandler.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/SendHandler.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,55 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +/** + * A simple callback object for asynchronous sending of web socket messages. + * + * @author dannycoward + */ +public interface SendHandler { + + /** + * Called once the message has been transmitted. + * + * @param result the result. + */ + void onResult(SendResult result); +} Index: 3rdParty_sources/websocket/javax/websocket/SendResult.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/SendResult.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/SendResult.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,89 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +/** + * The result of asynchronously sending a web socket message. A SendResult is either + * ok indicating there was no problem, or is not OK in which case there was a problem + * and it carries an exception to indicate what the problem was. + * + * @author dannycoward + */ +final public class SendResult { + + private final Throwable exception; + private final boolean isOK; + + /** + * Construct a SendResult carrying an exception. + * + * @param exception the exception causing a send failure. + */ + public SendResult(Throwable exception) { + this.exception = exception; + this.isOK = false; + } + + /** + * Construct a SendResult signifying a successful send carrying no exception. + */ + public SendResult() { + this.exception = null; + this.isOK = true; + } + + /** + * The problem sending the message. + * + * @return the problem or {@code null} if the send was successful. + */ + public Throwable getException() { + return exception; + } + + /** + * Determines if this result is ok or not. + * + * @return whether the send was successful or not. + */ + public boolean isOK() { + return this.isOK; + } +} Index: 3rdParty_sources/websocket/javax/websocket/Session.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/Session.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/Session.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,350 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2014 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.io.Closeable; +import java.io.IOException; +import java.net.URI; +import java.security.Principal; +import java.util.List; +import java.util.Map; +import java.util.Set; + + +/** + * A Web Socket session represents a conversation between two web socket endpoints. As soon + * as the websocket handshake completes successfully, the web socket implementation provides + * the endpoint an open websocket session. The endpoint can then register interest in incoming + * messages that are part of this newly created session by providing a MessageHandler to the + * session, and can send messages to the other end of the conversation by means of the RemoteEndpoint object + * obtained from this session. + *

+ * Once the session is closed, it is no longer valid for use by applications. Calling any of + * its methods (with the exception of the close() methods) + * once the session has been closed will result in an {@link java.lang.IllegalStateException} being thrown. + * Developers should retrieve any information from the session during the + * {@link Endpoint#onClose} method. Following the convention of {@link java.io.Closeable} + * calling the Session close() methods after the Session has been closed has no + * effect. + *

+ * Session objects may be called by multiple threads. Implementations must + * ensure the integrity of the mutable properties of the session under such circumstances. + * + * @author dannycoward + */ +public interface Session extends Closeable { + + /** + * Return the container that this session is part of. + * + * @return the container. + */ + WebSocketContainer getContainer(); + + /** + * Register to handle to incoming messages in this conversation. A maximum of one message handler per + * native websocket message type (text, binary, pong) may be added to each Session. I.e. a maximum + * of one message handler to handle incoming text messages a maximum of one message handler for + * handling incoming binary messages, and a maximum of one for handling incoming pong + * messages. For further details of which message handlers handle which of the native websocket + * message types please see {@link MessageHandler.Whole} and {@link MessageHandler.Partial}. + * Adding more than one of any one type will result in a runtime exception. + *

+ * This method is not safe to use unless you are providing an anonymous class derived directly + * from {@link javax.websocket.MessageHandler.Whole} or {@link javax.websocket.MessageHandler.Partial}. + * In all other cases (Lambda Expressions, more complex inheritance or generic type arrangements), + * one of the following methods have to be used: + * {@link #addMessageHandler(Class, javax.websocket.MessageHandler.Whole)} or + * {@link #addMessageHandler(Class, javax.websocket.MessageHandler.Partial)}. + * + * @param handler the MessageHandler to be added. + * @throws IllegalStateException if there is already a MessageHandler registered for the same native + * websocket message type as this handler. + */ + void addMessageHandler(MessageHandler handler) throws IllegalStateException; + + /** + * Register to handle to incoming messages in this conversation. A maximum of one message handler per + * native websocket message type (text, binary, pong) may be added to each Session. I.e. a maximum + * of one message handler to handle incoming text messages a maximum of one message handler for + * handling incoming binary messages, and a maximum of one for handling incoming pong + * messages. For further details of which message handlers handle which of the native websocket + * message types please see {@link MessageHandler.Whole} and {@link MessageHandler.Partial}. + * Adding more than one of any one type will result in a runtime exception. + * + * @param clazz type of the message processed by message handler to be registered. + * @param handler whole message handler to be added. + * @throws IllegalStateException if there is already a MessageHandler registered for the same native + * websocket message type as this handler. + * @since 1.1 + */ + public void addMessageHandler(Class clazz, MessageHandler.Whole handler); + + /** + * Register to handle to incoming messages in this conversation. A maximum of one message handler per + * native websocket message type (text, binary, pong) may be added to each Session. I.e. a maximum + * of one message handler to handle incoming text messages a maximum of one message handler for + * handling incoming binary messages, and a maximum of one for handling incoming pong + * messages. For further details of which message handlers handle which of the native websocket + * message types please see {@link MessageHandler.Whole} and {@link MessageHandler.Partial}. + * Adding more than one of any one type will result in a runtime exception. + * + * @param clazz type of the message processed by message handler to be registered. + * @param handler partial message handler to be added. + * @throws IllegalStateException if there is already a MessageHandler registered for the same native + * websocket message type as this handler. + * @since 1.1 + */ + public void addMessageHandler(Class clazz, MessageHandler.Partial handler); + + /** + * Return an unmodifiable copy of the set of MessageHandlers for this Session. + * + * @return the set of message handlers. + */ + Set getMessageHandlers(); + + /** + * Remove the given MessageHandler from the set belonging to this session. This method may block + * if the given handler is processing a message until it is no longer in use. + * + * @param handler the handler to be removed. + */ + void removeMessageHandler(MessageHandler handler); + + /** + * Returns the version of the websocket protocol currently being used. This is taken + * as the value of the Sec-WebSocket-Version header used in the opening handshake. i.e. "13". + * + * @return the protocol version. + */ + String getProtocolVersion(); + + /** + * Return the sub protocol agreed during the websocket handshake for this conversation. + * + * @return the negotiated subprotocol, or the empty string if there isn't one. + */ + String getNegotiatedSubprotocol(); + + /** + * Return the list of extensions currently in use for this conversation. + * + * @return the negotiated extensions. + */ + List getNegotiatedExtensions(); + + /** + * Return true if and only if the underlying socket is using a secure transport. + * + * @return whether its using a secure transport. + */ + boolean isSecure(); + + /** + * Return true if and only if the underlying socket is open. + * + * @return whether the session is active. + */ + boolean isOpen(); + + /** + * Return the number of milliseconds before this conversation may be closed by the + * container if it is inactive, i.e. no messages are either sent or received in that time. + * + * @return the timeout in milliseconds. + */ + long getMaxIdleTimeout(); + + /** + * Set the non-zero number of milliseconds before this session will be closed by the + * container if it is inactive, ie no messages are either sent or received. A value that is + * 0 or negative indicates the session will never timeout due to inactivity. + * + * @param milliseconds the number of milliseconds. + */ + void setMaxIdleTimeout(long milliseconds); + + /** + * Sets the maximum length of incoming binary messages that this Session can buffer. + * + * @param length the maximum length. + */ + void setMaxBinaryMessageBufferSize(int length); + + /** + * The maximum length of incoming binary messages that this Session can buffer. If + * the implementation receives a binary message that it cannot buffer because it + * is too large, it must close the session with a close code of {@link CloseReason.CloseCodes#TOO_BIG}. + * + * @return the maximum binary message size that can be buffered. + */ + int getMaxBinaryMessageBufferSize(); + + /** + * Sets the maximum length of incoming text messages that this Session can buffer. + * + * @param length the maximum length. + */ + void setMaxTextMessageBufferSize(int length); + + /** + * The maximum length of incoming text messages that this Session can buffer. If + * the implementation receives a text message that it cannot buffer because it + * is too large, it must close the session with a close code of {@link CloseReason.CloseCodes#TOO_BIG}. + * + * @return the maximum text message size that can be buffered. + */ + int getMaxTextMessageBufferSize(); + + /** + * Return a reference a RemoteEndpoint object representing the peer of this conversation + * that is able to send messages asynchronously to the peer. + * + * @return the remote endpoint. + */ + RemoteEndpoint.Async getAsyncRemote(); + + /** + * Return a reference a RemoteEndpoint object representing the peer of this conversation + * that is able to send messages synchronously to the peer. + * + * @return the remote endpoint. + */ + RemoteEndpoint.Basic getBasicRemote(); + + /** + * Returns a string containing the unique identifier assigned to this session. + * The identifier is assigned by the web socket implementation and is implementation dependent. + * + * @return the unique identifier for this session instance. + */ + String getId(); + + /** + * Close the current conversation with a normal status code and no reason phrase. + * + * @throws IOException if there was a connection error closing the connection. + */ + @Override + void close() throws IOException; + + /** + * Close the current conversation, giving a reason for the closure. The close + * call causes the implementation to attempt notify the client of the close as + * soon as it can. This may cause the sending of unsent messages immediately + * prior to the close notification. After the close notification has been sent + * the implementation notifies the endpoint's onClose method. Note the websocket + * specification defines the + * acceptable uses of status codes and reason phrases. If the application cannot + * determine a suitable close code to use for the closeReason, it is recommended + * to use {@link CloseReason.CloseCodes#NO_STATUS_CODE}. + * + * @param closeReason the reason for the closure. + * @throws IOException if there was a connection error closing the connection + */ + void close(CloseReason closeReason) throws IOException; + + /** + * Return the URI under which this session was opened, including + * the query string if there is one. + * + * @return the request URI. + */ + URI getRequestURI(); + + /** + * Return the request parameters associated with the request this session + * was opened under. + * + * @return the unmodifiable map of the request parameters. + */ + Map> getRequestParameterMap(); + + /** + * Return the query string associated with the request this session + * was opened under. + * + * @return the query string + */ + String getQueryString(); + + /** + * Return a map of the path parameter names and values used associated with the + * request this session was opened under. + * + * @return the unmodifiable map of path parameters. The key of the map is the parameter name, + * the values in the map are the parameter values. + */ + Map getPathParameters(); + + /** + * While the session is open, this method returns a Map that the developer may + * use to store application specific information relating to this session + * instance. The developer may retrieve information from this Map at any time + * between the opening of the session and during the onClose() method. But outside + * that time, any information stored using this Map may no longer be kept by the + * container. Web socket applications running on distributed implementations of + * the web container should make any application specific objects stored here + * java.io.Serializable, or the object may not be recreated after a failover. + * + * @return an editable Map of application data. + */ + Map getUserProperties(); + + /** + * Return the authenticated user for this Session or {@code null} if no user is authenticated for this session. + * + * @return the user principal. + */ + Principal getUserPrincipal(); + + /** + * Return a copy of the Set of all the open web socket sessions that represent + * connections to the same endpoint to which this session represents a connection. + * The Set includes the session this method is called on. These + * sessions may not still be open at any point after the return of this method. For + * example, iterating over the set at a later time may yield one or more closed sessions. Developers + * should use session.isOpen() to check. + * + * @return the set of sessions, open at the time of return. + */ + Set getOpenSessions(); +} Index: 3rdParty_sources/websocket/javax/websocket/SessionException.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/SessionException.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/SessionException.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,41 @@ +/* + * To change this template, choose Tools | Templates + * and open the template in the editor. + */ +package javax.websocket; + +/** + * A SessionException represents a general exception type reporting problems + * occurring on a websocket session. + * + * @author dannycoward + */ +public class SessionException extends Exception { + private final Session session; + private static final long serialVersionUID = 014; + + /** + * Creates a new instance of this exception with the given message, + * the wrapped cause of the exception and the session with which + * the problem is associated. + * + * @param message a description of the problem + * @param cause the error that caused the problem + * @param session the session on which the problem occurred. + */ + + public SessionException(String message, Throwable cause, Session session) { + super(message, cause); + this.session = session; + } + + /** + * Return the Session on which the problem occurred. + * + * @return the session + */ + + public Session getSession() { + return this.session; + } +} Index: 3rdParty_sources/websocket/javax/websocket/WebSocketContainer.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/WebSocketContainer.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/WebSocketContainer.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,234 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket; + +import java.io.*; +import java.net.URI; +import java.util.Set; + +/** + * A WebSocketContainer is an implementation provided object that provides applications + * a view on the container running it. The WebSocketContainer container various + * configuration parameters that control default session and buffer properties + * of the endpoints it contains. It also allows the developer to + * deploy websocket client endpoints by initiating a web socket handshake from + * the provided endpoint to a supplied URI where the peer endpoint is presumed to + * reside. + * + *

A WebSocketContainer may be accessed by concurrent threads, so + * implementations must ensure the integrity of its mutable attributes in such + * circumstances. + * + * @author dannycoward + */ +public interface WebSocketContainer { + + /** + * Return the number of milliseconds the implementation will timeout + * attempting to send a websocket message for all RemoteEndpoints associated + * with this container. A non-positive number indicates + * the implementation will not timeout attempting to send a websocket message + * asynchronously. Note this default may be overridden in each RemoteEndpoint. + * + * @return the timeout time in millsenconds. + */ + long getDefaultAsyncSendTimeout(); + + /** + * Sets the number of milliseconds the implementation will timeout + * attempting to send a websocket message for all RemoteEndpoints associated + * with this container. A non-positive number indicates + * the implementation will not timeout attempting to send a websocket message + * asynchronously. Note this default may be overridden in each RemoteEndpoint. + */ + void setAsyncSendTimeout(long timeoutmillis); + + /** + * Connect the supplied annotated endpoint instance to its server. The supplied + * object must be a class decorated with the class level + * {@link javax.websocket.server.ServerEndpoint} annotation. This method + * blocks until the connection is established, or throws an error if either + * the connection could not be made or there was a problem with the supplied + * endpoint class. If the developer uses this method to deploy the client + * endpoint, services like dependency injection that are supported, for + * example, when the implementation is part of the Java EE platform + * may not be available. If the client endpoint uses dependency injection, + * use {@link WebSocketContainer#connectToServer(java.lang.Class, java.net.URI)} + * instead. + * + * @param annotatedEndpointInstance the annotated websocket client endpoint + * instance. + * @param path the complete path to the server endpoint. + * @return the Session created if the connection is successful. + * @throws DeploymentException if the annotated endpoint instance is not valid. + * @throws IOException if there was a network or protocol problem that + * prevented the client endpoint being connected to its server. + * @throws IllegalStateException if called during the deployment phase + * of the containing application. + */ + Session connectToServer(Object annotatedEndpointInstance, URI path) throws DeploymentException, IOException; + + /** + * Connect the supplied annotated endpoint to its server. The supplied object must be a + * class decorated with the class level + * {@link javax.websocket.server.ServerEndpoint} annotation. This method blocks until the connection + * is established, or throws an error if either the connection could not be made or there + * was a problem with the supplied endpoint class. + * + * @param annotatedEndpointClass the annotated websocket client endpoint. + * @param path the complete path to the server endpoint. + * @return the Session created if the connection is successful. + * @throws DeploymentException if the class is not a valid annotated endpoint class. + * @throws IOException if there was a network or protocol problem that + * prevented the client endpoint being connected to its server. + * @throws IllegalStateException if called during the deployment phase + * of the containing application. + */ + Session connectToServer(Class annotatedEndpointClass, URI path) throws DeploymentException, IOException; + + + /** + * Connect the supplied programmatic client endpoint instance to its server + * with the given configuration. This method blocks until the connection + * is established, or throws an error if the connection could not be made. + * If the developer uses this method to deploy the client + * endpoint, services like dependency injection that are supported, for + * example, when the implementation is part of the Java EE platform + * may not be available. If the client endpoint uses dependency injection, + * use {@link WebSocketContainer#connectToServer(java.lang.Class, javax.websocket.ClientEndpointConfig, java.net.URI) } + * instead. + * + * @param endpointInstance the programmatic client endpoint instance {@link Endpoint}. + * @param path the complete path to the server endpoint. + * @param cec the configuration used to configure the programmatic endpoint. + * @return the Session created if the connection is successful. + * @throws DeploymentException if the configuration is not valid + * @throws IOException if there was a network or protocol problem that + * prevented the client endpoint being connected to its server + * @throws IllegalStateException if called during the deployment phase + * of the containing application. + */ + Session connectToServer(Endpoint endpointInstance, ClientEndpointConfig cec, URI path) throws DeploymentException, IOException; + + /** + * Connect the supplied programmatic endpoint to its server with the given + * configuration. This method blocks until the connection + * is established, or throws an error if the connection could not be made. + * + * @param endpointClass the programmatic client endpoint class {@link Endpoint}. + * @param path the complete path to the server endpoint. + * @param cec the configuration used to configure the programmatic endpoint. + * @return the Session created if the connection is successful. + * @throws DeploymentException if the configuration is not valid + * @throws IOException if there was a network or protocol problem that prevented the client endpoint being connected to its server + * @throws IllegalStateException if called during the deployment phase + * of the containing application. + */ + Session connectToServer(Class endpointClass, ClientEndpointConfig cec, URI path) throws DeploymentException, IOException; + + + + /** + * Return the default time in milliseconds after which any web socket sessions in this + * container will be closed if it has been inactive. A value that is + * 0 or negative indicates the sessions will never timeout due to inactivity. + * The value may be overridden on a per session basis using + * {@link Session#setMaxIdleTimeout(long) } + * + * @return the default number of milliseconds after which an idle session in this container + * will be closed + */ + long getDefaultMaxSessionIdleTimeout(); + + /** + * Sets the default time in milliseconds after which any web socket sessions in this + * container will be closed if it has been inactive. A value that is + * 0 or negative indicates the sessions will never timeout due to inactivity. + * The value may be overridden on a per session basis using + * {@link Session#setMaxIdleTimeout(long) } + * + * @param timeout the maximum time in milliseconds. + */ + void setDefaultMaxSessionIdleTimeout(long timeout); + + /** + * Returns the default maximum size of incoming binary message that this container + * will buffer. This default may be overridden on a per session basis using + * {@link Session#setMaxBinaryMessageBufferSize(int) } + * + * @return the maximum size of incoming binary message in number of bytes. + */ + int getDefaultMaxBinaryMessageBufferSize(); + + /** + * Sets the default maximum size of incoming binary message that this container + * will buffer. + * + * @param max the maximum size of binary message in number of bytes. + */ + void setDefaultMaxBinaryMessageBufferSize(int max); + + /** + * Returns the default maximum size of incoming text message that this container + * will buffer. This default may be overridden on a per session basis using + * {@link Session#setMaxTextMessageBufferSize(int) } + * + * @return the maximum size of incoming text message in number of bytes. + */ + int getDefaultMaxTextMessageBufferSize(); + + /** + * Sets the maximum size of incoming text message that this container + * will buffer. + * + * @param max the maximum size of text message in number of bytes. + */ + void setDefaultMaxTextMessageBufferSize(int max); + + /** + * Return the set of Extensions installed in the container. + * + * @return the set of extensions. + */ + Set getInstalledExtensions(); +} + + + Index: 3rdParty_sources/websocket/javax/websocket/package-info.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/package-info.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/package-info.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,46 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ + +/** + * This package contains all the WebSocket APIs common to both the client + * and server side. + */ +package javax.websocket; + Index: 3rdParty_sources/websocket/javax/websocket/server/DefaultServerEndpointConfig.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/server/DefaultServerEndpointConfig.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/server/DefaultServerEndpointConfig.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,175 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket.server; + +import java.util.Collections; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import javax.websocket.Decoder; +import javax.websocket.Encoder; +import javax.websocket.Endpoint; +import javax.websocket.Extension; + + +/** + * The DefaultServerEndpointConfig is a concrete class that embodies all the configuration + * parameters for an endpoint that is to be published as a server endpoint. Developers may + * subclass this class in order to override the configuration behavior. + * + * @author dannycoward + */ + final class DefaultServerEndpointConfig implements ServerEndpointConfig { + private String path; + private Class endpointClass; + private List subprotocols; + private List extensions; + private List> encoders; + private List> decoders; + private Map userProperties = new HashMap(); + private ServerEndpointConfig.Configurator serverEndpointConfigurator; + + + // The builder ensures nothing except configurator can be {@code null}. + DefaultServerEndpointConfig(Class endpointClass, + String path, + List subprotocols, + List extensions, + List> encoders, + List> decoders, + ServerEndpointConfig.Configurator serverEndpointConfigurator) { + this.path = path; + this.endpointClass = endpointClass; + this.subprotocols = Collections.unmodifiableList(subprotocols); + this.extensions = Collections.unmodifiableList(extensions); + this.encoders = Collections.unmodifiableList(encoders); + this.decoders = Collections.unmodifiableList(decoders); + if (serverEndpointConfigurator == null) { + this.serverEndpointConfigurator = ServerEndpointConfig.Configurator.fetchContainerDefaultConfigurator(); + } else{ + this.serverEndpointConfigurator = serverEndpointConfigurator; + } + } + + /** + * Returns the class of the Endpoint that this configuration configures. + * + * @return the class of the Endpoint. + */ + @Override + public Class getEndpointClass() { + return this.endpointClass; + } + + + /** + * Creates a server configuration with the given path + * + * @param path the URI or URI template. + */ + DefaultServerEndpointConfig(Class endpointClass, String path) { + this.path = path; + this.endpointClass = endpointClass; + } + + /** + * Return the Encoder implementation classes configured. These + * will be used by the container to encode outgoing messages. + * + * @return the encoder implementation classes, in an unmodifiable list, empty if there are none. + */ + @Override + public List> getEncoders() { + return this.encoders; + } + + /** + * Return the Decoder implementation classes configured. These + * will be used by the container to decode incoming messages + * into the expected custom objects on MessageHandler + * callbacks. + * + * @return the decoder implementation classes, in an unmodifiable list. + */ + @Override + public List> getDecoders() { + return this.decoders; + } + + /** + * Return the path of this server configuration. The path is a relative URI + * or URI-template. + * + * @return the path + */ + @Override + public String getPath() { + return path; + } + + + /** + * Return the ServerEndpointConfigurator + * @return the ServerEndpointConfigurator + */ + @Override + public ServerEndpointConfig.Configurator getConfigurator() { + return this.serverEndpointConfigurator; + } + + /** + * Editable map of user properties. + */ + @Override + public final Map getUserProperties() { + return this.userProperties; + } + + @Override + public final List getSubprotocols() { + return this.subprotocols; + } + + @Override + public final List getExtensions() { + return this.extensions; + } + +} Index: 3rdParty_sources/websocket/javax/websocket/server/HandshakeRequest.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/server/HandshakeRequest.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/server/HandshakeRequest.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,130 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket.server; + +import java.net.URI; +import java.security.Principal; +import java.util.List; +import java.util.Map; + +/** + * The handshake request represents the web socket defined Http GET request + * for the opening handshake of a web socket session. + * + * @author dannycoward + */ +public interface HandshakeRequest { + /** + * The Sec-WebSocket-Key header name + */ + static String SEC_WEBSOCKET_KEY = "Sec-WebSocket-Key"; + /** + * The Sec-WebSocket-Protocol header name + */ + static String SEC_WEBSOCKET_PROTOCOL = "Sec-WebSocket-Protocol"; + /** + * The Sec-WebSocket-Version header name + */ + static String SEC_WEBSOCKET_VERSION = "Sec-WebSocket-Version"; + /** + * The Sec-WebSocket-Extensions header name + */ + static String SEC_WEBSOCKET_EXTENSIONS = "Sec-WebSocket-Extensions"; + + /** + * Return the read only Map of Http Headers that came with the handshake request. The header names + * are case insensitive. + * + * @return the list of headers. + */ + Map> getHeaders(); + + /** + * Return the authenticated user or {@code null} if no user is authenticated + * for this handshake. + * + * @return the user principal. + */ + Principal getUserPrincipal(); + + /** + * Return the request URI of the handshake request. + * + * @return the request uri of the handshake request. + */ + URI getRequestURI(); + + /** + * Checks whether the current user is in the given role. Roles and role + * membership can be defined using deployment descriptors of the containing + * WAR file, if running in a Java EE web container. If the user has + * not been authenticated, the method returns {@code false}. + * + * @param role the role being checked. + * @return whether the authenticated user is in the role, or false if the user has not + * been authenticated. + */ + boolean isUserInRole(String role); + + /** + * Return a reference to the HttpSession that the web socket handshake that + * started this conversation was part of, if the implementation + * is part of a Java EE web container. + * + * @return the http session or {@code null} if either the websocket + * implementation is not part of a Java EE web container, or there is + * no HttpSession associated with the opening handshake request. + */ + Object getHttpSession(); + + /** + * Return the request parameters associated with the request. + * + * @return the unmodifiable map of the request parameters. + */ + Map> getParameterMap(); + + /** + * Return the query string associated with the request. + * + * @return the query string. + */ + String getQueryString(); +} Index: 3rdParty_sources/websocket/javax/websocket/server/PathParam.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/server/PathParam.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/server/PathParam.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,93 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket.server; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * This annotation may be used to annotate method parameters on server endpoints + * where a URI-template has been used in the path-mapping of the {@link ServerEndpoint} + * annotation. The method parameter may be of type String, any Java primitive + * type or any boxed version thereof. If a client URI matches the URI-template, + * but the requested path parameter cannot be decoded, then the websocket's error + * handler will be called. + * + *

For example:- + * 


+ * @ServerEndpoint("/bookings/{guest-id}")
+ * public class BookingServer {
+ * 
+ *     @OnMessage
+ *     public void processBookingRequest(@PathParam("guest-id") String guestID, String message, Session session) {
+ *         // process booking from the given guest here
+ *     }
+ * }
+ *
+ * + *

For example:- + * 


+ * @ServerEndpoint("/rewards/{vip-level}")
+ * public class RewardServer {
+ * 
+ *     @OnMessage
+ *     public void processReward(@PathParam("vip-level") Integer vipLevel, String message, Session session) {
+ *         // process reward here
+ *     }
+ * }
+ *
+ * + * @author dannycoward + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.PARAMETER) +public @interface PathParam { + + /** + * The name of the variable used in the URI-template. If the name does + * not match a path variable in the URI-template, the value of the method parameter + * this annotation annotates is {@code null}. + * + * @return the name of the variable used in the URI-template. + */ + public String value(); +} Index: 3rdParty_sources/websocket/javax/websocket/server/ServerApplicationConfig.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/server/ServerApplicationConfig.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/server/ServerApplicationConfig.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,84 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket.server; + +import java.util.Set; +import javax.websocket.Endpoint; + +/** + * Developers include implementations of ServerApplicationConfig in an archive containing + * websocket endpoints (WAR file, or JAR file within the WAR file) in order to specify the websocket + * endpoints within the archive the implementation must deploy. There is a separate + * method for programmatic endpoints and for annotated endpoints. + * + * @author dannycoward + */ +public interface ServerApplicationConfig { + + /** + * Return a set of ServerEndpointConfig instances that the server container + * will use to deploy the programmatic endpoints. The set of Endpoint classes passed in to this method is + * the set obtained by scanning the archive containing the implementation + * of this ServerApplicationConfig. This set passed in + * may be used the build the set of ServerEndpointConfig instances + * to return to the container for deployment. + * + * @param endpointClasses the set of all the Endpoint classes in the archive containing + * the implementation of this interface. + * @return the non-null set of ServerEndpointConfig s to deploy on the server, using the empty set to + * indicate none. + */ + public Set getEndpointConfigs(Set> endpointClasses); + + /** + * Return a set of annotated endpoint classes that the server container + * must deploy. The set of classes passed in to this method is + * the set obtained by scanning the archive containing the implementation + * of this interface. Therefore, this set passed in contains all the annotated endpoint classes + * in the JAR or WAR file containing the implementation of this interface. This set passed in + * may be used the build the set to return to the container for deployment. + * + * @param scanned the set of all the annotated endpoint classes in the archive containing + * the implementation of this interface. + * @return the non-null set of annotated endpoint classes to deploy on the server, using the empty + * set to indicate none. + */ + Set> getAnnotatedEndpointClasses(Set> scanned); +} Index: 3rdParty_sources/websocket/javax/websocket/server/ServerContainer.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/server/ServerContainer.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/server/ServerContainer.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,89 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket.server; + +import javax.websocket.*; +/** + * The ServerContainer is the specialized view of the WebSocketContainer available + * in server-side deployments. There is one ServerContainer instance per + * websocket application. The ServerContainer holds the methods to be able to + * register server endpoints during the initialization phase of the application. + *

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

+ *

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

+ *

Once the + * application deployment phase is complete, and the websocket application has + * begun accepting incoming connections, the registration methods may no + * longer be called. + * + * @author dannycoward + */ +public interface ServerContainer extends WebSocketContainer { + + /** + * Deploys the given annotated endpoint into this ServerContainer during the + * initialization phase of deploying the application. + * + * @param endpointClass the class of the annotated endpoint + * @throws DeploymentException if the annotated endpoint was badly formed. + * @throws IllegalStateException if the containing websocket application has already + * been deployed. + */ + public void addEndpoint(Class endpointClass) throws DeploymentException; + /** + * + * @param serverConfig the configuration instance representing the logical endpoint + * that will be registered. + * @throws DeploymentException if the endpoint was badly formed. + * @throws IllegalStateException if the containing websocket application has already + * been deployed. + */ + public void addEndpoint(ServerEndpointConfig serverConfig) throws DeploymentException; + +} Index: 3rdParty_sources/websocket/javax/websocket/server/ServerEndpoint.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/server/ServerEndpoint.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/server/ServerEndpoint.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,131 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket.server; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; +import javax.websocket.Decoder; +import javax.websocket.Encoder; + +/** + * This class level annotation declares that the class it decorates + * is a web socket endpoint that will be deployed and made available in the URI-space + * of a web socket server. The annotation allows the developer to + * define the URL (or URI template) which this endpoint will be published, and other + * important properties of the endpoint to the websocket runtime, such as the encoders + * it uses to send messages. + * + *

The annotated class + * must have a public no-arg constructor. + * + *

For example: + * 


+ * @ServerEndpoint("/hello");
+ * public class HelloServer {
+ *
+ *     @OnMessage
+ *     public void processGreeting(String message, Session session) {
+ *         System.out.println("Greeting received:" + message);
+ *     }
+ *
+ * }
+ *
+ * + * @author dannycoward + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.TYPE) +public @interface ServerEndpoint { + + /** + * The URI or URI-template, level-1 (See RFC 6570) where the endpoint will be deployed. The URI us relative to the + * root of the web socket container and must begin with a leading "/". Trailing "/"'s are ignored. Examples: + * 

+     * @ServerEndpoint("/chat")
+     * @ServerEndpoint("/chat/{user}")
+     * @ServerEndpoint("/booking/{privilege-level}")
+     *
+ * + * @return the URI or URI-template + */ + public String value(); + + /** + * The ordered array of web socket protocols this endpoint supports. + * For example, {"superchat", "chat"}. + * + * @return the subprotocols. + */ + public String[] subprotocols() default {}; + + /** + * The ordered array of decoder classes this endpoint will use. For example, + * if the developer has provided a MysteryObject decoder, this endpoint will be able to + * receive MysteryObjects as web socket messages. The websocket runtime will use the first + * decoder in the list able to decode a message, ignoring the remaining decoders. + * + * @return the decoders. + */ + public Class[] decoders() default {}; + + /** + * The ordered array of encoder classes this endpoint will use. For example, + * if the developer has provided a MysteryObject encoder, this class will be able to + * send web socket messages in the form of MysteryObjects. The websocket runtime will use the first + * encoder in the list able to encode a message, ignoring the remaining encoders. + * + * @return the encoders. + */ + public Class[] encoders() default {}; + + + /** + * The optional custom configurator class that the developer would like to use + * to further configure new instances of this endpoint. If no configurator + * class is provided, the implementation uses its own. The implementation + * creates a new instance of the configurator per logical endpoint. + * + * @return the custom configuration class, or ServerEndpointConfig.Configurator.class + * if none was set in the annotation. + */ + public Class configurator() default ServerEndpointConfig.Configurator.class; +} Index: 3rdParty_sources/websocket/javax/websocket/server/ServerEndpointConfig.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/server/ServerEndpointConfig.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/server/ServerEndpointConfig.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,385 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ +package javax.websocket.server; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; +import java.util.ServiceLoader; +import javax.websocket.Decoder; +import javax.websocket.Encoder; +import javax.websocket.EndpointConfig; +import javax.websocket.Extension; +import javax.websocket.HandshakeResponse; + +/** + * The ServerEndpointConfig is a special kind of endpoint configuration object that contains + * web socket configuration information specific only to server endpoints. For developers + * deploying programmatic endpoints, ServerEndpointConfig objects + * can be created using a {@link ServerEndpointConfig.Builder}. Certain configuration + * operations can be customized by providing a {@link ServerEndpointConfig.Configurator} + * + * @author dannycoward + */ +public interface ServerEndpointConfig extends EndpointConfig { + + /** + * Returns the Class of the endpoint this configuration is configuring. If + * the endpoint is an annotated endpoint, the value is the class of the Java class + * annotated with @ServerEndpoint. if the endpoint is a programmatic, the value + * is the class of the subclass of Endpoint. + * + * @return the class of the endpoint, annotated or programmatic. + */ + Class getEndpointClass(); + + /** + * Return the path for this endpoint configuration. The path is the URI or + * URI-template (level 1) relative to the websocket root of the server to which the + * endpoint using this configuration will be mapped. The path is always non-null + * and always begins with a leading "/". + * + * @return the relative path for this configuration. + */ + String getPath(); + + /** + * Return the websocket subprotocols configured. + * + * @return the list of subprotocols, the empty list if none + */ + List getSubprotocols(); + + /** + * Return the websocket extensions configured. + * + * @return the list of extensions, the empty list if none. + */ + List getExtensions(); + + /** + * Return the {@link ServerEndpointConfig.Configurator} this configuration + * is using. If none was set by calling + * {@link ServerEndpointConfig.Builder#configurator(javax.websocket.server.ServerEndpointConfig.Configurator) } + * this methods returns the platform default configurator. + * + * @return the configurator in use. + */ + ServerEndpointConfig.Configurator getConfigurator(); + + /** + * The ServerEndpointConfig.Configurator class may be extended by developers who want to + * provide custom configuration algorithms, such as intercepting the opening handshake, or + * providing arbitrary methods and algorithms that can be accessed from each endpoint + * instance configured with this configurator. + * + * The implementation must provide a platform default configurator loading using the service + * loader. + */ + public class Configurator { + private ServerEndpointConfig.Configurator containerDefaultConfigurator; + + static ServerEndpointConfig.Configurator fetchContainerDefaultConfigurator() { + for (ServerEndpointConfig.Configurator impl : ServiceLoader.load(javax.websocket.server.ServerEndpointConfig.Configurator.class)) { + return impl; + } + throw new RuntimeException("Cannot load platform configurator"); + } + + ServerEndpointConfig.Configurator getContainerDefaultConfigurator() { + if (this.containerDefaultConfigurator == null) { + this.containerDefaultConfigurator = fetchContainerDefaultConfigurator(); + } + return this.containerDefaultConfigurator; + + } + + /** + * Return the subprotocol the server endpoint has chosen from the requested + * list supplied by a client who wishes to connect, or none if there wasn't one + * this server endpoint liked. See + * Sending the + * Server's Opening Handshake. Subclasses may provide custom algorithms + * based on other factors. + * + *

The default platform implementation of this method returns the first + * subprotocol in the list sent by the client that the server supports, + * or the empty string if there isn't one. + * + * @param requested the requested subprotocols from the client endpoint + * @param supported the subprotocols supported by the server endpoint + * @return the negotiated subprotocol or the empty string if there isn't one. + */ + + public String getNegotiatedSubprotocol(List supported, List requested) { + return this.getContainerDefaultConfigurator().getNegotiatedSubprotocol(supported, requested); + } + + /** + * Return the ordered list of extensions that t server endpoint will support + * given the requested extension list passed in, the empty list if none. See + * Negotiating Extensions + * + *

The default platform implementation of this method returns a list + * containing all of the requested extensions passed to this method that + * it supports, using the order in the requested extensions, the empty + * list if none. + * + * @param installed the installed extensions on the implementation. + * @param requested the requested extensions, in the order they were + * requested by the client + * @return the list of extensions negotiated, the empty list if none. + */ + public List getNegotiatedExtensions(List installed, List requested) { + return this.getContainerDefaultConfigurator().getNegotiatedExtensions(installed, requested); + } + + + + + /** + * Check the value of the Origin header (See Origin Header) the client passed during the opening + * handshake. + * + *

The platform default implementation of this method makes a check of the + * validity of the Origin header sent along with + * the opening handshake following the recommendation at: + * Sending + * the Server's Opening Handshake. + * + * @param originHeaderValue the value of the origin header passed + * by the client. + * @return whether the check passed or not + */ + public boolean checkOrigin(String originHeaderValue) { + return this.getContainerDefaultConfigurator().checkOrigin(originHeaderValue); + } + + /** + * Called by the container after it has formulated a handshake response resulting from + * a well-formed handshake request. The container has already + * checked that this configuration has a matching URI, determined the + * validity of the origin using the checkOrigin method, and filled + * out the negotiated subprotocols and extensions based on this configuration. + * Custom configurations may override this method in order to inspect + * the request parameters and modify the handshake response that the server has formulated. + * and the URI checking also. + * + *

If the developer does not override this method, no further + * modification of the request and response are made by the implementation. + * + * @param sec the configuration object involved in the handshake + * @param request the opening handshake request. + * @param response the proposed opening handshake response + */ + public void modifyHandshake(ServerEndpointConfig sec, HandshakeRequest request, HandshakeResponse response) { + // nothing. + } + + + /** + * This method is called by the container each time a new client + * connects to the logical endpoint this configurator configures. + * Developers may override this method to control instantiation of + * endpoint instances in order to customize the initialization + * of the endpoint instance, or manage them in some other way. + * If the developer overrides this method, services like + * dependency injection that are otherwise supported, for example, when + * the implementation is part of the Java EE platform + * may not be available. + * The platform default implementation of this method returns a new + * endpoint instance per call, thereby ensuring that there is one + * endpoint instance per client, the default deployment cardinality. + * + * @param endpointClass the class of the endpoint + * @param the type of the endpoint + * @return an instance of the endpoint that will handle all + * interactions from a new client. + * @throws InstantiationException if there was an error producing the + * endpoint instance. + */ + public T getEndpointInstance(Class endpointClass) throws InstantiationException { + return this.getContainerDefaultConfigurator().getEndpointInstance(endpointClass); + } + + } + + + /** + * The ServerEndpointConfig.Builder is a class used for creating + * {@link ServerEndpointConfig.Builder} objects for the purposes of + * deploying a server endpoint. + * + *

Here are some examples: + * + *

Building a plain configuration for an endpoint with just a path. + * 


+     * ServerEndpointConfig config = ServerEndpointConfig.Builder.create(ProgrammaticEndpoint.class, "/foo").build();
+     *
+ * + *

Building a configuration with no subprotocols and a custom configurator. + * 


+     * ServerEndpointConfig config = ServerEndpointConfig.Builder.create(ProgrammaticEndpoint.class, "/bar")
+     *         .subprotocols(subprotocols)
+     *         .configurator(new MyServerConfigurator())
+     *         .build();
+     *
+ * + * @author dannycoward + */ + public final class Builder { + private String path; + private Class endpointClass; + private List subprotocols = Collections.emptyList(); + private List extensions = Collections.emptyList(); + private List> encoders = Collections.emptyList(); + private List> decoders = Collections.emptyList(); + private ServerEndpointConfig.Configurator serverEndpointConfigurator; + + /** + * Creates the builder with the mandatory information of the endpoint class + * (programmatic or annotated), the relative URI or URI-template to use, + * and with no subprotocols, extensions, encoders, decoders or custom + * configurator. + * @param endpointClass the class of the endpoint to configure + * @param path The URI or URI template where the endpoint will be deployed. + * A trailing "/" will be ignored and the path must begin with /. + * @return a new instance of ServerEndpointConfig.Builder + */ + public static Builder create(Class endpointClass, String path) { + return new Builder(endpointClass, path); + } + + // only one way to build them + private Builder() { + + } + /** + * Builds the configuration object using the current attributes + * that have been set on this builder object. + * + * @return a new ServerEndpointConfig object. + */ + public ServerEndpointConfig build() { + return new DefaultServerEndpointConfig( + this.endpointClass, + this.path, + Collections.unmodifiableList(this.subprotocols), + Collections.unmodifiableList(this.extensions), + Collections.unmodifiableList(this.encoders), + Collections.unmodifiableList(this.decoders), + this.serverEndpointConfigurator + ); + } + + private Builder(Class endpointClass, String path) { + if (endpointClass == null) { + throw new IllegalArgumentException("endpointClass cannot be null"); + } + this.endpointClass = endpointClass; + if (path == null || !path.startsWith("/")) { + throw new IllegalStateException("Path cannot be null and must begin with /"); + } + this.path = path; + } + + /** + * Sets the list of encoder implementation classes for this builder. + * + * @param encoders the encoders + * @return this builder instance + */ + public ServerEndpointConfig.Builder encoders(List> encoders) { + this.encoders = (encoders == null) ? new ArrayList>() : encoders; + return this; + } + + /** + * Sets the decoder implementation classes to use in the configuration. + * + * @param decoders the decoders + * @return this builder instance. + */ + public ServerEndpointConfig.Builder decoders(List> decoders) { + this.decoders = (decoders == null) ? new ArrayList>() : decoders; + return this; + } + + /** + * Sets the subprotocols to use in the configuration. + * + * @param subprotocols the subprotocols. + * @return this builder instance + */ + public ServerEndpointConfig.Builder subprotocols(List subprotocols) { + this.subprotocols = (subprotocols == null) ? new ArrayList() : subprotocols; + return this; + } + + + /** + * Sets the extensions to use in the configuration. + * + * @param extensions the extensions to use. + * @return this builder instance. + */ + public ServerEndpointConfig.Builder extensions(List extensions) { + this.extensions = (extensions == null) ? new ArrayList() : extensions; + return this; + } + + /** + * Sets the custom configurator to use on the configuration + * object built by this builder. + * + * @param serverEndpointConfigurator the configurator + * @return this builder instance + */ + public ServerEndpointConfig.Builder configurator(ServerEndpointConfig.Configurator serverEndpointConfigurator) { + this.serverEndpointConfigurator = serverEndpointConfigurator; + return this; + } + + + + } + + +} Index: 3rdParty_sources/websocket/javax/websocket/server/package-info.java =================================================================== diff -u --- 3rdParty_sources/websocket/javax/websocket/server/package-info.java (revision 0) +++ 3rdParty_sources/websocket/javax/websocket/server/package-info.java (revision ec3c5a5adbf38c525b3d3f2aec05af3f78f3968f) @@ -0,0 +1,46 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common Development + * and Distribution License("CDDL") (collectively, the "License"). You + * may not use this file except in compliance with the License. You can + * obtain a copy of the License at + * http://glassfish.java.net/public/CDDL+GPL_1_1.html + * or packager/legal/LICENSE.txt. See the License for the specific + * language governing permissions and limitations under the License. + * + * When distributing the software, include this License Header Notice in each + * file and include the License file at packager/legal/LICENSE.txt. + * + * GPL Classpath Exception: + * Oracle designates this particular file as subject to the "Classpath" + * exception as provided by Oracle in the GPL Version 2 section of the License + * file that accompanied this code. + * + * Modifications: + * If applicable, add the following below the License Header, with the fields + * enclosed by brackets [] replaced by your own identifying information: + * "Portions Copyright [year] [name of copyright owner]" + * + * Contributor(s): + * If you wish your version of this file to be governed by only the CDDL or + * only the GPL Version 2, indicate your decision by adding "[Contributor] + * elects to include this software in this distribution under the [CDDL or GPL + * Version 2] license." If you don't indicate a single choice of license, a + * recipient has the option to distribute your version of this file under + * either the CDDL, the GPL Version 2 or to extend the choice of license to + * its licensees as provided above. However, if you add GPL Version 2 code + * and therefore, elected the GPL Version 2 license, then the option applies + * only if the new code is made subject to such option by the copyright + * holder. + */ + +/** + * This package contains all the WebSocket APIs used only by server side + * applications. + */ +package javax.websocket.server; +