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.multievent;
015    
016    /**
017     * An event wrapping another event that could be one of several unrelated types. This allows a
018     * handler method to handle events of multiple types that are not assignable to each other. For
019     * example, the following method would be invoked whenever Strings or Doubles were posted on the
020     * event bus:
021     *
022     * <pre>
023     * &#064;Subscribe
024     * void handleMultipleTypes(&#064;EventTypes({String.class, Double.class}) MultiEvent event) {
025     *   if (event instanceof String) {
026     *     Window.alert(&quot;Got a string: &quot; + event.getEvent());
027     *   } else if (event instanceof Double) {
028     *     Window.alert(&quot;Got a double: &quot; + event.getEvent());
029     *   }
030     * }
031     * </pre>
032     *
033     * Note the use of the {@link EventTypes} annotation to indicate which types of events should be
034     * handled. Parameters of type {@link MultiEvent} in Subscribe-annotated methods must always contain
035     * this annotation.
036     * <p>
037     * Also note that this technique should be used relatively sparingly. Most of the time, events that
038     * should be handled in the same way should be made to extend a common base class or interface, in
039     * which case that type can be made the argument to the handler method instead of MultiEvent.
040     * MultiEvent should only be used to handle events of unrelated types that can't be made to extend a
041     * common base.
042     * <p>
043     * Instances of MultiEvent are created automatically by the event bus - users should never
044     * instantiate or post these events on the event bus.
045     *
046     * @author ekuefler@gmail.com (Erik Kuefler)
047     */
048    public class MultiEvent {
049    
050      private final Object event;
051    
052      /**
053       * Instantiates a new MultiEvent wrapping the given event. Users should never have to invoke this
054       * method directly.
055       */
056      public MultiEvent(Object event) {
057        this.event = event;
058      }
059    
060      /**
061       * Returns the underlying event that this event wraps, which will be of a type assignable to one
062       * of the types declared in the {@link EventTypes} annotation for this parameter.
063       */
064      public Object getEvent() {
065        return event;
066      }
067    }