The CometD Reference Book – 4.0.9

This mode of running the CometD Demos is suggested if you want to take a quick look at the CometD Demos and if you are prototyping/experimenting with your application, but it’s not the recommended way to deploy a CometD application in production. See the next section for the suggested way to deploy your CometD application in production.

Maven requires you to set up the JAVA_HOME environment variable to point to your JDK installation.

After that, running the CometD demos is very simple. Assuming that $COMETD is the CometD installation directory, and that you have the mvn executable in your path:

The last command starts an embedded Jetty server that listens on port 8080 for clear-text HTTP/1.1 (http) and on port 8443 for both encrypted HTTP/1.1 and HTTP/2 (https). Now point your browser to http://localhost:8080 or to https://localhost:8443 to see the CometD Demos main page.

When connecting using https, the browser may display a page that says something like "Your connection is not secure" or "This site is not secure". Don’t worry, this message is due to the fact that the CometD Demos use a self-signed certificate to encrypt the traffic between the browser and the embedded Jetty server. The browser will display a button or a link to consider the site safe and you will be able to continue to the CometD Demos main page.

The instructions below describe a very minimal Jetty setup that is needed to run CometD applications. Refer to the official Jetty documentation for further details about configuring Jetty.

Follow these steps to deploy your CometD application into Jetty. These instructions are valid for Unix/Linux operative systems, but can be easily translated for the Windows operative system.

Download the Jetty distribution from the Eclipse Jetty Downloads.

Then unpack the Jetty distribution in a directory of your choice, for example /tmp:

This creates a directory called /tmp/jetty-distribution-<version>/ that is referred to as the JETTY_HOME.

Create another directory of your choice, for example in your home directory:

This creates a directory called ~/jetty_cometd that is referred to as the JETTY_BASE.

Since Jetty is a highly modular Servlet Container, the JETTY_BASE is the directory where you configure Jetty with the Jetty modules that are needed to run your CometD application.

In order to run CometD applications, Jetty needs to be configured with these modules:

Therefore:

Now Jetty is configured to run CometD applications, and you just need to deploy your .war file to Jetty (you can use the CometD Demos .war file if you have not built your application yet):

Now you can start Jetty:

This last command starts Jetty, which deploys your .war file and makes your CometD application "live".

You can also deploy your CometD application programmatically, using the Jetty APIs to embed your web application as a normal Java application that you would start via command line.

Below you can find an example that shows how to setup Jetty embedded and CometD with support for HTTP, HTTPS and WebSocket transports:

Steps similar to what described above for Jetty are what you need to do to deploy your CometD application to different Servlet Containers.

Refer to the specific Servlet Container configuration manual for how to deploy the CometD application .war file in the Servlet Container of your choice.

To enable debug logging on the JavaScript client library (see also the JavaScript library section) you must pass the logLevel field to the configuration of the cometd object, with value 'debug' (see also the JavaScript library configuration section for other configuration options):

The CometD JavaScript library uses the window.console object to output log statements.

Once you have logging enabled on the JavaScript client library, you can see the debug logs in the browser JavaScript console. For example, in Firefox you can open the JavaScript console by clicking on Tools → Web Developer → Web Console, while in Chrome you can open the JavaScript console by clicking on Tools → Developer Tools.

The Java server library uses the SLF4J APIs, but it does not bind to any specific logging implementation. You have to choose what implementation you want to use. By default, SLF4J comes with with a simple binding that does not log statements produced at debug level.

Therefore you must configure SLF4J with a more advanced binding such as Log4J2 or Logback. Refer to the SLF4J documentation and the binding implementation documentation on how to configure logging when using these advanced bindings.

Therefore, to enable CometD debug logging for your application you need to configure whatever SLF4J binding you have chosen to use.

Once you have logging enabled on the Java server library, you can see the debug logs in the terminal where you launched your Servlet Container (or in its log files, depending on how it is configured).

Setting up a project based on the CometD libraries using Maven uses 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:

As you can see, there are four archetypes available that build a skeleton application using the Dojo or jQuery JavaScript toolkits, both with the choice of using Jetty 9 and/or Spring. Choose Dojo with Jetty 9, which is archetype number 1. The archetype generation requires that you define several properties and generates the application skeleton for you, for example:

Then:

The skeleton project now exists as follows:

The skeleton project is ready for you to run using the following command:

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

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

If you want to use a Jetty version different from CometD’s default Jetty version, you can easily do so by opening the main pom.xml file and modifying the value of the jetty-version element, for example:

Then you just need to re-build and re-run the project as explained above.

The first step is to configure your favorite JavaScript toolkit, in the example Dojo, that the web container must serve. Using the Maven Way, this is obtained automatically by overlaying the CometD Dojo bindings WAR file, cometd-javascript-dojo-<version>.war, but here you must do it manually (the cometd-javascript-dojo-<version>.war is located in the cometd-javascript/dojo/target directory of the CometD distribution).

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

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

The second step is to configure the server side. If you use Java, this means that you have to set up the CometD servlet that responds to messages from clients. The details of the server side configuration and service development are explained in the Java server library section.

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.

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

It also configures a JavaScript configuration object, config, with variables that the JavaScript application might need. This is totally optional.

The JavaScript application, contained in the application.js file, configures the cometd object and starts the application. The archetypes provide:

Notice the following:

A channel is a string that looks like a URL path such as /foo/bar, /meta/connect or /service/chat.

The Bayeux specification defines three types of channels: meta channels, service channels and broadcast channels.

A channel that starts with /meta/ is a meta channel, a channel that starts with /service/ is a service channel, and all other channels are broadcast channels.

A message whose channel field is a meta channel is referred to as a meta message, and similarly there are service messages and broadcast messages.

The application creates service channels and broadcast channels; an application can create as many as it needs, and can do so at any time.

Sessions are a central concept in CometD. They are the representation of the half-objects involved in the protocol communication.

There are three types of sessions:

The server is represented by an instance of org.cometd.bayeux.server.BayeuxServer. The BayeuxServer object acts as a:

Applications use listeners to interact with sessions, channels and the server. The Java and JavaScript APIs allow applications to register different kinds of listeners that receive notifications of the correspondent events. You can usefully think of extensions, security policies and authorizers as special types of listeners. The following sections treat them as such.

This section describes message processing on both the client and the server. Use the following image to understand the detailed components view that make up the client and the server.

When a client sends messages, it uses the client-side channel to publish them. The client retrieves the client channel from the client session via ClientSession.getChannel(String). Messages first pass through the extensions, which process messages one by one; if one extension denies processing of a message, it is deleted and it is not sent to the server. At the end of extension processing, the messages pass to the client transport.

The client transport converts the messages to JSON (for the Java client, this is done by a JSONContext.Client instance, see also the JSON section), establishes the conduit with the server transport and then sends the JSON string over the conduit, as the payload of a transport-specific envelope (for example, an HTTP request or a WebSocket message).

The envelope travels to the server, where the server transport receives it. The server transport converts the messages from the JSON format back to message objects (through a JSONContext.Server instance, see also the JSON section), then passes them to the BayeuxServer instance for processing.

The BayeuxServer processes each message in the following steps:

The round trip from client to server back to client is now complete.

When Bayeux messages are received by the server, a thread is allocated (by the Servlet Container, not by CometD) to process the messages, and server-side CometD listeners are invoked in this thread. The CometD implementation does not spawn new threads to call server-side listeners; in this way the threading model is kept simple and very similar to the Servlet threading model. Because this is the thread that runs the CometD code, let’s call it the CometD thread.

The CometD implementation also relies on a scheduler to perform periodic or delayed tasks. The execution of these tasks may invoke server-side CometD listeners, notably implementations of BayeuxServer.SessionListener#sessionRemoved() and ServerSession.RemoveListener#removed().

This simple threading model implies that if a server-side CometD listener takes a long time to process the message and to return control to the implementation, then the implementation cannot process the next messages that may arrive, most often halting the whole server processing and causing client disconnections.

This is due to the fact that a Bayeux client uses a limited number of connections to interact with the server. If a message sent to one connection takes a long time to be processed on the server, the client may send additional messages on that connection, but those will not be processed until the previous message processing ends.

It is therefore very important that if the application knows that a message may trigger a time consuming task (for example a database query), it does so in a separate thread, with a timeout to avoid to wait too long.

Similarly, if the application must contact an external service to provide an answer to the CometD implementation, it must arrange things in a way that either the external service is invoked in a separate thread, or invoking the external service is itself non-blocking and based on callbacks (or another similar mechanism). See the asynchronous authentication examples below.

Services (see also the java server services section) are an easy way to setup server-side listeners but share the same threading model with normal server-side listeners: if they need to perform time consuming tasks, they need to do so in a separate thread, for example:

Now that you know that applications interact with CometD through listeners, and how both the client and the server process messages, you need to know what an application should do to interact with messages to perform its business logic.

A client communicates with the server by exchanging Bayeux messages.

The Bayeux protocol requires that the first message a new client sends be a handshake message (a message sent on /meta/handshake channel). On the server, if the processing of the incoming handshake message is successful, BayeuxServer creates the server-side half-object instance (ServerSession) that represents the client that initiated the handshake. When the processing of the handshake completes, the server sends back a handshake reply to the client.

The client processes the handshake reply, and if it is successful, starts – under the covers – a heartbeat mechanism with the server, by exchanging connect messages (a message sent on a /meta/connect channel). The details of this heartbeat mechanism depend on the client transport used, but can be seen as the client sending a connect message and expecting a reply after some time (when using HTTP transports, the heartbeat mechanism is also known as long-polling). The heartbeat mechanism allows a client to detect if the server is gone (the client does not receive the connect message reply from the server), and allows the server to detect if the client is gone (the server does not receive the connect message request from the client).

Connect messages continue to flow between client and server until either side decides to disconnect by sending a disconnect message (a message sent on the /meta/disconnect channel).

While connected to the server, a client can subscribe to channels by sending a subscribe message (a message sent on a /meta/subscribe channel). Likewise, a client can unsubscribe from a channel by sending an unsubscribe message (a message sent on a /meta/unsubscribe channel). A client can publish messages containing application-specific data at any time while it is connected, and to any broadcast channel (even if it is not subscribed to that channel).

The Bayeux protocol message format is the JSON format, because the Bayeux protocol was designed when JavaScript did not have binary data types.

Recent versions of JavaScript have typed arrays that can be used to represent raw binary data such as files or images. A typical example of a JavaScript typed array is Uint8Array that represents an array of unsigned, 8-bit, integers. In turn, typed arrays are based on the lower level ArrayBuffer and DataView types.

The JavaScript Web APIs have been enriched to use ArrayBuffer or higher level typed arrays such as Uint8Array. In this way, applications can now read the content of a file via JavaScript APIs such as FileReader.readAsArrayBuffer() or use XMLHttpRequest to send and receive data as ArrayBuffer.

Java, of course, always had binary types in the form of byte[] and ByteBuffer.

Since Bayeux messages can only carry data in textual representation, the CometD libraries support upload and download of binary data by converting the binary data represented by JavaScript’s ArrayBuffer or Java’s byte[] into a textual format using the Z85 encoding/decoding and by using a specific format for the data field of a message.

The encoding/decoding to/from the binary representation is performed by CometD extensions on both the client and the server, see the binary extension section.

When transporting binary data, the format of the data field of a message is a specific one, represented by the org.cometd.bayeux.BinaryData class in Java and by an equivalent structure in JavaScript, that is an object with the following fields:

A complete binary message therefore looks like this, in JSON format, after the Z85 encoding:

Applications do not need to worry about the specific message format above because CometD offers APIs that simplify the creation of messages with binary data, for example see how to publish binary data from JavaScript, how to publish binary data from Java and the binary services section. The CometD implementation takes care of producing the right message format under the covers.

JavaScript applications can use ArrayBuffer, DataView or any typed array object as the binary representation.

Java applications (either client or server) must use the org.cometd.bayeux.BinaryData object as the binary representation.

Sometimes there is the need to connect to multiple Bayeux servers. The default cometd object available as dojox.cometd or $.cometd can only be configured to connect to one server.

However, it is easy to create other cometd objects. In Dojo, there is a dojox.CometD (note the capital 'C' and 'D' of CometD) constructor function that can be used to create new cometd objects. In jQuery, there is an equivalent $.CometD constructor function. It can be used in this way:

Note how the two cometd objects are initialized with different URLs.

Configuring extensions in the default cometd object is covered in the extensions section. To configure extensions for the additional cometd objects must be done manually in the following way:

You should not configure the extensions for the default cometd object in this way, but instead follow the extensions section.

You should configure extension manually like shown above only for additional cometd objects. You can configure zero, one, or all the extensions for the additional cometd objects, depending on your application needs.

It is not possible to subscribe to meta channels: the server replies with an error message. It is possible to listen to meta channels (see this section for an explanation of the difference between subscribers and listeners). You cannot (and 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 are used in the case of request/response style of communication between client and server (as opposed to the publish/subscribe style of communication on broadcast 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 is 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 it) using service channels.

Broadcast 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 broadcast channels and to publish to broadcast channels; this can only be forbidden using a security policy on the Bayeux server (see also the java server authorization section) or by using authorizers (see also the authorizers section). Broadcast channels are useful to broadcast messages to all subscribed clients, for example in case of a stock price change.

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

The addListener() function:

The subscribe() function:

If you want to be certain that the server received your subscription request (or not), you can either register a /meta/subscribe listener, or pass a callback function to subscribe():

Remember that subscriptions may fail on the server (for example, the client does not have enough permissions to subscribe) or on the client (for example, there is a network failure). In both cases /meta/subscribe listener, or the callback function, will be invoked with an unsuccessful subscribe message reply.

You can pass additional information to the subscribe message by passing an additional object to the subscribe() function:

Remember that the subscribe message is sent to the server only when subscribing to a channel for the first time. Additional subscriptions to the same channel will not result in a message being sent to the server. See also the javascript handshake section for further information about passing additional objects.

Both addListener() and subscribe() return a subscription object that is opaque to applications (that is, applications should not try to use the fields of this object since its format may vary across CometD releases).

The returned subscription object should be passed to, respectively, removeListener() and unsubscribe():

Function unsubscribe() can too take an additional object and a callback function as parameters:

Similarly to subscribe(), the unsubscribe message is sent to the server only when unsubscribing from a channel for the last time. See also the javascript handshake section for further information about passing additional objects.

The major difference between listeners and subscribers is that subscribers are automatically removed upon re-handshake, while listeners are not modified by a re-handshake. When a client subscribes to a channel, the server maintains a client-specific server-side subscription state. If the server requires a re-handshake, it means that it lost the state for that client, and therefore also the server-side subscription state. In order to maintain the client-side state consistent with that of the server, subscriptions – but not listeners – are automatically removed upon re-handshake.

A good place in the code to perform subscriptions is in a /meta/handshake function. Since /meta/handshake listeners are invoked in both explicit handshakes the client performs and in re-handshakes the server triggers, it is guaranteed that your subscriptions are always performed properly and kept consistent with the server state.

Equivalently, a callback function passed to the handshake() function behaves exactly like a /meta/handshake listener, and therefore can be used to perform subscriptions.

Applications do not need to unsubscribe in case of re-handshake; the CometD library takes care of removing all subscriptions upon re-handshake, so that when the /meta/handshake function executes again the subscriptions are correctly restored (and not duplicated).

For the same reason, you should never add listeners inside a /meta/handshake function, because this will add another listener without removing the previous one, resulting in multiple notifications of the same messages.

In cases where the Bayeux server is not reachable (due to network failures or because the server crashed), subscribe() and unsubscribe() behave as follows:

Often times, applications need to perform dynamic subscriptions and unsubscriptions, for example when a user clicks on a user interface element, you want to subscribe to a certain channel. In this case the subscription object returned upon subscription is stored to be able to dynamically unsubscribe from the channel upon user demand:

In case of a re-handshake, dynamic subscriptions are cleared (like any other subscription) and the application needs to figure out which dynamic subscription must be performed again. This information is already known to CometD at the moment cometd.subscribe(…​) was called (above in function dynamicSubscribe()), so applications can just call resubscribe() using the subscription object obtained from subscribe():

If a listener or subscriber function throws an exception (for example, calls a function on an undefined object), 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:

It is 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 does not break. Notice that a similar mechanism exists for extensions, see also the extensions section.

It is possible to subscribe to several channels simultaneously using wildcards:

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

With the double asterisk, the channels /events/stock/FOO and /events/forex/EUR 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 as follows:

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

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

Each meta channel is notified when the JavaScript CometD implementation handles the correspondent Bayeux message. 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, you can use it, 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.

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

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 server returns the active poll 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 use 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.

The publish() function allows you to publish data onto a certain channel:

You cannot (and it makes no sense to) publish to a meta channel, but you can publish to a service or broadcast channel even if you are not subscribed to that channel. However, you have to handshake (see the handshake section) before you can 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.

When the message you published arrives to the server, the server replies to the client with a publish acknowledgment; this allows clients to be sure that the message reached the server. The publish acknowledgment arrives on the same channel the message was published to, with the same message id, with a successful field. If the message publish fails for any reason, for example because server cannot be reached, then a publish failure will be emitted, similarly to a publish acknowledgment.

For historical reasons, publish acknowledgments and failures are notified on the /meta/publish channel (only in the JavaScript library), even if the /meta/publish channel is not part of the Bayeux protocol.

In order to be notified of publish acknowledgments or failures, is it recommended that you use this variant of the publish() function, passing a callback function:

If you need to publish several messages, possibly to different channels, you might want to use the javascript batch section.

When you publish to a broadcast channel, the server will automatically deliver the message to all subscribers for that channel. This is the publish/subscribe messaging style.

When you publish to a service channel, the server will receive the message but the message journey will end on the server, and the message will not be delivered to any remote client. The message should contain an application-specific identifier of the recipient of the message, so that application-specific code on the server can extract this identifier and deliver the message to that particular recipient. This is the peer-to-peer messaging style.

You can publish binary data by using the specialized publishBinary() API. A similar specialized API exists to perform remote calls with binary data.

Remember that you must have the binary extension enabled as specified in the binary extension section.

To publish binary data, you must first create or obtain a JavaScript typed array, a DataView or an ArrayBuffer, and then use the publishBinary() API:

In the example above, the binary data to send can be either the buffer or the view. The third parameter to publishBinary() is the last parameter that indicates whether the binary data is the last chunk; when omitted, it defaults to true. The fourth parameter to publishBinary() is the meta parameter that associates additional information to the binary data, and may be omitted.

Like normal publish() calls, you can pass as last parameter to publishBinary() a function that is notified of the publish acknowledgement.

When you need to just call the server to perform some action, such as retrieving data from a database, or updating some server state, you want to use a remote call:

The first argument of remoteCall() is the target of the remote call. You can think of it as a method name to invoke on the server, or you can think of it as the action you want to perform. It may or may not have a leading / character, and may be composed of multiple segments such as target/subtarget.

The second argument of remoteCall() is an object with the arguments of the remote call. You can think of it as the arguments of the remote method call, reified as an object, or you can think of it as the data needed to perform the action.

The third, optional, argument of remoteCall() is the timeout, in milliseconds, for the remote call to complete. If the timeout expires, the callback function will be invoked with a response object whose successful field is set to false, and whose error field is set to '406::timeout'. The default value of the timeout is the value specified by the maxNetworkDelay parameter. A negative value or 0 disables the timeout.

The last argument of remoteCall() is the callback function invoked when the remote call returns, or when it fails (for example due to network failures), or when it times out.

The following table shows what response fields are present in the response object passed to the callback, in what cases:

Internally, remote calls are translated to messages published to a service channel, and handled on the server side by means of an annotated service, in particular one with a @RemoteCall annotation.

However, remote calls are much simpler to use than service channels since the correlation between request and response is performed by CometD, along with error handling. In this way, application have a much simpler API to use.

Similarly to publishing binary data, it is possible to send binary data when performing remote calls.

Remember that you must have the binary extension enabled in the client as specified in the binary extension section.

Here is an example that sends an ArrayBuffer:

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

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 that the state of all clients is lost). In this case, the reconnection mechanism on the client performs the following steps:

If you register meta channels listener, or if you use callback functions, be aware of these steps, since a reconnection might involve more than one message exchange with the server.

The long-polling transport is the default transport if the browser and the server do not support WebSockets. This transport is used when the communication with the Bayeux server happens on the same domain, and also in the cross-domain mode for recent browsers, such as Firefox 3.5+ (see also the cross origin section). The data is sent to the server by means of a POST request with Content-Type: application/json;charset=UTF-8 via a plain XMLHttpRequest call.

The callback-polling transport is used when the communication with the Bayeux server happens on a different domain and when the cross-domain mode is not supported (see also the cross origin section).

The JavaScript XMLHttpRequest object used to have restrictions when the invocation was directed to a domain different from the one to which the script had been downloaded.

Recent browsers implement now a version of XMLHttpRequest object that supports cross domain invocations, but for the invocation to succeed the server must collaborate, typically by deploying a cross origin servlet filter.

In case of older browsers or servers that do not deploy a cross origin solution, the callback-polling transport uses the JSONP script injection, which injects a <script> element whose src attribute points to the Bayeux server. The browser notices 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 the browser then executes, (and calls back into the JavaScript CometD implementation).

There are three main drawbacks in using this transport:

The websocket transport is available if the browser and the server support WebSocket. The WebSocket protocol is designed to be the bidirectional communication protocol for the web, so it is a natural fit in the CometD project.

The easiest way of enabling/disabling the websocket transport is to set a boolean variable before performing the initial CometD handshake:

An alternative way of disabling the websocket transport is to unregister its transport, see also the transport unregistering section.

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

The CometD JavaScript API allows you 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 might be unreliable. For example, it is possible to unregister the WebSocket transport by unregistering it with the following code:

Recent browsers introduced the capability for XMLHttpRequest calls to be performed towards a different domain (see HTTP Access Control). The JavaScript CometD implementation also supports this, with no configuration necessary on the client (if the browser supports XMLHttpRequest cross-domain calls, CometD uses them) and with a bit of configuration for the server, explained in this section.

To use the cross-domain mode, you need:

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

To initiate the communication with the Bayeux server, you need to call:

The following is a typical use:

BayeuxClient must be instantiated passing the absolute URL (and therefore including the scheme, host, optionally the port and the path) of the Bayeux server. The scheme of the URL must always be either "http" or "https". The CometD Java Client implementation will transparently take care of converting the scheme to "ws" or "wss" in case of usage of the WebSocket protocol.

Once handshake() has been called, you must not call handshake() again unless you have explicitly disconnected by calling disconnect().

When handshake() is called, the BayeuxClient performs the handshake with the Bayeux server and establishes the long poll connection asynchronously.

To verify that the handshake is successful, you can pass a callback MessageListener to BayeuxClient.handshake():

An alternative, equivalent, way is to add a MessageListener before calling BayeuxClient.handshake():

Another alternative is to use the built-in synchronous features of the BayeuxClient and wait for the handshake to complete:

The BayeuxClient.waitFor() method waits the given timeout (in milliseconds) for the BayeuxClient to reach the given state, and returns true if the state is reached before the timeout expires.

The following sections provide information about subscribing and unsubscribing to channels.

CometD allows you to send messages in two ways:

The first case is covered by the ClientSessionChannel.publish(…​) API. The second case is covered by the ClientSession.remoteCall() API.

Disconnecting is straightforward:

Like the other APIs, you can pass a callback MessageListener to be notified that the server received and processed the disconnect request:

Alternatively, you can block and wait for the disconnect to complete:

You can configure org.cometd.client.BayeuxClient class to use multiple transports. It currently supports the long-polling transport (that in turn depends on Jetty’s asynchronous HttpClient) and the websocket transport (that in turn depends on Jetty’s asynchronous WebSocketClient).

There are two WebSocket transports available:

You should configure BayeuxClient with the websocket transport before the long-polling transport, so that BayeuxClient can fall back to the long-polling if the websocket transport fails. You do so by listing the WebSocket transport before the HTTP transport on the BayeuxClient constructor, for example:

It is always recommended that the WebSocket transport is never used without a fallback transport such as LongPollingTransport. This is how you configure the Jetty WebSocket transport:

You can specify BayeuxServer parameters and server transport parameters in web.xml as init parameters of the org.cometd.server.CometDServlet. If the CometD servlet creates the BayeuxServer instance, the servlet init parameters are passed to the BayeuxServer instance, which in turn configures the server transports.

If you followed the primer, Maven has configured the web.xml file for you; here are details its configuration, a sample web.xml:

You must define and map the org.cometd.server.CometDServlet in web.xml to enable the server to interpret the Bayeux protocol. It is normally mapped to /cometd/*, but you can change the url-pattern mapping if you prefer, or even have multiple mappings.

Here is the list of configuration init parameters that the BayeuxServer implementation accepts:

A CometD service is a Java class that allows a developer to specify the code to run when Bayeux channels receive Bayeux messages. When a message arrives on a channel to which the service instance subscribes, CometD invokes a callback method to execute user-specific code.

CometD services can be of two kinds:

You can also integrate CometD services with the Spring Framework as explained in the Spring Framework integration section.

The following sections present details about Java Server Services.

You can configure the BayeuxServer object with an org.cometd.bayeux.server.SecurityPolicy object, which allows you to control various steps of the Bayeux protocol such as handshake, subscription, and publish. By default, the BayeuxServer object has a default SecurityPolicy, that allows almost any operation.

The org.cometd.bayeux.server.SecurityPolicy interface has a default implementation in org.cometd.server.DefaultSecurityPolicy, that is useful as a base class to customize the SecurityPolicy (see the authentication section for an example).

The org.cometd.bayeux.server.SecurityPolicy methods are:

Those methods control, respectively, whether a handshake, a channel creation, a subscription to a channel or a publish to a channel are to be authorized.

The default implementation org.cometd.server.DefaultSecurityPolicy:

A typical custom SecurityPolicy may override the canHandshake(…​) method to control authentication:

To understand how to install your custom SecurityPolicy on the BayeuxServer object, see how it is done in the authentication section.

Follow also the authorizers section for further information about authorization.

Authentication is a complex task, and can be achieved in many ways, and most often each way is peculiar to a particular application. That is why CometD does not provide an out of the box solution for authentication but provides APIs that applications can use to implement in few steps their own authentication mechanism.

The recommended way to perform authentication in CometD is to pass the authentication credentials in the initial handshake message.

Both the JavaScript handshake API and the Java Client handshake API allow an application to pass an additional object that will be merged into the handshake message and sent to the server:

The Bayeux Protocol specification suggests that the authentication information is stored in the ext field of the handshake message (see here) and it is good practice to use a fully qualified name for the extension field, such as com.myapp.authn.

On the server, you need to configure the BayeuxServer object with an implementation of org.cometd.bayeux.server.SecurityPolicy to deny the handshake to clients that provide wrong credentials.

The section on services integration shows how to perform the initialization and configuration of the BayeuxServer object, and you can use similar code to configure the SecurityPolicy too, for example below using a configuration servlet:

Below you can find the code for the MyAppAuthenticator class referenced above:

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 application to application. 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.

The linking should be performed by some other object that can then be used by other code of the application, for example:

And below you can find a very simple implementation of the Users class:

The Users object can now be injected in CometD services and its API enriched to fit the application needs such as retrieving the user name for a given session, or the ServerSession for a given user name, etc.

Alternatively, the linking/unlinking (steps 5 and 8 above) can be performed in a BayeuxServer.SessionListener. These listeners are invoked after SecurityPolicy.canHandshake() and are invoked also when a ServerSession is removed, therefore there is no need to register a RemoveListener with the ServerSession like done in step 6 above:

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 you 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, most notably the use of TLS.

CometD provides application with authorizers, a feature that allows fine-grained control of authorization on channel operations.

The CometD server can send and receive Bayeux messages. These messages may be transported to/from the CometD server using different wire transports. The most common wire transports are HTTP (both HTTP/1.1 and HTTP/2) and WebSocket.

Server-side components such as services (see also the services section), extensions (see also the extensions section) or authorizers (see also the authorizers section) may need to access contextual information, that is information provided by the Servlet environment such as request attributes, HTTP session attributes, servlet context attributes or network address information.

While the Servlet model can easily provide such information, CometD can use also non-HTTP transports such as WebSocket that may not have such information readily available. CometD abstracts the retrieval of contextual information for any transport via the org.cometd.bayeux.server.BayeuxContext class.

An instance of BayeuxContext can be obtained from a ServerMessage instance:

A typical usage in a SecurityPolicy (see also the authorization section) is the following:

Refer to the Javadoc documentation for further information about methods available in BayeuxContext.

It is recommended to always call ServerMessage.getBayeuxContext() to obtain the BayeuxContext instance; it should never be cached and then reused across messages. This allows maximum portability of your code in case you’re using a mix of WebSocket and HTTP transports.

Sometimes applications need to send non-urgent messages to clients; alert messages such as "email received" or "server uptime", are typical examples, but chat messages sometimes also fit this definition. While these messages need to reach the client(s) eventually, there is no need to deliver them immediately: they are queued into the ServerSession message queue, but their delivery can be postponed to the first occasion.

In CometD, "first occasion" means whichever of the following things occurs first (see also the server configuration section for information about configuring the following parameters):

To support this feature, CometD introduces the concepts of lazy channel and lazy messages.

An application can mark a message as lazy by calling ServerMessage.Mutable.setLazy(true) on the message instance itself, for example:

In this example, an external system invokes method LazyService.receiveNewsFromExternalSystem(…​) every time there is news, and the service broadcasts the news to all interested clients. However, since the news need not be delivered immediately, the message is marked as lazy. Each remote client possibly receives the message at a different time: some receive it immediately (because, for example, they have other non-lazy messages to be delivered), some receive it after few milliseconds (because, for example, their /meta/connect timeout expires in a few milliseconds), while others receive it only upon the whole maxLazyInterval timeout.

In the same way you can mark a message as lazy, you can also mark server channels as lazy. Every message that is published to a lazy channel becomes a lazy message which is then queued into the `ServerSession’s message queue for delivery on first occasion.

You can mark server channels as lazy at any time, but it is best to configure them as lazy at creation time, for example:

When a server channel is marked lazy, by default it has a lazy timeout specified by the global maxLazyTimeout parameter (see also the server configuration section).

In more sophisticated cases, you may want to specify different lazy timeouts for different server channels, for example:

In the example above, channel /news inherits the default maxLazyTimeout (5000 ms), while the /chat channel is configured with a specific lazy timeout of 2000 ms. A server channel that has a non-zero, positive lazy timeout is automatically marked as lazy.

If a wildcard server channel such as /chat/* is marked as lazy, then all messages sent to server channels that match that wildcard server channel (such as /chat/1) will be lazy. Conversely, if a non-wildcard server channel such as /news is lazy, then all messages sent to children server channels of that non-wildcard server channel (such as /news/sport) will not be lazy.

In the HTTP/1.1 protocol, clients such as browsers open a limited number of connections for each domain, typically 6.

RFC 2616 recommended that client opened no more than two connections per domain. This limit has been removed in RFC 7230, but it is still not a good idea to open too many connections to a domain.

Clients such as browsers that have this implementation limit for the HTTP/1.1 protocol consequently limit also the number of concurrent, outstanding, requests that they can make to a server.

In browsers, all the tabs pointing to the same domain will share this small, per domain, connection pool. If a user opens 6 browser tabs to the same CometD application (and therefore, the same domain), then 6 long poll requests will be sent to the server, therefore consuming all available connections. This means that any further communication with the server (for example, the publish of a message, but also any other interaction, either via clicking on a link or using XMLHttpRequest) will be queued and will wait for one of the long polls to return before taking the chance to be sent to the server.

This is not good for the user experience. An interaction of the user with the application should result in some immediate feedback, but instead the interaction is queued for many seconds, leaving the user with the doubt that interaction with the user interface really happened, causing frustration in using the application.

The CometD Server implements the multiple-clients advice (see also this section). The server uses BAYEUX_BROWSER cookie to detect multiple CometD sessions from the same browser.

When the CometD server detects multiple sessions, it uses the parameter maxSessionsPerBrowser (by default set to 1) to decide how many sessions (or, equivalently, how many long polls) are allowed for that client when it uses the HTTP/1.1 protocol (see also the server configuration section). Additional long poll requests will be returned immediately by the server with the multiple-clients field of the advice object set to true. A negative value for maxSessionsPerBrowser allows unlimited number of long polls.

The advice object also contains an interval field set to the value of the multiSessionInterval parameter (see also the server configuration section). This instructs the client not to send another poll until that interval has elapsed. The effect of this advice is that additional client sessions will perform normal polls (not long polls) to the server with a period of multiSessionInterval. This avoids consuming all the HTTP connections at the cost of some latency for the additional tabs.

The recommendation is that the client application monitors the /meta/connect channel for multiple-clients field in the advice object. If detected, the application might ask the user to close the additional tabs, or it could automatically close them, or take some other action.

Non-browser clients should handle the BAYEUX_BROWSER cookie with the same semantic of browsers: store the cookies and send them along with subsequent requests to the corresponding domains. This ensures two things: that the server can recognize valid sessions (see the security section), and that the server can detect multiple sessions from the same client.

The HTTP/2 protocol uses a single connection for each domain, and a large number of concurrent requests can be multiplexed within this single connection. This has the effect of removing the limit of concurrent, outstanding, requests that a client can make to the server, allowing the server to support as many long poll requests as the client wants.

The parameter http2MaxSessionsPerBrowser (by default set to -1) controls the number of sessions (or, equivalently, how many long polls) that are allowed for that client when it uses the HTTP/2 protocol (see also the server configuration section).

A negative value of http2MaxSessionsPerBrowser allows an unlimited number of sessions; a positive value restricts the max number of session allowed per client.

Server-side CometD components may be exposed as JMX MBeans and visible via monitoring tools such as Java Mission Control, JVisualVM or JConsole.

CometD MBeans build on Jetty’s JMX support, and are portable across Servlet Containers.

The CometD Java client implementation (see also the client section) uses the JSON library 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.

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 you write the application code carefully.

Jackson may produce instances of java.util.List when deserializing JSON arrays. The Jetty library, however, produces java.lang.Object[] when deserializing JSON arrays.

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

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

Sometimes it is very useful to be able to obtain objects of application classes instead of just Map<String, Object> when calling message.getData().

You can easily achieve this with the Jetty JSON library. It is enough that the client formats the JSON object adding an additional class field whose value is the fully qualified class name that you want to convert the JSON to:

On the server, in the web.xml file, you register the org.cometd.server.JettyJSONContextServer as jsonContext (see also the JSON server configuration section), and at startup you add a custom converter for the org.cometd.example.EchoInfo class (see also the services integration section for more details about configuring CometD at startup).

Finally, these are the EchoInfoConvertor and EchoInfo classes:

If, instead of using the JavaScript client, you are using the Java client, it is possible to configure the Java client to perform the serialization/deserialization of JSON objects in the same way (see also the JSON client configuration section):

A typical, but not the only, infrastructure to set up an 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, which can be based on:

You should configure DNS with a single host name/IP address pair (that of the load balancer), so that in case of a node crash, when clients attempt to reconnect to the same host name, the load balancer notices that the node has crashed and directs the connection to another node. The second node does not know about this client, and upon receiving the connect request sends to the client the advice to handshake.

The next sections use the following terminology:

Any CometD server can become an Oort node by configuring an instance of org.cometd.oort.Oort. The org.cometd.oort.Oort instance is associated to the org.cometd.bayeux.server.BayeuxServer instance, and there can be only one Oort instance for each BayeuxServer instance.

Oort nodes need to know each others' URLs to connect and form a cluster. A new node that wants to join the cluster needs to know at least one URL of another node that is already part of the cluster. Once it has connected to one node, the cluster informs the new node of the other nodes to which the new node is not yet connected, and the new node then connects to all the existing nodes.

There are two ways for a new node to discover at least one other node:

For both static and automatic discovery there exists a set of parameters that you can use to configure the Oort instance. The following is the list of common configuration parameters the automatic discovery and static configuration servlets share:

You can configure the automatic discovery mechanism either via code, or by configuring a org.cometd.oort.OortMulticastConfigServlet in web.xml, for example:

Since Oort depends on BayeuxServer, the load-on-startup parameter of the OortMulticastConfigServlet must be greater than that of the CometDServlet.

The mandatory oort.url init parameter must identify the URL at which this Oort node can be contacted, and it must be the URL the CometDServlet of this node serves. This URL is sent to other Oort nodes, so it is important that the host part of the URL does not point to "localhost", but to a resolvable host name or to an IP address, so that other nodes in the cluster can contact this node. Likewise, you must properly configure the context path part of the URL for this web application.

In addition to the common configuration init parameters, OortMulticastConfigServlet supports the configuration of these additional init parameters:

Each node that you configure with automatic discovery emits an advertisement (containing the node URL) every oort.multicast.advertiseInterval milliseconds on the specified multicast address and port (oort.multicast.groupAddress and oort.multicast.groupPort) with the specified time-to-live (oort.multicast.timeToLive). Advertisements continue until the web application is stopped, and only serve to advertise that a new node has appeared. Oort has a built-in mechanism that takes care of membership organization (see also the membership organization section for details).

When enabling the Oort automatic discovery mechanism, you must be sure that:

Linux is normally compiled with multicast support in the most common distributions. You can control network interfaces with the ip link command to check if they have multicast enabled. You can check multicast routing with the command ip route, and the output should contain a line similar to:

You might also want to force the JVM to prefer an IPv4 stack by setting the system property -Djava.net.preferIPv4Stack=true to facilitate multicast networking.

You can use the static discovery mechanism if multicast is not available on the system where CometD is deployed. It is only slightly more cumbersome to set up. It does not allow dynamic discovery of new nodes, but it is enough to configure each node with the well-known URL of an existing, started, node (often named "primary"). The primary node should, of course, be started before all other nodes.

You can accomplish the static discovery configuration either via code, or by configuring an org.cometd.oort.OortStaticConfigServlet in web.xml, for example:

Just as for the automatic discovery, the load-on-startup parameter of the OortStaticConfigServlet must be greater than that of the CometDServlet.

OortStaticConfigServlet supports the common init parameters listed in the previous section, and the following additional init parameter:

Configured in this way, the Oort node is ready to be part of the Oort cluster, but it’s not part of the cluster yet, since it does not know the URLs of other nodes (and there is no automatic discovery). To make the Oort node part of the Oort cluster, you can configure the oort.cloud init parameter of the OortStaticConfigServlet with one (or a comma-separated list) of Oort node URL(s) to connect to:

A "primary" node may be configured without the oort.cloud parameter. The other nodes will be configured with the URL of the "primary" node, and when they connect to the "primary" node, the "primary" node will connect back to them, see the membership organization section.

Alternatively, it’s possible to write custom initialization code (see the section on the services integration section for suggestions on how to do so) that links the node to the Oort cluster (this might be useful if Oort node URLs cannot be known a priori, but can be known at runtime), for example:

The OortComet instance that Oort.observeComet(url) returns is a specialized version of BayeuxClient, see also the Java client section.

When an Oort node connects to another Oort node, a bidirectional communication is established. If nodeA connects to nodeB (for example, via oortA.observeComet(urlB)), then an OortComet instance is created in nodeA connected to nodeB, and another OortComet instance is created in nodeB connected to nodeA.

After this direct, bidirectional communication has been established, a special message broadcasts across the whole Oort cluster (on channel /oort/cluster) where the two nodes broadcast their known siblings. Every node receiving this message that does not know about those siblings then establishes a bidirectional communication with them.

For example, imagine that there are two simple Oort clusters, one made of nodes A and B and the other made of nodes C and D. When A and C connect, they broadcast their siblings (A broadcasts its siblings, now B and C, while C broadcasts its siblings, now A and D). All nodes connected, directly or indirectly, to the broadcaster receive this message. When C receives broadcasts from A’s siblings it notices that one is itself (so it does nothing since it’s already connected to A). The other is the unknown sibling B, and C establishes a bidirectional connection with B as well. Likewise, A receives the sibling broadcast message from C, and connects to D. Each new bidirectional connection triggers a sibling broadcast message on the whole cluster, until all nodes are connected.

If a node crashes, for example D, then all other nodes detect that and disconnect from the faulty node.

In this way, an Oort cluster is aware of its members, but it does not do anything useful for the application.

The next section covers broadcast message forwarding over the entire cluster.

When an Oort node connects to another Oort node, it sends a handshake message containing an extension field that is peculiar to Oort with the following format:

The oortURL field is the URL of the node that initiates the handshake; the cometURL field is the URL of the node that receives the handshake; the oortSecret is the base64 encoding of the SHA-1 digested bytes of the pre-shared secret of the initiating Oort node (see the earlier section, the Oort common configuration section).

These extension fields provide a way for an Oort node to distinguish a handshake of a remote client (which might be subject to authentication checks) from a handshake performed by a remote node. For example, assume that remote clients always send an extension field containing an authentication token; then it is possible to write an implementation of SecurityPolicy as follows (see also the authentication section):

The Oort.isOortHandshake(Message) method validates the handshake message and returns true if it is a handshake from another Oort node that has been configured with the same pre-shared secret. In this case, where you want to validate that the handshake attempt really comes from a valid Oort node (and not from an attacker that forged a message similar to what an Oort node sends), the pre-shared secret must be explicitly set to the same value for all Oort nodes, because it defaults to a random string that is different for each Oort node.

Broadcast messages (that is, messages sent to non-meta and non-service channels, (see also this section for further details) are by definition messages that all clients subscribing to the channel the message is being sent to should receive.

In an Oort cluster, you might have clients connected to different nodes that subscribe to the same channel. If clientA connects to nodeA, clientB connects to nodeB and clientC connects to nodeC, when clientA broadcasts a message and you want clientB and clientC to receive it, then the Oort cluster must forward the message (sent by clientA and received by nodeA) to nodeB and nodeC.

You accomplish this by configuring the Oort configuration servlets to set the oort.channels init parameter to a comma-separated list of channels whose messages are forwarded to the Oort cluster:

Alternatively, you can use Oort.observeChannel(String channelName) to instruct a node to listen for messages on that channel published to one of the known nodes it is connected to.

When nodeA observes a channel, it means that messages sent on that channel, but received by other nodes, are automatically forwarded to nodeA.

Forwarding of messages may be subject to temporary interruptions in case there is a temporary network connectivity failure between two nodes. To overcome this problem, the message acknowledgement extension (see also the acknowledgement extension section) is enabled by default among Oort nodes so that, for short failures, the messages lost are resent automatically by the acknowledgement extension. Refer to the Oort common configuration section for the configuration details.

Remember that the message acknowledgement extension is not a fully persistent solution for lost messages (for example it does not guarantee message redelivery in case of long network failures). CometD does not provide yet a fully persistent solution for messages in case of long network failures.

Since it has the ability to observe messages published to broadcast channels, an Oort cluster can already implement a simple chat application among users connected to different nodes. In the example below, when clientA publishes a message on channel /chat (green arrow), it arrives on nodeA; since nodeB and nodeC have been configured to observe channel /chat, they both receive the message from nodeA (green arrows), and therefore they can deliver the chat message to clientB and clientC respectively (green arrows).

If your application only needs to broadcast messages to clients connected to other nodes, an Oort instance is all you need.

If you need to send messages directly to particular clients (for example, clientA wants to send a message to clientC but not to clientB, then you need to set up an additional component of the Oort clustering called Seti, see also the Seti section.

Keep the following points in mind when configuring Seti:

A configuration example follows:

Seti allows you to associate a unique string representation of a user with one or more ServerSessions (see also the concepts section for more details on ServerSession).

This normally occurs when the user first logs in to the application, and the unique string representation of the user can be anything that the user provides to authenticate itself (a user name, a token, a database ID). For brevity, this unique string representation of the user is called userId. The same userId may log in multiple times (for example from a desktop computer and from a mobile device), so it is associated to multiple ServerSessions.

In practice, the best way to associate a userId with a ServerSession is in a SecurityPolicy during authentication, for example:

Alternatively, you can perform the association in a BayeuxServer.Extension or in a CometD service (see also the services section), in response to a specific message that the client always sends after a successful handshake.

When a Seti instance first associates a userId with a session, it broadcasts a presence message on the cluster (on channel /seti/all, (see also the Seti listeners section) that tells all the other nodes where this userId is located.

In this way, all the nodes in the cluster know where a particular userId resides. Further associations of the same userId (with different sessions) on the same Seti do not broadcast any presence message, because other Setis already know that that particular userId resides in that Seti. The same userId can be associated in different nodes (for example, the desktop computer logs in – and therefore is associated – in comet1, while the mobile device is associated in comet2).

Similarly, you can disassociate a userId at any time by calling Seti.disassociate(userId, session). If the user disconnects or "disappears" (for example, it crashed or its network dropped), the server removes or expires its session and Seti automatically disassociates the userId. When the last disassociation of a particular userId occurs on a Seti instance, Seti broadcasts a presence message on the cluster (on channel /seti/all) that tells all the other nodes that userId is no longer present on that Seti (although the same userId might still be associated in other Setis).

Applications can register presence listeners that are notified when a presence message arrives at a Seti instance:

The URL event.getURL() returns is the URL of an Oort node; you can use it to retrieve the OortComet instance connected to that node, for example to publish messages (or to subscribe to additional channels):

After users have been associated, Seti.sendMessage(String userId, String channel, Object data) can send messages to a particular user in the cluster.

In the example below, clientA wants to send a message to clientC but not to clientB. Therefore clientA sends a message to the server it is connected to using a service channel so that the message is not broadcast, and then a specialized service (see also the services section) routes the message to the appropriate user using Seti (see code snippet above). The Seti on nodeA knows that the target user is on nodeC (thanks to the association) and forwards the message to nodeC, which in turn delivers the message to clientC.

An org.cometd.oort.OortObject instance represents a named composite data entity that is distributed in an Oort cluster. Each node in the cluster has exactly one instance of an OortObject with a specific name, and the OortObject contains N data entities, one of each node in the cluster. There may be several Oort objects in the same node, provided they all have different names.

The data entity may be the number of users connected to each node, or the number of games played on each node, or the list of chat rooms created on each node, or the names of systems monitored by each node, etc., depending on your application’s business domain.

In the image below, you can see 3 nodes (nodeA, nodeB and nodeC), each containing an Oort object named "users" (in orange) that stores the names of the users connected to each Oort node. The data entity in this case is a List<String> representing the names of the connected users for each node.

NodeA has clients Ca1 and Ca2 connected, nodeB has only client Cb1 connected, while nodeC has 3 clients connected. Oort objects are composites in that they store N data entities, also called parts, where N is the number of nodes in the Oort cluster. You can see that each Oort object is made of 3 parts (the innermost blue, green and red boxes); each part is colored like the node it represents. The part that has the same color as the node it lives in it’s the local part.

Each Oort object can only update its local part: nodeA can only add/remove user names from its local (blue) part, and cannot add/remove from the remote parts (in green and red). Likewise, nodeB can only update the green part but not the blue and red parts, and nodeC can only update the red part, but not the blue and green ones.

If a new client connects to nodeB, say Cb2, then the application on nodeB takes the user name (B2) that wants to share with other nodes, and adds it to the Oort object on nodeB. The user name B2 will be added to the green part of nodeB, and a message will be broadcast to the other nodes, which will also modify the correspondent green parts on themselves, adding a copy of B2. The remote parts of an Oort object can only be updated by messages internal to the OortObject implementation; they cannot be updated by application code directly.

Each Oort object instance owns only its local part. In the example, the user name A2 is present in all the nodes, but it is owned only by the Oort object in nodeA. Anyone that wants to modify or remove A2 must perform this action in nodeA. the OortService section shows how to forward service actions from one node to another.

OortObject allows applications to add/remove OortObject.Listener that are notified of modification of a part, either local or remote. Your application can implement these listeners to perform custom logic, see also the OortObject listeners section.

An org.cometd.oort.OortService is a named CometD service (see also the services section) that forwards actions from a requesting node to the node in the cluster that owns the data onto which the action must be performed, called the owner node, and receives the action result back.

OortService builds on the concept introduced by OortObject that the ownership of a particular data entity belongs to one node only. Any node can read the data entity, but only the owner can create/modify/delete it. In order to perform actions that modify the data entity, a node has to know what is the node that owns the data entity, and then forward the action to the owner node. OortService provides the facilities to forward the action to the owner node and receive the result of the action, or its failure.

Class org.cometd.oort.OortService must be subclassed by the application to implement key methods that perform the action logic.

The typical workflow of an OortService is the following:

In general, applications can be seen as programs that create data and operate on that data. Given a certain node, the application may need to access data stored on a remote node. For modify/delete operations on the data, use an OortService and forward the action to the owner node. The read operation, however, can be performed either using an OortObject or using an OortService.

When using an OortObject, you trade more memory usage for smaller latencies to read the data, since the data is replicated to all nodes and therefore the read operation is local and does not involve network communication.

When using an OortService, you trade less memory usage for bigger latencies to read the data, since reading the data requires to forward the action to the node that owns the data and have the owner node to send it back to the requesting node.

Whether to use one solution or the other depends heavily on the application, the server machine specification (especially available memory), and may even change over time.

For example, an application that is able to handle user information for a user base of 500 users using OortObject may not be able to do so when it grows to 500,000 users. Similarly, if the nodes are colocated in the same data center connected via a fast network, it may be worth using OortService (as the network time will be negligible), but if the nodes and geographically distributed (for example, one in America, one in Europe, one in Asia), then the network time may become an issue and data replication through OortObject a better solution to minimize latencies.