All Downloads are FREE. Search and download functionalities are using the official Maven repository.
  • Log In
  • Register

    • javadoc.com.google.common.eventbus.EventBus.html Maven / Gradle / Ivy

    The newest version!
    






EventBus (Guava: Google Core Libraries for Java 11.0.1 API)













    






    

    



    
  
    
      Overview 
      Package 
    Class 
      Use 
      Tree 
      Deprecated 
      Index 
      Help 
  
    

    
    		




    


    

 PREV CLASS 
 NEXT CLASS

  FRAMES   
 NO FRAMES   
 





    

    

  SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

    

    




    


    

com.google.common.eventbus

    
Class EventBus
    

    java.lang.Object
  extended by com.google.common.eventbus.EventBus

    

    

    Direct Known Subclasses: 
    AsyncEventBus
    

    

    

    

    @Beta
public class EventBus
    extends Object

    Dispatches events to listeners, and provides ways for listeners to register themselves.

    The EventBus allows publish-subscribe-style communication between components without requiring the components to explicitly register with one another (and thus be aware of each other). It is designed exclusively to replace traditional Java in-process event distribution using explicit registration. It is not a general-purpose publish-subscribe system, nor is it intended for interprocess communication.

    Receiving Events

    To receive events, an object should:
    1. Expose a public method, known as the event handler, which accepts a single argument of the type of event desired;
    2. Mark it with a Subscribe annotation;
    3. Pass itself to an EventBus instance's register(Object) method.

    Posting Events

    To post an event, simply provide the event object to the post(Object) method. The EventBus instance will determine the type of event and route it to all registered listeners.

    Events are routed based on their type — an event will be delivered to any handler for any type to which the event is assignable. This includes implemented interfaces, all superclasses, and all interfaces implemented by superclasses.

    When post is called, all registered handlers for an event are run in sequence, so handlers should be reasonably quick. If an event may trigger an extended process (such as a database load), spawn a thread or queue it for later. (For a convenient way to do this, use an AsyncEventBus.)

    Handler Methods

    Event handler methods must accept only one argument: the event.

    Handlers should not, in general, throw. If they do, the EventBus will catch and log the exception. This is rarely the right solution for error handling and should not be relied upon; it is intended solely to help find problems during development.

    The EventBus guarantees that it will not call a handler method from multiple threads simultaneously, unless the method explicitly allows it by bearing the AllowConcurrentEvents annotation. If this annotation is not present, handler methods need not worry about being reentrant, unless also called from outside the EventBus.

    Dead Events

    If an event is posted, but no registered handlers can accept it, it is considered "dead." To give the system a second chance to handle dead events, they are wrapped in an instance of DeadEvent and reposted.

    If a handler for a supertype of all events (such as Object) is registered, no event will ever be considered dead, and no DeadEvents will be generated. Accordingly, while DeadEvent extends Object, a handler registered to receive any Object will never receive a DeadEvent.

    This class is safe for concurrent use.

    Since:
    10.0
    Author:
    Cliff Biffle

    Constructor Summary
    EventBus()
              Creates a new EventBus named "default".
    EventBus(String identifier)
              Creates a new EventBus with the given identifier.
     
    Method Summary
    protected  void dispatch(Object event, com.google.common.eventbus.EventHandler wrapper)
              Dispatches event to the handler in wrapper.
    protected  void dispatchQueuedEvents()
              Drain the queue of events to be dispatched.
    protected  void enqueueEvent(Object event, com.google.common.eventbus.EventHandler handler)
              Queue the event for dispatch during dispatchQueuedEvents().
    protected  Set<com.google.common.eventbus.EventHandler> newHandlerSet()
              Creates a new Set for insertion into the handler map.
     void post(Object event)
              Posts an event to all registered handlers.
     void register(Object object)
              Registers all handler methods on object to receive events.
     void unregister(Object object)
              Unregisters all handler methods on a registered object.
     
    Methods inherited from class java.lang.Object
    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
     

    Constructor Detail

    EventBus

    public EventBus()
    Creates a new EventBus named "default".

    EventBus

    public EventBus(String identifier)
    Creates a new EventBus with the given identifier.

    Parameters:
    identifier - a brief name for this bus, for logging purposes. Should be a valid Java identifier.
    Method Detail

    register

    public void register(Object object)
    Registers all handler methods on object to receive events. Handler methods are selected and classified using this EventBus's HandlerFindingStrategy; the default strategy is the AnnotatedHandlerFinder.

    Parameters:
    object - object whose handler methods should be registered.

    unregister

    public void unregister(Object object)
    Unregisters all handler methods on a registered object.

    Parameters:
    object - object whose handler methods should be unregistered.
    Throws:
    IllegalArgumentException - if the object was not previously registered.

    post

    public void post(Object event)
    Posts an event to all registered handlers. This method will return successfully after the event has been posted to all handlers, and regardless of any exceptions thrown by handlers.

    If no handlers have been subscribed for event's class, and event is not already a DeadEvent, it will be wrapped in a DeadEvent and reposted.

    Parameters:
    event - event to post.

    enqueueEvent

    protected void enqueueEvent(Object event,
                            com.google.common.eventbus.EventHandler handler)
    Queue the event for dispatch during dispatchQueuedEvents(). Events are queued in-order of occurrence so they can be dispatched in the same order.

    dispatchQueuedEvents

    protected void dispatchQueuedEvents()
    Drain the queue of events to be dispatched. As the queue is being drained, new events may be posted to the end of the queue.

    dispatch

    protected void dispatch(Object event,
                        com.google.common.eventbus.EventHandler wrapper)
    Dispatches event to the handler in wrapper. This method is an appropriate override point for subclasses that wish to make event delivery asynchronous.

    Parameters:
    event - event to dispatch.
    wrapper - wrapper that will call the handler.

    newHandlerSet

    protected Set<com.google.common.eventbus.EventHandler> newHandlerSet()
    Creates a new Set for insertion into the handler map. This is provided as an override point for subclasses. The returned set should support concurrent access.

    Returns:
    a new, mutable set for handlers.
    Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
     PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
    SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
    Copyright © 2010-2012. All Rights Reserved.



    © 2015 - 2025 Weber Informatics LLC | Privacy Policy