What Comet is Not.

It is not a socket API.

It is not a high level poller or poller API, for underlying poll()/select() methods

It is not a TCP socket, even though the events are fired based on IO

API Proposals

Currently there are two API proposals, one lead by remm(sandbox) and one by fhanik(trunk). Everything in here is up for change and comments. The proposals are not very far from each other, but confusion around Comet has lead to further confusion around the APIs. Here is an outline of differences

both intend to implement an event based model

sandbox API has events as implicit subscriptions

trunk API has explicits subscriptions, one must subscribe/unsubscribe for each event type

both APIs have the intention of implementing non blocking read and writes

the trunk API intends to allow both non blocking and blocking read/writes, but not both nor mixed for a connection

both APIs will have the non blocking implementation utilize the existing servlet/stream/reader/writer APIs, which will make the initial understanding of the APIs somewhat difficult, as the servlet/stream/reader/writer APIs are originally written for blocking APIs.

both APIs - A non blocking write will throw an IOException if a previous write has been done but not yet completed, this is as write has a void return signature, and it is impossible to return 0.

both APIs - A non blocking read will return 0, if no data exists.

both APIs will have helper methods isWriteable and isReadable to help with the state of the connection

both APIs will have the ability to suspend any future events, trunk by unregistering current subscriptions, sandbox by calling sleep() (or suggested suspend())

Remember, the API's have a fairly similar idea of what the underlying implementation will look like, the main difference is probably the implicit vs explicit event subscription, here are some examples