36 * referent of a phantom reference is <a |
36 * referent of a phantom reference is <a |
37 * href="package-summary.html#reachability">phantom reachable</a>, then at that |
37 * href="package-summary.html#reachability">phantom reachable</a>, then at that |
38 * time or at some later time it will enqueue the reference. |
38 * time or at some later time it will enqueue the reference. |
39 * |
39 * |
40 * <p> In order to ensure that a reclaimable object remains so, the referent of |
40 * <p> In order to ensure that a reclaimable object remains so, the referent of |
41 * a phantom reference may not be retrieved: The <code>get</code> method of a |
41 * a phantom reference may not be retrieved: The {@code get} method of a |
42 * phantom reference always returns <code>null</code>. |
42 * phantom reference always returns {@code null}. |
43 * |
43 * |
44 * <p> Unlike soft and weak references, phantom references are not |
44 * <p> Unlike soft and weak references, phantom references are not |
45 * automatically cleared by the garbage collector as they are enqueued. An |
45 * automatically cleared by the garbage collector as they are enqueued. An |
46 * object that is reachable via phantom references will remain so until all |
46 * object that is reachable via phantom references will remain so until all |
47 * such references are cleared or themselves become unreachable. |
47 * such references are cleared or themselves become unreachable. |
53 public class PhantomReference<T> extends Reference<T> { |
53 public class PhantomReference<T> extends Reference<T> { |
54 |
54 |
55 /** |
55 /** |
56 * Returns this reference object's referent. Because the referent of a |
56 * Returns this reference object's referent. Because the referent of a |
57 * phantom reference is always inaccessible, this method always returns |
57 * phantom reference is always inaccessible, this method always returns |
58 * <code>null</code>. |
58 * {@code null}. |
59 * |
59 * |
60 * @return <code>null</code> |
60 * @return {@code null} |
61 */ |
61 */ |
62 public T get() { |
62 public T get() { |
63 return null; |
63 return null; |
64 } |
64 } |
65 |
65 |
66 /** |
66 /** |
67 * Creates a new phantom reference that refers to the given object and |
67 * Creates a new phantom reference that refers to the given object and |
68 * is registered with the given queue. |
68 * is registered with the given queue. |
69 * |
69 * |
70 * <p> It is possible to create a phantom reference with a <tt>null</tt> |
70 * <p> It is possible to create a phantom reference with a {@code null} |
71 * queue, but such a reference is completely useless: Its <tt>get</tt> |
71 * queue, but such a reference is completely useless: Its {@code get} |
72 * method will always return null and, since it does not have a queue, it |
72 * method will always return null and, since it does not have a queue, it |
73 * will never be enqueued. |
73 * will never be enqueued. |
74 * |
74 * |
75 * @param referent the object the new phantom reference will refer to |
75 * @param referent the object the new phantom reference will refer to |
76 * @param q the queue with which the reference is to be registered, |
76 * @param q the queue with which the reference is to be registered, |
77 * or <tt>null</tt> if registration is not required |
77 * or {@code null} if registration is not required |
78 */ |
78 */ |
79 public PhantomReference(T referent, ReferenceQueue<? super T> q) { |
79 public PhantomReference(T referent, ReferenceQueue<? super T> q) { |
80 super(referent, q); |
80 super(referent, q); |
81 } |
81 } |
82 |
82 |