1 /* 2 * Copyright (c) 1994, 2016, 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 {@code Observer}. After an 35 * observable instance changes, an application calling the 36 * {@code Observable}'s {@code notifyObservers} method 37 * causes all of its observers to be notified of the change by a call 38 * to their {@code update} 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 {@code wait} and {@code notify} 49 * mechanism of class {@code Object}. 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 * {@code equals} 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 1.0 61 * 62 * @deprecated 63 * This class and the {@link Observer} interface have been deprecated. 64 * The event model supported by {@code Observer} and {@code Observable} 65 * is quite limited, the order of notifications delivered by 66 * {@code Observable} is unspecified, and state changes are not in 67 * one-for-one correspondence with notifications. 68 * For a richer event model, consider using the 69 * {@link java.beans} package. For reliable and ordered 70 * messaging among threads, consider using one of the concurrent data 71 * structures in the {@link java.util.concurrent} package. 72 * For reactive streams style programming, see the 73 * {@link java.util.concurrent.Flow} API. 74 */ 75 @Deprecated(since="9") 76 public class Observable { 77 private boolean changed = false; 78 private Vector<Observer> obs; 79 80 /** Construct an Observable with zero Observers. */ 81 Observable()82 public Observable() { 83 obs = new Vector<>(); 84 } 85 86 /** 87 * Adds an observer to the set of observers for this object, provided 88 * that it is not the same as some observer already in the set. 89 * The order in which notifications will be delivered to multiple 90 * observers is not specified. See the class comment. 91 * 92 * @param o an observer to be added. 93 * @throws NullPointerException if the parameter o is null. 94 */ addObserver(Observer o)95 public synchronized void addObserver(Observer o) { 96 if (o == null) 97 throw new NullPointerException(); 98 if (!obs.contains(o)) { 99 obs.addElement(o); 100 } 101 } 102 103 /** 104 * Deletes an observer from the set of observers of this object. 105 * Passing {@code null} to this method will have no effect. 106 * @param o the observer to be deleted. 107 */ deleteObserver(Observer o)108 public synchronized void deleteObserver(Observer o) { 109 obs.removeElement(o); 110 } 111 112 /** 113 * If this object has changed, as indicated by the 114 * {@code hasChanged} method, then notify all of its observers 115 * and then call the {@code clearChanged} method to 116 * indicate that this object has no longer changed. 117 * <p> 118 * Each observer has its {@code update} method called with two 119 * arguments: this observable object and {@code null}. In other 120 * words, this method is equivalent to: 121 * <blockquote>{@code 122 * notifyObservers(null)}</blockquote> 123 * 124 * @see java.util.Observable#clearChanged() 125 * @see java.util.Observable#hasChanged() 126 * @see java.util.Observer#update(java.util.Observable, java.lang.Object) 127 */ notifyObservers()128 public void notifyObservers() { 129 notifyObservers(null); 130 } 131 132 /** 133 * If this object has changed, as indicated by the 134 * {@code hasChanged} method, then notify all of its observers 135 * and then call the {@code clearChanged} method to indicate 136 * that this object has no longer changed. 137 * <p> 138 * Each observer has its {@code update} method called with two 139 * arguments: this observable object and the {@code arg} argument. 140 * 141 * @param arg any object. 142 * @see java.util.Observable#clearChanged() 143 * @see java.util.Observable#hasChanged() 144 * @see java.util.Observer#update(java.util.Observable, java.lang.Object) 145 */ notifyObservers(Object arg)146 public void notifyObservers(Object arg) { 147 /* 148 * a temporary array buffer, used as a snapshot of the state of 149 * current Observers. 150 */ 151 Object[] arrLocal; 152 153 synchronized (this) { 154 /* We don't want the Observer doing callbacks into 155 * arbitrary code while holding its own Monitor. 156 * The code where we extract each Observable from 157 * the Vector and store the state of the Observer 158 * needs synchronization, but notifying observers 159 * does not (should not). The worst result of any 160 * potential race-condition here is that: 161 * 1) a newly-added Observer will miss a 162 * notification in progress 163 * 2) a recently unregistered Observer will be 164 * wrongly notified when it doesn't care 165 */ 166 // Android-changed: Call out to hasChanged() to figure out if something changes. 167 // Upstream code avoids calling the nonfinal hasChanged() from the synchronized block, 168 // but that would break compatibility for apps that override that method. 169 // if (!changed) 170 if (!hasChanged()) 171 return; 172 arrLocal = obs.toArray(); 173 clearChanged(); 174 } 175 176 for (int i = arrLocal.length-1; i>=0; i--) 177 ((Observer)arrLocal[i]).update(this, arg); 178 } 179 180 /** 181 * Clears the observer list so that this object no longer has any observers. 182 */ deleteObservers()183 public synchronized void deleteObservers() { 184 obs.removeAllElements(); 185 } 186 187 /** 188 * Marks this {@code Observable} object as having been changed; the 189 * {@code hasChanged} method will now return {@code true}. 190 */ setChanged()191 protected synchronized void setChanged() { 192 changed = true; 193 } 194 195 /** 196 * Indicates that this object has no longer changed, or that it has 197 * already notified all of its observers of its most recent change, 198 * so that the {@code hasChanged} method will now return {@code false}. 199 * This method is called automatically by the 200 * {@code notifyObservers} methods. 201 * 202 * @see java.util.Observable#notifyObservers() 203 * @see java.util.Observable#notifyObservers(java.lang.Object) 204 */ clearChanged()205 protected synchronized void clearChanged() { 206 changed = false; 207 } 208 209 /** 210 * Tests if this object has changed. 211 * 212 * @return {@code true} if and only if the {@code setChanged} 213 * method has been called more recently than the 214 * {@code clearChanged} method on this object; 215 * {@code false} otherwise. 216 * @see java.util.Observable#clearChanged() 217 * @see java.util.Observable#setChanged() 218 */ hasChanged()219 public synchronized boolean hasChanged() { 220 return changed; 221 } 222 223 /** 224 * Returns the number of observers of this {@code Observable} object. 225 * 226 * @return the number of observers of this object. 227 */ countObservers()228 public synchronized int countObservers() { 229 return obs.size(); 230 } 231 } 232