[jsr356-experts] Next set of issues

From: Danny Coward <danny.coward_at_oracle.com>
Date: Thu, 31 Jan 2013 17:13:47 -0800

Hi folks,

I'm going to try to solve a bunch of issues at once in this email. As
usual, please call out if something does not look right to you.

* Allow annotations to specify extensions
If we did, I'd suggest we add,
String[] extension() to @WebSocketEndpoint and @WebSocketClient, where
the String follows the RFC 6455 definition of extension name plus 0 to n
extension parameters of the form ";name=parameter".
However, I don't think this is of primary interest to POJO developers,
so I'd lean towards leaving this out this version, maybe add it next
time when we see more of what people are doing with extensions.

* Semantics of send after the session is closed.

I updated the session methods to throw IllegalStateExceptions if the
Session has been closed, and the remoteendpoint.send methods have
adequate IOException sigs to cover the case when the developer attempts
an API call, but what is the implementation to do in this case

public String handle(String message, Session session) {
        try {
                  return something;// ???
             }catch (IOException e) {
             return "message";


The handle method has to complete, but since the session has closed, the
message cannot be delivered. I suggest we require the implementation
raise an IOException - something like IOException("Cannot deliver
message, session closed") and run that into the error handling method so
the developer has a chance to deal with this situation it if he elects to.

* Requirements on POJO classes

Here I am saying that POJOs that can be annotated as websockets need to
be is public, concrete classes with a public no args constructor. I know
that various injection frameworks can deal with other types of
constructors, so we might look at expanding the possibilities in the
next version, but I think this is clear and simple for this version.

* Client API implementation bootstrapping

Currently (as a stopgap) the ContainerProvider API has used an
undocumented system property to load the implementation class under
getWebSocketContainer(). Instead, I'm planning on switching this over to
use the ServiceLoader.load() mechanism. So provided the API classloader
can see a JAR containing the appropriate Manifest, the runtime will load
the implementation class. I don't think this should be controversial,
but I have a dim memory that this came up before, so I am putting it out
there in case I've missed something.

* Validity of message objects

Mark and I have exchanged comments over on the JIRA issue for this: for
the message objects that can be passed into the various MessageHandlers,
should they remain valid after the completion of the onMessage call ?
for example if the implementation passes in a ByteBuffer to represent a
binary message, can the developer be sure that it won't be recycled
after the onMessage call has completed.

I'd say it would be easier for developers if they could uses these
message objects outside the scope of the onMessage call, any other
opinions ?

* Container closing connection / onClose() and connection timeouts
(http://java.net/jira/browse/WEBSOCKET_SPEC-80 ,
http://java.net/jira/browse/WEBSOCKET_SPEC-117 )

I think the container should always call onClose() on the (local)
endpoint if the connection is being closed (for whatever reason). I
think its a central part of the programming model. So, yes on 80.

Second, I'd rather not invent new CloseCodes for various situations
where a container needs to close a connection: I think RFC 6455 already
defines a useful range of options sufficient for the needs of the
websocket developer. After all, all they are going to do with the
CloseCode is document it: there is little specific action they can take
based on the category of closure. I think 1001 works well for timeouts,
and 1005 is perfectly ok if the reason for the closure doesn't fit any
of the given options.


- Danny

<http://www.oracle.com> 	*Danny Coward *
Java EE
Oracle Corporation