001    /*
002     * Copyright 2013 Erik Kuefler
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005     * in compliance with the License. You may obtain a copy of the License at
006     *
007     * http://www.apache.org/licenses/LICENSE-2.0
008     *
009     * Unless required by applicable law or agreed to in writing, software distributed under the License
010     * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011     * or implied. See the License for the specific language governing permissions and limitations under
012     * the License.
013     */
014    package com.ekuefler.supereventbus.filtering;
015    
016    /**
017     * A filter capable of preventing an event handler method from receiving events. Filters are applied
018     * to event handlers using then {@link When} annotation. Filtering can be done based on the class
019     * containing the event handler, the event itself, or a combination of the two.
020     * <p>
021     * Note that all event handlers MUST define a zero-argument public constructor.
022     *
023     * @author ekuefler@gmail.com (Erik Kuefler)
024     *
025     * @param <H> type of the class containing the event handler method. This can be a general type like
026     *          {@link Object}, in which case the filter can be applied in any class.
027     * @param <E> type of event to which the filter applies. This can be a general type like
028     *          {@link Object}, in which can the filter can be applied to any handler method.
029     */
030    public interface EventFilter<H, E> {
031      /**
032       * Returns whether or not the given handler's {@link com.ekuefler.supereventbus.Subscribe}
033       * method should be invoked for the given event. If this method returns <code>false</code>, the
034       * underlying event handler will never be called.
035       *
036       * @param handler class containing the {@link com.ekuefler.supereventbus.Subscribe}-
037       *          annotated method to which the event is about to be dispatched
038       * @param event event currently being dispatched
039       * @return <code>true</code> to allow the method to handle the event, <code>false</code> to
040       *         prevent it
041       */
042      boolean accepts(H handler, E event);
043    }