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 }