package java.util;

import ej.annotation.Nullable;

/**
 * This class represents an observable object, or "data" in the model-view paradigm. It can be
 * subclassed to represent an object that the application wants to have observed.
 * <p>
 * An observable object can have one or more observers. An observer may be any object that
 * implements interface <code>Observer</code>. After an observable instance changes, an application
 * calling the <code>Observable</code>'s <code>notifyObservers</code> method causes all of its
 * observers to be notified of the change by a call to their <code>update</code> method.
 * <p>
 * The order in which notifications will be delivered is unspecified. The default implementation
 * provided in the Observable class will notify Observers in the order in which they registered
 * interest, but subclasses may change this order, use no guaranteed order, deliver notifications on
 * separate threads, or may guarantee that their subclass follows this order, as they choose.
 * <p>
 * Note that this notification mechanism is has nothing to do with threads and is completely
 * separate from the <code>wait</code> and <code>notify</code> mechanism of class <code>Object</code>.
 * <p>
 * When an observable object is newly created, its set of observers is empty. Two observers are
 * considered the same if and only if the <code>equals</code> method returns true for them.
 */
public class Observable {

    /**
     * Construct an Observable with zero Observers.
     */
    public Observable() {
        throw new RuntimeException();
    }

    /**
     * Adds an observer to the set of observers for this object, provided that it is not the same as
     * some observer already in the set. The order in which notifications will be delivered to multiple
     * observers is not specified. See the class comment.
     *
     * @param o
     *        an observer to be added.
     * @throws NullPointerException
     *         if the parameter o is null.
     */
    public void addObserver(Observer o) {
        throw new RuntimeException();
    }

    /**
     * Indicates that this object has no longer changed, or that it has already notified all of its
     * observers of its most recent change, so that the <code>hasChanged</code> method will now return
     * <code>false</code>. This method is called automatically by the <code>notifyObservers</code> methods.
     *
     * @see java.util.Observable#notifyObservers()
     * @see java.util.Observable#notifyObservers(java.lang.Object)
     */
    protected void clearChanged() {
        throw new RuntimeException();
    }

    /**
     * Returns the number of observers of this <code>Observable</code> object.
     *
     * @return the number of observers of this object.
     */
    public int countObservers() {
        throw new RuntimeException();
    }

    /**
     * Deletes an observer from the set of observers of this object. Passing <code>null</code> to this
     * method will have no effect.
     *
     * @param o
     *        the observer to be deleted.
     */
    public void deleteObserver(@Nullable Observer o) {
        throw new RuntimeException();
    }

    /**
     * Clears the observer list so that this object no longer has any observers.
     */
    public void deleteObservers() {
        throw new RuntimeException();
    }

    /**
     * Tests if this object has changed.
     *
     * @return <code>true</code> if and only if the <code>setChanged</code> method has been called more
     *         recently than the <code>clearChanged</code> method on this object; <code>false</code>
     *         otherwise.
     * @see java.util.Observable#clearChanged()
     * @see java.util.Observable#setChanged()
     */
    public boolean hasChanged() {
        throw new RuntimeException();
    }

    /**
     * If this object has changed, as indicated by the <code>hasChanged</code> method, then notify all
     * of its observers and then call the <code>clearChanged</code> method to indicate that this object
     * has no longer changed.
     * <p>
     * Each observer has its <code>update</code> method called with two arguments: this observable
     * object and <code>null</code>. In other words, this method is equivalent to: <blockquote><code>
     * notifyObservers(null)</code></blockquote>
     *
     * @see java.util.Observable#clearChanged()
     * @see java.util.Observable#hasChanged()
     * @see java.util.Observer#update(java.util.Observable, java.lang.Object)
     */
    public void notifyObservers() {
        throw new RuntimeException();
    }

    /**
     * If this object has changed, as indicated by the <code>hasChanged</code> method, then notify all
     * of its observers and then call the <code>clearChanged</code> method to indicate that this object
     * has no longer changed.
     * <p>
     * Each observer has its <code>update</code> method called with two arguments: this observable
     * object and the <code>arg</code> argument.
     *
     * @param arg
     *        any object.
     * @see java.util.Observable#clearChanged()
     * @see java.util.Observable#hasChanged()
     * @see java.util.Observer#update(java.util.Observable, java.lang.Object)
     */
    public void notifyObservers(@Nullable Object arg) {
        throw new RuntimeException();
    }

    /**
     * Marks this <code>Observable</code> object as having been changed; the <code>hasChanged</code> method will
     * now return <code>true</code>.
     */
    protected void setChanged() {
        throw new RuntimeException();
    }
}