Skip to main content

[websocket-spec~source-code-repository:53] javadoc updates

  • From:
  • To:
  • Subject: [websocket-spec~source-code-repository:53] javadoc updates
  • Date: Sat, 17 Nov 2012 02:04:34 +0000

Project:    websocket-spec
Repository: source-code-repository
Revision:   53
Author:     dannycoward
Date:       2012-11-17 02:04:32 UTC
Link:       

Log Message:
------------
javadoc updates


Revisions:
----------
53


Modified Paths:
---------------
trunk/api/src/main/java/javax/websocket/ContainerProvider.java
trunk/api/src/main/java/javax/websocket/HandshakeRequest.java
trunk/api/src/main/java/javax/websocket/WebSocketEndpoint.java
trunk/api/src/main/java/javax/websocket/EncodeException.java
trunk/api/src/main/java/javax/websocket/ClientContainer.java
trunk/api/src/main/java/javax/websocket/ServerEndpointConfiguration.java
trunk/api/src/main/java/javax/websocket/DeploymentException.java
trunk/api/src/main/java/javax/websocket/Session.java
trunk/api/src/main/java/javax/websocket/RemoteEndpoint.java
trunk/api/src/main/java/javax/websocket/DefaultClientConfiguration.java
trunk/api/src/main/java/javax/websocket/Encoder.java
trunk/api/src/main/java/javax/websocket/DecodeException.java
trunk/api/src/main/java/javax/websocket/SendResult.java
trunk/api/src/main/java/javax/websocket/DefaultServerConfiguration.java
trunk/api/src/main/java/javax/websocket/Decoder.java
trunk/api/src/main/java/javax/websocket/CloseReason.java
trunk/api/src/main/java/javax/websocket/WebSocketPathParam.java
trunk/api/src/main/java/javax/websocket/Endpoint.java
trunk/api/src/main/java/javax/websocket/ClientEndpointConfiguration.java


Diffs:
------
Index: 
trunk/api/src/main/java/javax/websocket/ServerEndpointConfiguration.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/ServerEndpointConfiguration.java  
  (revision 52)
+++ trunk/api/src/main/java/javax/websocket/ServerEndpointConfiguration.java  
  (revision 53)
@@ -62,7 +62,7 @@
      * Return the ordered list of extensions that this server 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>
      * @param requestedExtensions the requested extentions, in order.
-     * @return
+     * @return the list of extensions negotiated
      */
      List<String> getNegotiatedExtensions(List<String> requestedExtensions);
 
@@ -70,7 +70,7 @@
      * handshake.
      *
      * @param originHeaderValue the value of the origin header.
-     * @return
+     * @return whether the check passed or not
      */
      boolean checkOrigin(String originHeaderValue);
 
@@ -78,7 +78,7 @@
      * Answers whether the current configuration matches the given path. 
This method may be overridden
      * by implementations with any number of algorithms for determining a 
match.
      * @param uri the uri of the incoming handshake.
-     * @return
+     * @return whether there was a match
      */
 
      boolean matchesURI(URI uri);
Index: trunk/api/src/main/java/javax/websocket/DeploymentException.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/DeploymentException.java    
(revision 52)
+++ trunk/api/src/main/java/javax/websocket/DeploymentException.java    
(revision 53)
@@ -40,16 +40,25 @@
 package javax.websocket;
 
 /**
- *  http://java.net/jira/browse/WEBSOCKET_SPEC-47
+ *  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: trunk/api/src/main/java/javax/websocket/HandshakeRequest.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/HandshakeRequest.java       
(revision 52)
+++ trunk/api/src/main/java/javax/websocket/HandshakeRequest.java       
(revision 53)
@@ -81,7 +81,7 @@
      Map<String, String[]> getParameterMap();
 
     /** Return the query string associated with the request.
-     * @return
+     * @return the query string≥
      */
      String getQueryString();
 }
Index: trunk/api/src/main/java/javax/websocket/DecodeException.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/DecodeException.java        
(revision 52)
+++ trunk/api/src/main/java/javax/websocket/DecodeException.java        
(revision 53)
@@ -50,17 +50,27 @@
     private String encodedString;
     private static final long serialVersionUID = 006;
 
-        /* Constructor with the data being decoded, and the reason why it 
failed to be, and the cause. The buffer may represent the whole message,
+        /**
+         * Constructor with the data being decoded, and the reason why it 
failed to be, and the cause. The buffer may represent the whole message,
      * or part of the message, depending whether the application is using one
-     * of the streaming methods or not.*/
+     * of the streaming methods or not.
+     * @param bb the byte buffer with the data 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.bb = bb;
     }
 
-            /* Constructor with the data being decoded, and the reason why 
it failed to be, and the cause. The encoded string may represent the whole 
message,
+     /**
+      * Constructor with the data being decoded, and the reason why it 
failed to be, and the cause. The encoded string may represent the whole 
message,
      * or part of the message, depending whether the application is using one
-     * of the streaming methods or not.*/
+     * of the streaming methods or not.
+     * @param encodedString the string 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;
@@ -70,7 +80,7 @@
      * be decoded, and reason why. The buffer may represent the whole 
message,
      * or part of the message, depending whether the application is using one
      * of the streaming methods or not.
-     * @param bb
+     * @param bb the byte buffer with the data that could not be decoded
      * @param message
      */
     public DecodeException(ByteBuffer bb, String message) {
@@ -82,14 +92,20 @@
      * or part of the message, depending whether the application is using one
      * of the streaming methods or not.
      * @param bb
-     * @param message
+     * @param message the reason for the failure
      */
     public DecodeException(String encodedString, String message) {
         super(message);
         this.encodedString = encodedString;
     }
-    /** Return the ByteBuffer that cannot be decoded. */
+    /** 
+     * Return the ByteBuffer that cannot be decoded.
+     * @return the data not decoded.
+     */
     public ByteBuffer getBytes() {return this.bb;}
-    /** Return the encoded string that cannot be decoded. */
+    /** 
+     * Return the encoded string that cannot be decoded. 
+     * @return the text not decoded.
+     */
     public String getText() {return this.encodedString;}
 }
Index: trunk/api/src/main/java/javax/websocket/DefaultServerConfiguration.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/DefaultServerConfiguration.java   
  (revision 52)
+++ trunk/api/src/main/java/javax/websocket/DefaultServerConfiguration.java   
  (revision 53)
@@ -59,51 +59,74 @@
     protected DefaultServerConfiguration() {
 
     }
-    /** Creates a server configuration with the given URI. */
+    /** 
+     * Creates a server configuration with the given path
+     * @param path the URI or URI template.
+     */
     public DefaultServerConfiguration(String path) {
         this.path = path;
     }
-    /* Sets all the encoders that this configuration will support.*/
+    /** Sets all the encoders that this configuration will support.
+     * @param encoders the encoders supported
+     * @return this server configuration instance.
+     */
     public DefaultServerConfiguration setEncoders(List<Encoder> encoders) {
         this.encoders = encoders;
         return this;
     }
 
-    /** Sets all the decoders that this configuration will support. */
+    /**
+     * Sets all the decoders that this configuration will support.
+     * @param decoders the encoders supported
+     * @return this server configuration instance.
+     */
     public DefaultServerConfiguration setDecoders(List<Decoder> decoders) {
         this.decoders = decoders;
         return this;
     }
 
-    /** Sets all the subprotocols that this configuration will support. */
+    /** 
+     * Sets all the subprotocols that this configuration will support. 
+     * @param subprotocols the encoders supported
+     * @return this server configuration instance.
+     */
     public DefaultServerConfiguration setSubprotocols(List<String> 
subprotocols) {
         this.subprotocols = subprotocols;
         return this;
     }
 
     /** Sets all the extensions that this configuration will support.
+     * @param extensions the encoders supported
+     * @return this server configuration instance.
      */
     public DefaultServerConfiguration setExtensions(List<String> extensions) 
{
         this.extensions = extensions;
         return this;
     }
-    /** Return the Decoder implementations configured. These
-     will be used by the container to decode incoming messages
-     * into the expected custom objects on MessageListener.onMessage()
-     * callbacks.
+    /** Return the Encoder implementations configured. These
+     * will be used by the container to encode outgoing messages.
+     * @return the encoders.
      */
     public List<Encoder> getEncoders() {
         return this.encoders;
     }
+   
+    
      /** Return the Decoder implementations configured. These
-     will be used by the container to decode incoming messages
-     * into the expected custom objects on MessageListener.onMessage()
+     * will be used by the container to decode incoming messages
+     * into the expected custom objects on MessageHandler
      * callbacks.
+     * @return the encoders.
      */
     public List<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;
@@ -114,7 +137,7 @@
      * 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
-     * @return
+     * @return the negotiated subprotocol.
      */
     public String getNegotiatedSubprotocol(List<String> 
requestedSubprotocols) {
         throw new RuntimeException("To implement");
@@ -125,7 +148,7 @@
      * extensions passed to this method that it supports, using the order in 
the requested
      * extensions, the empty list if none. Subclasses may provide custom 
algorithms based on other factors.
      * @param requestedExtensions
-     * @return
+     * @return the list of extensions.
      */
 
     public List<String> getNegotiatedExtensions(List<String> 
requestedExtensions) {
@@ -136,7 +159,7 @@
      * handshake following the recommendation at: 
http://tools.ietf.org/html/rfc6455#section-4.2 ;.
      *
      * @param originHeaderValue
-     * @return
+     * @return whether the check passed or not.
      */
     public boolean checkOrigin(String originHeaderValue) {
         throw new RuntimeException("To implement");
@@ -146,8 +169,8 @@
      * it is an exact match in the case the configuration is a URI, and if 
and only if it is a valid
      * expansion of the configuration URI template, in the case where the 
configuration is a URI template. Subclasses may override this method to 
provide
      * different matching policies.
-     * @param uri
-     * @return
+     * @param uri the URL of the incoming request
+     * @return whether it matched this configuration or not.
      */
     public boolean matchesURI(URI uri) {
         return this.path.equals(uri.toString());
@@ -159,8 +182,8 @@
      * sent by the client. Additionally subclasses may choose to override 
this method to modify the outgoing
      * handshake response.
      * the outgoing handshake response
-     * @param request
-     * @param response
+     * @param request the handshake request from the client
+     * @param response the handshake response formulated by the container.
      */
     public void modifyHandshake(HandshakeRequest request, HandshakeResponse 
response) {}
 
Index: trunk/api/src/main/java/javax/websocket/Decoder.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/Decoder.java        (revision 52)
+++ trunk/api/src/main/java/javax/websocket/Decoder.java        (revision 53)
@@ -56,7 +56,8 @@
      */
      interface Binary<T> extends Decoder {
 
-        /** Decode the given bytes into an object of type T.
+        /** 
+         * Decode the given bytes into an object of type T.
          @param bytes the bytes to be decoded.
          * @return the decoded object
          */
@@ -75,13 +76,16 @@
 
         /**
          * Decode the given bytes read from the input stream into an object 
of type T.
+         * @return the decoded object
          * @param is the input stream carrying the bytes
          */
          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. */
+     /** 
+      * This interface defines how a custom object is decoded from a web 
socket message in
+     * the form of a string. 
+     */
      interface Text<T> extends Decoder {
         /** Decode the given String into an object of type T.
          * @param the string to be decoded.
Index: 
trunk/api/src/main/java/javax/websocket/ClientEndpointConfiguration.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/ClientEndpointConfiguration.java  
  (revision 52)
+++ trunk/api/src/main/java/javax/websocket/ClientEndpointConfiguration.java  
  (revision 53)
@@ -56,7 +56,7 @@
      * handshake for clients using this configuration. The first protocol 
name is the most preferred.
      * See <a href="http://tools.ietf.org/html/rfc6455#section-4.1";>Client 
Opening Handshake</a>
      *
-     * @return a list of subprotocols
+     * @return a list of the preferred subprotocols
      */
      List<String> getPreferredSubprotocols();
 
Index: trunk/api/src/main/java/javax/websocket/DefaultClientConfiguration.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/DefaultClientConfiguration.java   
  (revision 52)
+++ trunk/api/src/main/java/javax/websocket/DefaultClientConfiguration.java   
  (revision 53)
@@ -48,26 +48,18 @@
  * @author dannycoward
  */
 public class DefaultClientConfiguration implements 
ClientEndpointConfiguration {
-    private String path;
     private List<String> preferredSubprotocols = new ArrayList<String>();
     private List<String> extensions = new ArrayList<String>();
     private List<Encoder> encoders = new ArrayList<Encoder>();
     private List<Decoder> decoders = new ArrayList<Decoder>();
-    /** Creates a client configuration that will attempt
-     * to connect to the given URI.
-     * @param uri
+    /** Creates a client configuration with no preferred sub protocols, 
extensions, decoders or encoders.
      */
-    public DefaultClientConfiguration(String uri) {
-        this.path = uri;
+    public DefaultClientConfiguration() {
     }
 
-    public String getPath() {
-        return path;
-    }
-
     /** Return the protocols, in order of preference, favorite first, that 
this client would
      * like to use for its sessions.
-     * @return
+     * @return the preferred subprotocols.
      */
     public List<String> getPreferredSubprotocols() {
         return this.preferredSubprotocols;
@@ -75,7 +67,8 @@
 
     /** Assign the List of preferred subprotocols that this client would 
like to
      * use.
-     * @return
+     * @param preferredSubprotocols the preferred subprotocols.
+     * @return this endpoint configuration.
      */
     public DefaultClientConfiguration setPreferredSubprotocols(List<String> 
preferredSubprotocols) {
         this.preferredSubprotocols = preferredSubprotocols;
@@ -84,41 +77,50 @@
 
     /** Return the extensions, in order of preference, favorite first, that 
this client would
      * like to use for its sessions.
-     * @return
+     * @return the extension list.
      */
     public List<String> getExtensions() {
-        this.extensions = extensions;
-        return null;
+        return this.extensions;
     }
 
     /** Assign the List of preferred subprotocols that this client would 
like to
      * use.
-     * @return
+     * @param extensions the extensions
+     * @return this endpoint configuration.
      */
     public ClientEndpointConfiguration setExtensions(List<String> 
extensions) {
         this.extensions = extensions;
         return this;
     }
 
-    /** Assign the list of encoders this client will use.
-     * @return
+    /** 
+     * Assign the list of encoders this client will use.
+     * @return the encoder list.
      */
     public List<Encoder> getEncoders() {
         return this.encoders;
     }
-    /** Assign the list of encoders this client will use. */
+    /** Assign the list of encoders this client will use.
+     * @param encoders the encoders to use.
+     * @return this endpoint configuration.
+     */
      public ClientEndpointConfiguration setEncoders(List<Encoder> encoders) {
          this.encoders = encoders;
         return this;
     }
-    /** Assign the list of decoders this client will use.
-     * @return
+    /** 
+     * Assign the list of decoders this client will use.
+     * @return the decoders to use.
      */
     public List<Decoder> getDecoders() {
         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.
+         */
      public ClientEndpointConfiguration setDecoders(List<Decoder> decoders) {
          this.decoders = decoders;
         return this;
Index: trunk/api/src/main/java/javax/websocket/EncodeException.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/EncodeException.java        
(revision 52)
+++ trunk/api/src/main/java/javax/websocket/EncodeException.java        
(revision 53)
@@ -48,19 +48,31 @@
     private Object object;
         private static final long serialVersionUID = 006;
 
-    /* Constructor with the object being encoded, and the reason why it 
failed to be.*/
+    /** 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.*/
+    
+    
+    /**
+     * 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;
     }
 
 
-    /* Object being encoded. */
+    /** Return the Object that could not be encoded.
+     * @return the object
+     */
 
     public Object getObject() { return this.object;}
 }
Index: trunk/api/src/main/java/javax/websocket/CloseReason.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/CloseReason.java    (revision 52)
+++ trunk/api/src/main/java/javax/websocket/CloseReason.java    (revision 53)
@@ -52,8 +52,8 @@
 
     /** Creates a reason for closing a web socket connection with the given
      * code and reason phrase.
-     * @param closeCode
-     * @param reasonPhrase
+     * @param closeCode the close code
+     * @param reasonPhrase the reason phrase
      */
     public CloseReason(CloseReason.CloseCode closeCode, String reasonPhrase) 
{
         this.closeCode = closeCode;
@@ -133,7 +133,10 @@
             this.code = code;
         }
 
-        /** Return the code number of this status code. */
+        /** 
+         * Return the code number of this status code. 
+         * @return the code.
+         */
         public int getCode() {
             return code;
         }
Index: trunk/api/src/main/java/javax/websocket/Encoder.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/Encoder.java        (revision 52)
+++ trunk/api/src/main/java/javax/websocket/Encoder.java        (revision 53)
@@ -91,7 +91,7 @@
      */
      interface Binary<T> extends Encoder {
         /** Encode the given object into a byte array.
-         @param object the object being encoded
+         * @param object the object being encoded
          * @return the binary data
          */
          ByteBuffer encode(T object) throws EncodeException;
Index: trunk/api/src/main/java/javax/websocket/Endpoint.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/Endpoint.java       (revision 52)
+++ trunk/api/src/main/java/javax/websocket/Endpoint.java       (revision 53)
@@ -60,11 +60,11 @@
     public abstract EndpointConfiguration getEndpointConfiguration();
     /** Developers must implement this method to be notified when a new 
conversation has
      * just begun.
-     * @param session
+     * @param session the session that has just been activated.
      */
     public abstract void onOpen(Session session);
     /** This method is called when the session with the client is terminated.
-     * @param session
+     * @param closeReason the reason the session was closed.
      */
     public void onClose(CloseReason closeReason) {}
 
@@ -77,6 +77,7 @@
      * - conversion errors encoding incoming messages before any message 
handler has been called.<br>
      * TBD We may come up with less of a 'catch-all' mechanism for handling 
exceptions, especially given the varying nature
      * of these categories of exception.
+     * @param thr the throwable representing the problem.
      */
 
     public void onError(Throwable thr) {}
Index: trunk/api/src/main/java/javax/websocket/ClientContainer.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/ClientContainer.java        
(revision 52)
+++ trunk/api/src/main/java/javax/websocket/ClientContainer.java        
(revision 53)
@@ -51,11 +51,10 @@
 public interface ClientContainer {
     /** Connect the supplied programmatic endpoint to its server using the 
supplied handshake
      * parameters.
-     * @param endpoint the endpoint which will be connected to the server
      * @param olc  the client configuration used to connect the client
      * @param path the complete path to the server endpoint 
      */
-     void connectToServer(Endpoint endpoint, ClientEndpointConfiguration 
olc, URL path) throws DeploymentException;
+     void connectToServer(Endpoint endpoint, URL path) throws 
DeploymentException;
      
     /** 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
@@ -80,7 +79,7 @@
      long getMaxSessionIdleTimeout();
     /** Sets the maximum time that a web socket session may be idle before
      * the container may close it.
-     * @param the maximum time in milliseconds.
+     * @param max the maximum time in milliseconds.
      */
      void setMaxSessionIdleTimeout(long timeout);
      /** Returns the maximum size of binary message that this container
@@ -90,7 +89,7 @@
      long getMaxBinaryMessageBufferSize();
     /** Sets the maximum size of binary message that this container
       * will buffer.
-      * @param  the maximum size of binary message in number of bytes
+      * @param  max the maximum size of binary message in number of bytes
       */
      void setMaxBinaryMessageBufferSize(long max);
     /** Sets the maximum size of text message that this container
@@ -100,12 +99,14 @@
      long getMaxTextMessageBufferSize();
      /** Sets the maximum size of text message that this container
       * will buffer.
-      * @param the maximum size of text message in number of bytes
+      * @param max the maximum size of text message in number of bytes
       */
      void setMaxTextMessageBufferSize(long max);
 
-    /** Return the set of Extensions installed in the container.
-     @return the set of extensions. */
+    /** 
+     * Return the set of Extensions installed in the container.
+     * @return the set of extensions. 
+     */
      Set<String> getInstalledExtensions();
 }
 
Index: trunk/api/src/main/java/javax/websocket/Session.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/Session.java        (revision 52)
+++ trunk/api/src/main/java/javax/websocket/Session.java        (revision 53)
@@ -125,12 +125,14 @@
      */
      long getMaximumMessageSize();
     /** Return a reference to the RemoteEndpoint object representing the 
other end of this conversation.
-     @return the remote endpoint.
+     * @return the remote endpoint.
      */
      RemoteEndpoint getRemote();
 
 
-    /** Close the current conversation with a normal status code and no 
reason phrase. */
+    /** 
+     * Close the current conversation with a normal status code and no 
reason phrase.
+     */
      void close() throws IOException;
 
     /** Close the current conversation, giving a reason for the closure. 
Note the websocket spec defines the
@@ -161,7 +163,7 @@
       * endpoint was deployed with a URI-template and the client connected 
with a 
       * particular matching URL. 
       * 
-      * @return the map of path parameters. The key of the map is the 
parameter name,
+      * @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<String, String> getPathParameters();
Index: trunk/api/src/main/java/javax/websocket/WebSocketPathParam.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/WebSocketPathParam.java     
(revision 52)
+++ trunk/api/src/main/java/javax/websocket/WebSocketPathParam.java     
(revision 53)
@@ -87,7 +87,7 @@
     /** 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 null.
-     @return the value */
+     @return the name of the variable used in the URI-template. */
     public String value();
 
 }
Index: trunk/api/src/main/java/javax/websocket/WebSocketEndpoint.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/WebSocketEndpoint.java      
(revision 52)
+++ trunk/api/src/main/java/javax/websocket/WebSocketEndpoint.java      
(revision 53)
@@ -78,19 +78,27 @@
      * &nbsp@WebSocketEndpoint("/chat/{user}") <br>
      * &nbsp@WebSocketEndpoint("/booking/{privilege-level}") <br>
      * </code>
-     *
+     * @return the URI or URI-template
      */
     public String value();
-    /** The ordered array of web socket protocols this endpoint supports. 
For example, {'superchat', 'chat'}.*/
+    /** 
+     * 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,
+    /** 
+     * 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.*/
+     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. */
+     * 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 {};
 }
Index: trunk/api/src/main/java/javax/websocket/SendResult.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/SendResult.java     (revision 52)
+++ trunk/api/src/main/java/javax/websocket/SendResult.java     (revision 53)
@@ -49,23 +49,29 @@
 public class SendResult {
     private Throwable exception;
     private boolean isOK = true;
-    /** Construct a SendResult carrying an exception. */
+    /** 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 carrying an no exception. */
+    /** Construct a SendResult signifying a successful send carrying an no 
exception.
+     * 
+     */
     public SendResult() {
 
     }
 
 
-    /** The problem sending the message. */
+    /** The problem sending the message.
+     * @return the problem.
+     */
     public Throwable getException() {
         return exception;
     }
     /** Determines if this result is ok or not.
-     @return whether the send was successful or not.
+     * @return whether the send was successful or not.
      */
     public boolean isOK() {
         return this.isOK;
Index: trunk/api/src/main/java/javax/websocket/RemoteEndpoint.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/RemoteEndpoint.java (revision 52)
+++ trunk/api/src/main/java/javax/websocket/RemoteEndpoint.java (revision 53)
@@ -86,7 +86,7 @@
          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 output stream to which the message will be written.
+        * @return the writer to which the message will be written.
         */
          Writer getSendWriter() throws IOException;
         /** Sends a custom developer object, blocking until it has been 
transmitted. Containers will by default be able to encode
@@ -102,7 +102,6 @@
          * in transmission are given to the developer in the SendResult 
object.
          * @param text the text being sent.
          * @param completion the handler which will be notified of progress.
-         * @return
          */
          void sendStringByCompletion(String text, SendHandler completion);
          
@@ -110,8 +109,7 @@
          * is transmitted. Developers use the returned Future object to 
track progress of the transmission. Errors
          * in transmission are given to the developer in the SendResult 
object.
          * @param text the text being sent.
-         * @param completion the handler which will be notified of progress.
-         * @return
+         * @return the Future object representing the send operation.
          */
          Future<SendResult> sendStringByFuture(String text);
 
@@ -119,8 +117,7 @@
          * is transmitted. Developers use the returned Future object to 
track progress of the transmission. Errors
          * in transmission are given to the developer in the SendResult 
object.
          * @param data the data being sent.
-         * @param completion the handler that will be notified of progress.
-         * @return
+         * @return the Future object representing the send operation.
          */
          Future<SendResult> sendBytesByFuture(ByteBuffer data);
          
@@ -130,7 +127,6 @@
          * in transmission are given to the developer in the SendResult 
object.
          * @param data the data being sent.
          * @param completion the handler that will be notified of progress.
-         * @return
          */
          void sendBytesByCompletion(ByteBuffer data, SendHandler completion);
 
@@ -139,8 +135,7 @@
          * type in the endpoint configuration. Containers will by default be 
able to encode
          * java primitive types, their object equivalents, and arrays or 
collections thereof. Progress is be tracked using the Future object.
          * @param o the object being sent.
-         * @param completion the handler that will be notified of progress
-         * @return
+         * @return the Future object representing the send operation.
          */
          Future<SendResult> sendObjectByFuture(Object o);
          
@@ -150,7 +145,6 @@
          * through the supplied callback object.
          * @param o the object being sent.
          * @param completion the handler that will be notified of progress
-         * @return
          */
          void sendObjectByCompletion(Object o, SendHandler handler);
 
Index: trunk/api/src/main/java/javax/websocket/ContainerProvider.java
===================================================================
--- trunk/api/src/main/java/javax/websocket/ContainerProvider.java      
(revision 52)
+++ trunk/api/src/main/java/javax/websocket/ContainerProvider.java      
(revision 53)
@@ -45,12 +45,39 @@
  * @author dannycoward
  */
 public class ContainerProvider {
+    private static String SERVER_CLASSNAME_PROPERTYNAME = 
"webocket.servercontainer.classname";
+    private static String CLIENT_CLASSNAME_PROPERTYNAME = 
"webocket.clientcontainer.classname";
+    
+    /** Obtains a reference to the (singletone) ServerContainer 
implementation.
+     * 
+     * @return the server implementation.
+     */
 
     public static ServerContainer getServerContainer() {
-        return null;
+        return (ServerContainer) 
loadImplementation(CLIENT_CLASSNAME_PROPERTYNAME);  
     }
 
+    /** Obtains a reference to the (singleton) ClientContainer 
implementation.
+     * 
+     * @return the client implementation.
+     */
     public static ClientContainer getClientContainer() {
-        return null;
+        return (ClientContainer) 
loadImplementation(CLIENT_CLASSNAME_PROPERTYNAME);
     }
+    
+    private static Object loadImplementation(String name) {
+        String clName = System.getProperty(name);
+        if (clName != null) {
+            try {
+                Class c = Class.forName(name);
+                Object impl = c.newInstance();
+                return impl;
+            } catch (Exception e) {
+                throw new RuntimeException(e);
+            }
+        }
+        throw new RuntimeException("cannot find system property: " + name);
+    }
+    
+    
 }





[websocket-spec~source-code-repository:53] javadoc updates

dannycoward 11/17/2012
 
 
Close
loading
Please Confirm
Close