| /* |
| * 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(); |
| } |
