1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.shiro.event;
20
21 /**
22 * An event bus can publish events to event subscribers as well as provide a mechanism for registering and unregistering
23 * event subscribers.
24 * <p/>
25 * An event bus enables a publish/subscribe paradigm within Shiro - components can publish or consume events they
26 * find relevant without needing to be tightly coupled to other components. This affords great
27 * flexibility within Shiro by promoting loose coupling and high cohesion between components and a much safer pluggable
28 * architecture.
29 * <h2>Sending Events</h2>
30 * If a component wishes to publish events to other components:
31 * <pre>
32 * MyEvent myEvent = createMyEvent();
33 * eventBus.publish(myEvent);
34 * </pre>
35 * The event bus will determine the type of event and then dispatch the event to components that wish to receive
36 * events of that type.
37 * <h2>Receiving Events</h2>
38 * A component can receive events of interest by doing the following.
39 * <ol>
40 * <li>For each type of event you wish to consume, create a public method that accepts a single event argument.
41 * The method argument type indicates the type of event to receive.</li>
42 * <li>Annotate each of these public methods with the {@link org.apache.shiro.event.Subscribe Subscribe} annotation.</li>
43 * <li>Register the component with the event bus:
44 * <pre>
45 * eventBus.register(myComponent);
46 * </pre>
47 * </li>
48 * </ol>
49 * After registering the component, when when an event of a respective type is published, the component's
50 * {@code Subscribe}-annotated method(s) will be invoked as expected.
51 * <p/>
52 * This design (and its constituent helper components) was largely influenced by
53 * Guava's <a href="http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/eventbus/EventBus.html">EventBus</a>
54 * concept, although no code was viewed/copied/imported (even though Guava code is Apache 2.0 licensed and could have
55 * been used).
56 *
57 * @since 1.3
58 */
59 public interface EventBus {
60
61 /**
62 * Publishes the specified event to an event subsystem that will deliver events to relevant {@link Subscribe}rs.
63 *
64 * @param event The event object to distribute to relevant subscribers.
65 */
66 void publish(Object event);
67
68 /**
69 * Registers all event handler methods on the specified instance to receive relevant events. The handler methods
70 * are determined by the {@code EventBus} implementation, typically by using an
71 * {@link org.apache.shiro.event.support.EventListenerResolver EventListenerResolver}
72 * (e.g. {@link org.apache.shiro.event.support.AnnotationEventListenerResolver AnnotationEventListenerResolver}).
73 *
74 * @param subscriber the object whose event handler methods should be registered to receive events.
75 */
76 void register(Object subscriber);
77
78 /**
79 * Unregisters all previously-registered event handler methods on the specified instance. If the specified object
80 * was not previously registered, calling this method has no effect.
81 *
82 * @param subscriber the previously
83 */
84 void unregister(Object subscriber);
85 }