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

  • Method Details

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

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

    • 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

      <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:

    • getScope

      EventScope getScope()
      Gets the scope of the events published on this event bus.
      Returns:
      the event scope, never null.
      See Also:

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

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

    • 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

      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

      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:

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

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