org.vaadin.spring.events

Interface EventBus

All Known Subinterfaces:

EventBus.ApplicationEventBus, EventBus.SessionEventBus, EventBus.UIEventBus, EventBus.ViewEventBus

All Known Implementing Classes:

ScopedEventBus, ScopedEventBus.DefaultApplicationEventBus, ScopedEventBus.DefaultSessionEventBus, ScopedEventBus.DefaultUIEventBus, ScopedEventBus.DefualtViewEventBus

public interface EventBus

Interface defining an event bus. This event bus infrastructure complements the ApplicationEventPublisher in the following ways:

• Events propagate from parent buses to children
• Events are scoped

There are four event scopes, and therefore four event bus types (each with their own sub interface):

1. EventScope.APPLICATION events are published to the entire application.
2. EventScope.SESSION events are published to the current session.
3. EventScope.UI events are published to the current UI.
4. EventScope.VIEW events are published to the current view.

The event buses are chained in the following way:

• Application events are propagated to the session event bus.
• Session events are propagated to the UI event bus.
• UI events are propagated to the view event bus.

Furthermore, ApplicationEventPublisher events can be propagated to any event bus by using ApplicationContextEventBroker.

You select which EventBus implementation to inject by using the corresponding interface. For example, to inject the UI-scoped event bus, you would use: @Autowired UIEventBus myUIScopedEventBus; With this implementation, you can subscribe to and publish events of the application, session and UI scopes (see publish(EventScope, Object, Object)).

Author:

Petter Holmström (petter@vaadin.com)

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	EventBus.ApplicationEventBus Interface implemented by the application scoped event bus.
static interface	EventBus.SessionEventBus Interface implemented by the session scoped event bus.
static interface	EventBus.UIEventBus Interface implemented by the UI scoped event bus.
static interface	EventBus.ViewEventBus Interface implemented by the view scoped event bus.

Method Summary

Modifier and Type	Method and Description
EventScope	getScope() Gets the scope of the events published on this event bus.
<T> void	publish(EventScope scope, Object sender, T payload) Publishes the specified payload on the event bus, or any of its parent buses, depending on the event scope.
<T> void	publish(EventScope scope, String topic, Object sender, T payload) Publishes the specified payload on the event bus, or any of its parent buses, depending on the event scope.
<T> void	publish(Object sender, T payload) Publishes the specified payload on the event bus, using the scope of this particular event bus.
<T> void	publish(String topic, Object sender, T payload) Publishes the specified payload on the event bus, using the scope of this particular event bus.
<T> void	subscribe(EventBusListener<T> listener) Subscribes the specified listener to the event bus, including propagated events from parent event buses.
<T> void	subscribe(EventBusListener<T> listener, boolean includingPropagatingEvents) Subscribes the specified listener to the event bus.
<T> void	subscribe(EventBusListener<T> listener, String topic) Subscribes the topic interested listener to the event bus, including propagated events from parent event buses.
void	subscribe(Object listener) Subscribes the specified listener to the event bus.
void	subscribe(Object listener, boolean includingPropagatingEvents) Subscribes the specified listener to the event bus.
void	subscribe(Object listener, String topic) Subscribes the topic interested listener to the event bus.
<T> void	subscribeWithWeakReference(EventBusListener<T> listener) Same as subscribe(EventBusListener), but uses a weak reference to store the listener internally.
<T> void	subscribeWithWeakReference(EventBusListener<T> listener, boolean includingPropagatingEvents) Same as subscribe(EventBusListener, boolean), but uses a weak reference to store the listener internally.
<T> void	subscribeWithWeakReference(EventBusListener<T> listener, String topic) Same as subscribe(EventBusListener, String), but uses a weak reference to store the listener internally.
void	subscribeWithWeakReference(Object listener) Same as subscribe(Object), but uses a weak reference to store the listener internally.
void	subscribeWithWeakReference(Object listener, boolean includingPropagatingEvents) Same as subscribe(Object, boolean), but uses a weak reference to store the listener internally.
void	subscribeWithWeakReference(Object listener, String topic) Same as subscribe(Object, String), but uses a weak reference to store the listener internally.
<T> void	unsubscribe(EventBusListener<T> listener) Unsubscribes the specified listener from the event bus.
void	unsubscribe(Object listener) Unsubscribes the specified listener (and all its listener methods) from the event bus.

Method Detail

publish

<T> void publish(Object sender,
                 T payload)

Publishes the specified payload on the event bus, using the scope of this particular event bus.

Type Parameters:

T - the type of the payload.

Parameters:

sender - the object that published the event, never null.

payload - the payload of the event to publish, never null.

See Also:

getScope()

publish

<T> void publish(String topic,
                 Object sender,
                 T payload)

Publishes the specified payload on the event bus, using the scope of this particular event bus. The topic specifies which listeners will be notified.

Type Parameters:

T - the type of the payload.

Parameters:

topic - the topic of the event to publish, never null.

sender - the object that published the event, never null.

payload - the payload of the event to publish, never null.

See Also:

getScope()

publish

<T> void publish(EventScope scope,
                 Object sender,
                 T payload)
          throws UnsupportedOperationException

Publishes the specified payload on the event bus, or any of its parent buses, depending on the event scope.

Type Parameters:

T - the type of the payload;

Parameters:

scope - the scope of the event, never null.

sender - the object that published the event, never null.

payload - the payload of the event to publish, never null.

Throws:

UnsupportedOperationException - if the payload could not be published with the specified scope.

See Also:

publish(Object, Object)

publish

<T> void publish(EventScope scope,
                 String topic,
                 Object sender,
                 T payload)
          throws UnsupportedOperationException

Publishes the specified payload on the event bus, or any of its parent buses, depending on the event scope. The topic specifies which listeners will be notified.

Type Parameters:

T - the type of the payload;

Parameters:

scope - the scope of the event, never null.

topic - the topic of the event to publish, never null.

sender - the object that published the event, never null.

payload - the payload of the event to publish, never null.

Throws:

UnsupportedOperationException - if the payload could not be published with the specified scope.

See Also:

publish(Object, Object)

getScope

EventScope getScope()

Gets the scope of the events published on this event bus.

Returns:

the event scope, never null.

See Also:

Event.getScope()

subscribe

<T> void subscribe(EventBusListener<T> listener)

Subscribes the specified listener to the event bus, including propagated events from parent event buses. The event bus will analyse the payload type of the listener to determine which events it is interested in receiving. This is the same as calling subscribe(listener, true).

Type Parameters:

T - the type of payload the listener is interested in.

Parameters:

listener - the listener to subscribe, never null.

See Also:

unsubscribe(EventBusListener), subscribeWithWeakReference(EventBusListener)

subscribeWithWeakReference

<T> void subscribeWithWeakReference(EventBusListener<T> listener)

Same as subscribe(EventBusListener), but uses a weak reference to store the listener internally.

subscribe

<T> void subscribe(EventBusListener<T> listener,
                   String topic)

Subscribes the topic interested listener to the event bus, including propagated events from parent event buses. The event bus will analyse the payload type and topic of the listener to determine which events it is interested in receiving.

Type Parameters:

T - the type of payload the listener is interested in

Parameters:

listener - the listener to subscribe, never null

topic - the topic of listener interest

subscribeWithWeakReference

<T> void subscribeWithWeakReference(EventBusListener<T> listener,
                                    String topic)

Same as subscribe(EventBusListener, String), but uses a weak reference to store the listener internally.

subscribe

<T> void subscribe(EventBusListener<T> listener,
                   boolean includingPropagatingEvents)

Subscribes the specified listener to the event bus. The event bus will analyse the payload type of the listener to determine which events it is interested in receiving.

Type Parameters:

T - the type of payload the listener is interested in.

Parameters:

listener - the listener to subscribe, never null.

includingPropagatingEvents - true to notify the listener of events that have propagated from the chain of parent event buses, false to only notify the listeners of events that are directly published on this event bus.

See Also:

unsubscribe(EventBusListener), subscribeWithWeakReference(EventBusListener, boolean)

subscribeWithWeakReference

<T> void subscribeWithWeakReference(EventBusListener<T> listener,
                                    boolean includingPropagatingEvents)

Same as subscribe(EventBusListener, boolean), but uses a weak reference to store the listener internally.

subscribe

void subscribe(Object listener)

Subscribes the specified listener to the event bus. The listener need not implement the EventBusListener interface, but must contain one or more methods that are annotated with the EventBusListenerMethod interface and conform to one of these method signatures: myMethodName(Event<MyPayloadType>) or myMethodName(MyPayloadType). The event bus will analyse the payload type of the listener methods to determine which events the different methods are interested in receiving. This is the same as calling subscribe(listener, true).

Parameters:

listener - the listener to subscribe, never null.

See Also:

subscribeWithWeakReference(Object)

subscribeWithWeakReference

void subscribeWithWeakReference(Object listener)

Same as subscribe(Object), but uses a weak reference to store the listener internally.

subscribe

void subscribe(Object listener,
               String topic)

Subscribes the topic interested listener to the event bus. The listener need not implement the EventBusListener interface, but must contain one or more methods that are annotated with the EventBusListenerMethod interface and conform to one of these method signatures: myMethodName(Event<MyPayloadType>) or myMethodName(MyPayloadType). The event bus will analyse the payload type of the listener methods to determine which events the different methods are interested in receiving.



Example: subscribe(Listener.this, "/news");

Parameters:

listener - the listener to subscribe, never null.

topic - the topic of listener interest

See Also:

subscribeWithWeakReference(Object, String)

subscribeWithWeakReference

void subscribeWithWeakReference(Object listener,
                                String topic)

Same as subscribe(Object, String), but uses a weak reference to store the listener internally.

subscribe

void subscribe(Object listener,
               boolean includingPropagatingEvents)

Subscribes the specified listener to the event bus. The listener need not implement the EventBusListener interface, but must contain one or more methods that are annotated with the EventBusListenerMethod interface and conform to one of these method signatures: myMethodName(Event<MyPayloadType>) or myMethodName(MyPayloadType). The event bus will analyse the payload type of the listener methods to determine which events the different methods are interested in receiving.

Parameters:

listener - the listener to subscribe, never null.

includingPropagatingEvents - true to notify the listener of events that have propagated from the chain of parent event buses, false to only notify the listeners of events that are directly published on this event bus.

See Also:

unsubscribe(Object), subscribeWithWeakReference(Object, boolean)

subscribeWithWeakReference

void subscribeWithWeakReference(Object listener,
                                boolean includingPropagatingEvents)

Same as subscribe(Object, boolean), but uses a weak reference to store the listener internally.

unsubscribe

<T> void unsubscribe(EventBusListener<T> listener)

Unsubscribes the specified listener from the event bus. Also works for listeners stored with weak references.

Type Parameters:

T - the type of the payload.

Parameters:

listener - the listener to unsubscribe, never null.

See Also:

subscribe(EventBusListener), subscribe(EventBusListener, boolean)

unsubscribe

void unsubscribe(Object listener)

Unsubscribes the specified listener (and all its listener methods) from the event bus. Also works for listeners stored with weak references.

Parameters:

listener - the listener to unsubscribe, never null.

See Also:

subscribe(Object), subscribe(Object, boolean)