/*
    * 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.support;
  
  import org.apache.shiro.event.EventBus;
  import org.slf4j.Logger;
  import org.slf4j.LoggerFactory;
  
  import java.util.ArrayList;
  import java.util.Collections;
  import java.util.HashSet;
  import java.util.LinkedHashMap;
  import java.util.List;
  import java.util.Map;
  import java.util.Set;
  import java.util.concurrent.locks.Lock;
  import java.util.concurrent.locks.ReentrantReadWriteLock;
  
  /**
   * A default event bus implementation that synchronously publishes events to registered listeners.  Listeners can be
   * registered or unregistered for events as necessary.
   * <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 that is more resilient to change over time.
   * <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.
   *
   * 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 shared/imported (even though Guava is Apache 2.0 licensed and could have
   * been used).
   *
   * This implementation is thread-safe and may be used concurrently.
   *
   * @since 1.3
   */
  public class DefaultEventBus implements EventBus {
  
      private static final Logger log = LoggerFactory.getLogger(DefaultEventBus.class);
  
      private static final String EVENT_LISTENER_ERROR_MSG = "Event listener processing failed.  Listeners should " +
              "generally handle exceptions directly and not propagate to the event bus.";
  
      //this is stateless, we can retain a static final reference:
      private static final EventListenerComparatorventListenerComparator">EventListenerComparator EVENT_LISTENER_COMPARATOR = new EventListenerComparator();
  
      private EventListenerResolver eventListenerResolver;
  
      //We want to preserve registration order to deliver events to objects in the order that they are registered
      //with the event bus.  This has the nice effect that any Shiro system-level components that are registered first
      //(likely to happen upon startup) have precedence over those registered by end-user components later.
      //
      //One might think that this could have been done by just using a ConcurrentSkipListMap (which is available only on
      //JDK 6 or later).  However, this approach requires the implementation of a Comparator to sort elements, and this
      //surfaces a problem: for any given random event listener, there isn't any guaranteed property to exist that can be
      //inspected to determine order of registration, since registration order is an artifact of this EventBus
      //implementation, not the listeners themselves.
      //
      //Therefore, we use a simple concurrent lock to wrap a LinkedHashMap - the LinkedHashMap retains insertion order
      //and the lock provides thread-safety in probably a much simpler mechanism than attempting to write a
      //EventBus-specific Comparator.  This technique is also likely to be faster than a ConcurrentSkipListMap, which
     //is about 3-5 times slower than a standard ConcurrentMap.
     private final Map<Object, Subscription> registry;
     private final Lock registryReadLock;
     private final Lock registryWriteLock;
 
     public DefaultEventBus() {
         this.registry = new LinkedHashMap<Object, Subscription>(); //not thread safe, so we need locks:
         ReentrantReadWriteLock rwl = new ReentrantReadWriteLock();
         this.registryReadLock = rwl.readLock();
         this.registryWriteLock = rwl.writeLock();
         this.eventListenerResolver = new AnnotationEventListenerResolver();
     }
 
     public EventListenerResolver getEventListenerResolver() {
         return eventListenerResolver;
     }
 
     public void setEventListenerResolver(EventListenerResolver eventListenerResolver) {
         this.eventListenerResolver = eventListenerResolver;
     }
 
     public void publish(Object event) {
         if (event == null) {
             log.info("Received null event for publishing.  Ignoring and returning.");
             return;
         }
 
         registryReadLock.lock();
         try {
             //performing the entire iteration within the lock will be a slow operation if the registry has a lot of
             //contention.  However, it is expected that the very large majority of cases the registry will be
             //read-mostly with very little writes (registrations or removals) occurring during a typical application
             //lifetime.
             //
             //The alternative would be to copy the registry.values() collection to a new LinkedHashSet within the lock
             //only and the iteration on this new collection could be outside the lock.  This has the performance penalty
             //however of always creating a new collection every time an event is published,  which could be more
             //costly for the majority of applications, especially if the number of listeners is large.
             //
             //Finally, the read lock is re-entrant, so multiple publish calls will be
             //concurrent without penalty since publishing is a read-only operation on the registry.
 
             for (Subscription subscription : this.registry.values()) {
                 subscription.onEvent(event);
             }
         } finally {
             registryReadLock.unlock();
         }
     }
 
     public void register(Object instance) {
         if (instance == null) {
             log.info("Received null instance for event listener registration.  Ignoring registration request.");
             return;
         }
 
         unregister(instance);
 
         List<EventListener> listeners = getEventListenerResolver().getEventListeners(instance);
 
         if (listeners == null || listeners.isEmpty()) {
             log.warn("Unable to resolve event listeners for subscriber instance [{}]. Ignoring registration request.",
                     instance);
             return;
         }
 
         Subscription subscription = new Subscription(listeners);
 
         this.registryWriteLock.lock();
         try {
             this.registry.put(instance, subscription);
         } finally {
             this.registryWriteLock.unlock();
         }
     }
 
     public void unregister(Object instance) {
         if (instance == null) {
             return;
         }
         this.registryWriteLock.lock();
         try {
             this.registry.remove(instance);
         } finally {
             this.registryWriteLock.unlock();
         }
     }
 
     private class Subscription {
 
         private final List<EventListener> listeners;
 
         public Subscription(List<EventListener> listeners) {
             List<EventListener> toSort = new ArrayList<EventListener>(listeners);
             Collections.sort(toSort, EVENT_LISTENER_COMPARATOR);
             this.listeners = toSort;
         }
 
         public void onEvent(Object event) {
 
             Set<Object> delivered = new HashSet<Object>();
 
             for (EventListener listener : this.listeners) {
                 Object target = listener;
                 if (listener instanceof SingleArgumentMethodEventListener) {
                     SingleArgumentMethodEventListenersupport/SingleArgumentMethodEventListener.html#SingleArgumentMethodEventListener">SingleArgumentMethodEventListener singleArgListener = (SingleArgumentMethodEventListener) listener;
                     target = singleArgListener.getTarget();
                 }
                 if (listener.accepts(event) && !delivered.contains(target)) {
                     try {
                         listener.onEvent(event);
                     } catch (Throwable t) {
                         log.warn(EVENT_LISTENER_ERROR_MSG, t);
                     }
                     delivered.add(target);
                 }
             }
         }
     }
 }