001: /*
002: * Copyright 2007 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package sun.java2d;
027:
028: /**
029: * This interface is used to track changes to the complex data of an
030: * object that implements the StateTrackable interface.
031: * <p>
032: * The usage pattern for code accessing the trackable data is as follows:
033: * <pre>
034: * StateTrackable trackedobject;
035: * MyInfo cacheddata;
036: * StateTracker cachetracker;
037: * public synchronized MyInfo getInfoAbout(StateTrackable obj) {
038: * if (trackedobject != obj || !cachetracker.isCurrent()) {
039: * // Note: Always call getStateTracker() before
040: * // caching any data about the objct...
041: * cachetracker = obj.getStateTracker();
042: * cacheddata = calculateInfoFrom(obj);
043: * trackedobject = obj;
044: * }
045: * return cacheddata;
046: * }
047: * </pre>
048: * Note that the sample code above works correctly regardless of the
049: * {@link StateTrackable.State State} of the complex data of the object,
050: * but it may be inefficient to store precalculated information about
051: * an object whose current {@link StateTrackable.State State} is
052: * {@link StateTrackable.State#UNTRACKABLE UNTRACKABLE}
053: * and it is unnecessary to perform the {@link #isCurrent} test for
054: * data whose current {@link StateTrackable.State State} is
055: * {@link StateTrackable.State#IMMUTABLE IMMUTABLE}.
056: * Optimizations to the sample code for either or both of those terminal
057: * States may be of benefit for some use cases, but is left out of the
058: * example to reduce its complexity.
059: *
060: * @see StateTrackable.State
061: * @since 1.7
062: */
063: public interface StateTracker {
064: /**
065: * An implementation of the StateTracker interface which
066: * always returns true.
067: * This implementation is useful for objects whose current
068: * {@link StateTrackable.State State} is
069: * {@link StateTrackable.State#IMMUTABLE IMMUTABLE}.
070: * @since 1.7
071: */
072: public StateTracker ALWAYS_CURRENT = new StateTracker() {
073: public boolean isCurrent() {
074: return true;
075: }
076: };
077:
078: /**
079: * An implementation of the StateTracker interface which
080: * always returns false.
081: * This implementation is useful for objects whose current
082: * {@link StateTrackable.State State} is
083: * {@link StateTrackable.State#UNTRACKABLE UNTRACKABLE}.
084: * This implementation may also be useful for some objects
085: * whose current {@link StateTrackable.State State} is
086: * {@link StateTrackable.State#DYNAMIC DYNAMIC}.
087: * @since 1.7
088: */
089: public StateTracker NEVER_CURRENT = new StateTracker() {
090: public boolean isCurrent() {
091: return false;
092: }
093: };
094:
095: /**
096: * Returns true iff the contents of the complex data of the
097: * associated StateTrackable object have not changed since
098: * the time that this StateTracker was returned from its
099: * getStateTracker() method.
100: * @see StateTrackable
101: * @since 1.7
102: */
103: public boolean isCurrent();
104: }
|