Errai 3.0.1-SNAPSHOT

org.jboss.errai.bus.client.api.messaging
Interface MessageBus

All Known Subinterfaces:
ClientMessageBus, ServerMessageBus
All Known Implementing Classes:
ClientBusProxyImpl, ClientMessageBusImpl, LocationAwareClientMessageBus, MessageBusProxy, ServerMessageBusImpl

public interface MessageBus

A message bus is capable of transmitting and receiving messages using the publisher/subscriber model. All implementations of the bus should implement this interface for both the client-side and the server-side.

The MessageBus architecture uses a flat topology with automatic bus-to-bus routing which is accomplished through automatic cross-subscription between federated buses. However, each bus-to-bus federated relationship has only a one-degree visibility with the federation. This means that while, in practice, client buses may be federated wth a server bus, each client bus can only see the server bus directly.

                         _____________________
                        /     (Context B)     \
  _________         _________         _________
 |        |        |        |        |        |
 | Client | <----> | Server | <----> | Client |
 |________|        |________|        |________|
 \_____________________/
       (Context A)
 
The diagram shows two clients federated within the messaging topology. The contexts indicate the scope by which direct communication is possible. In order to facilitate client-to-client communication, users must implement relay services in the server manually.

Services always live on the bus with which they a registered. When a new registration occurs, the service becomes generally available across the entire context. This is accomplished by notifying the proximate bus-- in real-time--that a subscription has been created with a BusCommand.RemoteSubscribe command containing the subject that has just become routable. Likewise, when a subject is unsubscribed, an BusCommand.RemoteUnsubscribe is sent.

Creating a service subscription is straight-forward:


 busInstance.subscribe("ServiceName",
                      new MessageCallback() {
                              public void callback(CommandMessage message) {
                                  // do something.
                              }
                      }
 );
 
The API for creating services is heterogeneous in both client and server code. The only semantic difference involves obtaining an instance of the MessageBus which is done using the ErraiBus.get() method in client code, and by default, is provided by the container using dependency injection in the server code. For example:


Author:
Mike Brock

Method Summary
 void addSubscribeListener(SubscribeListener listener)
          Registers a subscription listener, which is fired whenever a new subscription is created.
 void addUnsubscribeListener(UnsubscribeListener listener)
          Registers an un-subscribe listener, which is fired whenever a subscription is cancelled.
 void attachMonitor(BusMonitor monitor)
          Attach a monitor to the bus.
 boolean isSubscribed(String subject)
          Returns true if there the specified subject has one or more listeners registered.
 void send(Message message)
          Transmits a message.
 void send(Message message, boolean fireListeners)
          Transmits a message and may optionally supress message listeners from firing.
 void sendGlobal(Message message)
          Transmits the message to all directly-peered buses (global in relation to this bus only).
 Subscription subscribe(String subject, MessageCallback receiver)
          Subscribe a listener to the specified subject.
 Subscription subscribeLocal(String subject, MessageCallback receiver)
          Subscribe a listern locally, but do not advertise or make available the service to remote buses.
 void unsubscribeAll(String subject)
          Unsubscribe all listeners registered for the specified subject.
 

Method Detail

sendGlobal

void sendGlobal(Message message)
Transmits the message to all directly-peered buses (global in relation to this bus only).

Parameters:
message - - The message to be sent.

send

void send(Message message)
Transmits a message.

Parameters:
message -

send

void send(Message message,
          boolean fireListeners)
Transmits a message and may optionally supress message listeners from firing. This is useful if you are modifying a message from within a listener itself, and wish to retransmit the message.

Parameters:
message -
fireListeners -

subscribe

Subscription subscribe(String subject,
                       MessageCallback receiver)
Subscribe a listener to the specified subject.

Parameters:
subject -
receiver -

subscribeLocal

Subscription subscribeLocal(String subject,
                            MessageCallback receiver)
Subscribe a listern locally, but do not advertise or make available the service to remote buses.

Parameters:
subject -
receiver -

unsubscribeAll

void unsubscribeAll(String subject)
Unsubscribe all listeners registered for the specified subject.


isSubscribed

boolean isSubscribed(String subject)
Returns true if there the specified subject has one or more listeners registered.

Parameters:
subject -
Returns:

addSubscribeListener

void addSubscribeListener(SubscribeListener listener)
Registers a subscription listener, which is fired whenever a new subscription is created.

Parameters:
listener -

addUnsubscribeListener

void addUnsubscribeListener(UnsubscribeListener listener)
Registers an un-subscribe listener, which is fired whenever a subscription is cancelled.

Parameters:
listener -

attachMonitor

void attachMonitor(BusMonitor monitor)
Attach a monitor to the bus.

Parameters:
monitor -

Errai 3.0.1-SNAPSHOT

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