Back to index...

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

Back to index...