Package org.cometd.client

Class 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, and the most common transport is LongPollingTransport, which uses HTTP to transport Bayeux messages and it is based on Jetty's HTTP client.

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

    Typical usage:

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

 // Subscription to channels
 ClientSessionChannel channel = client.getChannel("/foo");
 channel.subscribe(new ClientSessionChannel.MessageListener()
 {
     public void onMessage(ClientSessionChannel channel, Message message)
     {
         // Handle the message
     }
 });

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

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

    • 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

      • getBackoffIncrement

        @Deprecated
public long getBackoffIncrement()
        Deprecated.
        use BayeuxClient.BackOffStrategy instead.
        Returns:
        the period of time that increments the pause to wait before trying to reconnect after each failed attempt to connect to the Bayeux server

      • getMaxBackoff

        @Deprecated
public long getMaxBackoff()
        Deprecated.
        use BayeuxClient.BackOffStrategy instead.
        Returns:
        the maximum pause to wait before trying to reconnect after each failed attempt to connect to the Bayeux server

      • 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

      • 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()

      • 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)

      • 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

      • initialize

        protected void initialize()

      • terminate

        protected void terminate()

      • getOptions

        public Map<String,​Object> getOptions()
        Returns:
        the options that configure with BayeuxClient.

      • onSending

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

        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

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

        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 ClientSession.Extensions instead.

        Extensions will be processed after the invocation of this method.

        Parameters:
        messages - the messages arrived

      • onFailure

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

        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​(String oldTransportName,
                                  String newTransportName,
                                  Throwable failure)