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 module hunt.shiro.event.EventBus; 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 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 methods with the {@link hunt.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 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 hunt.shiro.event.support.EventListenerResolver EventListenerResolver} 72 * (e.g. {@link hunt.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 }