Package com.intellij.util.messages

Interface MessageBus

All Superinterfaces:

Disposable

All Known Implementing Classes:

MessageBusImpl

public interface MessageBus
extends Disposable

Core of IntelliJ Platform messaging infrastructure. Basic functions:

• allows to push messages;
• allows to create connections for further subscriptions;

Use ComponentManager.getMessageBus() to obtain one.

Please see Messaging Infrastructure and Plugin Listeners.

Nested Class Summary

Nested classes/interfaces inherited from interface com.intellij.openapi.Disposable

Disposable.Parent

Method Summary

Modifier and Type	Method and Description
MessageBusConnection	connect() Allows to create new connection that is not bound to any Disposable.
MessageBusConnection	connect(Disposable parentDisposable) Allows to create new connection that is bound to the given Disposable.
void	dispose() Disposes current bus, i.e.
MessageBus	getParent() Message buses can be organised into hierarchies.
boolean	hasUndeliveredEvents(Topic<?> topic)
boolean	isDisposed() Returns true if this bus is disposed.
<L> L	syncPublisher(Topic<L> topic) Allows to retrieve an interface for publishing messages to the target topic.

Method Detail

getParent

MessageBus getParent()

Message buses can be organised into hierarchies. That allows facilities broadcasting.

Current method exposes parent bus (if any is defined).

Returns:

parent bus (if defined)

connect

MessageBusConnection connect()

Allows to create new connection that is not bound to any Disposable.

Returns:

newly created connection

connect

MessageBusConnection connect(Disposable parentDisposable)

Allows to create new connection that is bound to the given Disposable. That means that returned connection will be automatically released if given disposable parent is collected.

Parameters:

parentDisposable - target parent disposable to which life cycle newly created connection shall be bound

Returns:

newly created connection which life cycle is bound to the given disposable parent

syncPublisher

<L> L syncPublisher(Topic<L> topic)

Allows to retrieve an interface for publishing messages to the target topic.

Basically, the whole processing looks as follows:

1. Messaging clients create new connections within the target message bus and subscribe to the target topics;
2. Every time somebody wants to send a message for particular topic, he or she calls current method and receives object that conforms to the business interface of the target topic. Every method call on that object is dispatched by the messaging infrastructure to the subscribers. broadcasting is performed if necessary as well;

It's also very important to understand message processing strategy in case of nested dispatches. Consider the following situation:

1. Subscriber1 and subscriber2 are registered for the same topic within the same message bus;
2. Message1 is sent to that topic within the same message bus;
3. Queued messages delivery starts;
4. Queued messages delivery ends as there are no messages queued but not dispatched;
5. Message1 is queued for delivery to both subscribers;
6. Queued messages delivery starts;
7. Message1 is being delivered to the subscriber1;
8. Subscriber1 sends message2 to the same topic within the same bus;
9. Queued messages delivery starts;
10. Important: subscriber2 is being notified about all queued but not delivered messages, i.e. its callback is invoked for the message₁;
11. Queued messages delivery ends because all subscribers have been notified on the message1;
12. Message2 is queued for delivery to both subscribers;
13. Queued messages delivery starts;
14. Subscriber1 is notified on message2
15. Subscriber2 is notified on message2

Thread-safety. All subscribers are notified sequentially from the calling thread.

Memory management. Returned objects are very light-weight and stateless, so, they are cached by the message bus in 'per-topic' manner. That means that caller of this method is not obliged to keep returned reference along with the reference to the message for further publishing. It's enough to keep reference to the message bus only and publish like 'messageBus.syncPublisher(targetTopic).targetMethod()'.

Type Parameters:

L - business interface of the target topic

Parameters:

topic - target topic

Returns:

publisher for target topic

dispose

void dispose()

Disposes current bus, i.e. drops all queued but not delivered messages (if any) and disallows further connections.

Specified by:

dispose in interface Disposable

isDisposed

boolean isDisposed()

Returns true if this bus is disposed.

hasUndeliveredEvents

boolean hasUndeliveredEvents(Topic<?> topic)

Returns:

true when events in the given topic are being dispatched in the current thread, and not all listeners have received the events yet.