Skip to main content

[jsr356-experts] v001 API for comment

  • From: Danny Coward < >
  • To:
  • Subject: [jsr356-experts] v001 API for comment
  • Date: Fri, 11 May 2012 16:08:12 -0700

Hello all,

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 ?


- Danny

Danny Coward
Java EE
Oracle Corporation

[jsr356-experts] v001 API for comment

Danny Coward 05/11/2012
Please Confirm