1 /* 2 * Copyright (c) 1994, 2012, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.util; 27 28 /** 29 * This class represents an observable object, or "data" 30 * in the model-view paradigm. It can be subclassed to represent an 31 * object that the application wants to have observed. 32 * <p> 33 * An observable object can have one or more observers. An observer 34 * may be any object that implements interface <tt>Observer</tt>. After an 35 * observable instance changes, an application calling the 36 * <code>Observable</code>'s <code>notifyObservers</code> method 37 * causes all of its observers to be notified of the change by a call 38 * to their <code>update</code> method. 39 * <p> 40 * The order in which notifications will be delivered is unspecified. 41 * The default implementation provided in the Observable class will 42 * notify Observers in the order in which they registered interest, but 43 * subclasses may change this order, use no guaranteed order, deliver 44 * notifications on separate threads, or may guarantee that their 45 * subclass follows this order, as they choose. 46 * <p> 47 * Note that this notification mechanism has nothing to do with threads 48 * and is completely separate from the <tt>wait</tt> and <tt>notify</tt> 49 * mechanism of class <tt>Object</tt>. 50 * <p> 51 * When an observable object is newly created, its set of observers is 52 * empty. Two observers are considered the same if and only if the 53 * <tt>equals</tt> method returns true for them. 54 * 55 * @author Chris Warth 56 * @see java.util.Observable#notifyObservers() 57 * @see java.util.Observable#notifyObservers(java.lang.Object) 58 * @see java.util.Observer 59 * @see java.util.Observer#update(java.util.Observable, java.lang.Object) 60 * @since JDK1.0 61 */ 62 public class Observable { 63 private boolean changed = false; 64 private Vector<Observer> obs; 65 66 /** Construct an Observable with zero Observers. */ 67 68 public Observable() { 69 obs = new Vector<>(); 70 } 71 72 /** 73 * Adds an observer to the set of observers for this object, provided 74 * that it is not the same as some observer already in the set. 75 * The order in which notifications will be delivered to multiple 76 * observers is not specified. See the class comment. 77 * 78 * @param o an observer to be added. 79 * @throws NullPointerException if the parameter o is null. 80 */ 81 public synchronized void addObserver(Observer o) { 82 if (o == null) 83 throw new NullPointerException(); 84 if (!obs.contains(o)) { 85 obs.addElement(o); 86 } 87 } 88 89 /** 90 * Deletes an observer from the set of observers of this object. 91 * Passing <CODE>null</CODE> to this method will have no effect. 92 * @param o the observer to be deleted. 93 */ 94 public synchronized void deleteObserver(Observer o) { 95 obs.removeElement(o); 96 } 97 98 /** 99 * If this object has changed, as indicated by the 100 * <code>hasChanged</code> method, then notify all of its observers 101 * and then call the <code>clearChanged</code> method to 102 * indicate that this object has no longer changed. 103 * <p> 104 * Each observer has its <code>update</code> method called with two 105 * arguments: this observable object and <code>null</code>. In other 106 * words, this method is equivalent to: 107 * <blockquote><tt> 108 * notifyObservers(null)</tt></blockquote> 109 * 110 * @see java.util.Observable#clearChanged() 111 * @see java.util.Observable#hasChanged() 112 * @see java.util.Observer#update(java.util.Observable, java.lang.Object) 113 */ 114 public void notifyObservers() { 115 notifyObservers(null); 116 } 117 118 /** 119 * If this object has changed, as indicated by the 120 * <code>hasChanged</code> method, then notify all of its observers 121 * and then call the <code>clearChanged</code> method to indicate 122 * that this object has no longer changed. 123 * <p> 124 * Each observer has its <code>update</code> method called with two 125 * arguments: this observable object and the <code>arg</code> argument. 126 * 127 * @param arg any object. 128 * @see java.util.Observable#clearChanged() 129 * @see java.util.Observable#hasChanged() 130 * @see java.util.Observer#update(java.util.Observable, java.lang.Object) 131 */ 132 public void notifyObservers(Object arg) { 133 /* 134 * a temporary array buffer, used as a snapshot of the state of 135 * current Observers. 136 */ 137 Object[] arrLocal; 138 139 synchronized (this) { 140 /* We don't want the Observer doing callbacks into 141 * arbitrary code while holding its own Monitor. 142 * The code where we extract each Observable from 143 * the Vector and store the state of the Observer 144 * needs synchronization, but notifying observers 145 * does not (should not). The worst result of any 146 * potential race-condition here is that: 147 * 1) a newly-added Observer will miss a 148 * notification in progress 149 * 2) a recently unregistered Observer will be 150 * wrongly notified when it doesn't care 151 */ 152 // Android-changed: Call out to hasChanged() to figure out if something changes. 153 // Upstream code avoids calling the nonfinal hasChanged() from the synchronized block, 154 // but that would break compatibility for apps that override that method. 155 // if (!changed) 156 if (!hasChanged()) 157 return; 158 arrLocal = obs.toArray(); 159 clearChanged(); 160 } 161 162 for (int i = arrLocal.length-1; i>=0; i--) 163 ((Observer)arrLocal[i]).update(this, arg); 164 } 165 166 /** 167 * Clears the observer list so that this object no longer has any observers. 168 */ 169 public synchronized void deleteObservers() { 170 obs.removeAllElements(); 171 } 172 173 /** 174 * Marks this <tt>Observable</tt> object as having been changed; the 175 * <tt>hasChanged</tt> method will now return <tt>true</tt>. 176 */ 177 protected synchronized void setChanged() { 178 changed = true; 179 } 180 181 /** 182 * Indicates that this object has no longer changed, or that it has 183 * already notified all of its observers of its most recent change, 184 * so that the <tt>hasChanged</tt> method will now return <tt>false</tt>. 185 * This method is called automatically by the 186 * <code>notifyObservers</code> methods. 187 * 188 * @see java.util.Observable#notifyObservers() 189 * @see java.util.Observable#notifyObservers(java.lang.Object) 190 */ 191 protected synchronized void clearChanged() { 192 changed = false; 193 } 194 195 /** 196 * Tests if this object has changed. 197 * 198 * @return <code>true</code> if and only if the <code>setChanged</code> 199 * method has been called more recently than the 200 * <code>clearChanged</code> method on this object; 201 * <code>false</code> otherwise. 202 * @see java.util.Observable#clearChanged() 203 * @see java.util.Observable#setChanged() 204 */ 205 public synchronized boolean hasChanged() { 206 return changed; 207 } 208 209 /** 210 * Returns the number of observers of this <tt>Observable</tt> object. 211 * 212 * @return the number of observers of this object. 213 */ 214 public synchronized int countObservers() { 215 return obs.size(); 216 } 217 } 218
