View Javadoc

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  }