text: /*
   PureMVC - Copyright(c) 2006-08 Futurescale, Inc., Some rights reserved.
   Your reuse is governed by the Creative Commons Attribution 3.0 United States License
  */
  package org.puremvc.loomsdk.interfaces
  {
      
      /**
       * The interface definition for a PureMVC Mediator.
       *
       * <P>
       * In PureMVC, <code>IMediator</code> implementors assume these responsibilities:</P>
       * <UL>
       * <LI>Implement a common method which returns a list of all <code>INotification</code>s 
       * the <code>IMediator</code> has interest in.</LI>
       * <LI>Implement a notification callback method.</LI>
       * <LI>Implement methods that are called when the IMediator is registered or removed from the View.</LI>
       * </UL>
       * <P>
       * Additionally, <code>IMediator</code>s typically:
       * <UL>
       * <LI>Act as an intermediary between one or more view components such as text boxes or 
       * list controls, maintaining references and coordinating their behavior.</LI>
       * <LI>In Flash-based apps, this is often the place where event listeners are
       * added to view components, and their handlers implemented.</LI>
       * <LI>Respond to and generate <code>INotifications</code>, interacting with of 
       * the rest of the PureMVC app.
       * </UL></P>
       * <P>
       * When an <code>IMediator</code> is registered with the <code>IView</code>, 
       * the <code>IView</code> will call the <code>IMediator</code>'s 
       * <code>listNotificationInterests</code> method. The <code>IMediator</code> will 
       * return an <code>Array</code> of <code>INotification</code> names which 
       * it wishes to be notified about.</P>
       * 
       * <P>
       * The <code>IView</code> will then create an <code>Observer</code> object 
       * encapsulating that <code>IMediator</code>'s (<code>handleNotification</code>) method
       * and register it as an Observer for each <code>INotification</code> name returned by 
       * <code>listNotificationInterests</code>.</P>
       * 
       * <P>
       * A concrete IMediator implementor usually looks something like this:</P>
       * 
       * <listing>
       *    import org.puremvc.loomsdk.patterns.mediator.~~;
       *    import org.puremvc.loomsdk.patterns.observer.~~;
       *    import org.puremvc.loomsdk.core.view.~~;
       * 
       *    import com.me.myapp.model.~~;
       *    import com.me.myapp.view.~~;
       *    import com.me.myapp.controller.~~;
       *         
       *    import mx.controls.ComboBox;
       *    import mx.events.ListEvent;
       * 
       * public class MyMediator extends Mediator implements IMediator {
       * 
       *         public function MyComboMediator( viewComponent:Object ) {
       *             super( viewComponent );
       *             combo.addEventListener( Event.CHANGE, onChange );
       *         }
       *         
       *         override public function listNotificationInterests():Array {
       *                 return [ MyFacade.SET_SELECTION, 
       *                          MyFacade.SET_DATAPROVIDER ];
       *         }
       * 
       *         override public function handleNotification( notification:INotification ):void {
       *                 switch ( notification.getName() ) {
       *                     case MyFacade.SET_SELECTION:
       *                         setSelection(notification);
       *                         break;
       *                     case MyFacade.SET_DATAPROVIDER:
       *                         setDataProvider(notification);
       *                         break;
       *                 }
       *         }
       * 
       *         // Set the data provider of the combo box
       *         protected function setDataProvider( notification:INotification ):void {
       *             combo.dataProvider = notification.getBody() as Array;
       *         }
       * 
       *         // Invoked when the combo box dispatches a change event, we send a
       *      // notification with the
       *         protected function onChange(event:ListEvent):void {
       *             sendNotification( MyFacade.MYCOMBO_CHANGED, this );
       *         }
       * 
       *         // A private getter for accessing the view object by class
       *      protected function get combo():ComboBox  {
       *         return view as ComboBox;
       *      }
       * 
       * }
       * </listing>
       * 
       * @see org.puremvc.loomsdk.interfaces.INotification INotification
       */
      public interface IMediator
      {
          
          /**
           * Get the <code>IMediator</code> instance name
           * 
           * @return the <code>IMediator</code> instance name
           */
          function getMediatorName():String;
          
          /**
           * Get the <code>IMediator</code>'s view component.
           * 
           * @return Object the view component
           */
          function getViewComponent():Object;
  
          /**
           * Set the <code>IMediator</code>'s view component.
           * 
           * @param Object the view component
           */
          function setViewComponent( viewComponent:Object ):void;
          
          /**
           * List <code>INotification</code> interests.
           * 
           * @return an <code>Array</code> of the <code>INotification</code> names this <code>IMediator</code> has an interest in.
           */
          function listNotificationInterests( ):Vector.<String>;
          
          /**
           * Handle an <code>INotification</code>.
           * 
           * @param notification the <code>INotification</code> to be handled
           */
          function handleNotification( notification:INotification ):void;
          
          /**
           * Called by the View when the Mediator is registered
           */ 
          function onRegister( ):void;
  
          /**
           * Called by the View when the Mediator is removed
           */ 
          function onRemove( ):void;
          
      }
  }