1  
     2  /*
     3   * Copyright the original author or authors.
     4   * 
     5   * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (the "License");
     6   * you may not use this file except in compliance with the License.
     7   * You may obtain a copy of the License at
     8   * 
     9   *      http://www.mozilla.org/MPL/MPL-1.1.html
    10   * 
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17  
    18  import org.as2lib.env.event.EventListenerSource;
    19  import org.as2lib.env.event.distributor.EventDistributorControl;
    20  
    21  /**
    22   * {@code CompositeEventDistributorControl} allows flexible usage of events for complex class models.
    23   * 
    24   * <p>The {@link EventDistributorControl} class allows only for handling of one type of
    25   * listeners while this {@code CompositeEventDistributor} class allows multiple types
    26   * of listeners to provide more granularity if many different kinds of listeners are
    27   * used. It holds a collection of accepted types of listeners and checks if the listener
    28   * added via the {@link #addListener} method matches any of the accepted types and adds
    29   * it to the correct event distributor control(s).
    30   *
    31   * <p>Class that uses the composites functionalities:
    32   * <code>
    33   *   import org.as2lib.env.event.distributor.SimpleConsumableCompositeEventDistributorControl;
    34   *   
    35   *   class MyClass extends SimpleConsumableCompositeEventDistributorControl {
    36   *      
    37   *     public function MyClass(Void) {
    38   *       acceptListenerType(MyListener);
    39   *     }
    40   *     
    41   *     public function customMethod(Void):Void {
    42   *       var e:MyListener = getDistributor(MyListener);
    43   *       e.onEvent("1", "2");
    44   *     }
    45   *      
    46   *   }
    47   * </code>
    48   * 
    49   * <p>Listener interface:
    50   * <code>
    51   *   interface MyListener {
    52   *     
    53   *     public function onEvent(contentA:String, contentB:String):Void;
    54   *     
    55   *   }
    56   * </code>
    57   * 
    58   * <p>Listener interface implementation:
    59   * <code>
    60   *   class SimpleMyListener implements MyListener {
    61   *     
    62   *     private var prefix:String;
    63   *     
    64   *     public function SimpleMyListener(prefix:String) {
    65   *       this.prefix = prefix;
    66   *     }
    67   *     
    68   *     public function onEvent(contentA:String, contentB:String):Void {
    69   *       trace(prefix + contentA + ", " + prefix + contentB);
    70   *     }
    71   *     
    72   *   }
    73   * </code>
    74   * 
    75   * <p>Usage:
    76   * <code>
    77   *   var myClass:MyClass = new MyClass();
    78   *   myClass.addListener(new SimpleMyListener("a"));
    79   *   myClass.addListener(new SimpleMyListener("b"));
    80   *   // traces "a1, a2" and "b1, b2";
    81   *   myClass.customMethod();
    82   *   
    83   *   // throws an exception because listeners of type "Array" are not accepted
    84   *   myClass.addListener(new Array());
    85   * </code>
    86   * 
    87   * @author Martin Heidegger
    88   */
    89  interface org.as2lib.env.event.distributor.CompositeEventDistributorControl extends EventListenerSource {
    90  	
    91  	/**
    92  	 * Returns the distributor for the given {@code type} that can be used to distribute
    93  	 * events to all added listeners of the given {@code type}.
    94  	 * 
    95  	 * <p>The returned distributor can be casted to the given {@code type} (type-safe
    96  	 * distribution of events).
    97  	 * 
    98  	 * @return the distributor to distribute events
    99  	 */
   100  	public function getDistributor(type:Function);
   101  	
   102  	/**
   103  	 * Specifies that listeners of the given {@code type} are accepted, this includes
   104  	 * implementations of the given {@code type} as well as its sub-classes.
   105  	 * 
   106  	 * <p>{@code addListener} does not allow listeners that do not match (instanceof)
   107  	 * at least one accepted listener type.
   108  	 * 
   109  	 * @param listenerType the type of listeners that can be added
   110  	 */
   111  	public function acceptListenerType(listenerType:Function):Void;
   112  	
   113  	/**
   114  	 * Registers the given {@code eventDistributorControl} with its listener and
   115  	 * distributor type returned by its {@link EventDistributorControl#getType} method.
   116  	 * 
   117  	 * <p>If there is already a distributor control registered for the given type, it
   118  	 * will be overwritten.
   119  	 * 
   120  	 * <p>You use this method if you have a specific event that should be executed with
   121  	 * a special kind of distributor, for example with a consumable one.
   122  	 * 
   123  	 * @param eventDistributorControl the event distributor control to use for event
   124  	 * distribution for the given type
   125  	 * @see #setDefaultEventDistributorControl
   126  	 */
   127  	public function registerEventDistributorControl(eventDistributorControl:EventDistributorControl):Void;
   128  	
   129  	/**
   130  	 * Registers a default event distributor control with the given listener and
   131  	 * distributor type.
   132  	 * 
   133  	 * <p>If there is already a distributor control registered for the given type, it
   134  	 * will be overwritten.
   135  	 * 
   136  	 * @param type the type to register a default distributor control with
   137  	 */
   138  	public function registerDefaultEventDistributorControl(type:Function):Void;
   139  	
   140  }
as2api