View Javadoc
1   /*
2    * Copyright (c) 1995, 2004, 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.misc;
27  import java.lang.ref.SoftReference;
28  
29  
30  /**
31   * A "Ref" is an indirect reference to an object that the garbage collector
32   * knows about.  An application should override the reconstitute() method with one
33   * that will construct the object based on information in the Ref, often by
34   * reading from a file.  The get() method retains a cache of the result of the last call to
35   * reconstitute() in the Ref.  When space gets tight, the garbage collector
36   * will clear old Ref cache entries when there are no other pointers to the
37   * object.  In normal usage, Ref will always be subclassed.  The subclass will add the
38   * instance variables necessary for the reconstitute() method to work.  It will also add a
39   * constructor to set them up, and write a version of reconstitute().
40   *
41   * @deprecated This class has been replaced by
42   * <code>java.util.SoftReference</code>.
43   *
44   * @see java.util.SoftReference
45   *
46   */
47  @Deprecated
48  
49  public abstract class Ref {
50  
51      private SoftReference soft = null;
52  
53      /**
54       * Returns a pointer to the object referenced by this Ref.  If the object
55       * has been thrown away by the garbage collector, it will be
56       * reconstituted. This method does everything necessary to ensure that the garbage
57       * collector throws things away in Least Recently Used(LRU) order.  Applications should
58       * never override this method. The get() method effectively caches calls to
59       * reconstitute().
60       */
61      public synchronized Object get() {
62          Object t = check();
63          if (t == null) {
64              t = reconstitute();
65              setThing(t);
66          }
67          return t;
68      }
69  
70      /**
71       * Returns a pointer to the object referenced by this Ref by
72       * reconstituting it from some external source (such as a file).  This method should not
73       * bother with caching since the method get() will deal with that.
74       * <p>
75       * In normal usage, Ref will always be subclassed.  The subclass will add
76       * the instance variables necessary for reconstitute() to work.  It will
77       * also add a constructor to set them up, and write a version of
78       * reconstitute().
79       */
80      public abstract Object reconstitute();
81  
82      /**
83       * Flushes the cached object.  Forces the next invocation of get() to
84       * invoke reconstitute().
85       */
86      public synchronized void flush() {
87          SoftReference s = soft;
88          if (s != null) s.clear();
89          soft = null;
90      }
91  
92      /**
93       * Sets the thing to the specified object.
94       * @param thing the specified object
95       */
96      public synchronized void setThing(Object thing) {
97          flush();
98          soft = new SoftReference(thing);
99      }
100 
101     /**
102      * Checks to see what object is being pointed at by this Ref and returns it.
103      */
104     public synchronized Object check() {
105         SoftReference s = soft;
106         if (s == null) return null;
107         return s.get();
108     }
109 
110     /**
111      * Constructs a new Ref.
112      */
113     public Ref() { }
114 
115     /**
116      * Constructs a new Ref that initially points to thing.
117      */
118     public Ref(Object thing) {
119         setThing(thing);
120     }
121 
122 }