StateTrackableDelegate.java revision 0
0N/A * Copyright 2007 Sun Microsystems, Inc. All Rights Reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 0N/A * published by the Free Software Foundation. Sun designates this 0N/A * particular file as subject to the "Classpath" exception as provided 0N/A * by Sun in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 0N/A * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 0N/A * CA 95054 USA or visit www.sun.com if you need additional information or 0N/A * have any questions. 0N/A * This class provides a basic pre-packaged implementation of the 0N/A * complete {@link StateTrackable} interface with implementations 0N/A * of the required methods in the interface and methods to manage 0N/A * transitions in the state of the object. 0N/A * Classes which wish to implement StateTrackable could create an 0N/A * instance of this class and delegate all of their implementations 0N/A * for {@code StateTrackable} methods to the corresponding methods 0N/A * The {@code UNTRACKABLE_DELEGATE} provides an implementation 0N/A * of the StateTrackable interface that is permanently in the 0N/A * {@link State#UNTRACKABLE UNTRACKABLE} state. 0N/A * The {@code IMMUTABLE_DELEGATE} provides an implementation 0N/A * of the StateTrackable interface that is permanently in the 0N/A * {@link State#IMMUTABLE IMMUTABLE} state. 0N/A * Returns a {@code StateTrackableDelegate} instance with the 0N/A * specified initial {@link State State}. 0N/A * If the specified {@code State} is 0N/A * {@link State#UNTRACKABLE UNTRACKABLE} or 0N/A * {@link State#IMMUTABLE IMMUTABLE} 0N/A * then the approprirate static instance 0N/A * {@link #UNTRACKABLE_DELEGATE} or {@link #IMMUTABLE_DELEGATE} 0N/A * Constructs a StateTrackableDelegate object with the specified 0N/A // We return the NEVER_CURRENT tracker, but that is 0N/A // just temporary while we are in the DYNAMIC state. 0N/A * This method provides an easy way for delegating classes to 0N/A * change the overall {@link State State} of the delegate to 0N/A * {@link State#IMMUTABLE IMMUTABLE}. 0N/A * @throws IllegalStateException if the current state is 0N/A * {@link State#UNTRACKABLE UNTRACKABLE} 0N/A * @see #setUntrackable 0N/A "objects cannot become IMMUTABLE");
0N/A * This method provides an easy way for delegating classes to 0N/A * change the overall {@link State State} of the delegate to 0N/A * {@link State#UNTRACKABLE UNTRACKABLE}. 0N/A * This method is typically called when references to the 0N/A * internal data buffers have been made public. 0N/A * @throws IllegalStateException if the current state is 0N/A * {@link State#IMMUTABLE IMMUTABLE} 0N/A * @see #setImmutable 0N/A "become UNTRACKABLE");
0N/A * This method provides an easy way for delegating classes to 0N/A * manage temporarily setting the overall {@link State State} 0N/A * of the delegate to {@link State#DYNAMIC DYNAMIC} 0N/A * during well-defined time frames of dynamic pixel updating. 0N/A * This method should be called once before each flow of control 0N/A * that might dynamically update the pixels in an uncontrolled 0N/A * or unpredictable fashion. 0N/A * The companion method {@link #removeDynamicAgent} method should 0N/A * also be called once after each such flow of control has ended. 0N/A * Failing to call the remove method will result in this object 0N/A * permanently becoming {@link State#DYNAMIC DYNAMIC} 0N/A * and therefore effectively untrackable. 0N/A * This method will only change the {@link State State} of the 0N/A * delegate if it is currently {@link State#STABLE STABLE}. 0N/A * @throws IllegalStateException if the current state is 0N/A * {@link State#IMMUTABLE IMMUTABLE} 0N/A * This method provides an easy way for delegating classes to 0N/A * manage restoring the overall {@link State State} of the 0N/A * delegate back to {@link State#STABLE STABLE} 0N/A * after a well-defined time frame of dynamic pixel updating. 0N/A * This method should be called once after each flow of control 0N/A * that might dynamically update the pixels in an uncontrolled 0N/A * or unpredictable fashion has ended. 0N/A * The companion method {@link #addDynamicAgent} method should 0N/A * have been called at some point before each such flow of 0N/A * If this method is called without having previously called 0N/A * the add method, the {@link State State} of this object 0N/A * will become unreliable. 0N/A * This method will only change the {@link State State} of the 0N/A * delegate if the number of outstanding dynamic agents has 0N/A * gone to 0 and it is currently 0N/A * {@link State#DYNAMIC DYNAMIC}. 0N/A * This method provides an easy way for delegating classes to 0N/A * indicate that the contents have changed. 0N/A * This method will invalidate outstanding StateTracker objects 0N/A * so that any other agents which maintain cached information 0N/A * about the pixels will know to refresh their cached copies. 0N/A * This method should be called after every modification to 0N/A * the data, such as any calls to any of the setElem methods. 0N/A * Note that, for efficiency, this method does not check the 0N/A * {@link State State} of the object to see if it is compatible 0N/A * with being marked dirty 0N/A * (i.e. not {@link State#IMMUTABLE IMMUTABLE}). 0N/A * It is up to the callers to enforce the fact that an 0N/A * {@code IMMUTABLE} delegate is never modified.