org.puremvc.java.interfaces.IMediator Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of PureMVC Show documentation

PureMVC is a lightweight framework for creating applications based upon the classic Model-View-Controller design meta-pattern. This is the specific implementation for the Java language. It does not support modular programming since it uses Singletons as Core actors rather than the Multiton used in the MultiCore Version.

The newest version!

//
//  PureMVC Java Standard
//
//  Copyright(c) 2019 Saad Shams 
//  Your reuse is governed by the Creative Commons Attribution 3.0 License
//

package org.puremvc.java.interfaces;

/**
 * The interface definition for a PureMVC Mediator.
 *
 * In PureMVC, IMediator implementors assume these responsibilities:
 *
 * 
 * Implement a common method which returns a list of all INotifications
 * the IMediator has interest in.
 * Implement a notification callback method.
 * Implement methods that are called when the IMediator is registered or removed from the View.
 * 
 *
 * Additionally, IMediators typically:
 *
 * 
 * Act as an intermediary between one or more view components such as text boxes or
 * list controls, maintaining references and coordinating their behavior.
 * In Flash-based apps, this is often the place where event listeners are
 * added to view components, and their handlers implemented.
 * Respond to and generate INotifications, interacting with of
 * the rest of the PureMVC app.
 * 
 *
 * When an IMediator is registered with the IView,
 * the IView will call the IMediator's
 * listNotificationInterests method. The IMediator will
 * return an Array of INotification names which
 * it wishes to be notified about.
 *
 * The IView will then create an Observer object
 * encapsulating that IMediator's (handleNotification) method
 * and register it as an Observer for each INotification name returned by
 * listNotificationInterests.
 *
 * A concrete IMediator implementor usually looks something like this:
 *
 *  * {@code import org.puremvc.as3.multicore.patterns.mediator.*;
 * import org.puremvc.as3.multicore.patterns.observer.*;
 * import org.puremvc.as3.multicore.core.view.*;
 *
 * import com.me.myapp.model.*;
 * import com.me.myapp.view.*;
 * import com.me.myapp.controller.*;
 *
 * import javax.swing.JComboBox;
 * import java.awt.event.ActionListener;
 *
 * public class MyMediator extends Mediator implements IMediator, ActionListener {
 *
 *     public MyMediator( Object viewComponent ) {
 *         super( viewComponent );
 *         combo.addActionListener( this );
 *     }
 *
 *     public String[] listNotificationInterests() {
 *         return [ MyFacade.SET_SELECTION,
 *                  MyFacade.SET_DATAPROVIDER ];
 *     }
 *
 *     public void handleNotification( INotification notification ) {
 *         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 void setDataProvider( INotification notification ) {
 *         combo.setModel(ComboBoxModel(notification.getBody()));
 *     }
 *
 *     // Invoked when the combo box dispatches a change event, we send a
 *     // notification with the
 *     public void actionPerformed(ActionEvent event) {
 *         sendNotification( MyFacade.MYCOMBO_CHANGED, this );
 *     }
 *
 *     // A private getter for accessing the view object by class
 *     protected JComboBox getViewComponent() {
 *         return viewComponent;
 *     }
 *
 * }
 * }
 * 
 *
 * @see org.puremvc.java.interfaces.INotification INotification
 */
public interface IMediator extends INotifier {

    /**
     * Get the IMediator instance name
     *
     * @return the IMediator instance name
     */
    String getMediatorName();

    /**
     * Get the IMediator's view component.
     *
     * @return Object the view component
     */
    Object getViewComponent();

    /**
     * Set the IMediator's view component.
     *
     * @param viewComponent the view component
     */
    void setViewComponent(Object viewComponent);

    /**
     * List INotification interests.
     *
     * @return an Array of the INotification names this IMediator has an interest in.
     */
    String[] listNotificationInterests();

    /**
     * Handle an INotification.
     *
     * @param notification the INotification to be handled
     */
    void handleNotification(INotification notification);

    /**
     * Called by the View when the Mediator is registered
     */
    void onRegister();

    /**
     * Called by the View when the Mediator is removed
     */
    void onRemove();
}