Source for java.lang.ref.Reference

   1: /* java.lang.ref.Reference
   2:    Copyright (C) 1999, 2002, 2003, 2004, 2006 Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10:  
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package java.lang.ref;
  40: 
  41: /**
  42:  * This is the base class of all references.  A reference allows
  43:  * refering to an object without preventing the garbage collector to
  44:  * collect it.  The only way to get the referred object is via the
  45:  * <code>get()</code>-method.  This method will return
  46:  * <code>null</code> if the object was collected. <br>
  47:  *
  48:  * A reference may be registered with a queue.  When a referred
  49:  * element gets collected the reference will be put on the queue, so
  50:  * that you will be notified. <br>
  51:  *
  52:  * There are currently three types of references:  soft reference,
  53:  * weak reference and phantom reference. <br>
  54:  *
  55:  * Soft references will be cleared if the garbage collector is told
  56:  * to free some memory and there are no unreferenced or weakly referenced
  57:  * objects.  It is useful for caches. <br>
  58:  *
  59:  * Weak references will be cleared as soon as the garbage collector
  60:  * determines that the refered object is only weakly reachable.  They
  61:  * are useful as keys in hashtables (see <code>WeakHashtable</code>) as
  62:  * you get notified when nobody has the key anymore.
  63:  *
  64:  * Phantom references don't prevent finalization.  If an object is only
  65:  * phantom reachable, it will be finalized, and the reference will be
  66:  * enqueued, but not cleared.  Since you mustn't access an finalized
  67:  * object, the <code>get</code> method of a phantom reference will never
  68:  * work.  It is useful to keep track, when an object is finalized.
  69:  *
  70:  * @author Jochen Hoenicke
  71:  * @see java.util.WeakHashMap
  72:  */
  73: public abstract class Reference<T>
  74: {
  75:   /**
  76:    * The underlying object.  This field is handled in a special way by
  77:    * the garbage collector.
  78:    */
  79:   T referent;
  80: 
  81:   /**
  82:    * The queue this reference is registered on. This is null, if this
  83:    * wasn't registered to any queue or reference was already enqueued.
  84:    */
  85:   volatile ReferenceQueue<? super T> queue;
  86: 
  87:   /**
  88:    * Link to the next entry on the queue.  If this is null, this
  89:    * reference is not enqueued.  Otherwise it points to the next
  90:    * reference.  The last reference on a queue will point to itself
  91:    * (not to null, that value is used to mark a not enqueued
  92:    * reference).  
  93:    */
  94:   volatile Reference nextOnQueue;
  95: 
  96:   /**
  97:    * This lock should be taken by the garbage collector, before
  98:    * determining reachability.  It will prevent the get()-method to
  99:    * return the reference so that reachability doesn't change.
 100:    */
 101:   static Object lock = new Object();
 102: 
 103:   /**
 104:    * Creates a new reference that is not registered to any queue.
 105:    * Since it is package private, it is not possible to overload this
 106:    * class in a different package.  
 107:    * @param ref the object we refer to.
 108:    */
 109:   Reference(T ref)
 110:   {
 111:     referent = ref;
 112:   }
 113: 
 114:   /**
 115:    * Creates a reference that is registered to a queue.  Since this is
 116:    * package private, it is not possible to overload this class in a
 117:    * different package.  
 118:    * @param ref the object we refer to.
 119:    * @param q the reference queue to register on.
 120:    * @exception NullPointerException if q is null.
 121:    */
 122:   Reference(T ref, ReferenceQueue<? super T> q)
 123:   {
 124:     if (q == null)
 125:       throw new NullPointerException();
 126:     referent = ref;
 127:     queue = q;
 128:   }
 129: 
 130:   /**
 131:    * Returns the object, this reference refers to.
 132:    * @return the object, this reference refers to, or null if the 
 133:    * reference was cleared.
 134:    */
 135:   public T get()
 136:   {
 137:     synchronized (lock)
 138:       {
 139:     return referent;
 140:       }
 141:   }
 142: 
 143:   /**
 144:    * Clears the reference, so that it doesn't refer to its object
 145:    * anymore.  For soft and weak references this is called by the
 146:    * garbage collector.  For phantom references you should call 
 147:    * this when enqueuing the reference.
 148:    */
 149:   public void clear()
 150:   {
 151:     referent = null;
 152:   }
 153: 
 154:   /**
 155:    * Tells if the object is enqueued on a reference queue.
 156:    * @return true if it is enqueued, false otherwise.
 157:    */
 158:   public boolean isEnqueued()
 159:   {
 160:     return nextOnQueue != null;
 161:   }
 162: 
 163:   /**
 164:    * Enqueue an object on a reference queue.  This is normally executed
 165:    * by the garbage collector.
 166:    */
 167:   public boolean enqueue() 
 168:   {
 169:     ReferenceQueue q = queue;
 170:     if (q != null)
 171:       {
 172:     return q.enqueue(this);
 173:       }
 174:     return false;
 175:   }
 176: }