Skip to main content

[websocket-spec~source-code-repository:329] rc4 - Version corresponding to the Final Approval Ballot draft

  • From:
  • To:
  • Subject: [websocket-spec~source-code-repository:329] rc4 - Version corresponding to the Final Approval Ballot draft
  • Date: Tue, 2 Apr 2013 19:58:44 +0000

Project:    websocket-spec
Repository: source-code-repository
Revision:   329
Author:     dannycoward
Date:       2013-04-02 19:58:42 UTC
Link:       

Log Message:
------------
rc4 - Version corresponding to the Final Approval Ballot draft


Revisions:
----------
329


Modified Paths:
---------------
tags/javax.websocket-all-1.0-rc4/api/client
tags/javax.websocket-all-1.0-rc4/api/server


Added Paths:
------------
tags/javax.websocket-all-1.0-rc4/api/client/src/main/java/javax/websocket/WebSocketContainer.java
tags/javax.websocket-all-1.0-rc4/api
tags/javax.websocket-all-1.0-rc4/api/src/main/javadoc/doc-files/speclicense.html
tags/javax.websocket-all-1.0-rc4/api/client/src/main/java/javax/websocket/ClientEndpointConfig.java
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/ServerEndpointConfig.java
tags/javax.websocket-all-1.0-rc4


Diffs:
------
Index: 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/HandshakeRequest.java
===================================================================
--- 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/HandshakeRequest.java
      (revision 0)
+++ 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/HandshakeRequest.java
      (revision 329)
@@ -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<String, List<String>> 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<String, List<String>> getParameterMap();
+
+    /**
+     * Return the query string associated with the request.
+     *
+     * @return the query string.
+     */
+    String getQueryString();
+}
Index: 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/ServerApplicationConfig.java
===================================================================
--- 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/ServerApplicationConfig.java
       (revision 0)
+++ 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/ServerApplicationConfig.java
       (revision 329)
@@ -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<ServerEndpointConfig> getEndpointConfigs(Set<Class<? extends 
Endpoint>> 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<Class<?>> getAnnotatedEndpointClasses(Set<Class<?>> scanned);
+}
Index: 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/DefaultServerEndpointConfig.java
===================================================================
--- 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/DefaultServerEndpointConfig.java
   (revision 0)
+++ 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/DefaultServerEndpointConfig.java
   (revision 329)
@@ -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<String> subprotocols; 
+    private List<Extension> extensions;
+    private List<Class<? extends Encoder>> encoders;
+    private List<Class<? extends Decoder>> decoders;
+    private Map<String, Object> userProperties = new HashMap<String, 
Object>();
+    private ServerEndpointConfig.Configurator serverEndpointConfigurator;
+
+    
+    // The builder ensures nothing except configurator can be {@code null}.
+    DefaultServerEndpointConfig(Class<?> endpointClass,
+                                    String path,
+                                    List<String> subprotocols,
+                                    List<Extension> extensions,
+                                    List<Class<? extends Encoder>> encoders,
+                                    List<Class<? extends Decoder>> 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<? extends Endpoint> 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<Class<? extends Encoder>> 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<Class<? extends Decoder>> 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<String, Object> getUserProperties() {
+        return this.userProperties;
+    }
+    
+     @Override
+    public final List<String> getSubprotocols() {
+        return this.subprotocols;
+    }
+    
+    @Override
+    public final List<Extension> getExtensions() {
+        return this.extensions;
+    }
+
+}
Index: 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/ServerEndpoint.java
===================================================================
--- 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/ServerEndpoint.java
        (revision 0)
+++ 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/ServerEndpoint.java
        (revision 329)
@@ -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.
+ *
+ * <p>The annotated class
+ * must have a public no-arg constructor.
+ *
+ * <p>For example:
+ * <pre><code>
+ * &#64;ServerEndpoint("/hello");
+ * public class HelloServer {
+ *
+ *     &#64;OnMessage
+ *     public void processGreeting(String message, Session session) {
+ *         System.out.println("Greeting received:" + message);
+ *     }
+ *
+ * }
+ * </code></pre>
+ *
+ * @author dannycoward
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface ServerEndpoint {
+
+    /**
+     * The URI or URI-template, level-1 (<a 
href="http://http://tools.ietf.org/html/rfc6570";>See RFC 6570</a>) 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:
+     * <pre><code>
+     * &#64;ServerEndpoint("/chat")
+     * &#64;ServerEndpoint("/chat/{user}")
+     * &#64;ServerEndpoint("/booking/{privilege-level}")
+     * </code></pre>
+     *
+     * @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<? extends Decoder>[] 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<? extends Encoder>[] 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<? extends ServerEndpointConfig.Configurator> configurator() 
default ServerEndpointConfig.Configurator.class;
+}
Index: 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/ServerContainer.java
===================================================================
--- 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/ServerContainer.java
       (revision 0)
+++ 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/ServerContainer.java
       (revision 329)
@@ -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.
+ * <p>For websocket enabled web containers, developers may
+ * obtain a reference to the ServerContainer instance by retrieving it as an
+ * attribute named <code>javax.websocket.server.ServerContainer</code> 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. 
+ * </p>
+ * <p>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. 
+ * </p>
+ * <p>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: 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/PathParam.java
===================================================================
--- 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/PathParam.java
     (revision 0)
+++ 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/PathParam.java
     (revision 329)
@@ -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.
+ *
+ * <p>For example:-
+ * <pre><code>
+ * &#64;ServerEndpoint("/bookings/{guest-id}")
+ * public class BookingServer {
+ * 
+ *     &#64;OnMessage
+ *     public void processBookingRequest(@PathParam("guest-id") String 
guestID, String message, Session session) {
+ *         // process booking from the given guest here
+ *     }
+ * }
+ * </code></pre>
+ * 
+ * <p>For example:-
+ * <pre><code>
+ * &#64;ServerEndpoint("/rewards/{vip-level}")
+ * public class RewardServer {
+ * 
+ *     &#64;OnMessage
+ *     public void processReward(@PathParam("vip-level") Integer vipLevel, 
String message, Session session) {
+ *         // process reward here
+ *     }
+ * }
+ * </code></pre>
+ *
+ * @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: 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/ServerEndpointConfig.java
===================================================================
--- 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/ServerEndpointConfig.java
  (revision 0)
+++ 
tags/javax.websocket-all-1.0-rc4/api/server/src/main/java/javax/websocket/server/ServerEndpointConfig.java
  (revision 329)
@@ -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 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<String> getSubprotocols();
+    
+    /**
+     * Return the websocket extensions configured. 
+     *
+     * @return the list of extensions, the empty list if none.
+     */
+    List<Extension> 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
+         * <a 
href="http://tools.ietf.org/html/rfc6455#section-4.2.2";>Sending the 
+         * Server's Opening Handshake</a>. Subclasses may provide custom 
algorithms 
+         * based on other factors.
+         *
+         * <p>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<String> supported, 
List<String> 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 
+         * <a 
href="http://tools.ietf.org/html/rfc6455#section-9.1";>Negotiating 
Extensions</a>
+         *
+         * <p>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<Extension> getNegotiatedExtensions(List<Extension> 
installed, List<Extension> requested) {
+            return 
this.getContainerDefaultConfigurator().getNegotiatedExtensions(installed, 
requested);
+        }
+
+
+
+
+        /**
+         * Check the value of the Origin header (<a 
href="http://tools.ietf.org/html/rfc6454";>See Origin Header</a>) the client 
passed during the opening
+         * handshake.
+         *
+         * <p>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: 
+         * <a href="http://tools.ietf.org/html/rfc6455#section-4.2";>Sending 
+         * the Server's Opening Handshake</a>.
+         * 
+         * @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 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.
+         *
+         * <p>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 <T> 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> T getEndpointInstance(Class<T> 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.
+     *
+     * <p>Here are some examples:
+     *
+     * <p>Building a plain configuration for an endpoint with just a path.
+     * <pre><code>
+     * ServerEndpointConfig config = 
ServerEndpointConfig.Builder.create(ProgrammaticEndpoint.class, 
"/foo").build();
+     * </code></pre>
+     * 
+     * <p>Building a configuration with no subprotocols and a custom 
configurator.
+     * <pre><code>
+     * ServerEndpointConfig config = 
ServerEndpointConfig.Builder.create(ProgrammaticEndpoint.class, "/bar")
+     *         .subprotocols(subprotocols)
+     *         .configurator(new MyServerConfigurator())
+     *         .build();
+     * </code></pre>
+     * 
+     * @author dannycoward
+     */
+    public final class Builder {
+        private String path;
+        private Class<?> endpointClass;
+        private List<String> subprotocols = Collections.emptyList();
+        private List<Extension> extensions = Collections.emptyList();
+        private List<Class<? extends Encoder>> encoders = 
Collections.emptyList();
+        private List<Class<? extends Decoder>> 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<Class<? extends 
Encoder>> encoders) {
+            this.encoders = (encoders == null) ? new ArrayList<Class<? 
extends Encoder>>() : 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<Class<? extends 
Decoder>> decoders) {
+            this.decoders = (decoders == null) ? new ArrayList<Class<? 
extends Decoder>>() : decoders;
+            return this;
+        }
+
+        /**
+         * Sets the subprotocols to use in the configuration.
+         * 
+         * @param subprotocols the subprotocols.
+         * @return this builder instance
+         */
+        public ServerEndpointConfig.Builder subprotocols(List<String> 
subprotocols) {
+            this.subprotocols = (subprotocols == null) ? new 
ArrayList<String>() : 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<Extension> 
extensions) {
+            this.extensions = (extensions == null) ? new 
ArrayList<Extension>() : 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: tags/javax.websocket-all-1.0-rc4/api/server/pom.xml
===================================================================
--- tags/javax.websocket-all-1.0-rc4/api/server/pom.xml (revision 0)
+++ tags/javax.websocket-all-1.0-rc4/api/server/pom.xml (revision 329)
@@ -0,0 +1,165 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  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 acc
[truncated due to length]



[websocket-spec~source-code-repository:329] rc4 - Version corresponding to the Final Approval Ballot draft

dannycoward 04/02/2013
 
 
Close
loading
Please Confirm
Close