Errai 3.0.1-SNAPSHOT

org.jboss.errai.bus.client.api
Interface BusLifecycleListener

All Known Implementing Classes:
BusLifecycleAdapter

public interface BusLifecycleListener

Errai's ClientMessageBus has three conceptual states in its lifecycle: local only, connecting, and connected. This interface allows Errai applications to observe lifecycle state transitions in the bus.

The bus lifecycle is as follows. Every time the bus transitions from one state to another, the correspondingly named event is delivered to all listeners:

The bus begins in the local only state, and automatically transitions to the connecting state unless configured not to. Therefore, unless remote communication is disabled by static global configuration, application code will first observe the bus in its connecting state. In the connecting state, the bus "wants" to be connected to the server, and it actively tries to establish a connection, reconnecting after communication disruptions as necessary. When in the connecting state, the bus will make a configurable number of attempts to reach the connected state. After this many retries, the bus will give up and fall back to the local only state.

Once the bus has established a connection with the server and exchanged the list of available topics with the server bus, the bus is in the connected state, and bidirectional communication between client and server is possible.

If there is a communication error when the bus is in the connected state, the bus falls back to the connecting state, where it attempts to reconnect to the server.

Recursive event delivery

If you call {ClientMessageBus#stop()} or {ClientMessageBus#init()} from within one of these callback methods, be aware that this can cause another lifecycle event to be delivered before the current event has finished being delivered. This is especially important to avoid if your application employs more than one BusLifecycleListener, because some of these listeners will receive events out of order. An easy workaround for this problem is to wrap your bus.init() or bus.stop() call in a Timer with a delay of 1ms.

Author:
Jonathan Fuerth , Christian Sadilek

Method Summary
 void busAssociating(BusLifecycleEvent e)
          Indicates that the bus is about to transition from the local only to the connecting state.
 void busDisassociating(BusLifecycleEvent e)
          Indicates that the bus is about to transition from the connecting to the local only state.
 void busOffline(BusLifecycleEvent e)
          Indicates that the bus has just transitioned from the connected to the connecting state.
 void busOnline(BusLifecycleEvent e)
          Indicates that the bus has just transitioned from the connecting to the connected state.
 

Method Detail

busAssociating

void busAssociating(BusLifecycleEvent e)
Indicates that the bus is about to transition from the local only to the connecting state. While this event is being delivered, it is still permitted to change the remote endpoint URL of the server bus.

Parameters:
e - the object describing the event (includes a reference to the bus that fired the event).

busDisassociating

void busDisassociating(BusLifecycleEvent e)
Indicates that the bus is about to transition from the connecting to the local only state. This can happen automatically due to too many failed connection attempts, or because the application stopped the bus explicitly.

When you want to try to connect to the server again (for example, to fail over to another server, after a set timeout has elapsed, or in response to the user clicking a "Reconnect" button in the user interface), call ClientMessageBusImpl.init(). This will transition the bus back to the connecting state.

Parameters:
e - the object describing the event (includes a reference to the bus that fired the event).

busOnline

void busOnline(BusLifecycleEvent e)
Indicates that the bus has just transitioned from the connecting to the connected state. At the time when this event is delivered, it is possible to exchange messages with the remote bus.

Parameters:
e - the object describing the event (includes a reference to the bus that fired the event).

busOffline

void busOffline(BusLifecycleEvent e)
Indicates that the bus has just transitioned from the connected to the connecting state. In the connecting state, the bus will continue to attempt to reconnect to the server. If the reconnect is successful, you will receive a busOnline(BusLifecycleEvent) event. If the bus gives up trying to reconnect, you will receive a busDisassociating(BusLifecycleEvent) event.

At the time when this event is delivered, messages intended for the remote bus will be enqueued for delivery when (and if) the bus goes back online.

Parameters:
e - the object describing the event (includes a reference to the bus that fired the event).

Errai 3.0.1-SNAPSHOT

Copyright © 2013-2014 JBoss, a division of Red Hat. All Rights Reserved.