[jsr356-experts] Pot Pourri of issues from Public Draft

From: Danny Coward <danny.coward_at_oracle.com>
Date: Fri, 18 Jan 2013 17:23:29 -0800

Hi folks,

We have many issues to resolve, so I picked a collection to get things
started. As usual, I have outlined an approach for each issue to keep
things moving, so if you have other options or suggestions to add,
please chime in.

* Consider requiring authentication schemes to be supported on the
client container

I think BASIC and DIGEST are probably the most common. I think this is a
good idea, but I am wary of trying to come up with this in a short
period of time for the first version. Given that developers can
intercept and modify the handshake request (see below) and inspect the
handshake response, they have the ability to build http-based
authentication schemes on top of the API without any changes. So I'd
suggest we defer requiring client containers to support any particular
authentication schemes until the next release.

* Allow annotated client endpoints to intercept handshake (as well as
programmatic ones)

Currently we have a scheme whereby programmatic client endpoint can
override the default configuration (for example, to intercept the
opening handshake). But there isn't a way to allow annotated client
endpoints to do the same thing. Since server endpoints of both kinds can
do this, and given developers may want to plug in authentication schemes
or other header-manipulating code into client POJOs, I think we should
allow this by (based on the current scheme) adding an optional
configuration() attribute to @WebSocketClient.

* Allow Java primitives and class equivalents as message parameters for
@WebSocketMessage methods.


Currently, you are allowed to annotate methods that offer a String,
ByteBuffer, byte[] or custom developer object (with decoder) parameter
for whole message processing or (String,boolean), (ByteBuffer, boolean)
and (byte[], boolean) parameters for partial message processing. The
request is to allow methods that offer Java primitives for message

Since all of the classes Byte, Short, Integer, Long, Float, Double,
Boolean have unambiguous mappings from String via their single argument
String constructors, I think this would be a nice addition to allow this
for processing text messages. Character has one string parameter
constructor, but of course String.toCharArray() is unambiguous enough
for strings of length 1, so that could be included for completeness. Any
failure to decode an incoming message to its primitive/class equivalent,
according to those mapping would generate a DecodeException, in exactly
the same way as happens for incoming messages that the runtime is trying
to map to a custom developer object.

I don't see an unambiguous way to map binary data to Java primitive
types, so I'm suggesting we make this work only for text messages.

* Lifecycle of Decoders/Encoders

Currently the specification leaves it open to implementations as to when
they instantiate Encoders and Decoders for incoming and outgoing
messages. We could leave this up to the implementations, but it would be
better to define it since they are supposed to be portable. There are
clearly a number of choices here, but I do think we should guarantee
that no single instance of an Encoder or Decoder object is shared
between different connections. What are other people's thoughts ?

* Calling methods on closed Sessions / Making Session Closeable

Once a websocket session has closed, it is possible that code will still
reference the instance and (inadvertently?) call methods on it. In such
situations, I think the methods should throw IllegalStateException
because the session is closed and its data and operations are now

Secondly, since Session already has a close() method, we could make it
implement java.io.Closable, and hence it would then be possible to use
it in a JDK 7 try-with-resources block. I think this is a good idea too.

* Extension parameter ordering

Currently the API models extension parameters as Map<String, String>,
yet the parameters have an order in the http headers. While this order
doesn't have a meaning in the websocket protocol specification, both the
MUX and Compression extensions attach semantic meaning to specific
parameters, so it is perfectly possible that some new extension might
attach semantic meaning to their order. So, I think our API needs to
preserve them. I suggest we model extension parameters as
List<Parameter> where Parameter is a member type of Extension, and
contains the parameter name and value as Strings.

* Number of instances of client container / server container

Currently these are both modeled using the class WebSocketContainer.
This relates to two requests:

1) To allow the client developer to instantiate client container
instances at will, so that he can use different instances with different
property values, such as async send timeout or maximum message sizes.
This seems like a reasonable thing to accommodate.

2) To use a one instance of the server container WebSocketContainer per
application per VM instead of the current one instance per VM for all
applications. I think this is reasonable too - exactly matches the
cardinality of the ServletContext for web components.

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