Cometd Features and Extensions

The cometd project is nearing a 1.0 release and thus we are make a bit of a push to improve the project documentation. As part of this effort, we have realized that there are many cool features and extensions to cometd that have been under-publicized.  So this blog is an attempt to give a whirlwind tour of cometd features and extensions.

Clients and Servers

The cometd project provides many implementations of the Bayeux protocol.  The javascript and java implementations are most advanced, but there are also perl and python implementations under development within the project. There are also other implementations of Bayeux available outside the cometd project for groovy, flex, .net and atmosphere.

Javascript Client

There is now a common cometd-javascript client implementation used as the basis of the cometd-dojo and cometd-jquery implementations (dojox in 1.3.1 still contains a dojo specific client, but this will eventually be replaced with the common code base).  This common code base should able to be used to easily create implementation for other frameworks (eg ext.js or prototype).
For simplicity, our documentation get’s around the details of which javascript implementation you are using by assuming that you code is written in the context of a:

or

Basic Operation

Publish/Subscribe Messaging

The core operation of cometd is as a publish/subscribe messaging framework. A message is published to a channel with a URI like name (eg. /chat/room/demo ) and cometd will arrange to deliver that message to all subscribers for that channel, either locally in the server, remote in the client or a client of a clustered server.   The subscription may be for the channel itself (/chat/room/demo), a simple wildcard (/chat/room/*) or a deep wildcard (/chat/**).
Subscription in javascript needs to provide a callback function to handle the messages:

// Some initialization codevar subscription1 = cometd.addListener('/meta/connect', function() { ... });var subscription2 = cometd.subscribe('/foo/bar/', function() { ... });
// Some de-initialization codecometd.unsubscribe(subscription2);cometd.removeListener(subscription1);

Publishing a method in javascript is simply a matter of passing the channel name and the message itself:

cometd.publish('/mychannel', { wibble: { foo: 'bar' }, wobble: 2 });

Similar APIs for publish subscribe are available via a semi-standard cometd API and several java implementations are now using this.

Service Channels

With publish/subscribe, the basic feature set for a chat room is available. But non-trivial applications cannot be implemented with all communication broadcast on publicly accessible channels.  Thus cometd has a convention that any channel in the /meta/** or /service/** name space is a non-broadcast service channel (meta channels are used by the protocol itself and service channels are available to the application).  This means that a message published to a service channel will only be delivered to server side clients, listeners and extensions. A message to a service channel will never be remotely distributed to a remote client unless an application explicitly delivers or publishes a message to a particular client.
This allows a client to publish a message to a service channel and know that it will only be received by the server

Private Message Delivery

A cometd application often needs to deliver a message to a specific client.  Thus as an alternative to publishing to a channel, a java server side application can deliver a message to a specific user:

Client client = bayux.getClient(someClientId);client.deliver(fromClient,"/some/channel",aMsg,msgId);

Note that a private message delivery still identifies a channel. This is not to broadcast on that channel, but to identify the message handler within the client. This channel may be a service channel, so the client will know it is a private message, or it can be an ordinary channel, in which case the client cannot tell if the message was published or delivered to it.
Such private deliveries are often used to tell a newly subscribed client the latest state message. For example, consider a client that has subscribed to /portfolio/stock/GOOG.  That client needs to know the current price of the stock and should not have to wait until the price changes. Thus the portfolio application can detect the subscription server side and deliver a private message to the subscriber to tell them the latest price.

Lazy Messages

One of the key features of comet is delivering messages to clients from the server with low latency,  but not all messages need low latency. Consider a system status message, sent to all users, telling them something non urgent (eg maintenance scheduled for later in the day).  There is no need for that message to be sent to every single user on the system with minimal latency and there is a significant cost to try to do so.  If you have 10,000 users, then waking up 10k long polls will take a few seconds of server capacity which might be better used for urgent application events.
Thus the cometd-java server has the concept of lazy messages.  A message may be flagged as lazy by publishing it to a channel that is flagged as lazy (ChannelImpl#setLazy(boolean)) or by publishing to any channel with the ChannelImpl#publishLazy(…) method. [ Note these methods are not yet on the standard API, but should be before 1.0. Until they are, you must cast to ChannelImpl ].
A Lazy message will be queued for a client, but it will not wake up the long poll of that client.  So a lazy message will only be delivered when another non-lazy message is sent to that client, or the long poll naturally times out (in 30 to 200 seconds).  Thus low priority messages can be delivered with minimal additional load to the server.

Message Batching

Comet applications will often need to send several related messages in respond to the same action (for example subscribing to a chat room and sending a hello message).   To maximize communication efficiency, it is desirable that these multiple messages are transported on the same HTTP message.    Thus both the cometd client and server APIs support the concept of batching.  Once a batch is started, messages for a client a queued but not delivered until such time as the batch is ended. Batches may be nested, so it is safe to start a batch and call some other code that may do it’s own batching.
On the javascript client side, batching can be achieved with code like:

cometd.startBatch();cometd.unsubscribe(myChatSubscription);cometd.publish("/chat/demo",{text:'Elvis has left the building', from:'Elvis'});cometd.endBatch();

On the java server side, batching can be achieved with code like:

public void handleMessage(Client from, Message message){    from.startBatch();    processMessageForAll(from,message);    from.deliver(from,message.getChannel(),processResponseForOne(message),null);    from.endBatch();}

This will send any message published for all users and the private reply to the client in a single HTTP response.

Listeners, Data Filters and Extensions

There are several different ways that application code can attach to the cometd clients and servers in order to receive events about cometd and to modify cometd behaviour:

Security Policy

The SecurityPolicy API  is available in the java server and is used to authorize handshakes, channel creation, channel subscription and publishing.  If an SecurityPolicy implementation is constructed with a reference to the Bayeux instance, then it can call the getCurrentRequest() method to access the current HttpServletRequest and thus use standard web authentication and/or HttpSessions when authorizing actions.

Extensions

Timestamp Extension

The timestamp extension simply adds the optional timestamp field to every message sent.

Timesync Extension

The timesync extension implements a NTP-like time synchronization.  Thus a client can be aware of the offset between it’s local clock and the servers clock. This allows an application (eg an Auction site) to send a single message with the semantic: “the auction closes at 18:45 EST” and then each client can use it’s own local clock to count down the auction, without the need for wasteful tick messages from the server.

Acknowledged Message Extension

The Cometd/Bayeux protocol is carried over TCP/IP, so it is intrinsically reliable and messages will not get corrupted. However, with cometd, there are some edge cases where messages might get lost (dropped connections) or might arrive out of order (using multiple connections).
The acknowledge extension piggybacks message acknowlegements onto the long polling transports of cometd, so that messages are not lost or delivered out of order.

Reload Extension

The client side only reload extension is provided to allow a comet enabled web page to be reloaded with out needing to rehandshake.  The existing client ID can be passed from page to page, so that an Comet/Ajax style of user interface can be merged with a more traditional page based approach.

Clustering

Cometd servers may be aggregated into a cluster using Oort, which is a collection of extensions that use the java cometd client to link the servers together. Currently Oort is under documented, so is best understood by reading this summary and then looking at the Auction example.

Observing Comets

The Oort class allows cometd servers to observe each other, which means to open bayeux connections in both directions.  Observations are setup with the Oort#observerComet method and can be used to setup arbitrary topologies of servers (although fully connected is the norm and is implemented by the Oort cloud).
Once observed, Oort Comets may cluster particular channels by calling Oort#observerChannel,which will cause the local server to subscribe to that channel on all observed comet servers. Any messages received on those subscriptions will be re-published to the local instance of that channel (with loop prevention). Thus messages published to an observed channel will be published on all observered comet servers.

The Oort Cloud

The Oort cloud is a self organizing cluster of Oort Comet servers that use the Oort Observed /oort/cloud channel to publish information about discovered Oort Comets.  Once an Oort comet is told of another via the /oort/cloud channel, it will observe it and then publish its own list of known Oort comets.   This allows a fully connected cluster of Oort comets to self organize with only one or two comet nodes known in common.

Seti

Once an Oort Cloud has been established, a load balancer will be needed to spread load over the cluster, so a user might be connected to any node in the cloud.   Seti (as in the Search for Extra Terrestial Intelligence), is a mechanism that allows a private message to be sent to a particular user that may be located anywhere in the cloud. Sharding and location caching can be used to make this more efficient.

Examples

Chat

Chat is the hello world of web-2.0 and the introductory demo for cometd.  The server side of the chat monitors the join messages to maintain and distribute a membership list for each room. A services channel is used to provide a private message service.
There is both a dojo chat client and jquery chat client provided.

Auction

The Auction demonstration provided shows the Oort and timesync extensions in use to provide a moderately complete example of a cometd application.


Note that this example uses cometd-dojo for the client, but the UI is implemented in a mushup of prototype, behaviour and other js libs.  Volunteers desparately needed to make this all dojo or all jquery.

Archetypes

Assembling the components needed for a cometd web application can be a little complex as the server components need to be mixed with the javascript framework and the cometd client. To make this process easier, cometd now support cometd maven archetypes, that can build a blank cometd war project in a few lines.
So what are you waiting for! Go comet!