Observable.java revision 8de20a2d6076e8b5827434d8e1283665a53d160c
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 26package 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 */ 62public 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 if (!hasChanged()) 154 return; 155 arrLocal = obs.toArray(); 156 clearChanged(); 157 } 158 159 for (int i = arrLocal.length-1; i>=0; i--) 160 ((Observer)arrLocal[i]).update(this, arg); 161 } 162 163 /** 164 * Clears the observer list so that this object no longer has any observers. 165 */ 166 public synchronized void deleteObservers() { 167 obs.removeAllElements(); 168 } 169 170 /** 171 * Marks this <tt>Observable</tt> object as having been changed; the 172 * <tt>hasChanged</tt> method will now return <tt>true</tt>. 173 */ 174 protected synchronized void setChanged() { 175 changed = true; 176 } 177 178 /** 179 * Indicates that this object has no longer changed, or that it has 180 * already notified all of its observers of its most recent change, 181 * so that the <tt>hasChanged</tt> method will now return <tt>false</tt>. 182 * This method is called automatically by the 183 * <code>notifyObservers</code> methods. 184 * 185 * @see java.util.Observable#notifyObservers() 186 * @see java.util.Observable#notifyObservers(java.lang.Object) 187 */ 188 protected synchronized void clearChanged() { 189 changed = false; 190 } 191 192 /** 193 * Tests if this object has changed. 194 * 195 * @return <code>true</code> if and only if the <code>setChanged</code> 196 * method has been called more recently than the 197 * <code>clearChanged</code> method on this object; 198 * <code>false</code> otherwise. 199 * @see java.util.Observable#clearChanged() 200 * @see java.util.Observable#setChanged() 201 */ 202 public synchronized boolean hasChanged() { 203 return changed; 204 } 205 206 /** 207 * Returns the number of observers of this <tt>Observable</tt> object. 208 * 209 * @return the number of observers of this object. 210 */ 211 public synchronized int countObservers() { 212 return obs.size(); 213 } 214} 215