Skip to main content

[websocket-spec~source-code-repository:65] API tweaks in preparation for v009

  • From:
  • To:
  • Subject: [websocket-spec~source-code-repository:65] API tweaks in preparation for v009
  • Date: Fri, 30 Nov 2012 23:08:15 +0000

Project:    websocket-spec
Repository: source-code-repository
Revision:   65
Author:     dannycoward
Date:       2012-11-30 23:08:11 UTC
Link:       

Log Message:
------------
API tweaks in preparation for v009


Revisions:
----------
65


Modified Paths:
---------------
trunk/api/src/main/java/javax/websocket/ServerEndpointConfiguration.java
trunk/api/src/main/java/javax/websocket/ClientContainer.java
trunk/api/src/main/java/javax/websocket/ServerContainer.java
trunk/api/src/main/java/javax/websocket/DefaultClientConfiguration.java
trunk/api/src/main/java/javax/websocket/DefaultServerConfiguration.java
trunk/api/src/main/java/javax/websocket/WebSocketEndpoint.java
trunk/api/src/main/java/javax/websocket/Session.java
trunk/api/src/main/java/javax/websocket/Endpoint.java
trunk/api/src/main/java/javax/websocket/ClientEndpointConfiguration.java


Added Paths:
------------
trunk/api/src/main/java/javax/websocket/EndpointFactory.java


Diffs:
------
Index: 
trunk/api/src/main/java/javax/websocket/ServerEndpointConfiguration.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/ServerEndpointConfiguration.java  
  (revision 64)
+++ trunk/api/src/main/java/javax/websocket/ServerEndpointConfiguration.java  
  (revision 65)
@@ -44,14 +44,25 @@
 
 /**
  * The ServerEndpointConfiguration is a special kind of endpoint 
configuration object that contains
- * web socket configuration information specific only to server endpoints.
+ * web socket configuration information specific only to server endpoints. 
The parametrized type T is
+ * the type of the Endpoint that this configures.
  *
  * @author dannycoward
  * @since DRAFT 001
  */
-public interface ServerEndpointConfiguration extends EndpointConfiguration {
+public interface ServerEndpointConfiguration<T> extends 
EndpointConfiguration {
 
+
     /**
+     * Return the instance of an EndpointFactory that the developer wishes 
the container
+     * to use for creating new instances of the Endpoint, of type T, that 
this endpoint configuration
+     * configures. If null is returned, the implementation will attempt to 
use the
+     * public no arg constructor to create the endpoint.
+     * @return the EndpointFactory instance, or null if no factory is to be 
used.
+     */
+    EndpointFactory<T> getEndpointFactory();
+
+    /**
      * Return the subprotocol this 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>
Index: trunk/api/src/main/java/javax/websocket/DefaultServerConfiguration.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/DefaultServerConfiguration.java   
  (revision 64)
+++ trunk/api/src/main/java/javax/websocket/DefaultServerConfiguration.java   
  (revision 65)
@@ -50,7 +50,7 @@
  *
  * @author dannycoward
  */
-public class DefaultServerConfiguration implements 
ServerEndpointConfiguration {
+public class DefaultServerConfiguration<T> implements 
ServerEndpointConfiguration {
     private String path;
     private List<String> subprotocols = new ArrayList<String>();
     private List<String> extensions = new ArrayList<String>();
@@ -64,6 +64,16 @@
 
     }
 
+   /** The default implementation is to return null, which indicates the
+    * implementation is to use the public no arg constructor to create the
+    * instances of the Endpoint.
+    * @return null
+    */
+     public EndpointFactory<T> getEndpointFactory() {
+         return null;
+     }
+
+
     /**
      * Creates a server configuration with the given path
      *
@@ -156,10 +166,11 @@
      * The default implementation of this method returns, the first 
subprotocol in the list sent by the client that
      * the server supports, or null if there isn't one none. Subclasses may 
provide custom algorithms based on other factors.
      *
-     * @param requestedSubprotocols TODO
+     * @param requestedSubprotocols the list of requested subprotocols.
      * @return the negotiated subprotocol.
      */
-    public String getNegotiatedSubprotocol(List<String> 
requestedSubprotocols) {
+    @Override
+    public String getNegotiatedSubprotocol(List requestedSubprotocols) {
         throw new RuntimeException("To implement");
     }
 
@@ -172,8 +183,8 @@
      * @param requestedExtensions TODO
      * @return the list of extensions.
      */
-
-    public List<String> getNegotiatedExtensions(List<String> 
requestedExtensions) {
+    @Override
+    public List getNegotiatedExtensions(List requestedExtensions) {
         throw new RuntimeException("To implement");
     }
 
Index: 
trunk/api/src/main/java/javax/websocket/ClientEndpointConfiguration.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/ClientEndpointConfiguration.java  
  (revision 64)
+++ trunk/api/src/main/java/javax/websocket/ClientEndpointConfiguration.java  
  (revision 65)
@@ -71,6 +71,23 @@
      */
     List<String> getExtensions();
 
+    /** 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 response prior to the start of the handshake interaction.
+     * @param hr the handshake request the implementation is about to send to
+     * start the handshake interaction.
+     */
+    public void beforeRequest(HandshakeRequest hr);
+
+    /** 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);
+
 }
 
 
Index: trunk/api/src/main/java/javax/websocket/EndpointFactory.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/EndpointFactory.java        
(revision 0)
+++ trunk/api/src/main/java/javax/websocket/EndpointFactory.java        
(revision 65)
@@ -0,0 +1,23 @@
+/*
+ * To change this template, choose Tools | Templates
+ * and open the template in the editor.
+ */
+package javax.websocket;
+
+/**
+ * The EndpointFactory is used by logical endpoints that will be deployed on 
a server. Its purpose is
+ * to create a new instance of the Endpoint each time the implementation 
needs one because a
+ * new peer is connecting to the logical endpoint. The parametrized type T 
defines
+ * the type of the endpoint that will be created. EndpointFactories are 
supplied by the developer
+ * by returning an instance on the ServerEndpointConfiguration, or by 
referencing the EndpointFactory
+ * class from the @WebSocketEndpoint annotation.
+ * @author dannycoward
+ */
+public interface EndpointFactory<T> {
+
+    /**
+     * Create an instance of the Endpoint which is of type T.
+     * @return
+     */
+    public T createEndpoint();
+}
Index: trunk/api/src/main/java/javax/websocket/ServerContainer.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/ServerContainer.java        
(revision 64)
+++ trunk/api/src/main/java/javax/websocket/ServerContainer.java        
(revision 65)
@@ -50,11 +50,12 @@
 public interface ServerContainer extends ClientContainer {
 
     /**
-     * Publish the given endpoint with the provided configuration
+     * Publish the given programmatic endpoint with the provided 
configuration
      * information.
      *
      * @param endpointClazz the class of the endpoint to be deployed.
      *                      to deploy the endpoint.
      */
-    void publishServer(Class<? extends Endpoint> endpointClazz) throws 
DeploymentException;
+    void publishServer(Class<? extends ServerEndpointConfiguration> 
endpointClazz) throws DeploymentException;
+
 }
Index: trunk/api/src/main/java/javax/websocket/DefaultClientConfiguration.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/DefaultClientConfiguration.java   
  (revision 64)
+++ trunk/api/src/main/java/javax/websocket/DefaultClientConfiguration.java   
  (revision 65)
@@ -93,7 +93,7 @@
         return this;
     }
 
-    /** 
+    /**
      * Assign the list of encoders this client will use.
      * @return the encoder list.
      */
@@ -108,7 +108,7 @@
          this.encoders = encoders;
         return this;
     }
-    /** 
+    /**
      * Assign the list of decoders this client will use.
      * @return the decoders to use.
      */
@@ -116,8 +116,8 @@
         return this.decoders;
     }
 
-        /** 
-         * Assign the list of decoders this client will use. 
+        /**
+         * Assign the list of decoders this client will use.
          * @param decoders the extensions
          * @return this endpoint configuration.
          */
@@ -125,4 +125,16 @@
          this.decoders = decoders;
         return this;
     }
+
+      /**
+       * The default implementation of this method performs no actions on 
the HandshakeRequest.
+       * @param the handshake request the implementation has formulated
+     */
+    public void beforeRequest(HandshakeRequest hr){}
+
+    /** The default implementation of this method performs no actions on the 
HandshakeResponse.
+     *
+     * @param hr the handshake response sent by the server.
+     */
+    public void afterResponse(HandshakeResponse hr){}
 }
Index: trunk/api/src/main/java/javax/websocket/Endpoint.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/Endpoint.java       (revision 64)
+++ trunk/api/src/main/java/javax/websocket/Endpoint.java       (revision 65)
@@ -53,14 +53,8 @@
  */
 public abstract class Endpoint {
 
-    /**
-     * Developers must provide an EndpointConfiguration so that
-     * the container it is deployed in can configure it.
-     *
-     * @return an EndpointConfiguration used to configure the Endpoint
-     */
-    public abstract EndpointConfiguration getEndpointConfiguration();
 
+
     /**
      * Developers must implement this method to be notified when a new 
conversation has
      * just begun.
Index: trunk/api/src/main/java/javax/websocket/ClientContainer.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/ClientContainer.java        
(revision 64)
+++ trunk/api/src/main/java/javax/websocket/ClientContainer.java        
(revision 65)
@@ -54,22 +54,24 @@
     /**
      * Connect the supplied annotated object to its server using the 
supplied handshake
      * parameters. The supplied object must be a class decorated with the 
class level
-     * {@link WebSocketEndpoint} annotation.
+     * {@link WebSocketEndpoint} annotation. This method blocks until the 
connection
+     * is established, or throws an error if the connection could not be 
made.
      *
      * @param endpoint either subclass of {@link Endpoint} or a POJO 
annotated with {@link WebSocketClient} annotation.
      * @param path     the complete path to the server endpoint
+     * @return the Session created when the connection is successful
      */
-    void connectToServer(Object endpoint, URI path) throws 
DeploymentException;
+    Session connectToServer(Object endpoint, URI path) throws 
DeploymentException;
 
     /**
-     * Return a copy of the Set of the currently active web socket sessions. 
These
-     * sessions may not still be active at any point after the return of 
this method, for
-     * example, Iterating over the set at a later time may yield closed 
session. Use
-     * session.isActive() to check.
+     * Return a copy of the Set of the currently open web socket sessions. 
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. Use
+     * session.isOpen() to check.
      *
      * @return the set of sessions, active at the time of return.
      */
-    Set<Session> getActiveSessions();
+    Set<Session> getOpenSessions();
 
     /**
      * Return the maximum time in milliseconds that a web socket session may 
be idle before
Index: trunk/api/src/main/java/javax/websocket/Session.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/Session.java        (revision 64)
+++ trunk/api/src/main/java/javax/websocket/Session.java        (revision 65)
@@ -65,15 +65,8 @@
      */
     ClientContainer getContainer();
 
-    /**
-     * Sets the list of encoders to be used in this session in order of 
preference.
-     * The first element in the list that matches for a given type
-     * will be used rather than a later element in the list that matches for 
a given type.
-     *
-     * @param encoders the list of encoders.
-     */
-    void setEncoders(List<Encoder> encoders);
 
+
     /**
      * Register to handle to incoming messages in this conversation.
      *
@@ -137,7 +130,7 @@
      *
      * @return whether the session is active.
      */
-    boolean isActive();
+    boolean isOpen();
 
     /**
      * Return the number of milliseconds before this conversation will be 
closed by the
@@ -224,5 +217,15 @@
      */
     Map<String, String> 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.
+     * @return an editable Map of application data.
+     */
+    public Map<String, Object> getUserProperties();
 
+
 }
Index: trunk/api/src/main/java/javax/websocket/WebSocketEndpoint.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/WebSocketEndpoint.java      
(revision 64)
+++ trunk/api/src/main/java/javax/websocket/WebSocketEndpoint.java      
(revision 65)
@@ -110,4 +110,14 @@
      * @return the encoders.
      */
     public Class<? extends Encoder>[] encoders() default {};
+
+
+    /** The factory class that the developer would like to use
+     * in order to create a new instance of this POJO each time
+     * a new peer attempts to connect to it. If no factory is
+     * provided, the implementation will use the public no-args constructor
+     * of the POJO.
+     * @return
+     */
+    public Class<? extends EndpointFactory> factory();
 }





[websocket-spec~source-code-repository:65] API tweaks in preparation for v009

dannycoward 11/30/2012
 
 
Close
loading
Please Confirm
Close