Thankyou for all your comments over the last few weeks. After a while to digest our later discussions, I've pushed a version 3 of the API for another round of review. This time (in anticipation of some implementation code!) I've both the javadoc up, but also pushed the source code of the api to the repository.
APIdoc bundle: http://java.net/projects/websocket-spec/downloads/directory/Spec%20javadoc%20Drafts/v003
Below is a summary of the larger things that changed this round. As usual, please do take a close look at this API and let me know your review comments.
Summary of Changes from V002
* Streaming API - this versions adds the whole message callbacks, a blocking stream api and the async api that we seemed to favor. I think this best represents the discussion on the options I laid out, even though it was not conclusive. I'd like to get some implementation experience against this API before we finalize it - especially in terms of how to build the blocking API on top of an asynchronous infrastructure because of some of the doubts raised.
* Pings and Pongs - This version includes the means to send a Ping, listen for Pongs and also send a Pong. I've added a note to include a section in the spec that defines that the implementation
must respond to an incoming Ping with a Pong containing the same data. I can't see any other variables in or policies to apply ton this mechanism after reading sections 5.5.2 and 5.5.3 in the web socket RFC.
* Extensions - This version includes a definition of extensions in the API v3 based a previous discussion. The basic idea is that an extension has a name, a parameter Map and the ability to insert filter like frame-handlers 'underneath' an endpoint. Extensions receieve the frames formulated before them in the implementation and can modify/coalesce/multiply them as they pass them onto the next extension in the chain or back to the implementation - both for outgoing messages and incoming messages. I'm aiming to establish a concept here in the API; I'm expecting lots of feedback on this, especially from those of you who have got into websocket framing and extensions in detail, especially in the area of how to stream data into/out of the data frames.
* Handshake and URI matching
This version reworks handshake API for a number of factors: to encapsulate extension negotiation, expose the http handshake request attributes that we listed out, and allow for http handshake response modification. Please take a look in particular at ServerConfiguration and DefaultServerConfiguration. Its awkward that we do not have readymade HttpRequest, HttpResponse and HttpHeader interfaces in the JDK to reuse to model this, so this version of the api provides homegrown ones.
This version also includes the means, by allowing developers to create their own ServerConfigurations to allow for custom/dynamic URI matching policies other than exact match. I expect we'll want to provide some ready made matching policies, like pattern matching for example, in addition.
* Servlets and cross cutting concerns.
There was a bit of discussion about how this relates to servlets: could these components handle both http and websocket interactions ?
So, here's how I'm seeing it, in terms of the scope of this JSR: this API is focussed mainly on allowing developers to write code that deals with web socket messages and providing the environment for that. The relationship with servlets would be therefore as follows:-
1) Using servlets and/or servlet filters could be a great way of implementing the server side of the websocket handshake and granting the right access to the process. (but is outside the scope of this spec to define how).
2) We hope to build on the new Servlet 3.1 upgrade mechanism in the Oracle RI for websocket. But no-one else has to do so if they do not want to.
3) If developers want to write web applications that have both servlets and websocket components, they absolutely can. They can use the HttpSession and ServletContext (or EJBs !) to share data between the two.
4) And in fact, the new Servlet 3.1 mechanism allows developers create a servlet that handle both regular Http requests and websocket handshake requests, as I thin Joe you had laid out.
I realize this doesn't explain some of other issues raised, like how authentication/authorization will work for websockets and how HttpSession relates to websocket sessions, but I do hope to get to those soon.
[jsr356-experts] V003 API for your review