I've posted up a simple API in for discussion. It's here.
The goal of this API is to provide a starting point for discussion of what will ultimately evolve into the spec API. I've aimed at making it:
- very elementary and simple
- contain the core concepts of the protocol as need to be exposed to the application developer
- as symmetrical as possible between client and server APIs
- encompass a range of the fundamental ideas expressed in the APIs in our project list.
So please take a look when you get chance.
There are many simplifying assumptions and things that I have deliberately left out of the API. Here is a list of technical issues and assumptions that might help stimulate discussion as you look at the API:-
* Message representation: For now, the API only includes the simplest String and byte. Across the APIs we already have there's a wide range of possibilities for more sophisticated forms to expose to the developer: traditional i/o streams readers and writers, nio ByteBuffer and CharBuffers (and arrays thereof), I hope we can come up with a best list that allows a variety of implementation strategies.
* Connection modes: The API assumes simple blocking for sending messages. What's is the appetite for an asynchronous mode ? Perhaps send methods of the form void send(String text, CompletionHandlers) ? Or those using concurrency Futures ?
* The API assumes Pings and Pongs are implementation artifacts, but not of concern to application developers. Is that a reasonable assumption ?
* The API covers over data framing, obscuring it to developers. Is this realistic ?
* The server configuration assumes a simple programmatic mapping to URI. There's a range of possibilities, from static configuration to more dynamic schemes like in Grizzly.
* There are no annotations in this API. I expect we will work on annotations that map POJOs into Endpoint objects.
* Should developers be able to specific a reconnect policy ? For example, should a client endpoint be able to say under what circumstances to retry a connection to a web socket server endpoint if the connection goes down ?
* The API assumes the simplest model for session timeouts, and limits on message size. I know some APIs have finer grained detail on this - e.g. Jetty
* The API assumes security is set up somewhere else. In the EE setting, I'm expecting to be able to re-use much of what the web container has to offer.
* Handshake: the API assumes the developer has minimal knowledge of the details of the handshake process, save for the basic elements of the URI, optional Origin check, subprotocol preferences. What's missing ?
[jsr356-experts] v001 API for comment