home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / util / Observable.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  7.0 KB  |  201 lines
  1. /*
  2.  * @(#)Observable.java    1.25 98/03/18
  3.  *
  4.  * Copyright 1994-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.util;
  16.  
  17. /**
  18.  * This class represents an observable object, or "data"
  19.  * in the model-view paradigm. It can be subclassed to represent an 
  20.  * object that the application wants to have observed. 
  21.  * <p>
  22.  * An observable object can have one or more observers. An observer 
  23.  * may be any object that implements interface <tt>Observer</tt>. After an 
  24.  * observable instance changes, an application calling the 
  25.  * <code>Observable</code>'s <code>notifyObservers</code> method  
  26.  * causes all of its observers to be notified of the change by a call 
  27.  * to their <code>update</code> method. 
  28.  * <p>
  29.  * The order in which notifications will be delivered is unspecified.  
  30.  * The default implementation provided in the Observerable class will 
  31.  * notify Observers in the order in which they registered interest, but 
  32.  * subclasses may change this order, use no guaranteed order, deliver 
  33.  * notifications on separate threaads, or may guarantee that their
  34.  * subclass follows this order, as they choose.
  35.  * <p>
  36.  * Note that this notification mechanism is has nothing to do with threads 
  37.  * and is completely separate from the <tt>wait</tt> and <tt>notify</tt> 
  38.  * mechanism of class <tt>Object</tt>.
  39.  * <p>
  40.  * When an observable object is newly created, its set of observers is 
  41.  * empty. Two observers are considered the same if and only if the 
  42.  * <tt>equals</tt> method returns true for them.
  43.  *
  44.  * @author  Chris Warth
  45.  * @version 1.25, 03/18/98
  46.  * @see     java.util.Observable#notifyObservers()
  47.  * @see     java.util.Observable#notifyObservers(java.lang.Object)
  48.  * @see     java.util.Observer
  49.  * @see     java.util.Observer#update(java.util.Observable, java.lang.Object)
  50.  * @since   JDK1.0
  51.  */
  52. public class Observable {
  53.     private boolean changed = false;
  54.     private Vector obs;
  55.    
  56.     /** Construct an Observable with zero Observers */
  57.  
  58.     public Observable() {
  59.     obs = new Vector();
  60.     }
  61.  
  62.     /**
  63.      * Adds an observer to the set of observers for this object, provided 
  64.      * that it is not the same as some observer already in the set. 
  65.      * The order in which notifications will be delivered to multiple 
  66.      * observers is not specified. See the class comment.
  67.      *
  68.      * @param   o   an observer to be added.
  69.      */
  70.     public synchronized void addObserver(Observer o) {
  71.     if (!obs.contains(o)) {
  72.         obs.addElement(o);
  73.     }
  74.     }
  75.  
  76.     /**
  77.      * Deletes an observer from the set of observers of this object. 
  78.      *
  79.      * @param   o   the observer to be deleted.
  80.      */
  81.     public synchronized void deleteObserver(Observer o) {
  82.         obs.removeElement(o);
  83.     }
  84.  
  85.     /**
  86.      * If this object has changed, as indicated by the 
  87.      * <code>hasChanged</code> method, then notify all of its observers 
  88.      * and then call the <code>clearChanged</code> method to 
  89.      * indicate that this object has no longer changed. 
  90.      * <p>
  91.      * Each observer has its <code>update</code> method called with two
  92.      * arguments: this observable object and <code>null</code>. In other 
  93.      * words, this method is equivalent to:
  94.      * <blockquote><pre>
  95.      * notifyOvservers(null)</pre></blockquote>
  96.      *
  97.      * @see     java.util.Observable#clearChanged()
  98.      * @see     java.util.Observable#hasChanged()
  99.      * @see     java.util.Observer#update(java.util.Observable, java.lang.Object)
  100.      */
  101.     public void notifyObservers() {
  102.     notifyObservers(null);
  103.     }
  104.  
  105.     /**
  106.      * If this object has changed, as indicated by the 
  107.      * <code>hasChanged</code> method, then notify all of its observers 
  108.      * and then call the <code>clearChanged</code> method to indicate 
  109.      * that this object has no longer changed. 
  110.      * <p>
  111.      * Each observer has its <code>update</code> method called with two
  112.      * arguments: this observable object and the <code>arg</code> argument.
  113.      *
  114.      * @param   arg   any object.
  115.      * @see     java.util.Observable#clearChanged()
  116.      * @see     java.util.Observable#hasChanged()
  117.      * @see     java.util.Observer#update(java.util.Observable, java.lang.Object)
  118.      */
  119.     public void notifyObservers(Object arg) {
  120.     /*
  121.          * a temporary array buffer, used as a snapshot of the state of
  122.          * current Observers.
  123.          */
  124.         Object[] arrLocal;
  125.  
  126.     synchronized (this) {
  127.         /* We don't want the Observer doing callbacks into
  128.          * arbitrary code while holding its own Monitor.
  129.          * The code where we extract each Observable from 
  130.          * the Vector and store the state of the Observer
  131.          * needs synchronization, but notifying observers
  132.          * does not (should not).  The worst result of any 
  133.          * potential race-condition here is that:
  134.          * 1) a newly-added Observer will miss a
  135.          *   notification in progress
  136.          * 2) a recently unregistered Observer will be
  137.          *   wrongly notified when it doesn't care
  138.          */
  139.         if (!changed)
  140.                 return;
  141.             arrLocal = obs.toArray();
  142.             changed = false;
  143.         }
  144.  
  145.         for (int i = arrLocal.length-1; i>=0; i--)
  146.             ((Observer)arrLocal[i]).update(this, arg);
  147.     }
  148.  
  149.     /**
  150.      * Clears the observer list so that this object no longer has any observers.
  151.      */
  152.     public synchronized void deleteObservers() {
  153.     obs.removeAllElements();
  154.     }
  155.  
  156.     /**
  157.      * Marks this <tt>Observable</tt> object as having been changed; the 
  158.      * <tt>hasChanged</tt> method will now return <tt>true</tt>.
  159.      */
  160.     protected synchronized void setChanged() {
  161.     changed = true;
  162.     }
  163.  
  164.     /**
  165.      * Indicates that this object has no longer changed, or that it has 
  166.      * already notified all of its observers of its most recent change, 
  167.      * so that the <tt>hasChanged</tt> method will now return <tt>false</tt>. 
  168.      * This method is called automatically by the 
  169.      * <code>notifyObservers</code> methods. 
  170.      *
  171.      * @see     java.util.Observable#notifyObservers()
  172.      * @see     java.util.Observable#notifyObservers(java.lang.Object)
  173.      */
  174.     protected synchronized void clearChanged() {
  175.     changed = false;
  176.     }
  177.  
  178.     /**
  179.      * Tests if this object has changed. 
  180.      *
  181.      * @return  <code>true</code> if and only if the <code>setChanged</code> 
  182.      *          method has been called more recently than the 
  183.      *          <code>clearChanged</code> method on this object; 
  184.      *          <code>false</code> otherwise.
  185.      * @see     java.util.Observable#clearChanged()
  186.      * @see     java.util.Observable#setChanged()
  187.      */
  188.     public synchronized boolean hasChanged() {
  189.     return changed;
  190.     }
  191.  
  192.     /**
  193.      * Returns the number of observers of this <tt>Observable</tt> object.
  194.      *
  195.      * @return  the number of observers of this object.
  196.      */
  197.     public synchronized int countObservers() {
  198.     return obs.size();
  199.     }
  200. }
  201.