Hello again,
Here's a list of smaller API issues I'd like to close out. I've put int
my own proposal for how to handle each one, if I don't hear any
dissenting voices, I will fix as proposed.
Thanks !
- Danny
1) What are the inheritance semantics of the websocket annotations ?
For example, if I subclass a class annotated with @WebSocketEndpoint,
can a use @WebSocketMessage on methods on the subclass even if the
subclass is not annotated with @WebSocketMessage ?
My proposal is that we stick to the guidelines that JSR 250 ( Common
Annotations for the Java Platform) Senior Staff Engineer sets out in
section 2.1. The layman's version is that subclasses don't inherit any
of the metadata. Annotations only affect the class (or methods of the
class) they live on. The semantics start to get very tricky if we
diverge from those guidelines.
2) Can we use @WebSocketMessage on methods that take partial messages
and blocking streams in addition to the whole message versions ?
Currently, we do not allow the asynchronous message handling modes on
such methods. I propose we do, and in so doing, any method that can be
mapped to one of our MessageHandlers can be annotated @WebSocketMessage,
e.g.
@WebSocketMessage
public void doUpload(ByteBuffer bb, boolean last, Session s)
@WebSocketMessage
public void parseDocument(String partialString, boolean last)
@WebSocketMessage
public void parseDocument(Reader r)
should all be allowable in addition to the 'whole message' forms.
(Subject to the same one message handler type per endpoint rule we have
for programmatic endpoints)
3) Provide a way for developer to store application data on the Session
object.
I propose we support this: add public Map<String, Object>
getUserProperties() to Session.
4) Why not use JDK java.nio.channels.CompletionHandler
(
http://docs.oracle.com/javase/7/docs/api/java/nio/channels/CompletionHandler.html)
instead of our javax.websocket.SendHandler.
I do not propose we replace this. Our SendHandler is a single method
interface, which makes it convenient for lambdas. The CompletionHandler
is not commonly used outside NIO, so there is no gain on the learning
curve, and misses the type information (SendResult) which is going to
make it (a touch) more difficult to use.
5) Merge Endpoint and EndpointConfiguration
This suggestion predates our change to the object cardinality whereby
now there is a new instance of Endpoint per peer, and we only need one
instance of the EndpointConfiguration. So even if it made sense before,
it does not now.
6) Remove ability to set encoders on the Session.
I do not remember why Session has this setEncoders() API, but I propose
to remove it unless someone can remember the reasoning. Configuring the
encoders on the EndpointConfiguration should be sufficient.
- Danny
--
<http://www.oracle.com> *Danny Coward *
Java EE
Oracle Corporation