[jsr340-experts] Re: Websockets

[Alex <alex@caucho.com>]

> Well I guess it can be read either way.
> 
> For those interested, here is the Caucho API:

> http://caucho.com/resin-4.0-javadoc/com/caucho/websocket/package-summary.html

Yep, that's the current link. A small write up by Scott explains our design 
approach:

Design notes:

General:
======

 1. The API is designed to be more minimal than a final design would be to 
make it easier to focus on the critical design decisions, and to avoid 
feature bloat if possible.

 2. The key model is the InputStream/Reader and OutputStream/PrintWriter 
stream-based data model, following the Servlet API. It's expected that 
application frameworks may create String or byte array APIs on top, but the 
low-level servlet API is a simple stream API which scales from tiny messages 
to very large messages.

In other words, I'm expecting this API to be aimed more at the framework 
developers, just like the servlet API, not necessarily the end users. (In 
part, because frameworks should really be exposing a specific WebSocket 
sub-protocol, like a JSON message system, not the raw stream.)

 3. The API is at the message layer, not the frame layer. The frame layer 
should be an implementation detail for now (e.g. supporting muxing or 
compression, implementation efficiency, etc.). While it may eventually be 
worthwhile to expose a standard frame API/SPI for WebSocket extensions, I 
think it's best put off for a bit, like the Servlet Filters were, until the 
Servlet users and also the WebSocket community understands better what 
extensions should look like. I think extension implementation will be rare 
and might always be container features. So keeping focused on the key 
application message layer seems like a better move for now.

 4. The WebSocketContext and WebSocketListener do not have any servlet API 
dependencies because they should also be used for the client API. (Because 
WebSocket is symmetrical once established, it would be a mistake to have 
separate Java client and server APIs.)

WebSocketServletRequest:
=================

 1. This is an interface only to decouple it from the Resin implementation. 
I'd expect it to be a HttpServletRequest method in the servlet spec.

 2. startWebSocket is meant to resemble startAsync. It issues the upgrade 
response. It's the responsibility of the application servlet to check headers 
and set the "Protocol" header before calling startWebSocket.

 3. The WebSocketListener is passed as an argument (instead of a setter) 
because client messages might be delivered immediately, even before the 
startWebSocket returns.

 4. The WebSocketContext is returned so the server can start sending messages.

WebSocketContext:
============

 1. intended to resemble AsyncContext

 2. Does _not_ have servlet API dependencies because it is intended to be a 
valid Java WebSocket client API.

 3. _not_ thread-safe.  (Thread safety would be impossible in any case, 
because the message doesn't complete until the output stream is closed.)

 4. Only two major methods: startTextMessage() and startBinaryMessage().

 5. Message ends when OutputStream.close() or Writer.close() is called.

 6. Implementations MAY reuse the OutputStream/Writer objects, like the 
ServletRequest spec.

 7. (Extensions deliberately ignored in the draft proposal to keep things 
simple.)

WebSocketListener:
============

 1. somewhat similar to async listeners, but the listener is unique.

 2. the listener is serialized/single-threaded, e.g. a new message will not 
be delivered until the application returns from onReadBinary/onReadText.

 3. WebSocketContext is passed as an argument for timing reasons (i.e. there 
may be a message before the startWebSocket returns.)

 4. message reading is complete when the onReadBinary/onReadText returns. If 
more data is available in the message, the implementation skips the rest of 
the message.

 5. (Extension data again deliberately ignored in the draft to keep things 
simple.)

Final general notes:
=============

 1. The stream API at the message layer is important to me (as opposed to a 
String/byte[] API at the frame layer.)

 2. Any frame/extension API/SPI should be an added/lower layer (like the CDI 
extensions), not part of the messaging layer. (And should probably be 
postponed for now.)

 3. The Listener/Context is nice, but it's not as important as the core 
stream.

 4. I expect some complications to be added for extensions (possibly in the 
Context), but wanted to focus on the core API for a first proposal. So I 
expect the onReadBinary and startBinaryMessage signatures to change.

Alex
> 
> 
> On 27 May 2011 18:42, Remy Maucherat <rmaucher@redhat.com> wrote:
>> On Fri, 2011-05-27 at 18:38 +1000, Greg Wilkins wrote:
>>> On 27 May 2011 17:32, Remy Maucherat <rmaucher@redhat.com> wrote:
>>>> On Fri, 2011-05-27 at 08:21 +1000, Greg Wilkins wrote:
>>>>> I make no representations that this is the best way to proceed, or
>>>>> even a good way... it is just how we have done it so far.  Users have
>>>>> been warned that significant changes to this API are likely.
>>>> 
>>>> Besides the upgrade mechanism, this has not been mentioned as being in
>>>> scope for this JSR. Which is quite understandable IMO, it's a lot of
>>>> spec work on something that is not finalized yet.
>>> 
>>> Remy,
>>> 
>>> it is in the JSR340 proposal:
>>> 
>>>    http://www.jcp.org/en/jsr/proposalDetails?id=340
>> 
>> "Enable support for WebSockets and other such protocols that work on /
>> do initial handshake over HTTP."
>> 
>> --
>> Remy Maucherat <rmaucher@redhat.com>
>> Red Hat Inc
>> 
>> 
> 
>