org.cometd.client

Class BayeuxClient

java.lang.Object

org.cometd.common.AbstractClientSession

org.cometd.client.BayeuxClient

All Implemented Interfaces:

Bayeux, ClientSession, Session, org.eclipse.jetty.util.component.Dumpable

Direct Known Subclasses:

OortComet

public class BayeuxClient
extends AbstractClientSession
implements Bayeux

BayeuxClient is the implementation of a client for the Bayeux protocol.

A BayeuxClient can receive/publish messages from/to a Bayeux server, and it is the counterpart in Java of the JavaScript library used in browsers (and as such it is ideal for Swing applications, load testing tools, etc.).

A BayeuxClient handshakes with a Bayeux server and then subscribes ClientSessionChannel.MessageListener to channels in order to receive messages, and may also publish messages to the Bayeux server.

BayeuxClient relies on pluggable transports for communication with the Bayeux server.

When the communication with the server is finished, the BayeuxClient can be disconnected from the Bayeux server.

Typical usage:

 // Setup Jetty's HttpClient.
 HttpClient httpClient = new HttpClient();
 httpClient.start();

 // Handshake
 String url = "http://localhost:8080/cometd";
 BayeuxClient client = new BayeuxClient(url, new JettyHttpClientTransport(null, httpClient));
 client.handshake();
 client.waitFor(1000, BayeuxClient.State.CONNECTED);

 // Subscription to channels
 ClientSessionChannel channel = client.getChannel("/foo");
 channel.subscribe((channel, message) -> {
     // Handle the message
 });

 // Publishing to channels
 Map<String, Object> data = new HashMap<>();
 data.put("bar", "baz");
 channel.publish(data);

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	BayeuxClient.BackOffStrategy A strategy to controls wait times of the retry attempts in case of heartbeat failures.
protected class	BayeuxClient.BayeuxClientChannel A channel scoped to this BayeuxClient.
static class	BayeuxClient.Scheduler
static class	BayeuxClient.State The states that a BayeuxClient may assume.

Nested classes/interfaces inherited from class org.cometd.common.AbstractClientSession

AbstractClientSession.AbstractSessionChannel

Nested classes/interfaces inherited from interface org.cometd.bayeux.Bayeux

Bayeux.BayeuxListener, Bayeux.Validator

Nested classes/interfaces inherited from interface org.cometd.bayeux.client.ClientSession

ClientSession.Extension, ClientSession.MessageListener

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.Dumpable

org.eclipse.jetty.util.component.Dumpable.DumpableContainer

Field Summary

Fields

Modifier and Type	Field and Description
static String	BACKOFF_INCREMENT_OPTION
static String	BAYEUX_VERSION
static String	MAX_BACKOFF_OPTION

Fields inherited from interface org.eclipse.jetty.util.component.Dumpable

KEY

Constructor Summary

Constructors

Constructor and Description
BayeuxClient(String url, ClientTransport transport, ClientTransport... transports) Creates a BayeuxClient that will connect to the Bayeux server at the given URL and with the given transport(s).
BayeuxClient(String url, ScheduledExecutorService scheduler, ClientTransport transport, ClientTransport... transports) Creates a BayeuxClient that will connect to the Bayeux server at the given URL, with the given scheduler and with the given transport(s).

Method Summary

Modifier and Type	Method and Description
void	abort() Interrupts abruptly the communication with the Bayeux server.
void	addTransportListener(TransportListener listener)
void	disconnect(ClientSession.MessageListener callback) Disconnects this session, ending the link between the client and the server peers.
boolean	disconnect(long timeout) Performs a disconnect and uses the given timeout to wait for the disconnect to complete.
protected void	enqueueSend(Message.Mutable message)
List<String>	getAllowedTransports()
BayeuxClient.BackOffStrategy	getBackOffStrategy()
HttpCookie	getCookie(String name) Retrieves the first cookie with the given name, if available.
CookieStore	getCookieStore()
String	getId() The clientId of the session.
Set<String>	getKnownTransportNames()
Object	getOption(String qualifiedName)
Set<String>	getOptionNames()
Map<String,Object>	getOptions()
protected BayeuxClient.State	getState()
ClientTransport	getTransport()
ClientTransport	getTransport(String transport)
String	getURL()
void	handshake(ClientSession.MessageListener callback)
BayeuxClient.State	handshake(long waitMs) Performs the handshake and waits at most the given time for the handshake to complete.
void	handshake(Map<String,Object> fields, ClientSession.MessageListener callback) Initiates the bayeux protocol handshake with the server(s).
BayeuxClient.State	handshake(Map<String,Object> template, long waitMs) Performs the handshake with the given template and waits at most the given time for the handshake to complete.
protected void	initialize()
boolean	isConnected() A connected session is a session where the link between the client and the server has been established.
boolean	isDisconnected()
boolean	isHandshook() A handshook session is a session where the handshake has successfully completed
protected void	messagesFailure(Throwable cause, List<? extends Message> messages)
protected AbstractClientSession.AbstractSessionChannel	newChannel(ChannelId channelId)
protected ChannelId	newChannelId(String channelId)
void	onFailure(Throwable failure, List<? extends Message> messages) Deprecated. use addTransportListener(TransportListener) instead
void	onMessages(List<Message.Mutable> messages) Deprecated. use addTransportListener(TransportListener) instead
void	onSending(List<? extends Message> messages) Deprecated. use addTransportListener(TransportListener) instead
protected void	onTransportFailure(Message message, ClientTransport.FailureInfo failureInfo, ClientTransport.FailureHandler handler)
protected void	onTransportFailure(String oldTransportName, String newTransportName, Throwable failure)
protected void	processConnect(Message.Mutable connect)
protected void	processDisconnect(Message.Mutable disconnect)
protected void	processHandshake(Message.Mutable handshake)
protected void	processMessage(Message.Mutable message)
void	putCookie(HttpCookie cookie)
void	removeTransportListener(TransportListener listener)
protected boolean	scheduleConnect(long interval, long backOff)
protected boolean	scheduleHandshake(long interval, long backOff)
protected void	send(Message.Mutable message)
protected void	sendBatch()
protected void	sendConnect()
protected void	sendHandshake()
protected void	sendMessages(List<Message.Mutable> messages, Promise<Boolean> promise)
void	setBackOffStrategy(BayeuxClient.BackOffStrategy backOffStrategy)
void	setOption(String qualifiedName, Object value)
protected void	terminate(Throwable failure)
String	toString()
boolean	waitFor(long waitMs, BayeuxClient.State state, BayeuxClient.State... states) Waits for this BayeuxClient to reach the given state(s) within the given time.

Methods inherited from class org.cometd.common.AbstractClientSession

addExtension, batch, dump, endBatch, extendIncoming, extendOutgoing, getAttribute, getAttributeNames, getChannel, getChannel, getChannels, getExtensions, isBatching, newMessage, newMessageId, notifyCallback, notifyListeners, receive, registerCallback, registerSubscriber, remoteCall, removeAttribute, removeExtension, resetSubscriptions, setAttribute, startBatch, unregisterCallback, unregisterSubscriber

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.cometd.bayeux.client.ClientSession

disconnect, handshake, handshake

Methods inherited from interface org.eclipse.jetty.util.component.Dumpable

dump, dump, dumpContainer, dumpIterable, dumpMapEntries, dumpObject, dumpObjects, dumpSelf, named

Field Detail

BACKOFF_INCREMENT_OPTION

public static final String BACKOFF_INCREMENT_OPTION

See Also:

Constant Field Values

MAX_BACKOFF_OPTION

public static final String MAX_BACKOFF_OPTION

See Also:

Constant Field Values

BAYEUX_VERSION

public static final String BAYEUX_VERSION

See Also:

Constant Field Values

Constructor Detail

BayeuxClient

public BayeuxClient(String url,
                    ClientTransport transport,
                    ClientTransport... transports)

Creates a BayeuxClient that will connect to the Bayeux server at the given URL and with the given transport(s).

This constructor allocates a new scheduler; it is recommended that when creating a large number of BayeuxClients a shared scheduler is used.

Parameters:

url - the Bayeux server URL to connect to

transport - the default (mandatory) transport to use

transports - additional optional transports to use in case the default transport cannot be used

See Also:

BayeuxClient(String, ScheduledExecutorService, ClientTransport, ClientTransport...)

BayeuxClient

public BayeuxClient(String url,
                    ScheduledExecutorService scheduler,
                    ClientTransport transport,
                    ClientTransport... transports)

Creates a BayeuxClient that will connect to the Bayeux server at the given URL, with the given scheduler and with the given transport(s).

Parameters:

url - the Bayeux server URL to connect to

scheduler - the scheduler to use for scheduling timed operations

transport - the default (mandatory) transport to use

transports - additional optional transports to use in case the default transport cannot be used

Method Detail

getURL

public String getURL()

Returns:

the URL passed when constructing this instance

getBackOffStrategy

public BayeuxClient.BackOffStrategy getBackOffStrategy()

setBackOffStrategy

public void setBackOffStrategy(BayeuxClient.BackOffStrategy backOffStrategy)

getCookieStore

public CookieStore getCookieStore()

getCookie

public HttpCookie getCookie(String name)

Retrieves the first cookie with the given name, if available.

Note that currently only HTTP transports support cookies.

Parameters:

name - the cookie name

Returns:

the cookie, or null if no such cookie is found

See Also:

putCookie(HttpCookie)

putCookie

public void putCookie(HttpCookie cookie)

getId

public String getId()

Description copied from interface: Session

The clientId of the session.

This would more correctly be called a "sessionId", but for backwards compatibility with the Bayeux protocol, it is a field called "clientId" that identifies a session.

Specified by:

getId in interface Session

Returns:

the id of this session

isHandshook

public boolean isHandshook()

Description copied from interface: Session

A handshook session is a session where the handshake has successfully completed

Specified by:

isHandshook in interface Session

Returns:

whether the session is handshook

isConnected

public boolean isConnected()

Description copied from interface: Session

A connected session is a session where the link between the client and the server has been established.

Specified by:

isConnected in interface Session

Returns:

whether the session is connected

See Also:

Session.disconnect()

isDisconnected

public boolean isDisconnected()

Returns:

whether this BayeuxClient is terminating or disconnected

getState

protected BayeuxClient.State getState()

Returns:

the current state of this BayeuxClient

addTransportListener

public void addTransportListener(TransportListener listener)

Parameters:

listener - the TransportListener to add

removeTransportListener

public void removeTransportListener(TransportListener listener)

Parameters:

listener - the TransportListener to remove

handshake

public void handshake(ClientSession.MessageListener callback)

Parameters:

callback - the message listener to notify of the handshake result

handshake

public void handshake(Map<String,Object> fields,
                      ClientSession.MessageListener callback)

Description copied from interface: ClientSession

Initiates the bayeux protocol handshake with the server(s).

The handshake initiated by this method is asynchronous and does not wait for the handshake response.

Specified by:

handshake in interface ClientSession

Parameters:

fields - additional fields to add to the handshake message.

callback - the message listener to notify of the handshake result

handshake

public BayeuxClient.State handshake(long waitMs)

Performs the handshake and waits at most the given time for the handshake to complete.

When this method returns, the handshake may have failed (for example because the Bayeux server denied it), so it is important to check the return value to know whether the handshake completed or not.

Parameters:

waitMs - the time to wait for the handshake to complete

Returns:

the state of this BayeuxClient

See Also:

handshake(Map, long)

handshake

public BayeuxClient.State handshake(Map<String,Object> template,
                                    long waitMs)

Performs the handshake with the given template and waits at most the given time for the handshake to complete.

When this method returns, the handshake may have failed (for example because the Bayeux server denied it), so it is important to check the return value to know whether the handshake completed or not.

Parameters:

template - the template object to be merged with the handshake message

waitMs - the time to wait for the handshake to complete

Returns:

the state of this BayeuxClient

See Also:

handshake(long)

sendHandshake

protected void sendHandshake()

waitFor

public boolean waitFor(long waitMs,
                       BayeuxClient.State state,
                       BayeuxClient.State... states)

Waits for this BayeuxClient to reach the given state(s) within the given time.

Parameters:

waitMs - the time to wait to reach the given state(s)

state - the state to reach

states - additional states to reach in alternative

Returns:

true if one of the state(s) has been reached within the given time, false otherwise

sendConnect

protected void sendConnect()

newChannelId

protected ChannelId newChannelId(String channelId)

Specified by:

newChannelId in class AbstractClientSession

newChannel

protected AbstractClientSession.AbstractSessionChannel newChannel(ChannelId channelId)

Specified by:

newChannel in class AbstractClientSession

sendBatch

protected void sendBatch()

Specified by:

sendBatch in class AbstractClientSession

sendMessages

protected void sendMessages(List<Message.Mutable> messages,
                            Promise<Boolean> promise)

disconnect

public void disconnect(ClientSession.MessageListener callback)

Description copied from interface: ClientSession

Disconnects this session, ending the link between the client and the server peers.

Specified by:

disconnect in interface ClientSession

Parameters:

callback - the message listener to notify of the disconnect result

disconnect

public boolean disconnect(long timeout)

Performs a disconnect and uses the given timeout to wait for the disconnect to complete.

When a disconnect is sent to the server, the server also wakes up the long poll that may be outstanding, so that a connect reply message may arrive to the client later than the disconnect reply message.

This method waits for the given timeout for the disconnect reply, but also waits the same timeout for the last connect reply; in the worst case the maximum time waited will therefore be twice the given timeout parameter.

This method returns true if the disconnect reply message arrived within the given timeout parameter, no matter if the connect reply message arrived or not.

Parameters:

timeout - the timeout to wait for the disconnect to complete

Returns:

true if the disconnect completed within the given timeout

abort

public void abort()

Interrupts abruptly the communication with the Bayeux server.

This method may be useful to simulate network failures.

See Also:

ClientSession.disconnect()

messagesFailure

protected void messagesFailure(Throwable cause,
                               List<? extends Message> messages)

processHandshake

protected void processHandshake(Message.Mutable handshake)

processConnect

protected void processConnect(Message.Mutable connect)

processDisconnect

protected void processDisconnect(Message.Mutable disconnect)

processMessage

protected void processMessage(Message.Mutable message)

scheduleHandshake

protected boolean scheduleHandshake(long interval,
                                    long backOff)

scheduleConnect

protected boolean scheduleConnect(long interval,
                                  long backOff)

getAllowedTransports

public List<String> getAllowedTransports()

Specified by:

getAllowedTransports in interface Bayeux

Returns:

the ordered list of transport names that will be used in the negotiation of transports with the other peer.

See Also:

Bayeux.getKnownTransportNames()

getKnownTransportNames

public Set<String> getKnownTransportNames()

Specified by:

getKnownTransportNames in interface Bayeux

Returns:

the set of known transport names of this Bayeux object.

See Also:

Bayeux.getAllowedTransports()

getTransport

public ClientTransport getTransport(String transport)

Specified by:

getTransport in interface Bayeux

Parameters:

transport - the transport name

Returns:

the transport with the given name or null if no such transport exist

getTransport

public ClientTransport getTransport()

initialize

protected void initialize()

terminate

protected void terminate(Throwable failure)

getOption

public Object getOption(String qualifiedName)

Specified by:

getOption in interface Bayeux

Parameters:

qualifiedName - the configuration option name

Returns:

the configuration option with the given qualifiedName

See Also:

Bayeux.setOption(String, Object), Bayeux.getOptionNames()

setOption

public void setOption(String qualifiedName,
                      Object value)

Specified by:

setOption in interface Bayeux

Parameters:

qualifiedName - the configuration option name

value - the configuration option value

See Also:

Bayeux.getOption(String)

getOptionNames

public Set<String> getOptionNames()

Specified by:

getOptionNames in interface Bayeux

Returns:

the set of configuration options

See Also:

Bayeux.getOption(String)

getOptions

public Map<String,Object> getOptions()

Returns:

the options that configure with BayeuxClient.

send

protected void send(Message.Mutable message)

Specified by:

send in class AbstractClientSession

enqueueSend

protected void enqueueSend(Message.Mutable message)

onSending

@Deprecated
public void onSending(List<? extends Message> messages)

Deprecated. use addTransportListener(TransportListener) instead

Callback method invoked when the given messages have hit the network towards the Bayeux server.

The messages may not be modified, and any modification will be useless because the message have already been sent.

Parameters:

messages - the messages sent

onMessages

@Deprecated
public void onMessages(List<Message.Mutable> messages)

Deprecated. use addTransportListener(TransportListener) instead

Callback method invoke when the given messages have just arrived from the Bayeux server.

The messages may be modified, but it's suggested to use Extensions instead.

Extensions will be processed after the invocation of this method.

Parameters:

messages - the messages arrived

onFailure

@Deprecated
public void onFailure(Throwable failure,
                                  List<? extends Message> messages)

Deprecated. use addTransportListener(TransportListener) instead

Callback method invoked when the given messages have failed to be sent.

The default implementation logs the failure at DEBUG level.

Parameters:

failure - the exception that caused the failure

messages - the messages being sent

onTransportFailure

protected void onTransportFailure(Message message,
                                  ClientTransport.FailureInfo failureInfo,
                                  ClientTransport.FailureHandler handler)

onTransportFailure

protected void onTransportFailure(String oldTransportName,
                                  String newTransportName,
                                  Throwable failure)

toString

public String toString()

Overrides:

toString in class Object