/* 
 * This code is part of Project Waterloo from King's College London
 * 
 *
 * Copyright King's College London 2011-
 * 
 * @author Malcolm Lidierth, King's College London  [Contact]
 * 
 * Project Waterloo is free software:  you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * Project Waterloo is distributed in the hope that it will  be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see .
 *
 */
package kcl.waterloo.observable;

import java.beans.PropertyChangeEvent;
import java.beans.PropertyChangeListener;

/**
 * 

 * GJObservableInterface: Components can implement the interface directly or
 * extend the GJAbstractObservable class.
 *
 * 

 * Listeners can be added using the addPropertyChangeListener methods and are
 * registered in a PropertyChangeSupport instance stored as a property of the
 * GJAbstractObservable superclass instance.
 *
 * 

 * A list of linked objects is maintained in an internal ArrayList. Objects in
 * the list can be modified in propertyChange methods of classes that implement
 * the interface.
 *
 * @author Malcolm Lidierth
 */
public interface GJObservableInterface extends PropertyChangeListener {

    /**
     * Adds a property change listener.
     *
     * Note that addPropertyChangeListener might be called from a
     * super-constructor with some L&Fs so addPropertyChangeListener should test
     * for null PropertyChangeSupport and initialize it if needed.
     *
     * @param listener - the object that listens.
     */
    public void addPropertyChangeListener(PropertyChangeListener listener);

    /**
     * See 
     * java.beans.PropertyChangeSupport
     *
     * @param propertyName
     * @param listener
     */
    public void addPropertyChangeListener(String propertyName, PropertyChangeListener listener);

    /**
     * See 
     * java.beans.PropertyChangeSupport
     *
     * @return a PropertyChangeListener[]
     */
    public PropertyChangeListener[] getPropertyChangeListeners();

    /**
     * See 
     * java.beans.PropertyChangeSupport
     *
     * @param propertyName
     * @return a PropertyChangeListener[]
     */
    public PropertyChangeListener[] getPropertyChangeListeners(String propertyName);

    /**
     * See 
     * java.beans.PropertyChangeSupport
     *
     * @param listener
     */
    public void removePropertyChangeListener(PropertyChangeListener listener);

    /**
     * See 
     * java.beans.PropertyChangeSupport
     *
     * @param propertyName
     * @param listener
     */
    public void removePropertyChangeListener(String propertyName, PropertyChangeListener listener);

    /**
     * Returns true if this instance has installed listeners. See 
     * java.beans.PropertyChangeSupport
     *
     * @param propertyName
     * @return the flag
     */
    public boolean hasListeners(String propertyName);

    /**
     * Returns true if the implementing instance is a listener.
     *
     * @return true/false
     */
    public boolean hasSelfListener();

    public void firePropertyChange(PropertyChangeEvent pce);
}