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.priority;
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     * Defines the priority of a handler method annotated with
023     * {@link com.ekuefler.supereventbus.Subscribe}. Handlers with a higher priority are always invoked
024     * before handlers with a lower priority. The order in which handlers of the same priority are
025     * invoked is undefined. If a priority is not specified with this annotation, it will be given a
026     * priority of zero. For example, defining the following three handlers and posting MyEvent would
027     * cause the alters "three", "two", and "one" to be shown, in that order:
028     *
029     * <pre>
030     * &#064;Subscribe &#064;WithPriority(-1)
031     * void after(MyEvent event) {
032     *   Window.alert("one");
033     * }
034     *
035     * &#064;Subscribe
036     * void normal(MyEvent event) {
037     *   Window.alert("two");
038     * }
039     *
040     * &#064;Subscribe &#064;WithPriority(1)
041     * void before(MyEvent event) {
042     *   Window.alert("three");
043     * }
044     * </pre>
045     *
046     * In general it is best to minimize usage of this annotation such that each handler can operate
047     * independently of other handlers. Priorities should only be set for handlers that must explicitly
048     * run before or after the majority of handlers, such as loggers that record when events start and
049     * finish being processed.
050     *
051     * @author ekuefler@gmail.com (Erik Kuefler)
052     */
053    @Documented
054    @Inherited
055    @Target(value = ElementType.METHOD)
056    public @interface WithPriority {
057      /**
058       * The priority to use for this handler. Higher-priority events are always handled before
059       * lower-priority events, with the default priority being 0. Note that priorities may be negative
060       * to force handlers to be run after other handlers.
061       */
062      int value();
063    }