[WEBSOCKET_SPEC-187] EndPoint javadoc is incorrect about cardinality Created: 18/Apr/13 Updated: 23/Apr/13 Resolved: 23/Apr/13
|Remaining Estimate:||Not Specified|
|Time Spent:||Not Specified|
|Original Estimate:||Not Specified|
The javadoc for EndPoint says that a single instance is created per connection. However this is just a policy implemented by the default ServerEndpoingConfig.Configurator and it is possible (and I'd say advisable) that shared Endpoint instances can be created.
I suggest that the text be updated to:
When deployed as a server endpoint, that is to say, the endpoint is registered to a URL, the server uses the registered ServerEndpointConfig instance to obtain an Endpoint instance. ServerEndpointConfig instances using the default ServerEndpointConfig.Configurator instance will instantiate a new Endpoint object for each connection, which means the developer is guaranteed that there will be at most one thread in each endpoint instance. However, alternative ServerEndpointConfig implementations may change the cardinality of the Endpoint so that an instance is shared between many connections, in which case the developer should write thread safe Endpoint code and use the passed Session instance for any per connection handling.
|Comment by dannycoward [ 23/Apr/13 ]|
Yes I see the issue - thanks ! I reworked the whole thing to say
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 onOpen method, the programmatic endpoint gains access to the Session object, to which the developer may add MessageHandler implementations in order to intercept incoming websocket messages. Each instance of a websocket endpoint is guaranteed not to be called by more than one thread at a time per active connection.
If deployed as a client endpoint, it will be instantiated once for the single connection to the server.
When deployed as a server endpoint, the implementation uses the ServerEndpointConfig.Configurator.getEndpointInstance(java.lang.Class<T>) method to obtain the endpoint instance it will use for each new client connection. If the developer uses the default ServerEndpointConfig.Configurator, there will be precisely one endpoint instance per active client connection. Consequently, in this typical case, when implementing/overriding the methods of Endpoint, the developer is guaranteed that there will be at most one thread calling each endpoint instance at a time.
If the developer provides a custom 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.