org.apache.cometd.bayeux
Interface Bayeux

All Known Implementing Classes:

TomcatBayeux

public interface Bayeux

Bayeux Interface.
This interface represents the server side API for the Bayeux messaging protocol. Bayeux is a simple subscribe/publish/receive methodology, not far from JMS, but much simplified.
It is used both by the actual implementation and by server side clients.
Server side clients use this to create, retrieve and subscribe to channels. Server side clients are represented, just like remote clients, through the Client interface.
The Bayeux implementations is intended to be thread safe and multiple threads may simultaneously call Bayeux methods.
The Bayeux object, is the starting point for any cometd application relying on the Bayeux object. Dependent on the container, the Bayeux object will be stored in the javax.servlet.ServletContext object as an attribute under the name Bayeux.DOJOX_COMETD_BAYEUX
To retrieve this object, one would simply call
Bayeux bx = (Bayeux)getServletContext().getAttribute(Bayeux.DOJOX_COMETD_BAYEUX);

The Bayeux protocol is pretty straight forward and includes a bunch of messaging that is not needed to be known to clients, both server side and remote clients. This object gets initialized by a container dependent servlet, and the servlet then handles all Bayeux communication from the client. Remote messsages are delivered to channels, and to server side clients using the Listener interface.

A Bayeux session is active as long as the webapp hosting the Bayeux object is active.
When the webapplication shuts down, the Bayeux object will unsubscribe all clients and remove all the active channels.

Author:

Greg Wilkins, Filip Hanik

Field Summary

static java.lang.String	ADVICE_FIELD Field names inside Bayeux messages - advice field
static java.lang.String	CHANNEL_FIELD Field names inside Bayeux messages - channel field
static java.lang.String	CLIENT_FIELD Field names inside Bayeux messages - clientId field
static java.lang.String	CONNECTION_TYPE_FIELD Field names inside Bayeux messages - connectionType field
static java.lang.String	DATA_FIELD Field names inside Bayeux messages - data field
static java.lang.String	DOJOX_COMETD_BAYEUX ServletContext attribute name used to obtain the Bayeux object
static java.lang.String	ERROR_FIELD Field names inside Bayeux messages - error field
static java.lang.String	EXT_FIELD Field names inside Bayeux messages - ext field
static java.lang.String	HANDSHAKE_RESPONSE Field values inside Bayeux messages - handshake response
static java.lang.String	ID_FIELD Field names inside Bayeux messages - id field
static java.lang.String	INTERVAL_FIELD Field names inside Bayeux messages - interval field
static java.lang.String	JSON_COMMENT_FILTERED_FIELD Field names inside Bayeux messages - json-comment-filtered field
static java.lang.String	JSON_CONTENT_TYPE http helpers - text/json content type
static java.lang.String	JSONP_DEFAULT_NAME http helpers - default name of the jsonp callback function
static java.lang.String	JSONP_PARAMETER http helpers - name of the jsonp parameter
static java.lang.String	MESSAGE_PARAMETER http helpers - parameter name for json message
static java.lang.String	META Meta definitions for channels
static java.lang.String	META_CLIENT Meta definitions for channels - client messsage
static java.lang.String	META_CONNECT Meta definitions for channels - connect message
static java.lang.String	META_DISCONNECT Meta definitions for channels - disconnect messsage
static java.lang.String	META_HANDSHAKE Meta definitions for channels - handshake messsage
static java.lang.String	META_PING Meta definitions for channels - ping messsage
static java.lang.String	META_RECONNECT Deprecated.
static java.lang.String	META_SLASH Meta definitions for channels
static java.lang.String	META_STATUS Meta definitions for channels - status messsage
static java.lang.String	META_SUBSCRIBE Meta definitions for channels - subscribe messsage
static java.lang.String	META_UNSUBSCRIBE Meta definitions for channels - unsubscribe messsage
static java.lang.String	MIN_VERSION_FIELD Field names inside Bayeux messages - minimumVersion field
static java.lang.String	NONE_RESPONSE Field values inside Bayeux messages - none response
static java.lang.String	RECONNECT_FIELD Field names inside Bayeux messages - reconnect field
static java.lang.String	RETRY_RESPONSE Field values inside Bayeux messages - retry response
static java.lang.String	SERVICE Service channel names-starts with
static java.lang.String	SERVICE_SLASH Service channel names-trailing slash
static java.lang.String	SUBSCRIPTION_FIELD Field names inside Bayeux messages - subscription field
static java.lang.String	SUCCESSFUL_FIELD Field names inside Bayeux messages - successful field
static java.lang.String	SUPP_CONNECTION_TYPE_FIELD Field names inside Bayeux messages - supportedConnectionTypes field
static java.lang.String	TIMESTAMP_FIELD Field names inside Bayeux messages - timestamp field
static java.lang.String	TRANSPORT_CALLBACK_POLL Transport types - callback polling
static java.lang.String	TRANSPORT_FIELD Field names inside Bayeux messages - transport field
static java.lang.String	TRANSPORT_FLASH Transport types - flash
static java.lang.String	TRANSPORT_IFRAME Transport types - iframe
static java.lang.String	TRANSPORT_LONG_POLL Transport types - long polling
static java.lang.String	VERSION_FIELD Field names inside Bayeux messages - version field

Method Summary

Channel	getChannel(java.lang.String channelId, boolean create) Returns the channel for a given channel id.
java.util.List<Channel>	getChannels() Returns a list of currently active channels in this Bayeux session.
Client	getClient(java.lang.String clientid) retrieve a client based on an ID.
java.util.List<Client>	getClients() Returns a non modifiable list of all the clients that are currently active in this Bayeux session
SecurityPolicy	getSecurityPolicy() Returns the security policy associated with this Bayeux session
boolean	hasChannel(java.lang.String channelId) returns true if a channel with the given channelId exists.
boolean	hasClient(java.lang.String clientId) Returns true if a client with the given id exists.
Client	newClient(java.lang.String idprefix, Listener listener) Creates a new server side client.
Message	newMessage(Client from) Creates a new message to be sent by a server side client.
Channel	remove(Channel channel) Removes a channel from the Bayeux object.
Client	remove(Client client) Removes the client all together.
void	setSecurityPolicy(SecurityPolicy securityPolicy) Sets the security policy to be used in this Bayeux session

Field Detail

META

static final java.lang.String META

Meta definitions for channels

See Also:

Constant Field Values

META_SLASH

static final java.lang.String META_SLASH

Meta definitions for channels

See Also:

Constant Field Values

META_CONNECT

static final java.lang.String META_CONNECT

Meta definitions for channels - connect message

See Also:

Constant Field Values

META_CLIENT

static final java.lang.String META_CLIENT

Meta definitions for channels - client messsage

See Also:

Constant Field Values

META_DISCONNECT

static final java.lang.String META_DISCONNECT

Meta definitions for channels - disconnect messsage

See Also:

Constant Field Values

META_HANDSHAKE

static final java.lang.String META_HANDSHAKE

Meta definitions for channels - handshake messsage

See Also:

Constant Field Values

META_PING

static final java.lang.String META_PING

Meta definitions for channels - ping messsage

See Also:

Constant Field Values

META_RECONNECT

static final java.lang.String META_RECONNECT

Deprecated.

Meta definitions for channels - reconnect messsage

See Also:

Constant Field Values

META_STATUS

static final java.lang.String META_STATUS

Meta definitions for channels - status messsage

See Also:

Constant Field Values

META_SUBSCRIBE

static final java.lang.String META_SUBSCRIBE

Meta definitions for channels - subscribe messsage

See Also:

Constant Field Values

META_UNSUBSCRIBE

static final java.lang.String META_UNSUBSCRIBE

Meta definitions for channels - unsubscribe messsage

See Also:

Constant Field Values

CLIENT_FIELD

static final java.lang.String CLIENT_FIELD

Field names inside Bayeux messages - clientId field

See Also:

Constant Field Values

DATA_FIELD

static final java.lang.String DATA_FIELD

Field names inside Bayeux messages - data field

See Also:

Constant Field Values

CHANNEL_FIELD

static final java.lang.String CHANNEL_FIELD

Field names inside Bayeux messages - channel field

See Also:

Constant Field Values

ID_FIELD

static final java.lang.String ID_FIELD

Field names inside Bayeux messages - id field

See Also:

Constant Field Values

ERROR_FIELD

static final java.lang.String ERROR_FIELD

Field names inside Bayeux messages - error field

See Also:

Constant Field Values

TIMESTAMP_FIELD

static final java.lang.String TIMESTAMP_FIELD

Field names inside Bayeux messages - timestamp field

See Also:

Constant Field Values

TRANSPORT_FIELD

static final java.lang.String TRANSPORT_FIELD

Field names inside Bayeux messages - transport field

See Also:

Constant Field Values

ADVICE_FIELD

static final java.lang.String ADVICE_FIELD

Field names inside Bayeux messages - advice field

See Also:

Constant Field Values

SUCCESSFUL_FIELD

static final java.lang.String SUCCESSFUL_FIELD

Field names inside Bayeux messages - successful field

See Also:

Constant Field Values

SUBSCRIPTION_FIELD

static final java.lang.String SUBSCRIPTION_FIELD

Field names inside Bayeux messages - subscription field

See Also:

Constant Field Values

EXT_FIELD

static final java.lang.String EXT_FIELD

Field names inside Bayeux messages - ext field

See Also:

Constant Field Values

CONNECTION_TYPE_FIELD

static final java.lang.String CONNECTION_TYPE_FIELD

Field names inside Bayeux messages - connectionType field

See Also:

Constant Field Values

VERSION_FIELD

static final java.lang.String VERSION_FIELD

Field names inside Bayeux messages - version field

See Also:

Constant Field Values

MIN_VERSION_FIELD

static final java.lang.String MIN_VERSION_FIELD

Field names inside Bayeux messages - minimumVersion field

See Also:

Constant Field Values

SUPP_CONNECTION_TYPE_FIELD

static final java.lang.String SUPP_CONNECTION_TYPE_FIELD

Field names inside Bayeux messages - supportedConnectionTypes field

See Also:

Constant Field Values

JSON_COMMENT_FILTERED_FIELD

static final java.lang.String JSON_COMMENT_FILTERED_FIELD

Field names inside Bayeux messages - json-comment-filtered field

See Also:

Constant Field Values

RECONNECT_FIELD

static final java.lang.String RECONNECT_FIELD

Field names inside Bayeux messages - reconnect field

See Also:

Constant Field Values

INTERVAL_FIELD

static final java.lang.String INTERVAL_FIELD

Field names inside Bayeux messages - interval field

See Also:

Constant Field Values

RETRY_RESPONSE

static final java.lang.String RETRY_RESPONSE

Field values inside Bayeux messages - retry response

See Also:

Constant Field Values

HANDSHAKE_RESPONSE

static final java.lang.String HANDSHAKE_RESPONSE

Field values inside Bayeux messages - handshake response

See Also:

Constant Field Values

NONE_RESPONSE

static final java.lang.String NONE_RESPONSE

Field values inside Bayeux messages - none response

See Also:

Constant Field Values

SERVICE

static final java.lang.String SERVICE

Service channel names-starts with

See Also:

Constant Field Values

SERVICE_SLASH

static final java.lang.String SERVICE_SLASH

Service channel names-trailing slash

See Also:

Constant Field Values

TRANSPORT_LONG_POLL

static final java.lang.String TRANSPORT_LONG_POLL

Transport types - long polling

See Also:

Constant Field Values

TRANSPORT_CALLBACK_POLL

static final java.lang.String TRANSPORT_CALLBACK_POLL

Transport types - callback polling

See Also:

Constant Field Values

TRANSPORT_IFRAME

static final java.lang.String TRANSPORT_IFRAME

Transport types - iframe

See Also:

Constant Field Values

TRANSPORT_FLASH

static final java.lang.String TRANSPORT_FLASH

Transport types - flash

See Also:

Constant Field Values

DOJOX_COMETD_BAYEUX

static final java.lang.String DOJOX_COMETD_BAYEUX

ServletContext attribute name used to obtain the Bayeux object

See Also:

Constant Field Values

JSON_CONTENT_TYPE

static final java.lang.String JSON_CONTENT_TYPE

http helpers - text/json content type

See Also:

Constant Field Values

MESSAGE_PARAMETER

static final java.lang.String MESSAGE_PARAMETER

http helpers - parameter name for json message

See Also:

Constant Field Values

JSONP_PARAMETER

static final java.lang.String JSONP_PARAMETER

http helpers - name of the jsonp parameter

See Also:

Constant Field Values

JSONP_DEFAULT_NAME

static final java.lang.String JSONP_DEFAULT_NAME

http helpers - default name of the jsonp callback function

See Also:

Constant Field Values

Method Detail

newClient

Client newClient(java.lang.String idprefix,
                 Listener listener)

Creates a new server side client. This method is to be invoked by server side objects only. You cannot create a remote client by using this method. A client represents an entity that can subscribe to channels and publish and receive messages through these channels

Parameters:

idprefix - String - the prefix string for the id generated, can be null

listener - Listener - a callback object to be called when messages are to be delivered to the new client

Returns:

Client - returns an implementation of the client interface.

getClient

Client getClient(java.lang.String clientid)

retrieve a client based on an ID. Will return null if the client doesn't exist.

Parameters:

clientid - String

Returns:

Client-null if the client doesn't exist.returns the client if it does.

getClients

java.util.List<Client> getClients()

Returns a non modifiable list of all the clients that are currently active in this Bayeux session

Returns:

List - a list containing all clients. The List can not be modified.

hasClient

boolean hasClient(java.lang.String clientId)

Returns true if a client with the given id exists.
Same as executing getClient(id)!=null.

Parameters:

clientId - String

Returns:

boolean - true if the client exists

remove

Client remove(Client client)

Removes the client all together. This will unsubscribe the client to any channels it may be subscribed to and remove it from the list.

Parameters:

client - Client

Returns:

Client - returns the client that was removed, or null if no client was removed.

getChannel

Channel getChannel(java.lang.String channelId,
                   boolean create)

Returns the channel for a given channel id. If the channel doesn't exist, and the create parameter is set to true, the channel will be created and added to the list of active channels.
if create is set to false, and the channel doesn't exist, null will be returned.

Parameters:

channelId - String - the id of the channel to be retrieved or created

create - boolean - true if the Bayeux impl should create the channel

Returns:

Channel - null if create is set to false and the channel doesn't exist, otherwise it returns a channel object.

getChannels

java.util.List<Channel> getChannels()

Returns a list of currently active channels in this Bayeux session.

Returns:

List

remove

Channel remove(Channel channel)

Removes a channel from the Bayeux object. This will also unsubscribe all the clients currently subscribed to the the channel.

Parameters:

channel - Channel - the channel to be removed

Returns:

Channel - returns the channel that was removed, or null if no channel was removed.

hasChannel

boolean hasChannel(java.lang.String channelId)

returns true if a channel with the given channelId exists.
Same as executing Bayeux.getChannel(channelId,false)!=null

Parameters:

channelId - String

Returns:

boolean - true if the channel exists.

newMessage

Message newMessage(Client from)

Creates a new message to be sent by a server side client.

Returns:

Message - returns a new Message object, that has a unique id.

getSecurityPolicy

SecurityPolicy getSecurityPolicy()

Returns the security policy associated with this Bayeux session

Returns:

SecurityPolicy

setSecurityPolicy

void setSecurityPolicy(SecurityPolicy securityPolicy)

Sets the security policy to be used in this Bayeux session

Parameters:

securityPolicy - SecurityPolicy