The CometD 2 JavaScript library is a portable JavaScript implementation with bindings for the
major JavaScript toolkits, currently Dojo and
jQuery.
This means that the CometD Bayeux JavaScript implementation is written in pure JavaScript with no dependencies on
the toolkits, and that the toolkit bindings add the syntactic sugar that makes the Bayeux APIs feel like they are
native to the toolkit.
For example, it is possible to refer to the standard cometd object using the following notation:

If you followed Chapter 5, Primer, you might have noticed that the skeleton project requires you
to reference both the portable implementation, under org/cometd.js, and one binding - for example
Dojo's - under dojox/cometd.js. For jQuery, the binding is under jquery/jquery.cometd.js.
The use of the Bayeux APIs from the JavaScript toolkits is almost identical, and the following sections do not
refer to a particular toolkit.
Small differences surface only when passing callback functions to the Bayeux API, where Dojo users might use
dojo.hitch(), while jQuery users might prefer an anonymous function approach.

The following sections present details about the JavaScript Bayeux APIs and their implementation secrets.

7.1. Configuring and Initializing

After you set up your skeleton project following Chapter 5, Primer, you probably want to fully
understand how to customize and configure the parameters that govern the behavior of the CometD implementation.

The complete API is available through a single object prototype named org.cometd.Cometd.
The Dojo toolkit has one instance of this object available under the name dojox.cometd, while for
jQuery it is available under the name $.cometd.
This default cometd object has been instantiated and configured with the default values and it has
not yet started any Bayeux communication.

Before the cometd object can start Bayeux communication it needs a mandatory parameter:
the URL of the Bayeux server.
The URL of the server must be absolute (and therefore include the scheme, host, optionally the port and the path
of the server).
The scheme of the URL must always be either "http" or "https". The CometD JavaScript implementation will
transparently take care of converting the scheme to "ws" or "wss" in case of usage of the WebSocket protocol.

The maximum number of connections used to connect to the Bayeux server. Change this value only if you know
exactly the client's connection limit and what "request queued behind long poll" means.

backoffIncrement

no

1000

The number of milliseconds that the backoff time increments every time a connection with the Bayeux server fails.
CometD attempts to reconnect after the backoff time elapses.

maxBackoff

no

60000

The maximum number of milliseconds of the backoff time after which the backoff time is not incremented
further.

reverseIncomingExtensions

no

true

Controls whether the incoming extensions are called in reverse order with respect to the registration order.

maxNetworkDelay

no

10000

The maximum number of milliseconds to wait before considering a request to the Bayeux server failed.

requestHeaders

no

{}

An object containing the request headers to be sent for every Bayeux request
(for example, {"My-Custom-Header":"MyValue"}).

appendMessageTypeToURL

no

true

Determines whether or not the Bayeux message type (handshake, connect, disconnect) is appended to the
URL of the Bayeux server (see above).

autoBatch

no

false

Determines whether multiple publishes that get queued are sent as a batch on the first occasion,
without requiring explicit batching.

connectTimeout

no

0

The maximum number of milliseconds to wait for a WebSocket connection to be opened.
It does not apply to HTTP connections. A timeout value of 0 means to wait forever.

stickyReconnect

no

true

Only applies to the WebSocket transport. Determines whether to stick using the WebSocket transport
when a WebSocket transport failure has been detected after the WebSocket transport
was able to successfully connect to the server.

After you have configured the cometd object, the Bayeux communication does not start until you call
handshake() (see Section 7.2, “Handshaking”).

Previous users of the JavaScript CometD implementation called a method named init().
This method still exists, and it is a shorthand for calling configure() followed by
handshake().
Follow the advice in Section 7.2, “Handshaking” as it applies as well to init().

7.1.1. Configuring and Initializing Multiple Objects

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

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

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.