The CometD Reference Book — 8.0.6

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 minimally 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 set up 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 a simple binding that does not log statements produced at debug level.

Therefore, you must configure SLF4J with a more advanced binding such as jetty-slf4j-impl, 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 other projects 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 archetypes available that build a skeleton application using plain ES6 or using jQuery, both with the choice of using Jetty and/or Spring. Choose ES6 with Jetty, which in the example above is archetype number 1 (it may have a different number for you).

Next, you have to choose the version of the archetype you want to use, typically the last version of the 8.0.x series:

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/es6-jetty12-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 client-side files necessary to set up a CometD project can be obtained in two ways:

The server-side dependencies are typically the following:

You may have different dependencies if you choose to use different CometD or Jetty features.

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 (or HTML) file index.jsp contains the reference to the JavaScript application file:

The reason to use a JSP file rather than an HTML file is that JSP allows you to more easily obtain contextual information such as the web application context path, but it is not necessary.

In the example above, the JSP file configures a JavaScript configuration object name config, with fields that the JavaScript application might need, for example contextPath. This is totally optional.

The JavaScript application, contained in the application.js file, configures the cometd object and starts the application. The archetypes provide the following implementation, that you can use as inspiration to write your own:

Note 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.RemovedListener#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.

However, it is easy to create other cometd objects by simply creating more instances of the CometD class:

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

Each cometd object may be configured with the same or different extensions, simply by registering each extension in each cometd instance. Extensions are covered in the extensions section.

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 method 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:

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 origin, and also in the cross-origin mode for recent browsers (see also the cross-origin section). The data is sent to the server by means of a POST request with Content-Type: application/json via a plain XMLHttpRequest call.

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

XMLHttpRequest supports cross-origin invocations, but for the invocation to succeed the server must collaborate, typically by deploying a cross-origin component.

In case of older browsers or servers that do not deploy a cross-origin component, 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.

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:

The cross-origin mode is in play when the CometD JavaScript files are downloaded from a domain server, but the JavaScript application wants to connect to a CometD server different from the domain server, the cross server.

Browsers use the CORS protocol to control whether the script downloaded from the domain server can connect to the cross server.

To use the cross-origin mode, you need to configure the cross server with a cross-origin component. For example, Jetty can be configured with the CrossOriginHandler or the CrossOriginFilter.

With this setup, even when the communication with the Bayeux server is cross-origin, 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 BayeuxClient.handshake().

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.

BayeuxClient currently supports transport based on HTTP (long-polling) and WebSocket (websocket).

These are the choices of transports for long-polling:

These are the choices of transports for websocket:

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 long-polling transport in the BayeuxClient constructor:

It is always recommended that the websocket transport is never used without a fallback long-polling transport such as JettyHttpClientTransport.

This is how you configure the transports based on OkHttp:

You can specify BayeuxServer parameters and server transport parameters in web.xml as init parameters of the org.cometd.server.http.jakarta.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.http.jakarta.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.