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    import java.lang.annotation.Documented;
017    import java.lang.annotation.ElementType;
018    import java.lang.annotation.Inherited;
019    import java.lang.annotation.Target;
020    
021    /**
022     * Applies a filter to a {@link com.ekuefler.supereventbus.Subscribe}-annotated method so that the
023     * annotated method will be invoked only if the filter allows it. For example, the following filter
024     * would only listen for events when the enclosing widget was visible:
025     *
026     * <pre>
027     * class IsVisible implements EventFilter&lt;HasVisibility, Object&gt; {
028     *   &#064;Override
029     *   public boolean accepts(HasVisibility handler, Object event) {
030     *     return handler.isVisible();
031     *   }
032     * }
033     * </pre>
034     *
035     * That filter could be applied to a handler method as follows:
036     *
037     * <pre>
038     * &#064;Subscribe &#064;When(IsVisible.class)
039     * void onMyEvent(MyEvent event) {
040     *   // Handle the event
041     * }
042     * </pre>
043     *
044     * Whenever MyEvent is fired, the handler method would be notified only if the widget containing it
045     * was visible.
046     *
047     * @author ekuefler@gmail.com (Erik Kuefler)
048     */
049    @Documented
050    @Inherited
051    @Target(value = ElementType.METHOD)
052    public @interface When {
053      /**
054       * The list of filters that must be passed before this method is invoked. If multiple filters are
055       * specified, they must all pass in order for the method to be invoked. The check is
056       * short-circuiting, so later filters will not be invoked if earlier filters fail.
057       */
058      Class<? extends EventFilter<?, ?>>[] value();
059    }