All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.common.eventbus.package-info Maven / Gradle / Ivy

There is a newer version: 3.9
Show newest version
/*
 * Copyright (C) 2007 The Guava Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * 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.
 * 
 * 

See the Guava User Guide article on * {@code EventBus}. * *

One-Minute Guide

* * Converting an existing EventListener-based system to use the EventBus is * easy. * *

For Listeners

* To listen for a specific flavor of event (say, a CustomerChangeEvent)... *
    *
  • ...in traditional Java events: implement an interface * defined with the event — such as CustomerChangeEventListener.
  • *
  • ...with EventBus: create a method that accepts * CustomerChangeEvent as its sole argument, and mark it with the * {@link com.google.common.eventbus.Subscribe} annotation.
  • *
* *

To register your listener methods with the event producers... *

    *
  • ...in traditional Java events: pass your object to each * producer's {@code registerCustomerChangeEventListener} method. These * methods are rarely defined in common interfaces, so in addition to * knowing every possible producer, you must also know its type.
  • *
  • ...with EventBus: pass your object to the * {@link com.google.common.eventbus.EventBus#register(Object)} method on an * EventBus. You'll need to * make sure that your object shares an EventBus instance with the event * producers.
  • *
* *

To listen for a common event supertype (such as EventObject or Object)... *

    *
  • ...in traditional Java events: not easy.
  • *
  • ...with EventBus: events are automatically dispatched to * listeners of any supertype, allowing listeners for interface types * or "wildcard listeners" for Object.
  • *
* *

To listen for and detect events that were dispatched without listeners... *

    *
  • ...in traditional Java events: add code to each * event-dispatching method (perhaps using AOP).
  • *
  • ...with EventBus: subscribe to {@link * com.google.common.eventbus.DeadEvent}. The * EventBus will notify you of any events that were posted but not * delivered. (Handy for debugging.)
  • *
* *

For Producers

* To keep track of listeners to your events... *
    *
  • ...in traditional Java events: write code to manage * a list of listeners to your object, including synchronization, or use a * utility class like EventListenerList.
  • *
  • ...with EventBus: EventBus does this for you.
  • *
* *

To dispatch an event to listeners... *

    *
  • ...in traditional Java events: write a method to * dispatch events to each event listener, including error isolation and * (if desired) asynchronicity.
  • *
  • ...with EventBus: pass the event object to an EventBus's * {@link com.google.common.eventbus.EventBus#post(Object)} method.
  • *
* *

Glossary

* * The EventBus system and code use the following terms to discuss event * distribution: *
*
Event
Any object that may be posted to a bus.
*
Subscribing
The act of registering a listener with an * EventBus, so that its handler methods will receive events.
*
Listener
An object that wishes to receive events, by exposing * handler methods. *
Handler method
A public method that the EventBus should use to * deliver posted events. Handler methods are marked by the * {@link com.google.common.eventbus.Subscribe} annotation.
*
Posting an event
Making the event available to any * listeners through the EventBus. *
* *

FAQ

*

Why must I create my own Event Bus, rather than using a singleton?

* * The Event Bus doesn't specify how you use it; there's nothing stopping your * application from having separate EventBus instances for each component, or * using separate instances to separate events by context or topic. This also * makes it trivial to set up and tear down EventBus objects in your tests. * *

Of course, if you'd like to have a process-wide EventBus singleton, * there's nothing stopping you from doing it that way. Simply have your * container (such as Guice) create the EventBus as a singleton at global scope * (or stash it in a static field, if you're into that sort of thing). * *

In short, the EventBus is not a singleton because we'd rather not make * that decision for you. Use it how you like. * *

Why use an annotation to mark handler methods, rather than requiring the * listener to implement an interface?

* We feel that the Event Bus's {@code @Subscribe} annotation conveys your * intentions just as explicitly as implementing an interface (or perhaps more * so), while leaving you free to place event handler methods wherever you wish * and give them intention-revealing names. * *

Traditional Java Events use a listener interface which typically sports * only a handful of methods -- typically one. This has a number of * disadvantages: *

    *
  • Any one class can only implement a single response to a given event. *
  • Listener interface methods may conflict. *
  • The method must be named after the event (e.g. {@code * handleChangeEvent}), rather than its purpose (e.g. {@code * recordChangeInJournal}). *
  • Each event usually has its own interface, without a common parent * interface for a family of events (e.g. all UI events). *
* *

The difficulties in implementing this cleanly has given rise to a pattern, * particularly common in Swing apps, of using tiny anonymous classes to * implement event listener interfaces. * *

Compare these two cases:

 *   class ChangeRecorder {
 *     void setCustomer(Customer cust) {
 *       cust.addChangeListener(new ChangeListener() {
 *         void customerChanged(ChangeEvent e) {
 *           recordChange(e.getChange());
 *         }
 *       };
 *     }
 *   }
 *
 *   // Class is typically registered by the container.
 *   class EventBusChangeRecorder {
 *     @Subscribe void recordCustomerChange(ChangeEvent e) {
 *       recordChange(e.getChange());
 *     }
 *   }
* * The intent is actually clearer in the second case: there's less noise code, * and the event handler has a clear and meaningful name. * *

What about a generic {@code Handler} interface?

* Some have proposed a generic {@code Handler} interface for EventBus * listeners. This runs into issues with Java's use of type erasure, not to * mention problems in usability. * *

Let's say the interface looked something like the following:

   {@code
 *   interface Handler {
 *     void handleEvent(T event);
 *   }}
* * Due to erasure, no single class can implement a generic interface more than * once with different type parameters. This is a giant step backwards from * traditional Java Events, where even if {@code actionPerformed} and {@code * keyPressed} aren't very meaningful names, at least you can implement both * methods! * *

Doesn't EventBus destroy static typing and eliminate automated * refactoring support?

* Some have freaked out about EventBus's {@code register(Object)} and {@code * post(Object)} methods' use of the {@code Object} type. * *

{@code Object} is used here for a good reason: the Event Bus library * places no restrictions on the types of either your event listeners (as in * {@code register(Object)}) or the events themselves (in {@code post(Object)}). * *

Event handler methods, on the other hand, must explicitly declare their * argument type -- the type of event desired (or one of its supertypes). Thus, * searching for references to an event class will instantly find all handler * methods for that event, and renaming the type will affect all handler methods * within view of your IDE (and any code that creates the event). * *

It's true that you can rename your {@code @Subscribed} event handler * methods at will; Event Bus will not stop this or do anything to propagate the * rename because, to Event Bus, the names of your handler methods are * irrelevant. Test code that calls the methods directly, of course, will be * affected by your renaming -- but that's what your refactoring tools are for. * *

What happens if I {@code register} a listener without any handler * methods?

* Nothing at all. * *

The Event Bus was designed to integrate with containers and module * systems, with Guice as the prototypical example. In these cases, it's * convenient to have the container/factory/environment pass every * created object to an EventBus's {@code register(Object)} method. * *

This way, any object created by the container/factory/environment can * hook into the system's event model simply by exposing handler methods. * *

What Event Bus problems can be detected at compile time?

* Any problem that can be unambiguously detected by Java's type system. For * example, defining a handler method for a nonexistent event type. * *

What Event Bus problems can be detected immediately at registration?

* Immediately upon invoking {@code register(Object)} , the listener being * registered is checked for the well-formedness of its handler methods. * Specifically, any methods marked with {@code @Subscribe} must take only a * single argument. * *

Any violations of this rule will cause an {@code IllegalArgumentException} * to be thrown. * *

(This check could be moved to compile-time using APT, a solution we're * researching.) * *

What Event Bus problems may only be detected later, at runtime?

* If a component posts events with no registered listeners, it may * indicate an error (typically an indication that you missed a * {@code @Subscribe} annotation, or that the listening component is not loaded). * *

(Note that this is not necessarily indicative of a problem. There * are many cases where an application will deliberately ignore a posted event, * particularly if the event is coming from code you don't control.) * *

To handle such events, register a handler method for the {@code DeadEvent} * class. Whenever EventBus receives an event with no registered handlers, it * will turn it into a {@code DeadEvent} and pass it your way -- allowing you to * log it or otherwise recover. * *

How do I test event listeners and their handler methods?

* Because handler methods on your listener classes are normal methods, you can * simply call them from your test code to simulate the EventBus. */ package com.google.common.eventbus;




© 2015 - 2024 Weber Informatics LLC | Privacy Policy