1 /* 2 * @(#)PhantomReference.java 1.19 03/12/19 3 * 4 * Copyright 2004 Sun Microsystems, Inc. All rights reserved. 5 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. 6 */ 7 8 package java.lang.ref; 9 10 11 /** 12 * Phantom reference objects, which are enqueued after the collector 13 * determines that their referents may otherwise be reclaimed. Phantom 14 * references are most often used for scheduling pre-mortem cleanup actions in 15 * a more flexible way than is possible with the Java finalization mechanism. 16 * 17 * <p> If the garbage collector determines at a certain point in time that the 18 * referent of a phantom reference is <a 19 * HREF="package-summary.html#reachability">phantom reachable</a>, then at that 20 * time or at some later time it will enqueue the reference. 21 * 22 * <p> In order to ensure that a reclaimable object remains so, the referent of 23 * a phantom reference may not be retrieved: The <code>get</code> method of a 24 * phantom reference always returns <code>null</code>. 25 * 26 * <p> Unlike soft and weak references, phantom references are not 27 * automatically cleared by the garbage collector as they are enqueued. An 28 * object that is reachable via phantom references will remain so until all 29 * such references are cleared or themselves become unreachable. 30 * 31 * @version 1.19, 12/19/03 32 * @author Mark Reinhold 33 * @since 1.2 34 */ 35 36 public class PhantomReference<T> extends Reference<T> { 37 38 /** 39 * Returns this reference object's referent. Because the referent of a 40 * phantom reference is always inaccessible, this method always returns 41 * <code>null</code>. 42 * 43 * @return <code>null</code> 44 */ 45 public T get() { 46 return null; 47 } 48 49 /** 50 * Creates a new phantom reference that refers to the given object and 51 * is registered with the given queue. 52 * 53 * <p> It is possible to create a phantom reference with a <tt>null</tt> 54 * queue, but such a reference is completely useless: Its <tt>get</tt> 55 * method will always return null and, since it does not have a queue, it 56 * will never be enqueued. 57 * 58 * @param referent the object the new phantom reference will refer to 59 * @param q the queue with which the reference is to be registered, 60 * or <tt>null</tt> if registration is not required 61 */ 62 public PhantomReference(T referent, ReferenceQueue<? super T> q) { 63 super(referent, q); 64 } 65 66 } 67