/* * Copyright (c) 2007, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation.  Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package sun.java2d; /** * This interface is implemented by classes which contain complex state * so that other objects can track whether or not their state has changed * since earlier interactions with the object. * <p> * The suggested usage pattern for code that manages some trackable data * is as follows: * <pre> * class Trackable implements StateTrackable { *     TrackedInfo data; *     State curState = STABLE; *     StateTracker curTracker = null; *     // Hypothetical method to return a static piece of our tracked data. *     // Assume that Datum is either a copy of some piece of the tracked *     // data or that it is itself immutable. *     public Datum getSomeDatum(int key) { *         // No need to modify the state for this type of "get" call. *         return data.getDatum(key); *     } *     // Hypothetical method to return a raw reference to our tracked data. *     public TrackedInfo getRawHandleToInfo() { *         // Since we are returning a raw reference to our tracked *         // data and since we can not track what the caller will *         // do with that reference, we can no longer track the *         // state of this data. *         synchronized (this) { *             // Note: modifying both curState and curTracker requires *             // synchronization against the getStateTracker method. *             curState = UNTRACKABLE; *             curTracker = null; *         } *         return data; *     } *     // Hypothetical method to set a single piece of data to some *     // new static value. *     public void setSomeDatum(int key, Datum datum) { *         data.setDatum(key, datum); *         // We do not need to change state for this, we simply *         // invalidate the outstanding StateTracker objects. *         // Note: setting curTracker to null requires no synchronization. *         curTracker = null; *     } *     // getStateTracker must be synchronized against any code that *     // changes the State. *     public synchronized StateTracker getStateTracker() { *         StateTracker st = curTracker; *         if (st == null) { *             switch (curState) { *                 case IMMUTABLE:   st = StateTracker.ALWAYS_CURRENT; break; *                 case STABLE:      st = new Tracker(this); break; *                 case DYNAMIC:     st = StateTracker.NEVER_CURRENT; break; *                 case UNTRACKABLE: st = StateTracker.NEVER_CURRENT; break; *             } *             curTracker = st; *         } *         return st; *     } * *     static class Tracker implements StateTracker { *         Trackable theTrackable; *         public Tracker(Trackable t) { *             theTrackable = t; *         } *         public boolean isCurrent() { *             return (theTrackable.curTracker == this); *         } *     } * } * </pre> * Note that the mechanism shown above for invalidating outstanding * StateTracker objects is not the most theoretically conservative * way to implement state tracking in a "set" method. * There is a small window of opportunity after the data has changed * before the outstanding StateTracker objects are invalidated and * where they will indicate that the data is still the same as when * they were instantiated. * While this is technically inaccurate, it is acceptable since the more * conservative approaches to state management are much more complex and * cost much more in terms of performance for a very small gain in * correctness. * For example: * <p> * The most conservative approach would be to synchronize all accesses * and all modifications to the data, including its State. * This would require synchronized blocks around some potentially large * bodies of code which would impact the multi-threaded scalability of * the implementation. * Further, if data is to be coordinated or transferred between two * trackable objects then both would need to be synchronized raising * the possibility of deadlock unless some strict rules of priority * for the locking of the objects were established and followed * religiously. * Either or both of these drawbacks makes such an implementation * infeasible. * <p> * A less conservative approach would be to change the state of the * trackable object to DYNAMIC during all modifications of the data * and then to change it back to STABLE after those modifications * are complete. * While this state transition more accurately reflects the temporary * loss of tracking during the modification phase, in reality the * time period of the modifications would be small in most cases * and the 2 changes of state would each require synchronization. * <p> * In comparison the act of setting the <code>curTracker</code> * reference to null in the usage pattern above effectively invalidates * all outstanding <code>Tracker</code> objects as soon as possible * after the change to the data and requires very little code and no * synchronization to implement. * <p> * In the end it is up to the implementor of a StateTrackable object * how fine the granularity of State updates should be managed based * on the frequency and atomicity of the modifications and the * consequences of returning an inaccurate State for a particularly * small window of opportunity. * Most implementations are likely to follow the liberal, but efficient * guidelines found in the usage pattern proposed above. * * @since 1.7 */public interface StateTrackable {    /**     * An enumeration describing the current state of a trackable     * object.     * These values describe how often the complex data contained     * in a trackable object can be changed and whether or not it     * makes sense to try to track the data in its current state.     * @see StateTrackable#getState     * @since 1.7     */    public enum State {        /**         * The complex data will never change again.         * Information related to the current contents of the complex         * data can be calculated and cached indefinitely with no         * further checks to see if the information is stale.         */        IMMUTABLE,         /**         * The complex data is currently stable, but could change at         * some point in the future.         * Information related to the current contents of the complex         * data can be calculated and cached, but a StateTracker should         * be used to verify the freshness of such precalculated data         * before each future use.         */        STABLE,         /**         * The complex data is currently in flux and is frequently         * changing.         * While information related to the current contents of the         * complex data could be calculated and cached, there is a         * reasonably high probability that the cached information         * would be found to be out of date by the next time it is         * used.         * It may also be the case that the current contents are         * temporarily untrackable, but that they may become trackable         * again in the future.         */        DYNAMIC,         /**         * The complex data can currently be changed by external         * references and agents in a way that cannot be tracked.         * If any information about the current contents of the complex         * data were to be cached, there would be no way to determine         * whether or not that cached information was out of date.         */        UNTRACKABLE,    };     /**     * Returns the general state of the complex data held by this     * object.     * This return value can be used to determine if it makes     * strategic sense to try and cache information about the current     * contents of this object.     * The StateTracker returned from the getStateTracker() method     * will further aid in determining when the data has been     * changed so that the caches can be verified upon future uses.     * @return the current state of trackability of the complex     * data stored in this object.     * @see #getStateTracker     * @since 1.7     */    public State getState();     /**     * Returns an object which can track future changes to the     * complex data stored in this object.     * If an external agent caches information about the complex     * data of this object, it should first get a StateTracker     * object from this method so that it can check if such     * information is current upon future uses.     * Note that a valid StateTracker will always be returned     * regardless of the return value of getState(), but in some     * cases the StateTracker may be a trivial implementation     * which always returns the same value from its     * {@link StateTracker#isCurrent isCurrent} method.     * <ul>     * <li>If the current state is {@link State#IMMUTABLE IMMUTABLE},     * this StateTracker and any future StateTracker objects     * returned from this method will always indicate that     * the state has not changed.</li>     * <li>If the current state is {@link State#UNTRACKABLE UNTRACKABLE},     * this StateTracker and any future StateTracker objects     * returned from this method will always indicate that     * the state has changed.</li>     * <li>If the current state is {@link State#DYNAMIC DYNAMIC},     * this StateTracker may always indicate that the current     * state has changed, but another StateTracker returned     * from this method in the future when the state has changed     * to {@link State#STABLE STABLE} will correctly track changes.</li>     * <li>Otherwise the current state is {@link State#STABLE STABLE}     * and this StateTracker will indicate whether or not the     * data has changed since the time at which it was fetched     * from the object.</li>     * </ul>     * @return an object implementing the StateTracker interface     * that tracks whether changes have been made to the complex     * contents of this object since it was returned.     * @see State     * @see #getState     * @since 1.7     */    public StateTracker getStateTracker();}