001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.shiro.event;
020
021/**
022 * An event bus can publish events to event subscribers as well as provide a mechanism for registering and unregistering
023 * event subscribers.
024 * <p/>
025 * An event bus enables a publish/subscribe paradigm within Shiro - components can publish or consume events they
026 * find relevant without needing to be tightly coupled to other components.  This affords great
027 * flexibility within Shiro by promoting loose coupling and high cohesion between components and a much safer pluggable
028 * architecture.
029 * <h2>Sending Events</h2>
030 * If a component wishes to publish events to other components:
031 * <pre>
032 *     MyEvent myEvent = createMyEvent();
033 *     eventBus.publish(myEvent);
034 * </pre>
035 * The event bus will determine the type of event and then dispatch the event to components that wish to receive
036 * events of that type.
037 * <h2>Receiving Events</h2>
038 * A component can receive events of interest by doing the following.
039 * <ol>
040 *     <li>For each type of event you wish to consume, create a public method that accepts a single event argument.
041 *     The method argument type indicates the type of event to receive.</li>
042 *     <li>Annotate each of these public methods with the {@link org.apache.shiro.event.Subscribe Subscribe} annotation.</li>
043 *     <li>Register the component with the event bus:
044 *     <pre>
045 *         eventBus.register(myComponent);
046 *     </pre>
047 *     </li>
048 * </ol>
049 * After registering the component, when when an event of a respective type is published, the component's
050 * {@code Subscribe}-annotated method(s) will be invoked as expected.
051 * <p/>
052 * This design (and its constituent helper components) was largely influenced by
053 * Guava's <a href="http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/eventbus/EventBus.html">EventBus</a>
054 * concept, although no code was viewed/copied/imported (even though Guava code is Apache 2.0 licensed and could have
055 * been used).
056 *
057 * @since 1.3
058 */
059public interface EventBus {
060
061    /**
062     * Publishes the specified event to an event subsystem that will deliver events to relevant {@link Subscribe}rs.
063     *
064     * @param event The event object to distribute to relevant subscribers.
065     */
066    void publish(Object event);
067
068    /**
069     * Registers all event handler methods on the specified instance to receive relevant events.  The handler methods
070     * are determined by the {@code EventBus} implementation, typically by using an
071     * {@link org.apache.shiro.event.support.EventListenerResolver EventListenerResolver}
072     * (e.g. {@link org.apache.shiro.event.support.AnnotationEventListenerResolver AnnotationEventListenerResolver}).
073     *
074     * @param subscriber the object whose event handler methods should be registered to receive events.
075     */
076    void register(Object subscriber);
077
078    /**
079     * Unregisters all previously-registered event handler methods on the specified instance.  If the specified object
080     * was not previously registered, calling this method has no effect.
081     *
082     * @param subscriber the previously
083     */
084    void unregister(Object subscriber);
085}