CometD JavaScript Configuration

JavaScript CometD API: Configuration and Initialization

After you have setup your skeleton project following the Primer, you may want to fully understand how to customize and configure the parameters that govern the behavior of the Cometd implementation.

The whole API is available through a single object prototype named org.cometd.Cometd.
The Dojo toolkit has one instance of this object available under the name dojox.cometd, while for jQuery it is available under the name $.cometd.

This default cometd object has been instantiated and configured with the default values and it has not started any Bayeux communication yet.
Before it can start any Bayeux communication it needs a mandatory parameter: the URL of the Bayeux server.

There are 2 ways of passing this parameter:

// First style: URL string
cometd.configure('http://localhost:8080/cometd');

// Second style: configuration object
cometd.configure({
    url: 'http://localhost:8080/cometd'
});

The first way is a shorthand for the second way.
However, the second way allows to pass other configuration parameters, currently:

 
After you have configured the cometd object, it has not started the Bayeux communication yet. To start the Bayeux communication, you need to call handshake(), see the next section.

Previous users of the JavaScript Cometd implementation were used to call a method called init(). This method still exists, and it is a shorthand for calling configure() followed by handshake().
Follow the advices in the next section as they apply as well to init().

CometD JavaScript Handshake

JavaScript CometD API: Handshake

The call to handshake() (or to init()) is the one that initiates the Bayeux communication with the Bayeux server.

The Bayeux handshake performs 2 tasks:

• the client and the server negotiate the type of transport to use
• once the transport is negotiated successfully, the server informs the client with the detailed timings of the requests

As with several methods of the JavaScript CometD API, it is an asynchronous method: it returns immediately, well before the Bayeux handshake steps have completed.

Note
Calling handshake() does not mean that you have completed the handshake with the server when handshake() returns.

The handshake may fail for several reasons:

• you mistyped the server URL
• the transport could not be negotiated successfully
• the server denied the handshake (for example, the authentication credentials were wrong)
• the server crashed
• there was a network failure

Therefore it is not a good idea to write this code:

// Configure and handshake
cometd.init('http://localhost:8080/cometd');

// Publish to a channel
cometd.publish('/foo', { foo: 'bar' });

It is not a good idea, because there is no guarantee that the call to publish() (which we cover in a later section) can actually succeed in contacting the Bayeux server.
Since the API is asynchronous, you have no way of knowing synchronously (i.e. by having handshake() return an error code or by throwing an exception) that the handshake failed.
Even if the handshake succeeds, you may still be "disconnected" from the Bayeux server, for example because the server crashed just after the successful handshake.

Fortunately there is a way to be notified about the details of the Bayeux protocol message exchange: by adding listeners to special channels (called meta channels).
This is explained in the section about subscriptions.

CometD JavaScript Subscription

JavaScript CometD API: Subscribing and Unsubscribing

Channels

The Bayeux specification defines the concept of a channel: it is like a messaging topic where interested parties can subscribe to receive information published onto the channel.
There are 3 types of channels:

• meta channels
• service channels
• normal channels

A channel looks like a directory path such as /meta/connect (a meta channel; all meta channels starts with the prefix /meta/), or /service/chat (a service channel; all service channels starts with the prefix /service/) or /foo/bar (a normal channel).

Meta Channels

Meta channels are created by the Bayeux protocol itself.
It is not possible to subscribe to meta channels: the server will reply with an error message. However, it is possible to listen to meta channels (see below the difference between subscribing and listening).
It makes no sense to publish messages to meta channels: only the Bayeux protocol implementation creates and sends messages on meta channels.
Meta channels are useful on the client to listen for error messages like handshake errors (for example because the client did not provide the correct credentials) or network errors (for example to know when the connection with the server has broken or when it has been re-established).

Service Channels

Service channels are used in the case of request/response style of communication between client and server (as opposed to the publish/subscribe style of communication or normal channels).
While subscribing to service channels yields no errors, this is a no-operation for the server: the server ignores the subscription request.
It is possible to publish to service channels, with the semantic of a communication between a specific client (the one that's publishing the message on the service channel) and the server.
Service channels are useful to implement, for example, private chat messages: in a chat with userA, userB and userC, userA can publish a private message to userC (without userB knowing about) using service channels.

Normal Channels

Normal channels have the semantic of a messaging topic and are used in the case of publish/subscribe style of communication.
Usually, it is possible to subscribe to normal channels and to publish to normal channels; this can only be forbidden using a security policy on the Bayeux server.
Normal channels are useful to implement broadcasting of messages to all subscribed clients, for example in case of a stock price change.

Subscribers versus Listeners

The JavaScript CometD API has 2 APIs to work with channel subscriptions:

• addListener() and the correspondent removeListener()
• subscribe() and the correspondent unsubscribe()

The addListener() method:

• must be used to listen to meta channel messages
• may be used to listen to service channel messages (you may also use subscribe())
• should not be used to listen normal channel messages (use subscribe() instead)
• does not involve any communication with the Bayeux server, and as such can be called before calling handshake()
• is synchronous: when it returns, you are guaranteed that the listener has been added

The subscribe() method:

• must not be used to listen to meta channels messages (otherwise the server will return an error)
• may be used to listen to service channel messages (you may also use addListener())
• should be used to listen to normal channel messages
• involves a communication with the Bayeux server and as such cannot be called before calling handshake()
• is asynchronous: it returns immediately, well before the Bayeux server has received the subscription request

Note
Calling subscribe() does not mean that you have completed the subscription with the server when subscribe() returns.

Both addListener() and subscribe() return a subscription object that must be passed to, respectively, removeListener() and unsubscribe():

// Some initialization code
var subscription1 = cometd.addListener('/meta/connect', function() { ... });
var subscription2 = cometd.subscribe('/foo/bar/', function() { ... });

// Some de-initialization code
cometd.unsubscribe(subscription2);
cometd.removeListener(subscription1);

A common pattern of utilization is to handle the subscription code in an idempotent method, like this:

var _subscription;

// The idempotent method
function _refresh()
{
    _appUnsubscribe();
    _appSubscribe();
}

function _appUnsubscribe()
{
    if (_subscription) 
        cometd.unsubscribe(_subscription);
    _subscription = null;
}

function _appSubscribe()
{
    _subscription = cometd.subscribe('/foo/bar', function() { ... });
}

The same of course applies also for addListener()/removeListener().

The point is that you have to be careful in your application: you have to remove your subscriptions, in order to avoid to leak functions, or to execute functions more than once (since you could erroneously bind the same callback twice).
Refer also to the Primer for a discussion about using idempotent methods.

How do subscribe() and unsubscribe() behave in case the Bayeux server is not reachable (due to network failures or because the server crashed) ?
In subscribe() the local listener is first added to the list of subscribers for that channel, then the server communication is attempted. If the communication fails, the server will not know that it has to send messages to this client and therefore on the client the local listener (although present) will never be invoked.
In unsubscribe(), the local listener is first removed from the list of subscribers for that channel, then the server communication is attempted. If the communication fails, the server will still send the message to the client but there will be no local listener to dispatch to.

Listeners/Subscribers Exception Handling

If a listener or subscriber function throws an exception (for example, calls a method on an undefined object, etc.), then the error message is logged (at level "debug").
However, there is a way to intercept these errors by defining the global listener exception handler, that is invoked every time a listener or subscriber throws an exception:

cometd.onListenerException = function(exception, subscriptionHandle, isListener, message)
{
    // Uh-oh, something went wrong, disable this listener/subscriber
    // Object "this" points to the CometD object
    if (isListener)
        this.removeListener(subscriptionHandle);
    else
        this.unsubscribe(subscriptionHandle);
}

It is be possible to send messages to the server from the listener exception handler.
If the listener exception handler itself throws an exception, this exception is logged at level "info" and the CometD implementation will not break.
Note that a similar mechanism exists for extensions, see here.

Wildcard Subscriptions

It is possible to subscribe to several channels at once using wildcards, like this:

cometd.subscribe("/chatrooms/*", function(message) { ... });

A single asterisk has the meaning of matching a single channel segment, so in the example above it will match channels /chatrooms/12 and /chatrooms/15, but not /chatrooms/12/upload.
To match multiple channel segments, use the double asterisk:

cometd.subscribe("/events/**", function(message) { ... });

With the double asterisk, the channels /events/stock/FOO and /events/forex/EUR will match, as well as /events/feed and /events/feed/2009/08/03.

The wildcard mechanism works also for listeners, so it is possible to listen to all meta channels like this:

cometd.addListener("/meta/*", function(message) { ... });

By default, subscriptions to the global wildcards /* and /** result in an error, but this behavior can be changed by specifying a custom security policy on the Bayeux server.

The wildcards can only be specified as last segment of the channel, so these are invalid subscriptions: /**/foo or /foo/*/bar.

Meta Channel List

These are the meta channels available in the JavaScript CometD implementation:

• /meta/handshake
• /meta/connect
• /meta/disconnect
• /meta/subscribe
• /meta/unsubscribe
• /meta/publish
• /meta/unsuccessful

Each meta channel is notified when the correspondent Bayeux message is handled by the JavaScript Cometd implementation.
The /meta/unsuccessful channel is notified in case of any failure.

By far the most interesting meta channel to subscribe to is /meta/connect, because it gives the status of the current connection with the Bayeux server. In combination with /meta/disconnect, it can be used, for example, to display a green "connected" icon or a red "disconnected" icon on the page, depending on the connection status with the Bayeux server.

This is a common pattern using the /meta/connect and /meta/disconnect channels:

var _connected = false;

cometd.addListener('/meta/connect', function(message)
{
    // if (cometd.getStatus() === 'disconnecting' || cometd.getStatus() === 'disconnected')
    if (cometd.isDisconnected()) // Available since 1.1.2
    {
        return;
    }
    var wasConnected = _connected;
    _connected = message.successful;
    if (!wasConnected && _connected)
    {
        // Reconnected
    }
    else if (wasConnected && !_connected)
    {
        // Disconnected
    }
});

cometd.addListener('/meta/disconnect', function(message)
{
    if (message.successful)
    {
        _connected = false;
    }
}

One small caveat with the /meta/connect channel is that /meta/connect is also used for polling the server.
Therefore, if a disconnect is issued during an active poll, the active poll is returned by the server and this triggers the /meta/connect listener.
The initial check on the status verifies that is not the case before executing the connection logic.

Another interesting usage of meta channels is when there is an authentication step during the handshake.
In this case the registration to the /meta/handshake channel can give details about, for example, authentication failures.

CometD JavaScript Publish

JavaScript CometD API: Publishing

The publish() method allow you to publish data onto a certain channel:

cometd.publish('/mychannel', { mydata: { foo: 'bar' } });

You cannot (and it makes no sense) to publish to a meta channel, and you can publish to a channel even if you are not subscribed to that channel.
However, you have to handshake before being able to publish.

As with other JavaScript CometD API, publish() involves a communication with the server and it is asynchronous: it returns immediately, well before the Bayeux server has received the message.

Note
Calling publish() does not mean that you have published the message when publish() returns.

If you have to publish several messages to different channels, you may want to use message batching.

CometD JavaScript Disconnection

JavaScript CometD API: Disconnecting

The JavaScript CometD implementation performs automatic reconnect in case of network or Bayeux server failures.
The reconnect parameters are described in the configuration section.

Short Network Failures

In case of temporary network failures, the client is notified through the /meta/connect channel (see this section about meta channels) with messages that have the successful field set to false (see also the archetypes in the primer as an example).
However, the Bayeux server may be able to keep the client's state, and when the network resumes the Bayeux server may behave as if nothing happened.
The client in this case just re-establishes the long poll, but any message published by the client during the network failure is not automatically re-sent (though it is possible to be notified, through the /meta/publish channel, of the failed publishes).

Long Network Failures or Server Failures

If the network failure is long enough, the Bayeux server times out the lost client, and deletes the state associated with it. The same happens when the Bayeux server crashes (except of course that the state of all clients is lost).
In this case, the reconnection mechanism on the client performs the following steps:

• a long poll is re-attempted, but the server rejects it with a 402::Unknown client error message
• a handshake is attempted, and the server normally accepts it and allocates a new client
• upon the successful re-handshake, a long poll is re-established

If you register with meta channels, be aware of these steps, since a reconnection may involve more than one message exchange with the server.

Disconnecting

Calling the JavaScript CometD API disconnect() result in a message being sent to the Bayeux server, so that it can cleanup any state associated with that client.
As with all methods that involve a communication with the Bayeux server, it is an asynchronous method: it returns immediately, well before the Bayeux server has received the disconnect request.
If the server cannot be reached (because it is down or because of network failures), the JavaScript CometD implementation will stop any reconnection attempt and cleanup any local state.
It is normally safe to ignore if the disconnect() call has been successful or not: the client is in any case disconnected, its local state cleaned up, and if the server has not been reached it will eventually time out the client and cleanup any server-side state for that client.

Tip
If you are debugging your application with Firebug, and you shutdown the server, you'll see in the Firebug console the attempts to reconnect.
To stop those attempts, simply type in the Firebug command line: dojox.cometd.disconnect() (for Dojo) or $.cometd.disconnect() (for jQuery).

CometD JavaScript Message Batching

JavaScript CometD API: Message Batching

It is often needed by an application to send several messages to possibly different channels.

One, naive, way of doing it is the following:

cometd.handshake();

// Warning: non-optimal code
cometd.publish('/channel1', { product: 'foo' });
cometd.publish('/channel2', { notificationType: 'all' });
cometd.publish('/channel3', { update: false });

You may think that the 3 publishes will leave the client one after the other, but that's actually not the case.
Remember that publish() is asynchronous (so it returns immediately), so the 3 publish() calls in sequence may return well before a single byte hits the network.

What happens is that the first publish() will be executed immediately, and the other 2 will be put in a queue, waiting for the first publish() to complete.
A publish() is complete when the server received it, the server sent back the meta response, and the client received the meta response for that publish.
When the first publish is completed, the second publish is executed and waited to complete. After that, finally the third publish() is executed.

Since CometD 1.1.2, a new configuration parameter called autoBatch can be set to true, allowing the implementation to automatically batch messages that have been queued up.
So, in the example above, the first publish() will be executed immediately, and when it completes, the implementation will batch the second and third publish() into one request to the server.
The autoBatch feature may be interesting for those systems where events received asynchronously and unpredictably, either at a fast rate or in bursts, end up in generating a publish() to the server: in such cases, using the batching API is not effective (as each event would generate only one publish()).
A bursts of events on the client will generate a bursts of publish() to the server, but this mechanism batches them automatically, making the communication more efficient.

This queueing mechanism is needed to avoid to queue a publish() behind a long poll. If not for this mechanism, the browser would receive 3 publish requests but only has 2 connections available, and one is already occupied by the long poll request. So the browser may decide to round robin the publish requests, so that the first publish goes on the second connection (remember that the first connection is already busy with the long poll request), which is free and it is actually sent over the network, schedule the second publish to the first connection (after the long poll returns), and schedule the third publish again to the second connection, after the first publish returns.
The result is that if you have a long poll timeout of 5 minutes, the second publish request may arrive to the server 5 minutes later than the first and the third publish request.

You can optimize the 3 publish using batching, which is a way to group messages together so that a single Bayeux message actually carries the 3 publish messages.

cometd.handshake();

cometd.batch(function()
{
    cometd.publish('/channel1', { product: 'foo' });
    cometd.publish('/channel2', { notificationType: 'all' });
    cometd.publish('/channel3', { update: false });
});

// Alternatively, but not recommended
cometd.startBatch()
cometd.publish('/channel1', { product: 'foo' });
cometd.publish('/channel2', { notificationType: 'all' });
cometd.publish('/channel3', { update: false });
cometd.endBatch()

Note how the 3 publish() calls are now within a function passed to batch().
Alternatively, but less recommended, you can surround the 3 publish() calls between startBatch() and endBatch().

Warning
Remember to call endBatch() after having called startBatch().
If you don't, for example because an exception is thrown in the middle of the batch, your messages will continue to queue up, and your application will not work as expected.

Function batch() already does the correct batching for you (also in case of errors), so it's the recommended way to do message batching.

When a batch is started, subsequent API calls are not sent to the server, but instead queued up, until the batch is ended.
The end of the batch packs up all the queued messages into one single Bayeux message and send it over the network to the Bayeux server.

Message batching allow an efficient utilization of the network, as instead of making 3 requests/responses cycles, batching makes only one request/response cycle.

Batches can be made up of different API calls:

var _subscription;

cometd.batch(function()
{
    cometd.unsubscribe(_subscription);
    _subscription = cometd.subscribe('/foo', function(message) { ... });
    cometd.publish('/bar', { ... });
});

Batched messages will be processed by the Bayeux server in the order they are sent.

If you still want to risk and use the startBatch() and endBatch() calls, remember that they must be done from the same context of execution; message batching has not been designed to span multiple user interactions.
So, for example, it would be wrong to start a batch in, say, functionA (triggered by user interaction), and ending the batch in functionB (also triggered by user interaction and not called by functionA).
Similarly, it would be wrong to start a batch in functionA and then schedule (using setTimeout()) the execution of functionB to end the batch.

CometD JavaScript Transports

JavaScript CometD Transports

The Bayeux specification defines two mandatory transports:

• long-polling
• callback-polling

The JavaScript CometD implementation implements exactly these two transports.

For most recent browsers (such as Firefox 3.5) it is possible to use the long-polling transport also for cross-domain Bayeux communication, see below the cross-domain mode.

The long-polling Transport

The long-polling transport is the default transport.
This transport is used when the communication with the Bayeux server happens on the same domain, and in the cross-domain mode (see below).
The data is sent to the server by means of a POST request with Content-Type text/json via a plain XMLHttpRequest call.

The callback-polling Transport

The callback-polling transport is the transport that is used when the communication with the Bayeux server happens on a different domain (when the cross-domain mode is not supported, see below for the cross-domain mode section).

It is well known that XMLHttpRequest calls have restrictions when the invocation is directed to a domain different from the one the script has been downloaded (but see below the cross-domain mode for an alternative solution).
To overcome XMLHttpRequest restrictions, this transport uses the JSONP script injection: instead of using XMLHttpRequest it injects a <script> element whose src attribute points to the Bayeux server.
The browser will notice the script element injection and performs a GET request to the specified source URL.
The Bayeux server is aware that this is a JSONP request and replies with a JavaScript function that is then executed by the browser (and that calls back into the JavaScript Cometd implementation).

There are three main drawbacks in using this transport:

• The transport is chattier.
  This is due to the fact that the browser executes the injected scripts sequentially, and until a script has been completely "downloaded", it cannot be executed.
  For example, imagine a communication that involves a script injection for the long poll, and a script injection for a message publish. The browser injects the long poll script, a request is made to the Bayeux server, but the Bayeux server holds the request waiting for server-side events (so the "script" is not "downloaded"). Then the browser injects the publish script, the request is made to the Bayeux server, which replies (so the "script is "downloaded"). However, the browser does not execute the second script, because it has not executed the first yet (since its "download" is not finished). In these conditions, the publish would be executed only after the long poll returns. To avoid this situation the Bayeux server, in case of callback-polling transport, resumes the client's long poll for every message that arrives from that client, and that's why the transport is chattier: the long poll returns more often.
• The message size is limited.
  This is necessary to support IE7, that has a 2083 character limit for GET requests.
• The reaction to failures is slower.
  This is due to the fact that if the script injection points to a URL that returns an error (for example the Bayeux server is down), this is silently ignored by the browser.

The cross-domain Mode

Firefox 3.5 introduced the capability for XMLHttpRequest calls to be performed towards a different domain (see here).

As of version 1.0.0.rc0, this is supported also in the JavaScript CometD implementation, with no configuration necessary on the client (if the browser supports XMLHttpRequest cross-domain calls, they will be used) and with a bit of configuration for the server. Refer to this document for the server configuration.

To use the cross-domain mode, you need:

• a cross-domain compliant browser (for example Firefox 3.5)
• a compliant server (for example Jetty configured with the CrossOriginFilter)

With this setup, even when the communication with the Bayeux server is cross-domain, the long-polling transport will be used, avoiding the drawbacks of the callback-polling transport.

CometD Server APIs

CometD Java Server Implementation

In order to run the CometD server implementation, you need to deploy a Java web application to a servlet container.

The web application needs to configure the CometD servlet (see here for configuration details) to interpret the Bayeux protocol.

Most of the times it is also needed to write one or more user-defined services that can act upon receiving messages on Bayeux channels.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.continuation.ContinuationCometdServlet</servlet-class>
        <init-param>
            <param-name>timeout</param-name>
            <param-value>60000</param-value>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

</web-app>

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.continuation.ContinuationCometdServlet</servlet-class>
        <init-param>
            <param-name>timeout</param-name>
            <param-value>60000</param-value>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <filter>
        <filter-name>cross-origin</filter-name>
        <filter-class>org.eclipse.jetty.servlets.CrossOriginFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>cross-origin</filter-name>
        <url-pattern>/cometd/*</url-pattern>
    </filter-mapping>

</web-app>

boolean canHandshake(Message message);

boolean canCreate(Client client, String channel, Message message);

boolean canSubscribe(Client client, String channel, Message message);

boolean canPublish(Client client, String channel, Message message);

public class EchoService extends BayeuxService                       (1)
{
    public EchoService(Bayeux bayeux)                                (2)
    {
        super(bayeux, "echo");                                       (3)
        subscribe("/echo", "processEcho");                           (4)
    }

    public void processEcho(Client remote, Map<String, Object> data) (5)
    {
        remote.deliver(getClient(), "/echo", data, null);            (6)
    }
}

// Obtains the remote client object and the message object
public void processEcho(Client remote, Message message)

// Obtains the remote client object and the message's data object
// (additional message information, such as the channel or the id is lost)
public void processEcho(Client remote, Map<String, Object> data)

// Obtains the remote client object, the channel name, the message object and the message id
public void processEcho(Client remote, String channelName, Message message, String messageId)

// Obtains the remote client object, the channel name, the message's data object and the message id
public void processEcho(Client remote, String channelName, Map<String, Object> data, String messageId)

public class BaseballTeamService extends BayeuxService
{
    public BaseballTeamService(Bayeux bayeux)
    {
        super(bayeux, "baseballTeam");
        subscribe("/baseball/team/*", "processBaseballTeam");
    }

    public void processBaseballTeam(Client remote, String channelName, Map<String, Object> data, String messageId)
    {
        // Upon receiving a message on channel /baseball/team/*, forward to channel /events/baseball/team/*
        getBayeux().getChannel("/events" + channelName, true).publish(getClient(), data, null);
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.continuation.ContinuationCometdServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <servlet>
        <servlet-name>configuration</servlet-name>
        <servlet-class>com.acme.cometd.ConfigurationServlet</servlet-class>
        <load-on-startup>2</load-on-startup>
    </servlet>

</web-app>

public class ConfigurationServlet extends GenericServlet
{
    public void init() throws ServletException
    {
        // Grab the Bayeux object
        Bayeux bayeux = (Bayeux)getServletContext().getAttribute(Bayeux.ATTRIBUTE);
        new EchoService(bayeux);
        // Create other services here

        // This is also the place where you can configure the Bayeux object
        // by adding extensions or specifying a SecurityPolicy
    }

    public void service(ServletRequest request, ServletResponse response) throws ServletException, IOException
    {
        throw new ServletException();
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.continuation.ContinuationCometdServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <listener>
        <listener-class>com.acme.cometd.BayeuxInitializer</listener-class>
    </listener>

</web-app>

public class BayeuxInitializer implements ServletContextAttributeListener
{
    public void attributeAdded(ServletContextAttributeEvent event)
    {
        if (Bayeux.ATTRIBUTE.equals(event.getName()))
        {
            // Grab the Bayeux object
            Bayeux bayeux = (Bayeux)event.getValue();
            new EchoService(bayeux);
            // Create other services here

            // This is also the place where you can configure the Bayeux object
            // by adding extensions or specifying a SecurityPolicy
        }
    }

    public void attributeRemoved(ServletContextAttributeEvent event)
    {
    }

    public void attributeReplaced(ServletContextAttributeEvent event)
    {
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.continuation.ContinuationCometdServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <listener>
        <listener-class>com.acme.cometd.spring.LateSpringBayeuxInitializer</listener-class>
    </listener>

</web-app>

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">

    <bean id="echoService" class="com.acme.cometd.EchoService">
        <constructor-arg><ref bean="bayeux" /></constructor-arg>
    </bean>

</beans>

public class LateSpringBayeuxInitializer implements ServletContextListener, ServletContextAttributeListener
{
    private volatile ContextLoader loader;

    public void contextInitialized(ServletContextEvent event)
    {
    }

    public void contextDestroyed(ServletContextEvent event)
    {
        ContextLoader loader = this.loader;
        if (loader != null)
            loader.closeWebApplicationContext(event.getServletContext());
    }

    public void attributeAdded(ServletContextAttributeEvent event)
    {
        if (Bayeux.ATTRIBUTE.equals(event.getName()))
        {
            Bayeux bayeux = (Bayeux) event.getValue();

            StaticListableBeanFactory factory = new StaticListableBeanFactory();
            factory.addBean("bayeux", bayeux);
            GenericApplicationContext bayeuxApplicationContext = new GenericApplicationContext(new DefaultListableBeanFactory(factory));
            bayeuxApplicationContext.refresh();

            loader = new BayeuxContextLoader(bayeuxApplicationContext);
            ApplicationContext applicationContext = loader.initWebApplicationContext(event.getServletContext());

            customizeBayeux(bayeux, applicationContext);
        }
    }

    public void attributeRemoved(ServletContextAttributeEvent event)
    {
    }

    public void attributeReplaced(ServletContextAttributeEvent event)
    {
    }

    protected void customizeBayeux(Bayeux bayeux, ApplicationContext applicationContext)
    {
    }

    private static class BayeuxContextLoader extends ContextLoader
    {
        private final ApplicationContext parentApplicationContext;

        public BayeuxContextLoader(ApplicationContext parentApplicationContext)
        {
            this.parentApplicationContext = parentApplicationContext;
        }

        @Override
        protected ApplicationContext loadParentContext(ServletContext servletContext) throws BeansException
        {
            return parentApplicationContext;
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.continuation.ContinuationCometdServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>
    <listener>
        <listener-class>com.acme.cometd.spring.LazySpringBayeuxInitializer</listener-class>
    </listener>

</web-app>

public class LazySpringBayeuxInitializer implements ServletContextAttributeListener
{
    public void attributeAdded(ServletContextAttributeEvent event)
    {
        if (Bayeux.ATTRIBUTE.equals(event.getName()))
        {
            Bayeux bayeux = (Bayeux) event.getValue();
            BayeuxHolder.setBayeux(bayeux);
        }
    }

    public void attributeRemoved(ServletContextAttributeEvent event)
    {
    }

    public void attributeReplaced(ServletContextAttributeEvent event)
    {
    }
}

public class BayeuxHolder
{
    private static volatile Bayeux bayeux;

    public static void setBayeux(Bayeux bayeux)
    {
        BayeuxHolder.bayeux = bayeux;
    }

    public static Bayeux getBayeux()
    {
        return bayeux;
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">

    <bean id="nonLazyService" class="com.acme..." />

    <bean id="bayeux" class="com.acme.cometd.spring.BayeuxHolder" factory-method="getBayeux" lazy-init="true" />

    <bean id="echoService" class="com.acme.cometd.EchoService" lazy-init="true">
        <constructor-arg><ref local="bayeux" /></constructor-arg>
        <constructor-arg><ref local="nonLazyService" /></constructor-arg>
    </bean>

</beans>

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.continuation.ContinuationCometdServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

</web-app>

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">

    <bean id="nonLazyService" class="com.acme..." />

    <bean id="bayeux" class="org.cometd.server.continuation.ContinuationBayeux">
        <property name="timeout" value="15000" />
    </bean>

    <bean class="org.springframework.web.context.support.ServletContextAttributeExporter">
        <property name="attributes">
            <map>
                <entry key="org.cometd.bayeux">
                    <ref local="bayeux" />
                </entry>
            </map>
        </property> 
    </bean>

    <bean id="echoService" class="com.acme.cometd.EchoService" lazy-init="true">
        <constructor-arg><ref local="bayeux" /></constructor-arg>
        <constructor-arg><ref local="nonLazyService" /></constructor-arg>
    </bean>

</beans>

public class ConfigurationServlet extends GenericServlet
{
    public void init() throws ServletException
    {
        // Grab Spring's ApplicationContent
        ApplicationContext context = WebApplicationContextUtils.getRequiredWebApplicationContext(getServletContext());

        // Trigger CometD service initialization
        context.getBean("echoService");
    }
    
    public void service(ServletRequest request, ServletResponse response) throws ServletException, IOException
    {
        throw new ServletException();
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.continuation.ContinuationCometdServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <servlet>
        <servlet-name>configuration</servlet-name>
        <servlet-class>com.acme.cometd.ConfigurationServlet</servlet-class>
        <load-on-startup>2</load-on-startup>
    </servlet>

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

</web-app>

Bayeux.setSecurityPolicy(SecurityPolicy policy)

Bayeux.getChannel(String channel, boolean create)

public class GameService extends BayeuxService
{
    ...
    public void processPlayerAction(Client remote, Message message)
    {
        // Forward the action to other players
        Channel channel = getBayeux().getChannel("/dungeons/blue_cavern", false);
        channel.publish(getClient(), message.getData(), null);
    }
    ...
}

Bayeux.getClient(String clientId)

public class ChatService extends BayeuxService
{
    ...
    public void processPrivateChat(Client remote, Map<String, Object> data)
    {
        // Extract the userId
        String friendUserId = (String)data.get("friendUserId");

        // Do not forget to check if that friendUserId is really your friend !

        // Map the database userId to a Bayeux clientId via some other service
        String friendClientId = this.userToClientMapper.get(friendUserId);
        
        Client remoteFriend = getBayeux().getClient(friendClientId);
        remoteFriend.deliver(getClient(), "/chat-room/1", data, null);
    }
    ...
}

Bayeux.getCurrentRequest()

Bayeux.addExtension(Extension)
Bayeux.removeExtension(Extension)

Channel.publish(Client local, Object data, String messageId)

public class StockService extends BayeuxService
{
    ...
    public void stockChanged(String stockName, double price)
    {
        Channel channel = getBayeux().getChannel("/nyse/stocks/" + stockName, false);
        if (channel != null)
        {
            Map<String, Object> data = new HashMap<String, Object>();
            data.put("price", price);
            channel.publish(null, message, null);
        }
    }
    ...
}

Channel.addDataFilter(DataFilter filter);
Channel.removeDataFilter(DataFilter filter);

Channel.isPersistent()
Channel.setPersistent(boolean persistent)

Channel.isLazy()
Channel.setLazy(boolean lazy)

Client.getId()

Client.addExtension(Extension extension)
Client.removeExtension(Extension extension)

Client.addListener(ClientListener listener)
Client.removeListener(ClientListener listener)

RemoveListener.removed(String clientId, boolean timeout)

MessageListener.deliver(Client from, Client to, Message message)

public class BatchingService extends BayeuxService
{
    ....
    public void processBatch(Client remote, Message message)
    {
        remote.startBatch();

        Map<String, Object> externalData = new HashMap<String, Object>();
        // Fill the external data
        remote.deliver(getClient(), "/external", externalData, null);

        Map<String, Object> emailData = new HashMap<String, Object>();
        // Fill the email data
        remote.deliver(getClient(), "/email", emailData, null);

        remote.endBatch();
    }
    ...
}

CometD Client APIs

CometD Java Client Implementation

The CometD client implementation can be used in any JSE^TM or JEE^TM application.

It is made of one main class, org.cometd.client.BayeuxClient, that depends on Jetty's asynchronous HttpClient.

Typical usages of the CometD Java client are:

• As the transport for a rich thick Java UI (for example, Swing) to communicate to a Bayeux Server (also via firewalls)
• As a load generator to simulate thousands of CometD clients, like for example org.cometd.client.BayeuxLoadGenerator

A BayeuxClient also implements the org.cometd.Client interface, so all information given in the Client section regarding extensions and listeners is valid also for BayeuxClient.
Furthermore, the CometD Java Client API is very similar to the CometD JavaScript Client API, so reading that section may give you a better understanding.

The following sections will go in detail about the JavaScript Bayeux APIs and their implementation secrets.

BayeuxClient.start()

// Create (and eventually setup) Jetty's HttpClient
HttpClient httpClient = new HttpClient();
// Here setup Jetty's HttpClient, for example:
// httpClient.setMaxConnectionsPerAddress(2);
httpClient.start();

BayeuxClient client = new BayeuxClient(httpClient, "http://localhost:8080/cometd");
// Here setup the BayeuxClient, for example:
// client.addListener(new MessageListener() { ... });
client.start();

HttpClient httpClient = ...
BayeuxClient client = new BayeuxClient(httpClient, "http://localhost:8080/cometd");
client.addListener(new MessageListener() 
{ 
    public void deliver(Client from, Client to, Message message)
    {
        if (Bayeux.META_HANDSHAKE.equals(message.getChannel())
        {
            Boolean successful = message.get(Bayeux.SUCCESSFUL_FIELD);
            if (successful != null && successful)
            {
                // Here handshake is successful
            }
        }
    }
});
client.start();

public class Example 
{
    private static final String CHANNEL = "/foo";
    private final MessageListener fooListener = new FooListener();

    public void attach()
    {
        HttpClient httpClient = ...
        BayeuxClient client = new BayeuxClient(httpClient, "http://localhost:8080/cometd");
        client.start();

        client.addListener(fooListener);
        client.subscribe(CHANNEL);
    }

    private static class FooListener implements MessageListener
    {
        public void deliver(Client from, Client to, Message message)
        {
            if (CHANNEL.equals(message.getChannel())
            {
                // Here we received a message on the channel
            }
        }
    }
}

public class Example 
{
    ...
    public void detach()
    {
        client.removeListener(fooListener);
        client.unsubscribe(CHANNEL);
    }
}

BayeuxClient.publish(String channel, Object data, String messageId)

HttpClient httpClient = ...
BayeuxClient client = new BayeuxClient(httpClient, "http://localhost:8080/cometd");
client.start();

Map<String, Object> data = new HashMap<String, Object>();
// Fill in the data
client.publish("/game/table/1", data, null);

HttpClient httpClient = ...
BayeuxClient client = new BayeuxClient(httpClient, "http://localhost:8080/cometd");
client.start();

client.startBatch();
try
{
    Map<String, Object> data = new HashMap<String, Object>();
    // Fill in the data map object
    client.publish("/game/table/1", data, null);

    Map<String, Object> extra = new HashMap<String, Object>();
    // Fill in the extra map object
    client.publish("/extra/1", data, null);
}
finally
{
    client.endBatch();
}

BayeuxClient.disconnect();

CometD Acknowledge Extension

CometD Acknowledge Extension

The acknowledged messages extension provides reliable ordered messaging to the Bayeux protocol.
This extension requires both a client-side extension and a server-side extension. The server-side extension is available in Java.

Enabling the Server-side Extension

To enable support for acknowledged messages, the extension must be added to the org.cometd.Bayeux instance during initialization:

bayeux.addExtension(new org.cometd.server.ext.AcknowledgedMessagesExtension());

The AcknowledgedMessageExtension is a per-server extension that monitors handshakes from new clients, looking for clients that also support the acknowledged message extension and then adds the AcknowledgedMessagesClientExtension to each client during the handshake.

Once added to a client, the AcknowledgedMessagesClientExtension prevents messages being delivered on any request other than a long poll request.
This prevents the possibility of out of order delivery.
The extension also maintains a list of non-acknowledged messages and intercepts the traffic on the /meta/connect channel to insert and check acknowledge IDs.

Enabling the Client-side Extension

The client side extension binding for Dojo is provided by dojox/cometd/ack.js and it is sufficient to use Dojo's dojo.require mechanism:

dojo.require("dojox.cometd.ack");

The client side extension binding for jQuery is provided by the file jquery.cometd-ack.js. This file must be included in the HTML page via the <script> tag:

<script type="text/javascript" src="AckExtension.js"></script>
<script type="text/javascript" src="jquery.cometd-ack.js"></script>

In both Dojo and jQuery extension bindings, the extension is registered on the default cometd object under the name "ack".

Furthermore, the extension may be programmatically disabled/enabled before initialization by setting the ackEnabled boolean field on the cometd object:

// Disables the ack extension during handshake
cometd.ackEnabled = false;
cometd.init(cometdURL);

Acknowledge Extension Details

In order to enable message acknowledgement, both client and server must indicate that they support message acknowledgement.
This is negotiated during handshake. On handshake, the client sends {"ext":{"ack": "true"}} to indicate that it supports message acknowledgement.
If the server also supports message acknowledgment, it likewise replies with {"ext":{"ack": "true"}}.

The extension does not insert ack IDs to every message, as this would impose a significant burden on the server for messages sent to multiple clients (which would need to be reserialized to json for each client). Instead the ack ID is inserted in the ext field of the /meta/connect messages that are associated with message delivery. Each /meta/connect request contains the ack ID of the last received ack response: "ext":{"ack": 42}. Similarly, each /meta/connect response contains an ext ack ID that uniquely identifies the batch of responses sent.

If a /meta/connect message is received with an ack ID lower that any unacknowledged messages held by the extension, then these messages are requeued prior to any more recently queued messages and the /meta/connect response sent with a new ack ID.

Demo

There is an example of acknowledged messages in the Dojo chat demo that comes bundled with the Cometd distribution.
The example can also be run by building the Cometd project.

To run the demo, follow these steps:

$ cd cometd-demo
$ mvn jetty:run

Then point your browser to http://localhost:8080/dojo-examples/chat/ and make sure to check "Enable reliable messaging".

Use two different browsers instances to begin a chat session, then briefly disconnect one browser from the network (you can do this by setting the "work offline" feature).
While one browser is disconnected, type some chat in the other browser and this will be received when the disconnected browser is reconnected to the network.

Note that if the disconnected browser is disconnected for in excess of maxInterval (default 10s), then the client will be timed out and the unacknowledged queue discarded.

CometD Timestamp Extension

CometD Timestamp Extension

The timestamp extension add a timestamp to the message object, for every message sent by the client and/or server.
It is a non standard extension because it does not add the additional fields to the ext field, but to the message object itself.
This extension requires both a client-side extension and a server-side extension. The server-side extension is available in Java.

Enabling the Server-side Extension

To enable support for timestamped messages, the extension must be added to the org.cometd.Bayeux instance during initialization:

bayeux.addExtension(new org.cometd.server.ext.TimestampExtension());

Enabling the Client-side Extension

The client side extension binding for Dojo is provided by dojox/cometd/ack.js and it is sufficient to use Dojo's dojo.require mechanism:

dojo.require("dojox.cometd.timestamp");

The client side extension binding for jQuery is provided by the file jquery.cometd-timestamp.js. This file must be included in the HTML page via the <script> tag:

<script type="text/javascript" src="jquery.cometd-timestamp.js"></script>

In both Dojo and jQuery extension bindings, the extension is registered on the default cometd object under the name "timestamp".

CometD Timesync Extension

CometD Timesync Extension

The timesync extension uses the messages exchanged between a client and a server to calculate the offset between the client's clock and the server's clock.
This is independent from the timestamp extension, which uses the local clock for all timestamps.
This extension requires both a client-side extension and a server-side extension. The server-side extension is available in Java.

Enabling the Server-side Extension

To enable support for acknowledged messages, the extension must be added to the org.cometd.Bayeux instance during initialization:

bayeux.addExtension(new org.cometd.server.ext.TimesyncExtension());

Enabling the Client-side Extension

The client side extension binding for Dojo is provided by dojox/cometd/timesync.js and it is sufficient to use Dojo's dojo.require mechanism:

dojo.require("dojox.cometd.timesync");

The client side extension binding for jQuery is provided by the file jquery.cometd-timesync.js. This file must be included in the HTML page via the <script> tag:

<script type="text/javascript" src="jquery.cometd-timesync.js"></script>

In both Dojo and jQuery extension bindings, the extension is registered on the default cometd object under the name "timesync".

Timesync Extension Details

The timesync extension allows the client and server to exchange time information on every handshake and connect message so that the client may calculate an approximate offset from it's own clock epoch to that of the server.
The algorithm used is very similar to the NTP algorithm.

With each handshake or connect, the extension sends timestamps within the ext field like:

{ext:{timesync:{tc:12345567890,l:23,o:4567},...},...}

where:

• tc is the client timestamp in ms since 1970 of when the message was sent
• l is the network lag that the client has calculated
• o is the clock offset that the client has calculated

The accuracy of the offset and lag may be calculated with tc-now-l-o, which should be zero if the calculated offset and lag are perfectly accurate.

A Bayeux server that supports timesync, should respond only if the measured accuracy value is greater than accuracy target.
The response will be an ext field like:

{ext:{timesync:{tc:12345567890,ts:1234567900,p:123,a:3},...},...}

where:

• tc is the client timestamp of when the message was sent
• ts is the server timestamp of when the message was received
• p is the poll duration in ms - ie the time the server took before sending the response
• a is the measured accuracy of the calculated offset and lag sent by the client

On receipt of the response, the client is able to use current time to determine the total trip time, from which p is subtracted to determine an approximate two way network traversal time. Thus:

• lag = (now-tc-p)/2
• offset = ts-tc-lag

In order to smooth over any transient fluctuations, the extension keeps a sliding average of the offsets received.
By default this is over 10 messages, but this can be changed by passing a configuration object during the creation of the extension:

// Unregister the default timesync extension
cometd.unregisterExtension('timesync');

// Re-register with different configuration
cometd.registerExtension('timesync', new org.cometd.TimeSyncExtension({ maxSamples: 20 }));

The client-side timesync extension also exposes several methods to deal with the result of the time synchronization:

• getNetworkLag(), to obtain the calculated network latency between client and server
• getTimeOffset(), to obtain the offset between the client's clock and the server's clock in ms
• getServerTime(), to obtain the server's time
• setTimeout(), to schedule a function to be executed at a certain server time

Reload

Reload Extension

The reload extension allows a page to be loaded (or the same page to be reloaded) without having to re-handshake in the new (or reloaded) page, therefore resuming the existing CometD connection.
This extension requires only the client-side extension.

Enabling the Client-side Extension

The client side extension binding for Dojo is provided by dojox/cometd/reload.js and it is sufficient to use Dojo's dojo.require mechanism:

dojo.require("dojox.cometd.reload");

The client side extension binding for jQuery is provided by the file jquery.cometd-reload.js. This file must be included in the HTML page via the <script> tag, along with the jQuery cookie plugin and the reload extension implementation:

<script type="text/javascript" src="jquery.cookie.js"></script>
<script type="text/javascript" src="ReloadExtension.js"></script>
<script type="text/javascript" src="jquery.cometd-reload.js"></script>

In both Dojo and jQuery extension bindings, the extension is registered on the default cometd object under the name "reload".

Reload Extension Details

The reload extension allows a page to be reloaded and an existing CometD connection resumed by the reloaded page.

To activate the reload extension, the page must call cometd.reload() just before the page is reloaded (for example, after a link is clicked or on the page unload event).
This saves a short lived cookie with the connection details.
The new page still needs to call subscribe to the channels it is interested in to register the callbacks, since the client state has been completely reset due to the reload.

An example simple usage is:

<html>
    <head>
        <script type="text/javascript" src="dojo/dojo.js"></script>
        <script type="text/javascript">
            dojo.require("dojox.cometd");
            dojo.require("dojox.cometd.reload");

            dojox.cometd.init({ url: "/context/cometd", logLevel: "info" });
            dojox.cometd.subscribe("/some/channel", function() { ... });
            dojox.cometd.subscribe("/some/other/channel", function() { ... });
            
            // On page unload, call dojox.cometd.reload()
            dojo.addOnUnload(dojox.cometd, "reload");
        </script>
    </head>
    <body>
    ...
    </body>
</html>

Primer

Preparation

Working on a project that uses the CometD API requires some preparation, especially regarding tools, that can save you a huge amount of time.
One tool that should not be missing is Firebug (if you're using Firefox for development), or the equivalent for Internet Explorer 8, called Developer Tools.

The CometD project is built using Maven, and using Maven to build also your application is a natural fit.
The Primer will use Maven as the basis for the setup, build and run of your application, but the same concepts can be applied by other build tools as well.

Warning
If you are working in the Windows OS, avoid at all costs to use a path that contains spaces, such as "C:\Document And Settings\", as your base path.
Use a base path such as "C:\CometD\" instead.

Project Setup

The project can be setup in 2 ways, using the Maven Way or the Non-Maven Way.
For both, you can follow the detailed explanation of how some of the files of the project have been setup.

The Maven Way

Setting up a project based on the CometD libraries using Maven is very simple, and leverages the Maven archetypes, which create the skeleton of the project, in a style very similar to Rails scaffolding.
Issue the following command from a directory that does not contain a pom.xml file (otherwise you will get a Maven error), for example an empty directory:

$ mvn archetype:generate -DarchetypeCatalog=http://cometd.org
...
Choose archetype:
1: local -> cometd-archetype-dojo-jetty6 (CometD :: Archetypes :: Dojo and Jetty6)
2: local -> cometd-archetype-jquery-jetty6 (CometD :: Archetypes :: jQuery and Jetty6)
3: local -> cometd-archetype-dojo-jetty7 (CometD :: Archetypes :: Dojo and Jetty7)
4: local -> cometd-archetype-jquery-jetty7 (CometD :: Archetypes :: jQuery and Jetty7)
Choose a number:  (1/2/3/4): 

As you can see, there are 4 archetypes available, that build a skeleton application using the Dojo or jQuery JavaScript toolkits, both with the choice of using Jetty6 or Jetty7.
Let's choose Dojo with Jetty7, so choice number 3.
The archetype generation will ask few more questions and generate the application skeleton for you, for example:

Choose a number:  (1/2/3/4): 3
Define value for groupId: : org.cometd.primers
Define value for artifactId: : dojo-jetty7-primer
Define value for version:  1.0-SNAPSHOT: : 
Define value for package:  org.cometd.primers: : 
Confirm properties configuration:
jettyVersion: 7.0.1.v20091125
cometdVersion: 1.0.0
groupId: org.cometd.primers
artifactId: dojo-jetty7-primer
version: 1.0-SNAPSHOT
package: org.cometd.primers
 Y: : 
[INFO] BUILD SUCCESSFUL

Then:

$ cd dojo-jetty7-primer/

The skeleton project has now been created as follows:

$ tree
.
|-- pom.xml
`-- src
    `-- main
        |-- java
        |   `-- org
        |       `-- cometd
        |           `-- primers
        |               |-- BayeuxInitializer.java
        |               `-- HelloService.java
        `-- webapp
            |-- WEB-INF
            |   `-- web.xml
            |-- application.js
            `-- index.jsp

The skeleton project is ready to be run with the following command:

$ mvn install jetty:run
...

Now point your browser at http://localhost:8080/dojo-jetty7-primer, and you should see this message:

CometD Connection Succeeded
Server Says: Hello, World

That's it. You have already written your first CometD application :-)

The Non-Maven Way

The first step is to configure your favorite JavaScript toolkit, in our example Dojo, that must be served by the web container.
Using the Maven Way, this is obtained automatically by overlaying the CometD Dojo bindings war file, cometd-javascript-dojo-[version].war, but here must be done manually.
The cometd-javascript-dojo-[version].war is located in the cometd-javascript/dojo/target directory of the CometD distribution.

• Unpack the Dojo toolkit to a directory.
• Delete the dojox/cometd directory provided by Dojo and replace it with the one contained in the cometd-javascript-dojo-[version].war.
  The content of the dojox/cometd directory should be the following:

  dojox/cometd
  |-- ack.js
  |-- reload.js
  |-- timestamp.js
  `-- timesync.js
  

• Delete the file dojox/cometd.js provided by Dojo and replace it with the one at the same path in the cometd-javascript-dojo-[version].war.
• Add the org directory from the cometd-javascript-dojo-[version].war, and all its content, at the same level of the dojox directory.

The final content, equivalent to that produced by the Maven way, should be like this, for CometD 1:

.
|-- dijit
|-- dojo
|-- dojox
|   |-- cometd
|   |   |-- ack.js
|   |   |-- reload.js
|   |   |-- timestamp.js
|   |   `-- timesync.js
|   `-- cometd.js
|-- org
|   |-- cometd
|   |   |-- AckExtension.js
|   |   |-- ReloadExtension.js
|   |   |-- TimeStampExtension.js
|   |   `-- TimeSyncExtension.js
|   `-- cometd.js
|-- WEB-INF
|   |-- classes
|   |   `-- org
|   |       `-- cometd
|   |           `-- primers
|   |               |-- BayeuxInitializer.class
|   |               `-- HelloService.class
|   |-- lib
|   |   |-- cometd-api-[version].jar
|   |   |-- cometd-java-server-[version].jar
|   |   |-- jetty-continuation-[version].jar
|   |   |-- jetty-servlets-[version].jar
|   |   `-- jetty-util-[version].jar
|   `-- web.xml
|-- application.js
`-- index.jsp

and like this for CometD 2:

.
├── dijit
├── dojo
├── dojox
│   ├── cometd
│   │   ├── ack.js
│   │   ├── reload.js
│   │   ├── timestamp.js
│   │   └── timesync.js
│   ├── cometd.js
├── org
│   ├── cometd
│   │   ├── AckExtension.js
│   │   ├── ReloadExtension.js
│   │   ├── TimeStampExtension.js
│   │   └── TimeSyncExtension.js
│   └── cometd.js
├── WEB-INF
│   ├── classes
│   │   └── org
│   │       └── cometd
│   │           └── primers
│   │               ├── BayeuxInitializer.class
│   │               └── HelloService.class
│   ├── lib
│   │   ├── bayeux-api-[version].jar
│   │   ├── cometd-java-common-[version].jar
│   │   ├── cometd-java-server-[version].jar
│   │   ├── jetty-continuation-[version].jar
│   │   ├── jetty-jmx-[version].jar
│   │   ├── jetty-servlets-[version].jar
│   │   └── jetty-util-[version].jar
│   └── web.xml
├── application.js
└── index.jsp

The org directory contains the new shared CometD implementation and the shared extensions, while the correspondent files in the dojox directory are the Dojo bindings. Other bindings exist for the jQuery toolkit, but the shared CometD implementation is the same.

The second step is to configure the server side. If you use Java, this means that you have to setup the CometD servlet that respond to the Bayeux messages.
The details of the server side configuration and service development are explained here for CometD 1 and here for CometD 2.

The last step is to write a JSP (or HTML) file that downloads the JavaScript dependencies and the JavaScript application, as explained in the following section.

Setup Details

The JSP file, index.jsp, contains the reference to the JavaScript toolkit dependencies and to the JavaScript application file:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
    <script type="text/javascript" src="${pageContext.request.contextPath}/dojo/dojo.js.uncompressed.js"></script>
    <script type="text/javascript" src="application.js"></script>
    <script type="text/javascript">
        var config = {
            contextPath: '${pageContext.request.contextPath}'
        };
    </script>
</head>
<body>
    ...
</body>
</html>

It also configures a JavaScript configuration object, config, with variables that may be needed by the JavaScript application. This is totally optional.

The JavaScript application, contained in the application.js file, configures the cometd object and starts the application.
Here is a sketch of what the archetypes provide:

dojo.require("dojox.cometd");

dojo.addOnLoad(function()
{
    var _connected = false;

    function _connectionSucceeded()
    {
        dojo.byId('body').innerHTML = 'CometD Connection Succeeded';
    }

    function _connectionBroken()
    {
        dojo.byId('body').innerHTML = 'CometD Connection Broken';
    }

    function _metaConnect(message)
    {
        var wasConnected = _connected;
        _connected = message.successful === true;
        if (!wasConnected && _connected)
        {
            _connectionSucceeded();
        }
        else if (wasConnected && !_connected)
        {
            _connectionBroken();
        }
    }

    var cometd = dojox.cometd;

    // Disconnect when the page unloads
    dojo.addOnUnload(function()
    {
        cometd.disconnect();
    });

    var cometURL = location.protocol + "//" + location.host + config.contextPath + "/cometd";
    cometd.configure({
        url: cometURL,
        logLevel: 'debug'
    });

    cometd.addListener('/meta/connect', _metaConnect);

    cometd.handshake();
});

Note the following:

• The use of dojo.addOnLoad() to wait for the document to load up before executing the cometd object initialization.
• The use of dojo.addOnUnload() to disconnect when the page is refreshed or closed.
• The use of the function _metaConnect() to detect when the Bayeux communication has been successfully established (or re-established). This is totally optional, but highly recommended.
  Be warned that the use of the _metaConnect() along with the _connected status variable can result in your code (that in this simple example sets the innerHTML property) to be called more than once if, for example, you experience temporary network failures or if the server restarts.

  Therefore is it very important that the code that you put in the _connectionSucceeded() function must be idempotent.
  In other words, you have to make sure that if the _connectionSucceeded() function is called more than one time, it will behave exactly as if it is called exactly once.

Authentication

CometD Authentication

Authentication is a complex task, and can be achieved in many ways, and most often each way is peculiar to a particular project.

Below you can find few ideas on how you can perform authentication.

Authentication via XMLHttpRequest

Authentication information could be passed by the CometD JavaScript client to the server via XMLHttpRequest.open(method, url, async, user, password), but this is currently not supported.
The main reason is that it will not work in the cross domain case, since XMLHttpRequest does not support cross domain authentication.

Authentication via HTTP request headers

Authentication information can be passed by the CometD JavaScript client to the server via HTTP request headers in each CometD request, and verified by the server (for example via a servlet filter).
It's possible to specify such request headers using the requestHeaders configuration parameter as specified here.

Authentication via Bayeux SecurityPolicy and Extension

This method is more complicated than previous ones, but gives more flexibility.
Authentication information can be passed by the CometD JavaScript client to the server during Bayeux handshake.
The CometD JavaScript client handshake() and init() methods take an extra object that's merged with the handshake message, for example:

cometd.configure({
    url: 'http://localhost:8080/myapp/cometd'
});

// Register a listener to be notified of authentication success or failure
cometd.addListener('/meta/handshake', function(message) 
{
    var auth = message.ext && message.ext.authentication;
    if (auth && auth.failed === true)
    {
        // Authentication failed, tell the user
        window.alert('Authentication failed!');
    }
});

var username = 'foo';
var password = 'bar';

// Send the authentication information
cometd.handshake({
    ext: {
        authentication: {
            user: username,
            credentials: password
        }
    }
});

The Bayeux specification suggests that authentication information is stored in the ext field of the handshake message (see here).

On the server, we need to configure the Bayeux object with a org.cometd.SecurityPolicy (to deny the handshake to clients that provide bad authentication information) and with an org.cometd.Extension to process the successful authentication.

It is possible to configure the Bayeux object using the same methods used to integrate Bayeux services (see also the Spring Integration).
For example, using a configuration servlet:

public class BayeuxInitializer extends GenericServlet
{
    @Override
    public void init() throws ServletException
    {
        Bayeux bayeux = (Bayeux)getServletContext().getAttribute(Bayeux.ATTRIBUTE);
        BayeuxAuthenticator authenticator = new BayeuxAuthenticator();
        bayeux.setSecurityPolicy(authenticator);
        bayeux.addExtension(authenticator);
    }

    @Override
    public void service(ServletRequest req, ServletResponse res) throws ServletException, IOException
    {
        throw new ServletException();
    }
}

Below you can find the code for the BayeuxAuthenticator class:

public class BayeuxAuthenticator extends AbstractBayeux.DefaultPolicy implements Extension, RemoveListener (1)
{
    @Override
    public boolean canHandshake(Message message)                                                           (2)
    {
        Map<String, Object> ext = message.getExt(false);
        if (ext == null)
            return false;

        // Be sure the client does not cheat us
        ext.remove("authenticationData");

        Map<String, Object> authentication = (Map<String, Object>)ext.get("authentication");
        if (authentication == null)
            return false;

        Object authenticationData = verify(authentication);                                                (3)
        if (authenticationData == null)
            return false;

        // Store the authentication result in the message for later processing
        ext.put("authenticationData", authenticationData);                                                 (4)

        return true;
    }

    public Message sendMeta(Client remote, Message responseMessage)                                        (5)
    {
        if (Bayeux.META_HANDSHAKE.equals(responseMessage.getChannel()))                                    (6)
        {
            Message requestMessage = responseMessage.getAssociated();                                      (7)

            Map<String, Object> requestExt = requestMessage.getExt(false);
            Object authenticationData = requestExt.get("authenticationData");
            if (authenticationData != null)
            {
                // Authentication successful

                // Link authentication data to the remote client                                           (8)

                // Be notified when the remote client disappears
                remote.addListener(this);                                                                  (9)
            }
            else
            {
                // Authentication failed
                
                // Add extra fields to the response                                                        (10)
                Map<String, Object> responseExt = responseMessage.getExt(true);
                Map<String, Object> authentication = new HashMap<String, Object>();
                responseExt.put("authentication", authentication);
                authentication.put("failed", true);

                // Tell the client to stop any further attempt to handshake                                (11)
                Map<String, Object> advice = new HashMap<String, Object>();
                advice.put(Bayeux.RECONNECT_FIELD, Bayeux.NONE_RESPONSE);
                responseMessage.put(Bayeux.ADVICE_FIELD, advice);
            }
        }
        return responseMessage;
    }

    public void removed(String clientId, boolean expired)                                                  (12)
    {
        // Unlink authentication data from the remote client                                               (13)
    }
    
    // Other methods omitted
}

Note that:

• in (1) we make BayeuxAuthenticator be a SecurityPolicy, an Extension and a RemoveListener, since the code is really tied together
• in (2) we override canHandshake() (a SecurityPolicy method), where we extract the authentication information from the message sent by the client
• in (3) we verify the authentication information sent by the client, and obtain back server-side authentication data that we can later associate with the remote client
• in (4) we store the server-side authentication data in the message to be processed later in (8)
• in (5) we implement sendMeta() (an Extension method), which is called just after canHandshake() and just before sending the handshake response to the remote client
• in (6) we perform our authentication logic only for handshake messages (i.e. messages that are sent on the handshake meta channel)
• in (7) we retrieve the request message sent by the client from the response message that has been passed to sendMeta(), and we further retrieve the server-side authentication data set in (4)
• in (8) we link the server-side authentication data to the remote client object
• in (9) we register to be notified when the remote client disappears (which we will react to in (12))
• in (10) we may want to add extra fields to the response message to detail why the authentication failed to the client
• in (11) we set a Bayeux advice that tells the Bayeux client implementation to not retry to handshake automatically (since retrying automatically will resend the same credentials, and the authentication will fail again)
• in (12) we implement removed() (a RemoveListener method), which is called when the remote client disappears, either because it disconnected or because it crashed
• in (13) we unlink the server-side authentication data from the remote client object, the operation opposite to (8)

The reason for all this machinery is that at the moment of the invocation of canHandshake() the org.cometd.Client (server-side) object representing the remote client has not been created yet; it is only created if the handshake is allowed.

The most important steps are the number 8 and the number 13, where the server-side authentication data is linked/unlinked to/from the org.cometd.Client object.
This linking depends very much from project to project.
It may link a database primary key (of the row representing the user account) with the remote client id (obtained with remote.getId()), and/or viceversa, or it may link OAUTH tokens with the remote client id, etc.

Each Bayeux message always come with a client id, which can be thought as similar to the Http session id.
In the same way it is widespread practice to put the server-side authentication data in the HttpSession object (identified by the Http session id), in CometD web applications we can put server-side authentication data in a data structure where it can be later retrieved by Bayeux client id.
This data structure representing the "session" of a Bayeux client is not (yet) offered by the CometD API, and must be therefore coded by the CometD web application developer.

The Bayeux client ids are long, randomly generated numbers, exactly like Http session ids, and offer the same level security offered by a Http session id.
If an attacker manages to sniff a Bayeux client id, it can impersonate that Bayeux Client exactly in the same way it can sniff a Http session id and impersonate that Http session.
And, of course, the same solutions to this problem used to secure Http applications can be used to secure CometD web applications.

Load Testing

Load Testing

Please look at CometD 2 Load Testing.

CometD 2 JavaScript Configuration

JavaScript CometD 2 API: Configuration and Initialization

After you have setup your skeleton project following the Primer, you may want to fully understand how to customize and configure the parameters that govern the behavior of the Cometd implementation.

The whole API is available through a single object prototype named org.cometd.Cometd.
The Dojo toolkit has one instance of this object available under the name dojox.cometd, while for jQuery it is available under the name $.cometd.

This default cometd object has been instantiated and configured with the default values and it has not started any Bayeux communication yet.
Before it can start any Bayeux communication it needs a mandatory parameter: the URL of the Bayeux server.

There are 2 ways of passing this parameter:

// First style: URL string
cometd.configure('http://localhost:8080/cometd');

// Second style: configuration object
cometd.configure({
    url: 'http://localhost:8080/cometd'
});

The first way is a shorthand for the second way.
However, the second way allows to pass other configuration parameters, currently:

 
After you have configured the cometd object, it has not started the Bayeux communication yet. To start the Bayeux communication, you need to call handshake(), see the next section.

Previous users of the JavaScript CometD implementation were used to call a method called init(). This method still exists, and it is a shorthand for calling configure() followed by handshake().
Follow the advices in the next section as they apply as well to init().

CometD 2 JavaScript Handshake

JavaScript CometD 2 API: Handshake

The call to handshake() (or to init()) is the one that initiates the Bayeux communication with the Bayeux server.

The Bayeux handshake performs 2 tasks:

• the client and the server negotiate the type of transport to use
• once the transport is negotiated successfully, the server informs the client with the detailed timings of the requests

As with several methods of the JavaScript CometD API, it is an asynchronous method: it returns immediately, well before the Bayeux handshake steps have completed.

Note
Calling handshake() does not mean that you have completed the handshake with the server when handshake() returns.

The handshake may fail for several reasons:

• you mistyped the server URL
• the transport could not be negotiated successfully
• the server denied the handshake (for example, the authentication credentials were wrong)
• the server crashed
• there was a network failure

Therefore it is not a good idea to write this code:

// Configure and handshake
cometd.init('http://localhost:8080/cometd');

// Publish to a channel
cometd.publish('/foo', { foo: 'bar' });

It is not a good idea, because there is no guarantee that the call to publish() (which we cover in a later section) can actually succeed in contacting the Bayeux server.
Since the API is asynchronous, you have no way of knowing synchronously (i.e. by having handshake() return an error code or by throwing an exception) that the handshake failed.
Even if the handshake succeeds, you may still be "disconnected" from the Bayeux server, for example because the server crashed just after the successful handshake.

Fortunately there is a way to be notified about the details of the Bayeux protocol message exchange: by adding listeners to special channels (called meta channels).
This is explained in the section about subscriptions.

CometD 2 JavaScript Subscription

JavaScript CometD 2 API: Subscribing and Unsubscribing

Channels

The Bayeux specification defines the concept of a channel: it is like a messaging topic where interested parties can subscribe to receive information published onto the channel.
There are 3 types of channels:

• meta channels
• service channels
• normal channels

A channel looks like a directory path such as /meta/connect (a meta channel; all meta channels starts with the prefix /meta/), or /service/chat (a service channel; all service channels starts with the prefix /service/) or /foo/bar (a normal channel).

Meta Channels

Meta channels are created by the Bayeux protocol itself.
It is not possible to subscribe to meta channels: the server will reply with an error message. However, it is possible to listen to meta channels (see below the difference between subscribing and listening).
It makes no sense to publish messages to meta channels: only the Bayeux protocol implementation creates and sends messages on meta channels.
Meta channels are useful on the client to listen for error messages like handshake errors (for example because the client did not provide the correct credentials) or network errors (for example to know when the connection with the server has broken or when it has been re-established).

Service Channels

Service channels are used in the case of request/response style of communication between client and server (as opposed to the publish/subscribe style of communication or normal channels).
While subscribing to service channels yields no errors, this is a no-operation for the server: the server ignores the subscription request.
It is possible to publish to service channels, with the semantic of a communication between a specific client (the one that's publishing the message on the service channel) and the server.
Service channels are useful to implement, for example, private chat messages: in a chat with userA, userB and userC, userA can publish a private message to userC (without userB knowing about) using service channels.

Normal Channels

Normal channels have the semantic of a messaging topic and are used in the case of publish/subscribe style of communication.
Usually, it is possible to subscribe to normal channels and to publish to normal channels; this can only be forbidden using a security policy on the Bayeux server or by using authorizers.
Normal channels are useful to implement broadcasting of messages to all subscribed clients, for example in case of a stock price change.

Subscribers versus Listeners

The JavaScript CometD API has 2 APIs to work with channel subscriptions:

• addListener() and the correspondent removeListener()
• subscribe() and the correspondent unsubscribe()

The addListener() method:

• must be used to listen to meta channel messages
• may be used to listen to service channel messages (you may also use subscribe(), but is less recommended)
• should not be used to listen normal channel messages (use subscribe() instead)
• does not involve any communication with the Bayeux server, and as such can be called before calling handshake()
• is synchronous: when it returns, you are guaranteed that the listener has been added

The subscribe() method:

• must not be used to listen to meta channels messages (otherwise the server will return an error)
• may be used to listen to service channel messages (you may also use addListener(), which is preferred)
• should be used to listen to normal channel messages
• involves a communication with the Bayeux server and as such cannot be called before calling handshake()
• is asynchronous: it returns immediately, well before the Bayeux server has received the subscription request

Note
Calling subscribe() does not mean that you have completed the subscription with the server when subscribe() returns.

Both addListener() and subscribe() return a subscription object that must be passed to, respectively, removeListener() and unsubscribe():

// Some initialization code
var subscription1 = cometd.addListener('/meta/connect', function() { ... });
var subscription2 = cometd.subscribe('/foo/bar/', function() { ... });

// Some de-initialization code
cometd.unsubscribe(subscription2);
cometd.removeListener(subscription1);

A common pattern of utilization is to handle the subscription code in an idempotent method, like this:

var _subscription;

// The idempotent method
function _refresh()
{
    _appUnsubscribe();
    _appSubscribe();
}

function _appUnsubscribe()
{
    if (_subscription) 
        cometd.unsubscribe(_subscription);
    _subscription = null;
}

function _appSubscribe()
{
    _subscription = cometd.subscribe('/foo/bar', function() { ... });
}

The same of course applies also for addListener()/removeListener().

The point is that you have to be careful in your application: you have to remove your subscriptions, in order to avoid to leak functions, or to execute functions more than once (since you could erroneously bind the same callback twice).
Refer also to the Primer for a discussion about using idempotent methods.

How do subscribe() and unsubscribe() behave in case the Bayeux server is not reachable (due to network failures or because the server crashed) ?
In subscribe() the local listener is first added to the list of subscribers for that channel, then the server communication is attempted. If the communication fails, the server will not know that it has to send messages to this client and therefore on the client the local listener (although present) will never be invoked.
In unsubscribe(), the local listener is first removed from the list of subscribers for that channel, then the server communication is attempted. If the communication fails, the server will still send the message to the client but there will be no local listener to dispatch to.

Listeners/Subscribers Exception Handling

If a listener or subscriber function throws an exception (for example, calls a method on an undefined object, etc.), then the error message is logged (at level "debug").
However, there is a way to intercept these errors by defining the global listener exception handler, that is invoked every time a listener or subscriber throws an exception:

cometd.onListenerException = function(exception, subscriptionHandle, isListener, message)
{
    // Uh-oh, something went wrong, disable this listener/subscriber
    // Object "this" points to the CometD object
    if (isListener)
        this.removeListener(subscriptionHandle);
    else
        this.unsubscribe(subscriptionHandle);
}

It is be possible to send messages to the server from the listener exception handler.
If the listener exception handler itself throws an exception, this exception is logged at level "info" and the CometD implementation will not break.
Note that a similar mechanism exists for extensions, see here.

Wildcard Subscriptions

It is possible to subscribe to several channels at once using wildcards, like this:

cometd.subscribe("/chatrooms/*", function(message) { ... });

A single asterisk has the meaning of matching a single channel segment, so in the example above it will match channels /chatrooms/12 and /chatrooms/15, but not /chatrooms/12/upload.
To match multiple channel segments, use the double asterisk:

cometd.subscribe("/events/**", function(message) { ... });

With the double asterisk, the channels /events/stock/FOO and /events/forex/EUR will match, as well as /events/feed and /events/feed/2009/08/03.

The wildcard mechanism works also for listeners, so it is possible to listen to all meta channels like this:

cometd.addListener("/meta/*", function(message) { ... });

By default, subscriptions to the global wildcards /* and /** result in an error, but this behavior can be changed by specifying a custom security policy on the Bayeux server.

The wildcards can only be specified as last segment of the channel, so these are invalid subscriptions: /**/foo or /foo/*/bar.

Meta Channel List

These are the meta channels available in the JavaScript CometD implementation:

• /meta/handshake
• /meta/connect
• /meta/disconnect
• /meta/subscribe
• /meta/unsubscribe
• /meta/publish
• /meta/unsuccessful

Each meta channel is notified when the correspondent Bayeux message is handled by the JavaScript Cometd implementation.
The /meta/unsuccessful channel is notified in case of any failure.

By far the most interesting meta channel to subscribe to is /meta/connect, because it gives the status of the current connection with the Bayeux server. In combination with /meta/disconnect, it can be used, for example, to display a green "connected" icon or a red "disconnected" icon on the page, depending on the connection status with the Bayeux server.

This is a common pattern using the /meta/connect and /meta/disconnect channels:

var _connected = false;

cometd.addListener('/meta/connect', function(message)
{
    // if (cometd.getStatus() === 'disconnecting' || cometd.getStatus() === 'disconnected')
    if (cometd.isDisconnected()) // Available since 1.1.2
    {
        return;
    }
    var wasConnected = _connected;
    _connected = message.successful;
    if (!wasConnected && _connected)
    {
        // Reconnected
    }
    else if (wasConnected && !_connected)
    {
        // Disconnected
    }
});

cometd.addListener('/meta/disconnect', function(message)
{
    if (message.successful)
    {
        _connected = false;
    }
}

One small caveat with the /meta/connect channel is that /meta/connect is also used for polling the server.
Therefore, if a disconnect is issued during an active poll, the active poll is returned by the server and this triggers the /meta/connect listener.
The initial check on the status verifies that is not the case before executing the connection logic.

Another interesting usage of meta channels is when there is an authentication step during the handshake.
In this case the registration to the /meta/handshake channel can give details about, for example, authentication failures.

CometD 2 JavaScript Publish

JavaScript CometD 2 API: Publishing

The publish() method allow you to publish data onto a certain channel:

cometd.publish('/mychannel', { mydata: { foo: 'bar' } });

You cannot (and it makes no sense) to publish to a meta channel, and you can publish to a channel even if you are not subscribed to that channel.
However, you have to handshake before being able to publish.

As with other JavaScript CometD API, publish() involves a communication with the server and it is asynchronous: it returns immediately, well before the Bayeux server has received the message.

Note
Calling publish() does not mean that you have published the message when publish() returns.

If you have to publish several messages to different channels, you may want to use message batching.

CometD 2 JavaScript Disconnection

JavaScript CometD 2 API: Disconnecting

The JavaScript CometD implementation performs automatic reconnect in case of network or Bayeux server failures.
The reconnect parameters are described in the configuration section.

Short Network Failures

In case of temporary network failures, the client is notified through the /meta/connect channel (see this section about meta channels) with messages that have the successful field set to false (see also the archetypes in the primer as an example).
However, the Bayeux server may be able to keep the client's state, and when the network resumes the Bayeux server may behave as if nothing happened.
The client in this case just re-establishes the long poll, but any message published by the client during the network failure is not automatically re-sent (though it is possible to be notified, through the /meta/publish channel, of the failed publishes).

Long Network Failures or Server Failures

If the network failure is long enough, the Bayeux server times out the lost client, and deletes the state associated with it. The same happens when the Bayeux server crashes (except of course that the state of all clients is lost).
In this case, the reconnection mechanism on the client performs the following steps:

• a long poll is re-attempted, but the server rejects it with a 402::Unknown client error message
• a handshake is attempted, and the server normally accepts it and allocates a new client
• upon the successful re-handshake, a long poll is re-established

If you register with meta channels, be aware of these steps, since a reconnection may involve more than one message exchange with the server.

Disconnecting

Calling the JavaScript CometD API disconnect() result in a message being sent to the Bayeux server, so that it can cleanup any state associated with that client.
As with all methods that involve a communication with the Bayeux server, it is an asynchronous method: it returns immediately, well before the Bayeux server has received the disconnect request.
If the server cannot be reached (because it is down or because of network failures), the JavaScript CometD implementation will stop any reconnection attempt and cleanup any local state.
It is normally safe to ignore if the disconnect() call has been successful or not: the client is in any case disconnected, its local state cleaned up, and if the server has not been reached it will eventually time out the client and cleanup any server-side state for that client.

Tip
If you are debugging your application with Firebug, and you shutdown the server, you'll see in the Firebug console the attempts to reconnect.
To stop those attempts, simply type in the Firebug command line: dojox.cometd.disconnect() (for Dojo) or $.cometd.disconnect() (for jQuery).

CometD 2 JavaScript Message Batching

JavaScript CometD 2 API: Message Batching

It is often needed by an application to send several messages to possibly different channels.

One, naive, way of doing it is the following:

cometd.handshake();

// Warning: non-optimal code
cometd.publish('/channel1', { product: 'foo' });
cometd.publish('/channel2', { notificationType: 'all' });
cometd.publish('/channel3', { update: false });

You may think that the 3 publishes will leave the client one after the other, but that's actually not the case.
Remember that publish() is asynchronous (so it returns immediately), so the 3 publish() calls in sequence may return well before a single byte hits the network.

What happens is that the first publish() will be executed immediately, and the other 2 will be put in a queue, waiting for the first publish() to complete.
A publish() is complete when the server received it, the server sent back the meta response, and the client received the meta response for that publish.
When the first publish is completed, the second publish is executed and waited to complete. After that, finally the third publish() is executed.

If the configuration parameter called autoBatch is set to true, the implementation automatically batches messages that have been queued up.
So, in the example above, the first publish() will be executed immediately, and when it completes, the implementation will batch the second and third publish() into one request to the server.
The autoBatch feature may be interesting for those systems where events received asynchronously and unpredictably, either at a fast rate or in bursts, end up in generating a publish() to the server: in such cases, using the batching API is not effective (as each event would generate only one publish()).
A bursts of events on the client will generate a bursts of publish() to the server, but this mechanism batches them automatically, making the communication more efficient.

This queueing mechanism is needed to avoid to queue a publish() behind a long poll. If not for this mechanism, the browser would receive 3 publish requests but only has 2 connections available, and one is already occupied by the long poll request. So the browser may decide to round robin the publish requests, so that the first publish goes on the second connection (remember that the first connection is already busy with the long poll request), which is free and it is actually sent over the network, schedule the second publish to the first connection (after the long poll returns), and schedule the third publish again to the second connection, after the first publish returns.
The result is that if you have a long poll timeout of 5 minutes, the second publish request may arrive to the server 5 minutes later than the first and the third publish request.

You can optimize the 3 publish using batching, which is a way to group messages together so that a single Bayeux message actually carries the 3 publish messages.

cometd.handshake();

cometd.batch(function()
{
    cometd.publish('/channel1', { product: 'foo' });
    cometd.publish('/channel2', { notificationType: 'all' });
    cometd.publish('/channel3', { update: false });
});

// Alternatively, but not recommended
cometd.startBatch()
cometd.publish('/channel1', { product: 'foo' });
cometd.publish('/channel2', { notificationType: 'all' });
cometd.publish('/channel3', { update: false });
cometd.endBatch()

Note how the 3 publish() calls are now within a function passed to batch().
Alternatively, but less recommended, you can surround the 3 publish() calls between startBatch() and endBatch().

Warning
Remember to call endBatch() after having called startBatch().
If you don't, for example because an exception is thrown in the middle of the batch, your messages will continue to queue up, and your application will not work as expected.

Function batch() already does the correct batching for you (also in case of errors), so it's the recommended way to do message batching.

When a batch is started, subsequent API calls are not sent to the server, but instead queued up, until the batch is ended.
The end of the batch packs up all the queued messages into one single Bayeux message and send it over the network to the Bayeux server.

Message batching allow an efficient utilization of the network, as instead of making 3 requests/responses cycles, batching makes only one request/response cycle.

Batches can be made up of different API calls:

var _subscription;

cometd.batch(function()
{
    cometd.unsubscribe(_subscription);
    _subscription = cometd.subscribe('/foo', function(message) { ... });
    cometd.publish('/bar', { ... });
});

Batched messages will be processed by the Bayeux server in the order they are sent.

If you still want to risk and use the startBatch() and endBatch() calls, remember that they must be done from the same context of execution; message batching has not been designed to span multiple user interactions.
So, for example, it would be wrong to start a batch in, say, functionA (triggered by user interaction), and ending the batch in functionB (also triggered by user interaction and not called by functionA).
Similarly, it would be wrong to start a batch in functionA and then schedule (using setTimeout()) the execution of functionB to end the batch.

CometD 2 JavaScript Transports

JavaScript CometD 2 Transports

The Bayeux specification defines two mandatory transports:

• long-polling
• callback-polling

The JavaScript CometD implementation implements these two transports and supports also the websocket transport.

Note
The websocket protocol is still an experimental protocol being changed by the IETF working group that is standardizing it.
Browsers that have deployed an initial support for the websocket protocol could be buggy, so we do not recommend to use the websocket protocol yet, though the CometD project supports it.

For recent browsers (such as Firefox 3.5+) it is possible to use the long-polling transport also for cross-domain Bayeux communication, see below the cross-domain mode.

The long-polling Transport

The long-polling transport is the default transport if the browser and the server do not support websocket.
This transport is used when the communication with the Bayeux server happens on the same domain, and in the cross-domain mode (see below).
The data is sent to the server by means of a POST request with Content-Type text/json via a plain XMLHttpRequest call.

The callback-polling Transport

The callback-polling transport is the transport that is used when the communication with the Bayeux server happens on a different domain (when the cross-domain mode is not supported, see below for the cross-domain mode section).

It is well known that XMLHttpRequest calls have restrictions when the invocation is directed to a domain different from the one the script has been downloaded (but see below the cross-domain mode for an alternative solution).
To overcome XMLHttpRequest restrictions, this transport uses the JSONP script injection: instead of using XMLHttpRequest it injects a <script> element whose src attribute points to the Bayeux server.
The browser will notice the script element injection and performs a GET request to the specified source URL.
The Bayeux server is aware that this is a JSONP request and replies with a JavaScript function that is then executed by the browser (and that calls back into the JavaScript Cometd implementation).

There are three main drawbacks in using this transport:

• The transport is chattier.
  This is due to the fact that the browser executes the injected scripts sequentially, and until a script has been completely "downloaded", it cannot be executed.
  For example, imagine a communication that involves a script injection for the long poll, and a script injection for a message publish. The browser injects the long poll script, a request is made to the Bayeux server, but the Bayeux server holds the request waiting for server-side events (so the "script" is not "downloaded"). Then the browser injects the publish script, the request is made to the Bayeux server, which replies (so the "script is "downloaded"). However, the browser does not execute the second script, because it has not executed the first yet (since its "download" is not finished). In these conditions, the publish would be executed only after the long poll returns. To avoid this situation the Bayeux server, in case of callback-polling transport, resumes the client's long poll for every message that arrives from that client, and that's why the transport is chattier: the long poll returns more often.
• The message size is limited.
  This is necessary to support IE7, that has a 2083 character limit for GET requests.
• The reaction to failures is slower.
  This is due to the fact that if the script injection points to a URL that returns an error (for example the Bayeux server is down), this is silently ignored by the browser.

The websocket transport

The websocket transport is available if the browser and the server supports websocket (Jetty 7 supports the websocket protocol).
This transport is still experimental, but it is being designed to be the bidirectional communication protocol for the web, so it is a natural fit in the CometD project.
However, the websocket protocol is still in alpha state, and browsers support it to various degree of reliability (often times the support is buggy), so currently it is not yet recommended to use it in production (see below on how to disable transports).
The websocket transport is disabled by default since CometD 2.1.0, but can be enabled easily, following this section.

Unregistering Transports

CometD JavaScript transports are added in the JavaScript toolkit bindings for the CometD JavaScript library.

The CometD JavaScript API allow to unregister transports, and this can be useful to force the use of only one transport (for example for testing purposes), or to disable certain transports that may be unreliable.

For example, it is possible to unregister the websocket transport by unregistering it with the following code:

var cometd = dojox.cometd; // Dojo style
var cometd = $.cometd; // jQuery style

cometd.unregisterTransport('websocket');

The cross-domain Mode

Firefox 3.5 introduced the capability for XMLHttpRequest calls to be performed towards a different domain (see here).

This is supported also in the JavaScript CometD implementation, with no configuration necessary on the client (if the browser supports XMLHttpRequest cross-domain calls, they will be used) and with a bit of configuration for the server. Refer to this document for the server configuration.

To use the cross-domain mode, you need:

• a cross-domain compliant browser (for example Firefox 3.5)
• a compliant server (for example Jetty configured with the CrossOriginFilter)

With this setup, even when the communication with the Bayeux server is cross-domain, the long-polling transport will be used, avoiding the drawbacks of the callback-polling transport.

CometD 2 Java Concepts

CometD 2 Java Concepts

The CometD project implements the Comet technique using the Bayeux protocol to provide a scalable HTTP-based messaging system.

In general, messaging system are made of a client part and of a server part that communicate via a procotol. This is captured by a pattern called half object plus protocol.

Sessions

A org.cometd.bayeux.client.ClientSession is the client-side half object that represent a communication session with a Bayeux server.

When client session half objects are created by a client, they are not initially associated with a correspondent org.cometd.bayeux.server.ServerSession half object.
Only when a client session handshakes with the server, its correspondent server session is created, and the link between the two half objects is created.

The concept of client session is straightforward for remote clients, but it exist on server-side as well.
The Bayeux server only knows about server session half objects, and the only way to create a server session half object is to create its correspondent client session first, and then make it handshake with the server.

For this reason, on server-side, there is the additional concept of a org.cometd.bayeux.server.LocalSession, which extends org.cometd.bayeux.client.ClientSession; it is a client session that happens to live on the server, and hence is local to the server.

For example, server-side services are associated with a local session. Upon creation of the server-side service, the local session handshakes and creates the correspondent server session half object, so that the Bayeux server can treat remote sessions and local session in the same way via org.cometd.bayeux.server.ServerSession.

In the CometD implementation, the two halves communicate by exchanging Bayeux messages.

Message

The Java API offers - on client-side - the org.cometd.bayeux.Message interface to interact with the content of a message in a read-only way.
Where user code is allowed to modify the content of a message, the inner sub-interface org.cometd.bayeux.Message.Mutable is passed as parameter to callback methods (for example in client-side extensions).

On server-side, the sub-interface org.cometd.bayeux.server.ServerMessage allows read-only interaction with messages, and the inner sub-interface org.cometd.bayeux.server.ServerMessage.Mutable is passed as parameter to callback methods where user code is allowed to modify the message (for example server-side extensions).

Messages are sent to channels.

Channel

A channel is a named topic to which messages are sent to and to which subscribers register if they are interested in receiving messages sent to that channel.
Channel names resembles directory paths and can be wildcarded, for example: /chat/room/1, /stocks/**, /cinema/trailers/*.
Bayeux channels are divided in three categories:

• Meta Channels (whose name starts with /meta/ and are reserved to the Bayeux protocol)
• Service Channels (whose name starts with /services/ and are used from client to server communication)
• Normal Channels (whose name starts with any other string and are used to broadcast messages between clients)

On server-side, the sub-interface org.cometd.bayeux.server.ServerChannel allows interaction with the channel (for example by publishing messages or adding listeners).

On client-side, channels are scoped to the client session that provides them via org.cometd.bayeux.client.ClientSessionChannel.

CometD 2 JSON Library Pluggability

CometD 2 JSON Library Pluggability

Since version 2.4.0, CometD allows to customize the JSON library that is used to convert incoming JSON into Bayeux messages and generate JSON from Bayeux messages.

There are two implementations available, one based on Jetty's org.eclipse.jetty.util.ajax.JSON class, and the other based on the Jackson library.
The default implementation uses the Jetty library.

The two libraries are among the fastest around and it turns out that, for the CometD specific case, the Jetty library is faster than Jackson in parsing, but slower in generating.

The Jackson library offers a richer API to customize JSON generation and parsing based on annotations, so it may have an advantage if you want to use objects of your custom classes as data of Bayeux messages (instead of using java.util.Map objects). Refer to the Jackson documentation for further details.

Also the Jetty library allows to plug in custom serializers and deserializers, perhaps in a simpler but more invasive way (your custom classes must implement Jetty's library interfaces). Refer to the org.eclipse.jetty.util.ajax.JSON javadocs for further details.

CometD JSONContext API

The JSON library is used by the CometD Java client implementation (see here) to generate JSON from and to parse JSON to org.cometd.bayeux.Message instances.
The JSON library class that performs this generation/parsing on the client must implement org.cometd.common.JSONContext.Client.

Similarly, on the server, a org.cometd.common.JSONContext.Server implementation generates JSON from and parses JSON to org.cometd.bayeux.server.ServerMessage instances.

Client Configuration

On the client, the org.cometd.common.JSONContext.Client instance must be passed directly into the transport configuration; if omitted, the default Jetty library will be used.
For example:

HttpClient httpClient = ...;

Map clientOptions = new HashMap();

// Use the Jackson implementation
JSONContext.Client jsonContext = new JacksonJSONContextClient();
clientOptions.put(ClientTransport.JSON_CONTEXT, jsonContext);

ClientTransport transport = new LongPollingTransport(clientOptions, httpClient);

BayeuxClient client = new BayeuxClient(cometdURL, transport);

The org.cometd.common.JSONContext.Client instance may be shared by all client transports (since only one transport will be used at any time).

You can customize the Jackson implementation and add your own serializers/deserializer in the following way:

public class MyJacksonJSONContextClient extends org.cometd.common.JacksonJSONContextClient
{
    public MyJacksonJSONContextClient()
    {
        org.codehaus.jackson.map.ObjectMapper objectMapper = getObjectMapper();
        objectMapper.registerModule(new MyModule());
    }

    private class MyModule extends org.codehaus.jackson.map.module.SimpleModule
    {
        public MyModule()
        {
            // Add your custom serializers/deserializers here
            addSerializer(Foo.class, new FooSerializer());
        }
    }
}

Server Configuration

On the server, the full qualified name of a class implementing org.cometd.common.JSONContext.Server may be specified as init-parameter of the CometdServlet (see also here); if omitted, the default Jetty library will be used.
For example:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.CometdServlet</servlet-class>
        ... other parameters
        <init-param>
            <param-name>jsonContext</param-name>
            <param-value>org.cometd.server.JacksonJSONContextServer</param-value>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

</web-app>

The class specified must be instantiable using the default parameterless constructor and implement org.cometd.common.JSONContext.Server, and it can be customized by adding serializers/deserializers as explained above.

Portability Considerations

It is possible to switch from one implementation of the JSON library to another - for example from the Jetty library to the Jackson library , provided that the application code is written carefully.

As of version 1.8.4, Jackson can only produce instances of java.util.List when deserializing JSON arrays.
The Jetty library, however, produces Object[] when deserializing JSON arrays.

Similarly, Jackson may produce lava.lang.Integer where the Jetty library produces java.lang.Long.

To write portable application code, use the following code patterns:

Message message = ...;
Map<String, Object> data = message.getDataAsMap();

// Expecting a JSON array

// WRONG
Object[] array = (Object[])data.get("array");

// CORRECT
Object field = data.get("array");
Object[] array = field instanceof List ? ((List)field).toArray() : (Object[])field;


// Expecting a long

// WRONG
long value = (Long)data.get("value");

// CORRECT
long value = ((Number)data.get("value")).longValue();

CometD 2 Java Server API

CometD 2 Java Server Implementation

In order to run the CometD server implementation, you need to deploy a Java web application to a servlet container.

The web application needs to configure the CometD servlet (see here for configuration details) to interpret the Bayeux protocol.

Most of the times it is also needed to write one or more user-defined services that can act upon receiving messages on Bayeux channels.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.CometdServlet</servlet-class>
        <init-param>
            <param-name>timeout</param-name>
            <param-value>60000</param-value>
        </init-param>
        <init-param>
            <param-name>logLevel</param-name>
            <param-value>3</param-value>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

</web-app>

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.continuation.ContinuationCometdServlet</servlet-class>
        <init-param>
            <param-name>timeout</param-name>
            <param-value>60000</param-value>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <filter>
        <filter-name>cross-origin</filter-name>
        <filter-class>org.eclipse.jetty.servlets.CrossOriginFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>cross-origin</filter-name>
        <url-pattern>/cometd/*</url-pattern>
    </filter-mapping>

</web-app>

boolean canHandshake(BayeuxServer server, ServerSession session, ServerMessage message);

boolean canCreate(BayeuxServer server, ServerSession session, String channelId, ServerMessage message);

boolean canSubscribe(BayeuxServer server, ServerSession session, ServerChannel channel, ServerMessage messsage);

boolean canPublish(BayeuxServer server, ServerSession session, ServerChannel channel, ServerMessage messsage);

public boolean canCreate   (BayeuxServer server, ServerSession session, String channelId,      ServerMessage message);
public boolean canSubscribe(BayeuxServer server, ServerSession session, ServerChannel channel, ServerMessage message);
public boolean canPublish  (BayeuxServer server, ServerSession session, ServerChannel channel, ServerMessage message);

public Result authorize(Operation operation, ChannelId channel, ServerSession session, ServerMessage message);

public Result authorize(Operation operation, ChannelId channel, ServerSession session, ServerMessage message);
{
    return Result.grant();
}

public Result authorize(Operation operation, ChannelId channel, ServerSession session, ServerMessage message);
{
    return Result.ignore();
}

public Result authorize(Operation operation, ChannelId channel, ServerSession session, ServerMessage message);
{
    return Result.deny("reason to deny");
}

BayeuxServer bayeuxServer = ...;
bayeuxServer.createIfAbsent("/game/**");
ServerChannel gameStarStar = bayeuxServer.getChannel("/game/**");
gameStarStar.addAuthorizer(GrantAuthorizer.GRANT_NONE);

gameStarStar.addAuthorizer(new Authorizer()
{
    public Result authorize(Operation operation, ChannelId channel, ServerSession session, ServerMessage message)
    {
        boolean isGameChannel = !channel.isWild() && new ChannelId("/game").isParentOf(channel);
        if (operation == Operation.CREATE && isGameChannel)
        {
            if (isCaptain(session))
                return Result.grant();
            return Result.deny("Only captains can create game channels");
        } 
        return Result.ignore();
    }
});

gameStarStar.addAuthorizer(GrantAuthorizer.GRANT_SUBSCRIBE);

ServerChannel gameChannel = bayeuxServer.getChannel("/game/" + gameId);
gameChannel.addAuthorizer(new Authorizer()
{
    public Result authorize(Operation operation, ChannelId channel, ServerSession session, ServerMessage message)
    {
        if (operation == Operation.PUBLISH)
        {
            if(isPlayer(session,channel))
                return Result.grant();
            return Result.deny("Only players can publish to "+channel);
        } 
        return Result.ignore();
    }
});

/game/**  --> one authorizer that ignores everything
          --> one authorizer that grants captains to create games
          --> one authorizer that grants everyone to watch games
/game/123 --> one authorizer that grants players to play

gameStarStar.addAuthorizer(new Authorizer()
{
    public Result authorize(Operation operation, ChannelId channel, ServerSession session, ServerMessage message)
    {
        boolean isCriminalSupporter = isCriminalSupporter(session);
        if (operation == Operation.SUBSCRIBE && isCriminalSupporter)
            return Result.deny("criminal_supporter"); 
        return Result.ignore();
    }
});

/game/**  --> one authorizer that ignores everything
          --> one authorizer that grants captains to create games
          --> one authorizer that grants everyone to watch games
          --> one authorizer that denies criminal supporters to watch games
/game/123 --> one authorizer that grants players to play

bayeuxServer.createIfAbsent("/game/"+game_id, new ConfigurableServerChannel.Initializer()
{
    public void configureChannel(ConfigurableServerChannel channel)
    {
        channel.addAuthorizer(new PlayerAuthorizer());
    }
});

public class EchoService extends AbstractService                                  (1)
{
    public EchoService(BayeuxServer bayeuxServer)                                 (2)
    {
        super(bayeuxServer, "echo");                                              (3)
        addService("/echo", "processEcho");                                       (4)
    }

    public void processEcho(ServerSession remote, Map<String, Object> data) (5)
    {
        remote.deliver(getServerSession(), "/echo", data, null);                  (6)
    }
}

// Obtains the remote session object and the message object
public void processEcho(ServerSession remote, Message message)

// Obtains the remote session object and the message's data object
// (additional message information, such as the channel or the id is lost)
public void processEcho(ServerSession remote, Map<String, Object> data)

// Obtains the remote session object, the channel name, the message object and the message id
public void processEcho(ServerSession remote, String channelName, Message message, String messageId)

// Obtains the remote session object, the channel name, the message's data object and the message id
public void processEcho(ServerSession remote, String channelName, Map<String, Object> data, String messageId)

public class BaseballTeamService extends AbstractService
{
    public BaseballTeamService(BayeuxServer bayeux)
    {
        super(bayeux, "baseballTeam");
        addService("/baseball/team/*", "processBaseballTeam");
    }

    public void processBaseballTeam(ServerSession remote, String channelName, Map<String, Object> data, String messageId)
    {
        // Upon receiving a message on channel /baseball/team/*, forward to channel /events/baseball/team/*
        getBayeux().getChannel("/events" + channelName).publish(getServerSession(), data, null);
    }
}

@org.cometd.annotation.Service("echoService")
public class EchoService
{
    @javax.inject.Inject
    private BayeuxServer bayeux;
}

public class EchoService extends AbstractService
{
    public EchoService(BayeuxServer bayeux)
    {
        super(bayeux, "echoService");
    }
}

@Service("echoService")
public class EchoService
{
    @Inject
    private BayeuxServer bayeux;

    @Configure("/echo")
    public void configure(ConfigurableServerChannel channel)
    {
        channel.setLazy(true);
        channel.addAuthorizer(GrantAuthorizer.GRANT_PUBLISH);
    }
}

@Service("echoService")
public class EchoService
{
    @Inject
    private BayeuxServer bayeux;

    @org.cometd.annotation.Session
    private LocalSession localSession;

    @org.cometd.annotation.Session
    private ServerSession serverSession;
}

@Service("echoService")
public class EchoService
{
    @Inject
    private BayeuxServer bayeux;
    @Session
    private ServerSession serverSession;

    @org.cometd.annotation.Listener("/echo")
    public void echo(ServerSession remote, ServerMessage.Mutable message)
    {
        String channel = message.getChannel();
        Object data = message.getData();
        remote.deliver(serverSession, channel, data, null);
    }
}

public class EchoService extends AbstractService
{
    public EchoService(BayeuxServer bayeux)
    {
        super(bayeux, "echoService");
        addService("/echo", "echo");
    }

    public void echo(ServerSession remote, ServerMessage.Mutable message)
    {
        String channel = message.getChannel();
        Object data = message.getData();
        remote.deliver(getServerSession(), channel, data, null);
    }
}

@Service("echoService")
public class EchoService
{
    @Inject
    private BayeuxServer bayeux;
    @Session
    private ServerSession serverSession;

    @org.cometd.annotation.Subscription("/echo")
    public void echo(Message message)
    {
        System.out.println("Echo service published " + message);
    }
}

BayeuxServer bayeux = ...;

// Create the ServerAnnotationProcessor
ServerAnnotationProcessor processor = new ServerAnnotationProcessor(bayeux);

// Create the service instance
EchoService service = new EchoService();

// Process the annotated service
processor.process(service);

@Service
public class Service
{
    @Session
    private ClientSession bayeuxClient;

    @Listener(Channel.META_CONNECT)
    public void metaConnect(Message connect)
    {
        // Connect handling...
    }

    @Subscription("/foo")
    public void foo(Message message)
    {
        // Message handling...
    }
}

ClientSession bayeuxClient = ...;

bayeuxClient.getChannel(Channel.META_CONNECT).addListener(new ClientSessionChannel.MessageListener()
{
    public void onMessage(ClientSessionChannel channel, Message message)
    {
        // Connect handling...
    }
});

bayeuxClient.handshake();
bayeuxClient.waitFor(1000, BayeuxClient.State.CONNECTED);

bayeuxClient.getChannel("/foo").subscribe(new ClientSessionChannel.MessageListener()
{
    public void onMessage(ClientSessionChannel channel, Message message)
    {
        // Message handling...
    }
});

@Service
public class Service
{
    @org.cometd.annotation.Session
    private ClientSession bayeuxClient;
}

@Service
public class Service
{
    @Listener(Channel.META_CONNECT)
    public void metaConnect(Message connect)
    {
        // Connect handling...
    }
}

bayeuxClient.getChannel(Channel.META_CONNECT).addListener(new ClientSessionChannel.MessageListener()
{
    public void onMessage(ClientSessionChannel channel, Message message)
    {
        // Connect handling...
    }
});

@Service
public class Service
{
    @Listener("/foo/*")
    public void foos(Message message)
    {
        // Message handling...
    }
}

bayeuxClient.getChannel("/foo/*").subscribe(new ClientSessionChannel.MessageListener()
{
    public void onMessage(ClientSessionChannel channel, Message message)
    {
        // Message handling...
    }
});

ClientSession bayeuxClient = ...;

// Create the ClientAnnotationProcessor
ClientAnnotationProcessor processor = new ClientAnnotationProcessor(bayeuxClient);

// Create the service instance
Service service = new Service();

// Process the annotated service
processor.process(service);

bayeuxClient.handshake();

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.CometdServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <servlet>
        <servlet-name>configuration</servlet-name>
        <servlet-class>com.acme.cometd.ConfigurationServlet</servlet-class>
        <load-on-startup>2</load-on-startup>
    </servlet>

</web-app>

public class ConfigurationServlet extends GenericServlet
{
    public void init() throws ServletException
    {
        // Grab the Bayeux object
        BayeuxServer bayeux = (BayeuxServer)getServletContext().getAttribute(BayeuxServer.ATTRIBUTE);
        new EchoService(bayeux);
        // Create other services here

        // This is also the place where you can configure the Bayeux object
        // by adding extensions or specifying a SecurityPolicy
    }

    public void service(ServletRequest request, ServletResponse response) throws ServletException, IOException
    {
        throw new ServletException();
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.CometdServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <listener>
        <listener-class>com.acme.cometd.BayeuxInitializer</listener-class>
    </listener>

</web-app>

public class BayeuxInitializer implements ServletContextAttributeListener
{
    public void attributeAdded(ServletContextAttributeEvent event)
    {
        if (Bayeux.ATTRIBUTE.equals(event.getName()))
        {
            // Grab the Bayeux object
            BayeuxServer bayeux = (BayeuxServer)event.getValue();
            new EchoService(bayeux);
            // Create other services here

            // This is also the place where you can configure the Bayeux object
            // by adding extensions or specifying a SecurityPolicy
        }
    }

    public void attributeRemoved(ServletContextAttributeEvent event)
    {
    }

    public void attributeReplaced(ServletContextAttributeEvent event)
    {
    }
}

public class ConfigurationServlet extends GenericServlet
{
    private final List<Object> services = new ArrayList<Object>();
    private ServerAnnotationProcessor processor;

    public void init() throws ServletException
    {
        // Grab the BayeuxServer object
        BayeuxServer bayeux = (BayeuxServer)getServletContext().getAttribute(BayeuxServer.ATTRIBUTE);
        
        // Create the annotation processor
        processor = new ServerAnnotationProcessor(bayeux);

        // Create your annotated service instance and process it
        Object service = new EchoService();
        processor.process(service);
        services.add(service);

        // Create other services here

        // This is also the place where you can configure the Bayeux object
        // by adding extensions or specifying a SecurityPolicy
    }

    public void destroy() throws ServletException
    {
        // Deprocess the services that have been created
        for (Object service : services)
            processor.deprocess(service);
    }

    public void service(ServletRequest request, ServletResponse response) throws ServletException, IOException
    {
        throw new ServletException();
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.java.annotation.AnnotationCometdServlet</servlet-class>
        <init-param>
            <param-name>services</param-name>
            <param-value>com.acme.cometd.FooService, com.acme.cometd.BarService</param-value>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

</web-app>

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.CometdServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

</web-app>

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">

    <bean id="otherService" class="com.acme..." />

    <bean id="bayeux" class="org.cometd.server.BayeuxServerImpl" init-method="start" destroy-method="stop">
        <property name="options">
            <map>
                <entry key="logLevel" value="3" />
                <entry key="timeout" value="15000" />
            </map>
        </property>  
    </bean>

    <bean id="echoService" class="com.acme.cometd.EchoService">
        <constructor-arg><ref local="bayeux" /></constructor-arg>
        <constructor-arg><ref local="otherService" /></constructor-arg>
    </bean>

    <bean class="org.springframework.web.context.support.ServletContextAttributeExporter">
        <property name="attributes">
            <map>
                <entry key="org.cometd.bayeux">
                    <ref local="bayeux" />
                </entry>
            </map>
        </property> 
    </bean>
</beans>

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
                           http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd">

    <context:component-scan base-package="com.acme..." />

</beans>

@javax.inject.Named // Tells Spring that this is a bean
@javax.inject.Singleton // Tells Spring that this is a singleton
@Service("echoService")
public class EchoService
{
    @Inject
    private BayeuxServer bayeux;
    @Session
    private ServerSession serverSession;

    @PostConstruct
    public void init()
    {
        System.out.println("Echo Service Initialized");
    }

    @Listener("/echo")
    public void echo(ServerSession remote, ServerMessage.Mutable message)
    {
        String channel = message.getChannel();
        Object data = message.getData();
        remote.deliver(serverSession, channel, data, null);
    }
}

@Component
public class Configurer implements DestructionAwareBeanPostProcessor, ServletContextAware
{
    private BayeuxServer bayeuxServer;
    private ServerAnnotationProcessor processor;

    @Inject
    private void setBayeuxServer(BayeuxServer bayeuxServer)
    {
        this.bayeuxServer = bayeuxServer;
    }

    @PostConstruct
    private void init()
    {
        this.processor = new ServerAnnotationProcessor(bayeuxServer);
    }

    public Object postProcessBeforeInitialization(Object bean, String name) throws BeansException
    {
        processor.processDependencies(bean);
        processor.processConfigurations(bean);
        processor.processCallbacks(bean);
        return bean;
    }

    public Object postProcessAfterInitialization(Object bean, String name) throws BeansException
    {
        return bean;
    }

    public void postProcessBeforeDestruction(Object bean, String name) throws BeansException
    {
        processor.deprocessCallbacks(bean);
    }

    @Bean(initMethod = "start", destroyMethod = "stop")
    public BayeuxServer bayeuxServer()
    {
        BayeuxServerImpl bean = new BayeuxServerImpl();
        bean.setOption(BayeuxServerImpl.LOG_LEVEL, "3");
        return bean;
    }

    public void setServletContext(ServletContext servletContext)
    {
        servletContext.setAttribute(BayeuxServer.ATTRIBUTE, bayeuxServer);
    }
}

CometD 2 Java Client API

CometD 2 Java Client Implementation

The CometD client implementation can be used in any JSE^TM or JEE^TM application.

It is made of one main class, org.cometd.client.BayeuxClient, which implements the org.cometd.bayeux.client.ClientSession interface.
Differently from CometD 1, this class now supports pluggable transports (to allow a WebSocket transport to be implemented in future when the WebSocket protocol is standardized), and currently only supports the long polling transport via HTTP, that depends on Jetty's asynchronous HttpClient.

Typical usages of the CometD Java client are:

• As the transport for a rich thick Java UI (for example, Swing) to communicate to a Bayeux Server (also via firewalls)
• As a load generator to simulate thousands of CometD clients, like for example org.cometd.client.BayeuxLoadGenerator

The following sections will go in detail about the Java BayeuxClient APIs and their implementation secrets.

BayeuxClient.handshake()

// Create (and eventually setup) Jetty's HttpClient
HttpClient httpClient = new HttpClient();
// Here setup Jetty's HttpClient, for example:
// httpClient.setMaxConnectionsPerAddress(2);
httpClient.start();

// Prepare the transport
Map<String, Object> options = new HashMap<String, Object>();
ClientTransport transport = LongPollingTransport.create(options, httpClient);

ClientSession client = new BayeuxClient("http://localhost:8080/cometd", transport);
// Here setup the BayeuxClient, for example:
// client.getChannel(Channel.META_CONNECT).addListener(new ClientSessionChannel.MessageListener() { ... });
client.handshake();

ClientTransport transport = ...
ClientSession client = new BayeuxClient("http://localhost:8080/cometd", transport);
client.getChannel(Channel.META_HANDSHAKE).addListener(new ClientSessionChannel.MessageListener() 
{ 
    public void onMessage(ClientSessionChannel channel, Message message)
    {
        if (message.isSuccessful())
        {
            // Here handshake is successful
        }
    }
});
client.handshake();

ClientTransport transport = ...
BayeuxClient client = new BayeuxClient("http://localhost:8080/cometd", transport);
client.handshake();
boolean handshaken = client.waitFor(1000, BayeuxClient.State.CONNECTED);
if (handshaken)
{
    // Here handshake is successful
}

public class Example 
{
    private static final String CHANNEL = "/foo";
    private final ClientSessionChannel.MessageListener fooListener = new FooListener();

    public void attach()
    {
        ClientTransport transport = ...
        ClientSession client = new BayeuxClient("http://localhost:8080/cometd", transport);
        client.handshake();
        boolean handshaken = client.waitFor(1000, BayeuxClient.State.CONNECTED);
        if (handshaken)
        {
            client.getChannel(CHANNEL).subscribe(fooListener);
        }
    }

    private static class FooListener implements ClientSessionChannel.MessageListener
    {
        public void onMessage(ClientSessionChannel channel, Message message)
        {
            // Here we received a message on the channel
        }
    }
}

public class Example 
{
    ...
    public void detach()
    {
        client.getChannel(CHANNEL).unsubscribe(fooListener);
    }
}

public class Example
{
    public void init()
    {
        ClientSession client = ...;
        client.getChannel(Channel.META_HANDSHAKE).addListener(new ClientSessionChannel.MessageListener()
        {
            public void onMessage(ClientSessionChannel channel, Message message)
            {
                // Here we received a handshake response message
            }
        });
    }
}

ClientTransport transport = ...
ClientSession client = new BayeuxClient("http://localhost:8080/cometd", transport);
client.handshake();

Map<String, Object> data = new HashMap<String, Object>();
// Fill in the data
client.getChannel("/game/table/1").publish(data);

final ClientSession client = ...;
client.handshake();

client.batch(new Runnable()
{
    public void run()
    {
        Map<String, Object> data1 = new HashMap<String, Object>();
        // Fill in the data1 map object
        client.getChannel("/game/table/1").publish(data1);

        Map<String, Object> data2 = new HashMap<String, Object>();
        // Fill in the data2 map object
        client.getChannel("/game/chat/1").publish(data2);
    }
});

BayeuxClient.disconnect();

BayeuxClient client = ...;
client.disconnect();
client.waitFor(1000, BayeuxClient.State.DISCONNECTED);

CometD 2 Clustering with Oort

CometD 2 Scalability Clustering with Oort

The CometD distribution ships a clustering solution called Oort that enhances the scalability of a CometD-based system.
Instead of connecting to a single node (usually represented by a virtual or physical host), clients connect to multiple nodes so that the processing power needed to cope with the load is spread among multiple nodes, giving the whole system more scalability then using a single node.

Oort clustering is not a high availability clustering solution: if one of the nodes crashes, then all the clients will be disconnected and will reconnect to other nodes (with a new CometD handshake).
All the information built by one client with its server up to that point (for example, the state of an online chess game) is generally lost (unless - of course - the application has implemented some other way to retrieve that information).

Typical Infrastructure

A typical, but not the only, infrastructure to setup a Oort cluster is to have a load balancer in front of Oort nodes, so that clients can connect transparently to any node.
The load balancer should implement stickyness, and this may be based on the remote IP address or on CometD's BAYEUX_BROWSER cookie (see the Bayeux Specification, section 8.1), or could be based on some other mechanism supported by the load balancer.
DNS should be configured with a single host name / IP address pair (the one of the load balancer), so that in case of a node crash, clients will attempt to reconnect to the same host name, but the load balancer will notice that the node is crashed and direct the connection to another node. The second node will not know about this client, and upon receiving the connect request will send to the client the advice to handshake.

Terminology

In the following sections, the following terminology will be used: an Oort cluster is also referred to as "Oort cloud" (and therefore "cloud" is a synonym for "cluster"), and a Oort node is also referred to as "Oort comet" (and therefore "comet" is a synonym for "node").

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.CometdServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <servlet>
        <servlet-name>oort</servlet-name>
        <servlet-class>org.cometd.oort.OortMulticastConfigServlet</servlet-class>
        <load-on-startup>2</load-on-startup>
        <init-param>
            <param-name>oort.url</param-name>
            <param-value>http://host:port/context/cometd</param-value>
        </init-param>
    </servlet>
</web-app>

Destination    Gateway    Genmask      Flags    Metric    Ref    Use    Iface
224.0.0.0      0.0.0.0    240.0.0.0      U         0       0      0     eth0

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.CometdServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <servlet>
        <servlet-name>oort</servlet-name>
        <servlet-class>org.cometd.oort.OortStaticConfigServlet</servlet-class>
        <load-on-startup>2</load-on-startup>
        <init-param>
            <param-name>oort.url</param-name>
            <param-value>http://host:port/context/cometd</param-value>
        </init-param>
    </servlet>
</web-app>

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.CometdServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <servlet>
        <servlet-name>oort</servlet-name>
        <servlet-class>org.cometd.oort.OortStaticConfigServlet</servlet-class>
        <load-on-startup>2</load-on-startup>
        <init-param>
            <param-name>oort.url</param-name>
            <param-value>http://host1:port/context/cometd</param-value>
        </init-param>
        <init-param>
            <param-name>oort.cloud</param-name>
            <param-value>http://host2:port/context/cometd,http://host3:port/context/cometd</param-value>
        </init-param>
    </servlet>
</web-app>

public class OortConfigurationServlet extends GenericServlet
{
    public void init() throws ServletException
    {
        // Grab the Oort object
        Oort oort = (Oort)getServletContext().getAttribute(Oort.OORT_ATTRIBUTE);

        // Figure out the URLs to connect to, using other discovery means
        List<String> urls = ...;

        // Connect to the other Oort comets
        for (String url : urls)
        {
            OortComet oortComet = oort.observeComet(url);
            if (!oortComet.waitFor(1000, BayeuxClient.State.CONNECTED))
                throw new ServletException("Cannot connect to Oort comet " + url);
        }
    }

    public void service(ServletRequest request, ServletResponse response) throws ServletException, IOException
    {
        throw new ServletException();
    }
}

{
    "channel": "/meta/handshake",
    ... /* other usual handshake fields */
    "ext": {
        "org.cometd.oort": {
            "oortURL": "http://halley.cometd.org:8080/cometd",
            "cometURL": "http://halebopp.cometd.org:8080/cometd",
            "oortSecret": "cstw27r+l+XqE62IrNZdCDiUObA="
        }
    }
}

public class OortSecurityPolicy extends DefaultSecurityPolicy
{
    private final Oort oort;

    private OortSecurityPolicy(Oort oort)
    {
        this.oort = oort;
    }

    @Override
    public boolean canHandshake(BayeuxServer server, ServerSession session, ServerMessage message)
    {
        // Local sessions can always handshake
        if (session.isLocalSession())
            return true;

        // Remote Oort comets are allowed to handshake
        if (oort.isOortHandshake(message))
            return true;

        // Remote clients must have a valid token
        Map ext = message.getExt();
        return ext != null && isValid(ext.get("token"));
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.CometdServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <servlet>
        <servlet-name>oort</servlet-name>
        <servlet-class>org.cometd.oort.OortMulticastConfigServlet</servlet-class>
        <load-on-startup>2</load-on-startup>
        <init-param>
            <param-name>oort.url</param-name>
            <param-value>http://host1:port/context/cometd</param-value>
        </init-param>
        <init-param>
            <param-name>oort.channels</param-name>
            <param-value>/stock/**,/forex/*,/alerts</param-value>
        </init-param>
    </servlet>
</web-app>

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.CometdServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <servlet>
        <servlet-name>oort</servlet-name>
        <servlet-class>org.cometd.oort.OortServlet</servlet-class>
        <load-on-startup>2</load-on-startup>
        <init-param>
            <param-name>oort.url</param-name>
            <param-value>http://host:port/context/cometd</param-value>
        </init-param>
    </servlet>

    <servlet>
        <servlet-name>seti</servlet-name>
        <servlet-class>org.cometd.oort.SetiServlet</servlet-class>
        <load-on-startup>3</load-on-startup>
    </servlet>
</web-app>

public class MySecurityPolicy extends DefaultSecurityPolicy
{
    private final Seti seti;

    public MySecurityPolicy(Seti seti)
    {
        this.seti = seti;
    }

    @Override
    public boolean canHandshake(BayeuxServer server, ServerSession session, ServerMessage message)
    {
        if (session.isLocalSession())
            return true;

        // Authenticate
        String userId = performAuthentication(session, message);
        if (userId == null)
            return false;

        // Associate
        seti.associate(userId, session);

        return true;
    }   
}

@Service("seti_forwarder");
public class SetiForwarder
{
    private final Seti seti;

    private SetiService(Seti seti)
    {
        this.seti = seti;
    }

    @Listener("/service/forward")
    public void forward(ServerSession session, ServerMessage message)
    {
        Map data = message.getDataAsMap();
        String targetUserId = (String)data.get("targetUserId");
        seti.sendMessage(targetUserId, message.getChannel(), data);
    }
}

CometD 2 Acknowledge Extension

CometD 2 Acknowledge Extension

The acknowledged messages extension provides reliable ordered messaging to the Bayeux protocol.
This extension requires both a client-side extension and a server-side extension. The server-side extension is available in Java.
If you are interested only in ordered messaging, see here.

Enabling the Server-side Extension

To enable support for acknowledged messages, the extension must be added to the org.cometd.bayeux.server.BayeuxServer instance during initialization:

bayeuxServer.addExtension(new org.cometd.server.ext.AcknowledgedMessagesExtension());

The AcknowledgedMessageExtension is a per-server extension that monitors handshakes from new clients, looking for clients that also support the acknowledged message extension and then adds the AcknowledgedMessagesClientExtension to each client during the handshake.

Once added to a client, the AcknowledgedMessagesClientExtension guarantees ordered delivery of messages, and resend of unacknowledged messages.
The extension also maintains a list of unacknowledged messages and intercepts the traffic on the /meta/connect channel to insert and check acknowledge IDs.

Enabling the Client-side Extension

The client side extension binding for Dojo is provided by dojox/cometd/ack.js and it is sufficient to use Dojo's dojo.require mechanism:

dojo.require("dojox.cometd.ack");

The client side extension binding for jQuery is provided by the file jquery.cometd-ack.js. This file must be included in the HTML page via the <script> tag:

<script type="text/javascript" src="AckExtension.js"></script>
<script type="text/javascript" src="jquery.cometd-ack.js"></script>

In both Dojo and jQuery extension bindings, the extension is registered on the default cometd object under the name "ack".

Furthermore, the extension may be programmatically disabled/enabled before initialization by setting the ackEnabled boolean field on the cometd object:

// Disables the ack extension during handshake
cometd.ackEnabled = false;
cometd.init(cometdURL);

Acknowledge Extension Details

In order to enable message acknowledgement, both client and server must indicate that they support message acknowledgement.
This is negotiated during handshake. On handshake, the client sends {"ext":{"ack": "true"}} to indicate that it supports message acknowledgement.
If the server also supports message acknowledgment, it likewise replies with {"ext":{"ack": "true"}}.

The extension does not insert ack IDs to every message, as this would impose a significant burden on the server for messages sent to multiple clients (which would need to be reserialized to json for each client). Instead the ack ID is inserted in the ext field of the /meta/connect messages that are associated with message delivery. Each /meta/connect request contains the ack ID of the last received ack response: "ext":{"ack": 42}. Similarly, each /meta/connect response contains an ext ack ID that uniquely identifies the batch of responses sent.

If a /meta/connect message is received with an ack ID lower that any unacknowledged messages held by the extension, then these messages are requeued prior to any more recently queued messages and the /meta/connect response sent with a new ack ID.

Demo

There is an example of acknowledged messages in the Dojo chat demo that comes bundled with the Cometd distribution.
The example can also be run by building the Cometd project.

To run the demo, follow these steps:

$ cd cometd-demo
$ mvn jetty:run

Then point your browser to http://localhost:8080/dojo-examples/chat/ and make sure to check "Enable reliable messaging".

Use two different browsers instances to begin a chat session, then briefly disconnect one browser from the network (you can do this by setting the "work offline" feature).
While one browser is disconnected, type some chat in the other browser and this will be received when the disconnected browser is reconnected to the network.

Note that if the disconnected browser is disconnected for in excess of maxInterval (default 10s), then the client will be timed out and the unacknowledged queue discarded.

CometD 2 Reload Extension

CometD 2 Reload Extension

The reload extension allows a page to be loaded (or the same page to be reloaded) without having to re-handshake in the new (or reloaded) page, therefore resuming the existing CometD connection.
This extension requires only the client-side extension.

Enabling the Client-side Extension

The client side extension binding for Dojo is provided by dojox/cometd/reload.js and it is sufficient to use Dojo's dojo.require mechanism:

dojo.require("dojox.cometd.reload");

The client side extension binding for jQuery is provided by the file jquery.cometd-reload.js. This file must be included in the HTML page via the <script> tag, along with the jQuery cookie plugin and the reload extension implementation:

<script type="text/javascript" src="jquery.cookie.js"></script>
<script type="text/javascript" src="ReloadExtension.js"></script>
<script type="text/javascript" src="jquery.cometd-reload.js"></script>

In both Dojo and jQuery extension bindings, the extension is registered on the default cometd object under the name "reload".

Reload Extension Details

The reload extension allows a page to be reloaded and an existing CometD connection resumed by the reloaded page.

To activate the reload extension, the page must call cometd.reload() just before the page is reloaded (for example, after a link is clicked or on the page unload event).
This saves a short lived cookie with the connection details.
The new page still needs to call subscribe to the channels it is interested in to register the callbacks, since the client state has been completely reset due to the reload.

An example simple usage is:

<html>
    <head>
        <script type="text/javascript" src="dojo/dojo.js"></script>
        <script type="text/javascript">
            dojo.require("dojox.cometd");
            dojo.require("dojox.cometd.reload");

            dojox.cometd.init({ url: "/context/cometd", logLevel: "info" });
            dojox.cometd.subscribe("/some/channel", function() { ... });
            dojox.cometd.subscribe("/some/other/channel", function() { ... });
            
            // On page unload, call dojox.cometd.reload()
            dojo.addOnUnload(dojox.cometd, "reload");
        </script>
    </head>
    <body>
    ...
    </body>
</html>

CometD 2 Timestamp Extension

CometD 2 Timestamp Extension

The timestamp extension add a timestamp to the message object, for every message sent by the client and/or server.
It is a non standard extension because it does not add the additional fields to the ext field, but to the message object itself.
This extension requires both a client-side extension and a server-side extension. The server-side extension is available in Java.

Enabling the Server-side Extension

To enable support for timestamped messages, the extension must be added to the org.cometd.bayeux.server.BayeuxServer instance during initialization:

bayeuxServer.addExtension(new org.cometd.server.ext.TimestampExtension());

Enabling the Client-side Extension

The client side extension binding for Dojo is provided by dojox/cometd/ack.js and it is sufficient to use Dojo's dojo.require mechanism:

dojo.require("dojox.cometd.timestamp");

The client side extension binding for jQuery is provided by the file jquery.cometd-timestamp.js. This file must be included in the HTML page via the <script> tag:

<script type="text/javascript" src="jquery.cometd-timestamp.js"></script>

In both Dojo and jQuery extension bindings, the extension is registered on the default cometd object under the name "timestamp".

CometD 2 Timesync Extension

CometD 2 Timesync Extension

The timesync extension uses the messages exchanged between a client and a server to calculate the offset between the client's clock and the server's clock.
This is independent from the timestamp extension, which uses the local clock for all timestamps.
This extension requires both a client-side extension and a server-side extension. The server-side extension is available in Java.

Enabling the Server-side Extension

To enable support for acknowledged messages, the extension must be added to the org.cometd.bayeux.server.BayeuxServer instance during initialization:

bayeuxServer.addExtension(new org.cometd.server.ext.TimesyncExtension());

Enabling the Client-side Extension

The client side extension binding for Dojo is provided by dojox/cometd/timesync.js and it is sufficient to use Dojo's dojo.require mechanism:

dojo.require("dojox.cometd.timesync");

The client side extension binding for jQuery is provided by the file jquery.cometd-timesync.js. This file must be included in the HTML page via the <script> tag:

<script type="text/javascript" src="jquery.cometd-timesync.js"></script>

In both Dojo and jQuery extension bindings, the extension is registered on the default cometd object under the name "timesync".

Timesync Extension Details

The timesync extension allows the client and server to exchange time information on every handshake and connect message so that the client may calculate an approximate offset from it's own clock epoch to that of the server.
The algorithm used is very similar to the NTP algorithm.

With each handshake or connect, the extension sends timestamps within the ext field like:

{ext:{timesync:{tc:12345567890,l:23,o:4567},...},...}

where:

• tc is the client timestamp in ms since 1970 of when the message was sent
• l is the network lag that the client has calculated
• o is the clock offset that the client has calculated

The accuracy of the offset and lag may be calculated with tc-now-l-o, which should be zero if the calculated offset and lag are perfectly accurate.

A Bayeux server that supports timesync, should respond only if the measured accuracy value is greater than accuracy target.
The response will be an ext field like:

{ext:{timesync:{tc:12345567890,ts:1234567900,p:123,a:3},...},...}

where:

• tc is the client timestamp of when the message was sent
• ts is the server timestamp of when the message was received
• p is the poll duration in ms - ie the time the server took before sending the response
• a is the measured accuracy of the calculated offset and lag sent by the client

On receipt of the response, the client is able to use current time to determine the total trip time, from which p is subtracted to determine an approximate two way network traversal time. Thus:

• lag = (now-tc-p)/2
• offset = ts-tc-lag

In order to smooth over any transient fluctuations, the extension keeps a sliding average of the offsets received.
By default this is over 10 messages, but this can be changed by passing a configuration object during the creation of the extension:

// Unregister the default timesync extension
cometd.unregisterExtension('timesync');

// Re-register with different configuration
cometd.registerExtension('timesync', new org.cometd.TimeSyncExtension({ maxSamples: 20 }));

The client-side timesync extension also exposes several methods to deal with the result of the time synchronization:

• getNetworkLag(), to obtain the calculated network latency between client and server
• getTimeOffset(), to obtain the offset between the client's clock and the server's clock in ms
• getServerTime(), to obtain the server's time
• setTimeout(), to schedule a function to be executed at a certain server time

CometD 2 Authentication

CometD 2 Authentication

Authentication is a complex task, and can be achieved in many ways, and most often each way is peculiar to a particular project.

Below you can find few ideas on how you can perform authentication.

Authentication via XMLHttpRequest

Authentication information could be passed by the CometD JavaScript client to the server via XMLHttpRequest.open(method, url, async, user, password), but this is currently not well supported.
The main reason is that it will not work in the cross domain case, since XMLHttpRequest does not support cross domain authentication.

Authentication via HTTP request headers

Authentication information can be passed by the CometD JavaScript client to the server via HTTP request headers in each CometD request, and verified by the server (for example via a servlet filter).
It's possible to specify such request headers using the requestHeaders configuration parameter as specified here.

Authentication via Bayeux SecurityPolicy and Extension

This method is more complicated than previous ones, but gives more flexibility.
Authentication information can be passed by the CometD JavaScript client to the server during Bayeux handshake.
The CometD JavaScript client handshake() and init() methods take an extra object that's merged with the handshake message, for example:

cometd.configure({
    url: 'http://localhost:8080/myapp/cometd'
});

// Register a listener to be notified of authentication success or failure
cometd.addListener('/meta/handshake', function(message) 
{
    var auth = message.ext && message.ext.authentication;
    if (auth && auth.failed === true)
    {
        // Authentication failed, tell the user
        window.alert('Authentication failed!');
    }
});

var username = 'foo';
var password = 'bar';

// Send the authentication information
cometd.handshake({
    ext: {
        authentication: {
            user: username,
            credentials: password
        }
    }
});

The Bayeux specification suggests that authentication information is stored in the ext field of the handshake message (see here).

On the server, we need to configure the BayeuxServer object with an implementation of org.cometd.bayeux.server.SecurityPolicy (to deny the handshake to clients that provide bad authentication information).

The BayeuxServer object need to be configured with the custom security policy, for example using a configuration servlet:

public class BayeuxInitializer extends GenericServlet
{
    @Override
    public void init() throws ServletException
    {
        BayeuxServer bayeux = (BayeuxServer)getServletContext().getAttribute(BayeuxServer.ATTRIBUTE);
        BayeuxAuthenticator authenticator = new BayeuxAuthenticator();
        bayeux.setSecurityPolicy(authenticator);
    }

    @Override
    public void service(ServletRequest req, ServletResponse res) throws ServletException, IOException
    {
        throw new ServletException();
    }
}

Below you can find the code for the BayeuxAuthenticator class:

public class BayeuxAuthenticator extends DefaultSecurityPolicy implements ServerSession.RemoveListener      (1)
{
    @Override
    public boolean canHandshake(BayeuxServer server, ServerSession session, ServerMessage message)          (2)
    {
        if (session.isLocalSession())                                                                       (3)
            return true;

        Map<String, Object> ext = message.getExt();
        if (ext == null)
            return false;

        Map<String, Object> authentication = (Map<String, Object>)ext.get("authentication");
        if (authentication == null)
            return false;

        Object authenticationData = verify(authentication);                                                 (4)
        if (authenticationData == null)
            return false;

        // Authentication successful                                      

        // Link authentication data to the session                                                          (5)

        // Be notified when the session disappears
        session.addListener(this);                                                                          (6)

        return true;
    }

    public void removed(ServerSession session, boolean expired)                                             (7)
    {
        // Unlink authentication data from the remote client                                                (8)
    }
}

Note that:

• in (1) we make BayeuxAuthenticator be a SecurityPolicy and a ServerSession.RemoveListener, since the code is really tied together
• in (2) we override canHandshake() (a SecurityPolicy method), where we extract the authentication information from the message sent by the client
• in (3) we allow handshake for any server-side local session (such as those associated with services)
• in (4) we verify the authentication information sent by the client, and obtain back server-side authentication data that we can later associate with the remote client
• in (5) we link the server-side authentication data to the session
• in (6) we register to be notified when the remote client disappears (which we will react to in (8))
• in (7) we implement removed() (a RemoveListener method), which is called when the remote client disappears, either because it disconnected or because it crashed
• in (8) we unlink the server-side authentication data from the remote client object, the operation opposite to (5)

The most important steps are the number 5 and the number 8, where the server-side authentication data is linked/unlinked to/from the org.cometd.bayeux.server.ServerSession object.
This linking depends very much from project to project.
It may link a database primary key (of the row representing the user account) with the remote session id (obtained with session.getId()), and/or viceversa, or it may link OAUTH tokens with the remote session id, etc.

Each Bayeux message always come with a session id, which can be thought as similar to the HTTP session id.
In the same way it is widespread practice to put the server-side authentication data in the HttpSession object (identified by the HTTP session id), in CometD web applications we can put server-side authentication data in the ServerSession object.

The Bayeux session ids are long, randomly generated numbers, exactly like HTTP session ids, and offer the same level security offered by a HTTP session id.
If an attacker manages to sniff a Bayeux session id, it can impersonate that Bayeux session exactly in the same way it can sniff a HTTP session id and impersonate that HTTP session.
And, of course, the same solutions to this problem used to secure Http applications can be used to secure CometD web applications.

Customizing the handshake response message

The handshake response message can be customized, for example adding an object to the ext field of the response, that specify further challenges data or the code/reason of the failure, and what action should be done by the client (for example, disconnecting or retrying the handshake).

This is an example of how the handshake response message can be customized in the SecurityPolicy:

public class MySecurityPolicy extends DefaultSecurityPolicy
{
    public boolean canHandshake(BayeuxServer server, ServerSession session, ServerMessage message)
    {
        if (!canAuthenticate(session, message))
        {
            // Retrieve the handshake response
            ServerMessage.Mutable handshakeReply = message.getAssociated();

            // Modify the advice, in this case tell to try again
            // If the advice is not modified it will default to disconnect the client
            Map advice = handshakeReply.getAdvice(true);
            advice.put(Message.RECONNECT_FIELD, Message.RECONNECT_HANDSHAKE_VALUE);
            
            // Modify the ext field with extra information on the authentication failure
            Map ext = handshakeReply.getExt(true);
            Map authentication = new HashMap();
            ext.put("com.acme.auth", authentication);
            authentication.put("failureReason", "invalid_credentials");
            return false;
        }
        return true;
    }
}

Alternatively, it is possible to customize the handshake response message by implementing a BayeuxServer.Extension:

public class HandshakeExtension implements BayeuxServer.Extension
{
    public boolean sendMeta(ServerSession to, ServerMessage.Mutable message)
    {
        if (Channel.META_HANDSHAKE.equals(message.getChannel()))
        {
            if (!message.isSuccessful())
            {
                Map advice = message.getAdvice(true);
                advice.put(Message.RECONNECT_FIELD, Message.RECONNECT_HANDSHAKE_VALUE);

                Map ext = message.getExt(true);
                Map authentication = new HashMap();
                ext.put("com.acme.auth", authentication);
                authentication.put("failureReason", "invalid_credentials");
            }
        }
    }

    // Other methods omitted
}

CometD 2 Load Testing

CometD 2 Load Testing

The CometD project comes with a load test tool that can be used to get the gist of how CometD scales.
Note however that real deployments often have a totally different behavior that depends on OS settings, TCP stack settings, other network settings, JVM settings and application settings, so the basic load test tool gives you information only up to a point.

Setup

Load testing can be very stressful to the OS, TCP stack and network, so you need to tune a few values to avoid that the OS, TCP stack or network become a bottleneck, making you think the CometD does not scale. It does scale.
The setup must be done on both client(s) and server.
A suggested setup is the following (for Linux; it may vary for other operative systems):

# ulimit -n 65536
# ifconfig eth0 txqueuelen 8192 # replace eth0 with the ethernet interface you are using
# /sbin/sysctl -w net.core.somaxconn=4096
# /sbin/sysctl -w net.core.netdev_max_backlog=16384
# /sbin/sysctl -w net.core.rmem_max=16777216
# /sbin/sysctl -w net.core.wmem_max=16777216
# /sbin/sysctl -w net.ipv4.tcp_max_syn_backlog=8192
# /sbin/sysctl -w net.ipv4.tcp_syncookies=1

Read also here for more information.

Running the server

If you have already deployed your Bayeux server, then you can use that as a load test server. The load test tool only requires to handshake, subscribe and publish to normal channels, which is what any Bayeux server can do out of the box.
If you have installed a security policy (see here), you may need to tweak the load test tool to satisfy the policy conditions (for example by adding security tokens and the like).
If you use your server, however, you will loose some important report that is available in the CometD load server (but that you can add to your server by looking at how it is done in the CometD load server).

If you don't have a server already running, then you need to build and run the CometD load server.
Follow the instructions in the build section to build the whole project (if not already done), then issue these commands in a terminal window:

$ cd cometd-java/cometd-java-examples // Use "cd cometd-java/cometd-java-client" for CometD versions prior 2.4.0  
$ mvn -Pserver install exec:exec

This command launches the CometD load server after a number of questions prompted in the terminal window; you can additionally tweak the command line by tweaking the pom.xml section related to the "server" profile.

Running the load test client

The load test client can be run on a different host than the server, and you need to build and run the tool from the sources.
Follow the instructions in the build section to build the whole project (if not already done), then issue these commands:

$ cd cometd-java/cometd-java-examples // Use "cd cometd-java/cometd-java-client" for CometD versions prior 2.4.0  
$ mvn -Pclient install exec:exec

This command launches the CometD load client after a number of questions prompted in the terminal window; you can additionally tweak the command line by tweaking the pom.xml section related to the "client" profile.

The load test tool simulates a chat client and prompts you for configuration options:

server [localhost]: 
port [8080]: 
transports:
  0 - long-polling
  1 - websocket
transport [0]: 1
use ssl [false]: 
max threads [256]: 
context [/cometd]: 
channel [/chat/demo]: 
rooms [100]: 
rooms per client [1]: 
record latency details [true]: 
-----
clients [100]: 1000
Waiting for clients to be ready...
Waiting for clients 999/1000
Clients ready
batch count [1000]: 
batch size [10]: 1
batch pause (µs) [10000]: 
message size [50]: 
randomize sends [false]: 

The default configuration connects 100 Bayeux clients to the server at http://localhost:8080/cometd, then sends 1000 batches of 10 messages (of size 50 bytes) with 10 ms pauses between each batch, choosing a random client for each batch as the sender. The client sends the messages to the chat room(s) it is subscribed to, the messages arrive to the server and the server broadcasted them back to the subscribers of the chat room(s), that receive the messages.
The latency between the sends and the receives is then measured and displayed, for example:

Outgoing: Elapsed | Rate = 10273 ms | 973 messages/s - 97 requests/s
Waiting for messages to arrive 15815/15868
All messages arrived 15868/15868
Messages - Success/Expected = 15868/15868
Incoming - Elapsed | Rate = 10667 ms | 1487 messages/s 
Messages - Latency Distribution Curve (X axis: Frequency, Y axis: Latency):
             @        _  13 ms (2436)
   @                  _  26 ms (581)
                   @  _  39 ms (3805)
                 @    _  52 ms (3301)
         @            _  65 ms (1802)
        @             _  78 ms (1501)
     @                _  91 ms (1029)
   @                  _  104 ms (537)
 @                    _  117 ms (280)
 @                    _  130 ms (163)
 @                    _  142 ms (158)
 @                    _  155 ms (107)
@                     _  168 ms (76)
@                     _  181 ms (30)
@                     _  194 ms (17)
@                     _  207 ms (33)
@                     _  220 ms (9)
@                     _  233 ms (1)
@                     _  246 ms (0)
@                     _  259 ms (2)
Messages - Latency Min/Ave/Max = 0/48/259 ms

Note how we chose a delay of 10 ms between batches, yielding a potential of 1000 messages sent/s (10 sends every 10 ms), and actually achieved 973 sends/s.

The number of messages depends on how many clients are subscribed to each chat room: sending one message to a chat room with 5 subscribers results in one messages being broadcasted back to each of the 5 subscribers.
In the example above we sent 10000 messages and received 15868, which makes sense since we have 100 clients subscribed randomly to 100 rooms so in average we have one client per room (with some room empty and some room with more than one subscriber). Had we chosen 1 chat room only, we would have had 10000 * 100 messages back (i.e. each message sent would have been broadcasted back to the 100 clients).

The rate of messages back is 1487 messages/s, and again makes sense that it is greater than the send rate if we consider that due to the random subscription, each message sent could have generated more than one message sent back (when more than one client is subscribed to the same chat room).

For the latency distribution curve, imagine to rotate it 90 degrees counter-clockwise. It shows a bell-shaped curve with the peak at around 33 ms, and reports the number of messages (in parenthesis) received in each interval of time. In the curve above, 2436 messages were received with a latency between 0 and 13 ms, 581 messages with a latency between 13 and 26 ms, and so on.

Finally, the minimum, average and maximum latency are reported.

Exiting the load test tool

To exit the load test tool by disconnecting orderly the clients, just enter 0 as the number of clients:

-----
clients [100]: 0
Waiting for clients to be ready...
Waiting for clients 68/0
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 45 seconds
[INFO] Finished at: Wed Mar 31 18:20:15 CEST 2010
[INFO] Final Memory: 33M/216M
[INFO] ------------------------------------------------------------------------

Warnings

There are many things that can influence the results of the load testing.
Among many the most important two are:

• OS / network stack setup
  See the section on setting up things above for details.
• Resolution of the sleep timer
  Pauses in the load test tool are implemented via Thread.sleep(). If you choose a 10 ms pause (equivalent to 10000 µs), it may happen that the actual time elapsed in sleep mode is way longer that what you specified.
  This is because when Thread.sleep() communicates to the JVM and then to the OS to sleep 10 ms, the OS may have a coarser sleep resolution, and actually sleep for 25 ms or more.
  To avoid this problem, the load test tool auto-tunes itself by detecting the timer resolution on startup.
  It is not uncommon, especially for virtualized servers, to have timer resolutions as high as 64 ms.

CometD 2 Strict Message Ordering

CometD 2 Strict Message Ordering

CometD does not enforce, by default, a strict order on message delivery. The reason is that there are (normally) two communication conducts between client and server: the meta connect conduct and the current request conduct (originated, for example, by a publish() performed by the client).
If the server receives two messages in different times for a client - say message1 and message2, it is possible that message1 is included in the response of a meta connect, but message2 is included in the response of a current request.
Because the messages are delivered on two different and independent communication conducts, it is possible that message2 arrives to the client before message1, for example because the thread scheduling on the server favored message2 or because the TCP communication for message1 was somehow slowed down (not to mention that browsers could as well be source of uncertainty).

CometD allows to enforce strict message ordering in two ways: using the acknowledge extension (which also provides delivery guarantee), or by specifying the long-polling.json.metaConnectDeliverOnly parameter for the long-polling server transport or, since CometD 2.4.0, the ws.metaConnectDeliverOnly parameter for the websocket server transport (see the configuration options).

The websocket transport enforces strict message ordering by returning messages via the the meta connect response instead of the current request, even if there is only one conduct.

The callback-polling server transport always enforce strict message ordering (and it is not possible to disable it).

When strict message ordering is enabled, all messages will be delivered via the meta connect response. In the example above, message1 will be delivered to the client, and message2 will wait on the server until another long poll is issued by the client (which happens immediately after message1 has been received).
It is clear that strict message ordering comes at the small price of slightly increased latencies (message2 has to wait the next long poll before being delivered), and slightly more activity for the server (since meta connects will be resumed more frequently than normal).

CometD 2 & WebSocket

Enabling/Disabling WebSocket support in CometD 2

Since CometD 2.1.0, WebSocket support has been disabled by default, since the support in browsers is still too buggy.
The JavaScript WebSocket transport is there, but it's disabled.

However, the CometD demo has WebSocket support enabled, and you can have that too in your applications simply by executing this code in your JavaScript application:

// Using dojo style; use $.cometd for jQuery
var cometd = dojox.cometd;
cometd.websocketEnabled = true;

This code must be execute before the handshake to be effective.

CometD 2 & Servlet Containers

CometD 2 Configuration in Servlet Containers

CometD relies on Jetty Continuations, a library that is portable among servlet containers.

While CometD 2 runs natively in Jetty 7 and in Servlet 3 compliant servlet containers, it requires additional configuration for other servlet containers such as Jetty 6 or Tomcat 6.

These other servlet containers need a ContinuationFilter to be configured for the paths that make use of Jetty Continuations (in CometD this path is usually "/cometd/*"), for example:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>cometd</servlet-name>
        <servlet-class>org.cometd.server.CometdServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>cometd</servlet-name>
        <url-pattern>/cometd/*</url-pattern>
    </servlet-mapping>

    <filter>
        <filter-name>continuation</filter-name>
        <filter-class>org.eclipse.jetty.continuation.ContinuationFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>continuation</filter-name>
        <url-pattern>/cometd/*</url-pattern>
    </filter-mapping>
</web-app>

In this example, the CometdServlet, which makes use of Jetty Continuations, is mapped to /cometd/*, and therefore the ContinuationFilter must also be mapped on that path.

quick start

quick start

building

building

quick start

quick start

building

building