Skip to main content

[websocket-spec~source-code-repository:342] clearer javadoc covering the custom configurator/default configurator cas

  • From:
  • To:
  • Subject: [websocket-spec~source-code-repository:342] clearer javadoc covering the custom configurator/default configurator cas
  • Date: Tue, 23 Apr 2013 18:34:04 +0000

Project:    websocket-spec
Repository: source-code-repository
Revision:   342
Author:     dannycoward
Date:       2013-04-23 18:33:59 UTC
Link:       

Log Message:
------------
clearer javadoc covering the custom configurator/default configurator cases 
better per issue: 187


Revisions:
----------
342


Modified Paths:
---------------
trunk/api/client/src/main/java/javax/websocket/Endpoint.java


Diffs:
------
Index: trunk/api/client/src/main/java/javax/websocket/Endpoint.java
===================================================================
--- trunk/api/client/src/main/java/javax/websocket/Endpoint.java        
(revision 341)
+++ trunk/api/client/src/main/java/javax/websocket/Endpoint.java        
(revision 342)
@@ -40,15 +40,36 @@
 package javax.websocket;
 
 
-/**
- * The Web Socket Endpoint represents an object that can handle a web socket 
conversations. When
- * deployed as a server endpoint, that is to say, the endpoint is registered 
to a URL, the server instantiates
- * a new endpoint instance for each client connection. If
- * deployed as a client, the endpoint will be instantiated once per single 
connection to the server.
- * If the endpoint is a server which will cater to multiple clients, each 
endpoint instance corresponding to each active client
- * is called by no more than one thread at a time. This means that when 
implementing/overriding the methods
- * of Endpoint, the developer is guaranteed that there will be at most one 
thread in each endpoint instance.
+/** 
+ * The Web Socket Endpoint represents an object that can handle websocket 
conversations. 
+ * Developers may extend this class in order to implement a programmatic 
websocket 
+ * endpoint. The Endpoint class holds lifecycle methods that may be 
+ * overridden to intercept websocket open, error and close events. By 
implementing 
+ * the {@link Endpoint#onOpen(javax.websocket.Session, 
javax.websocket.EndpointConfig) onOpen} method, the programmatic endpoint 
gains access to the {@link Session} object, 
+ * to which the developer may add {@link MessageHandler} implementations in 
order to 
+ * intercept incoming websocket messages. Each instance 
+ * of a websocket endpoint is guaranteed not to be called by more than one 
thread 
+ * at a time per active connection.
  *
+ * <p>If deployed as a client endpoint, it will be instantiated once for the 
+ * single connection to the server. 
+ *
+ * <p>When deployed as a server endpoint, the implementation uses the 
+ * {@link 
javax.websocket.server.ServerEndpointConfig.Configurator#getEndpointInstance} 
+ * method to obtain the 
+ * endpoint instance it will use for each new client connection.  If the 
developer uses 
+ * the default {@link 
javax.websocket.server.ServerEndpointConfig.Configurator}, 
+ * there will be precisely one 
+ * endpoint instance per active client connection. Consequently, in this 
typical 
+ * case, when implementing/overriding the methods of Endpoint, the developer 
is 
+ * guaranteed that there will be at most one thread calling each endpoint 
instance
+ * at a time.
+ * 
+ * <p>If the developer provides a custom {@link 
javax.websocket.server.ServerEndpointConfig.Configurator}
+ * which overrides the default policy for endpoint instance creation, for 
example, 
+ * using a single Endpoint instance for multiple client connections, the 
developer
+ * may need to write code that can execute concurrently.
+ *
  * <p>Here is an example of a simple endpoint that echoes any incoming text 
message back to the sender.
  * <pre><code>
  * public class EchoServer extends Endpoint {





[websocket-spec~source-code-repository:342] clearer javadoc covering the custom configurator/default configurator cas

dannycoward 04/23/2013
 
 
Close
loading
Please Confirm
Close