257 lines
11 KiB
Java
257 lines
11 KiB
Java
/*
|
|
* 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();
|
|
}
|