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