/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.
 */
package org.apache.shiro.event;

/**
 * An event bus can publish events to event subscribers as well as provide a mechanism for registering and unregistering
 * event subscribers.
 * <p/>
 * An event bus enables a publish/subscribe paradigm within Shiro - components can publish or consume events they
 * find relevant without needing to be tightly coupled to other components.  This affords great
 * flexibility within Shiro by promoting loose coupling and high cohesion between components and a much safer pluggable
 * architecture.
 * <h2>Sending Events</h2>
 * If a component wishes to publish events to other components:
 * <pre>
 *     MyEvent myEvent = createMyEvent();
 *     eventBus.publish(myEvent);
 * </pre>
 * The event bus will determine the type of event and then dispatch the event to components that wish to receive
 * events of that type.
 * <h2>Receiving Events</h2>
 * A component can receive events of interest by doing the following.
 * <ol>
 *     <li>For each type of event you wish to consume, create a public method that accepts a single event argument.
 *     The method argument type indicates the type of event to receive.</li>
 *     <li>Annotate each of these public methods with the {@link org.apache.shiro.event.Subscribe Subscribe} annotation.</li>
 *     <li>Register the component with the event bus:
 *     <pre>
 *         eventBus.register(myComponent);
 *     </pre>
 *     </li>
 * </ol>
 * After registering the component, when when an event of a respective type is published, the component's
 * {@code Subscribe}-annotated method(s) will be invoked as expected.
 * <p/>
 * This design (and its constituent helper components) was largely influenced by
 * Guava's <a href="http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/eventbus/EventBus.html">EventBus</a>
 * concept, although no code was viewed/copied/imported (even though Guava code is Apache 2.0 licensed and could have
 * been used).
 *
 * @since 1.3
 */
public interface EventBus {

    /**
     * Publishes the specified event to an event subsystem that will deliver events to relevant {@link Subscribe}rs.
     *
     * @param event The event object to distribute to relevant subscribers.
     */
    void publish(Object event);

    /**
     * Registers all event handler methods on the specified instance to receive relevant events.  The handler methods
     * are determined by the {@code EventBus} implementation, typically by using an
     * {@link org.apache.shiro.event.support.EventListenerResolver EventListenerResolver}
     * (e.g. {@link org.apache.shiro.event.support.AnnotationEventListenerResolver AnnotationEventListenerResolver}).
     *
     * @param subscriber the object whose event handler methods should be registered to receive events.
     */
    void register(Object subscriber);

    /**
     * Unregisters all previously-registered event handler methods on the specified instance.  If the specified object
     * was not previously registered, calling this method has no effect.
     *
     * @param subscriber the previously
     */
    void unregister(Object subscriber);
}