/*
 * @(#) MultiObservable.java - Interface for observable objects.
 * (c) 2000 Ivan Maidanski <ivmai@chat.ru> http://ivmai.chat.ru
 * Freeware class library sources. All rights reserved.
 **
 * Language: Java [pure]
 * Tested with: JDK v1.1.6
 * Last modified: 2000-12-13 17:15:00 GMT+03:00
 */

/*
 * This software is the proprietary information of the author.
 **
 * Permission to use, copy, and distribute this software and its
 * documentation for non-commercial purposes and without fee is
 * hereby granted provided that this copyright notice appears in all
 * copies.
 **
 * This software should not be modified in any way; any found bug
 * should be reported to the author.
 **
 * The author disclaims all warranties with regard to this software,
 * including all implied warranties of merchantability and fitness.
 * In no event shall the author be liable for any special, indirect
 * or consequential damages or any damages whatsoever resulting from
 * loss of use, data or profits, whether in an action of contract,
 * negligence or other tortuous action, arising out of or in
 * connection with the use or performance of this software.
 */

package ivmai.util;

/**
 * Interface for observable objects.
 **
 * Observable object represents mutable 'data' in the model-view
 * paradigm. Each time an observable object is changed, it calls
 * <CODE>update(this, argument)</CODE> for every registered observer
 * agent (in an unspecified order), where <VAR>argument</VAR>
 * describes the occurred changes (as it must be specified for a
 * particular object).
 **
 * @see Notifiable
 * @see ObservedCore
 **
 * @version 2.0
 * @author Ivan Maidanski
 */
public interface MultiObservable
{

/**
 * Registers one more observer.
 **
 * An observer registration means that <VAR>agent</VAR> will be
 * updated (notified) each time <CODE>this</CODE> observable object
 * is changed somehow. Duplicate agents are not added (registered).
 * If an exception is thrown then state of <CODE>this</CODE> object
 * is not changed. Important notes: registered observers should not
 * be accessible for other objects.
 **
 * @param agent
 * the observer agent (must be non-<CODE>null</CODE>) to be
 * registered.
 * @exception NullPointerException
 * if <VAR>agent</VAR> is <CODE>null</CODE>.
 * @exception OutOfMemoryError
 * if there is not enough memory.
 **
 * @see #removeObserver(ivmai.util.Notifiable)
 */
 public abstract void addObserver(Notifiable agent)
  throws NullPointerException;

/**
 * Unregisters a particular observer.
 **
 * If <VAR>agent</VAR> is not registered (or is <CODE>null</CODE>)
 * then nothing is performed. Else the specified agent is removed
 * from the observers list of <CODE>this</CODE> observable object
 * (this action is just the opposite to the agent registration).
 **
 * @param agent
 * the observer agent (may be <CODE>null</CODE>) to be unregistered.
 **
 * @see #addObserver(ivmai.util.Notifiable)
 */
 public abstract void removeObserver(Notifiable agent);
}