View Javadoc
1   /*
2    * Copyright (c) 2007, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package sun.java2d;
27  
28  /**
29   * This interface is used to track changes to the complex data of an
30   * object that implements the StateTrackable interface.
31   * <p>
32   * The usage pattern for code accessing the trackable data is as follows:
33   * <pre>
34   *     StateTrackable trackedobject;
35   *     MyInfo cacheddata;
36   *     StateTracker cachetracker;
37   *     public synchronized MyInfo getInfoAbout(StateTrackable obj) {
38   *         if (trackedobject != obj || !cachetracker.isCurrent()) {
39   *             // Note: Always call getStateTracker() before
40   *             // caching any data about the objct...
41   *             cachetracker = obj.getStateTracker();
42   *             cacheddata = calculateInfoFrom(obj);
43   *             trackedobject = obj;
44   *         }
45   *         return cacheddata;
46   *     }
47   * </pre>
48   * Note that the sample code above works correctly regardless of the
49   * {@link StateTrackable.State State} of the complex data of the object,
50   * but it may be inefficient to store precalculated information about
51   * an object whose current {@link StateTrackable.State State} is
52   * {@link StateTrackable.State#UNTRACKABLE UNTRACKABLE}
53   * and it is unnecessary to perform the {@link #isCurrent} test for
54   * data whose current {@link StateTrackable.State State} is
55   * {@link StateTrackable.State#IMMUTABLE IMMUTABLE}.
56   * Optimizations to the sample code for either or both of those terminal
57   * States may be of benefit for some use cases, but is left out of the
58   * example to reduce its complexity.
59   *
60   * @see StateTrackable.State
61   * @since 1.7
62   */
63  public interface StateTracker {
64      /**
65       * An implementation of the StateTracker interface which
66       * always returns true.
67       * This implementation is useful for objects whose current
68       * {@link StateTrackable.State State} is
69       * {@link StateTrackable.State#IMMUTABLE IMMUTABLE}.
70       * @since 1.7
71       */
72      public StateTracker ALWAYS_CURRENT = new StateTracker() {
73          public boolean isCurrent() {
74              return true;
75          }
76      };
77  
78      /**
79       * An implementation of the StateTracker interface which
80       * always returns false.
81       * This implementation is useful for objects whose current
82       * {@link StateTrackable.State State} is
83       * {@link StateTrackable.State#UNTRACKABLE UNTRACKABLE}.
84       * This implementation may also be useful for some objects
85       * whose current {@link StateTrackable.State State} is
86       * {@link StateTrackable.State#DYNAMIC DYNAMIC}.
87       * @since 1.7
88       */
89      public StateTracker NEVER_CURRENT = new StateTracker() {
90          public boolean isCurrent() {
91              return false;
92          }
93      };
94  
95      /**
96       * Returns true iff the contents of the complex data of the
97       * associated StateTrackable object have not changed since
98       * the time that this StateTracker was returned from its
99       * getStateTracker() method.
100      * @see StateTrackable
101      * @since 1.7
102      */
103     public boolean isCurrent();
104 }