1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 /* 18 * Copyright (C) 2008 The Android Open Source Project 19 * 20 * Licensed under the Apache License, Version 2.0 (the "License"); 21 * you may not use this file except in compliance with the License. 22 * You may obtain a copy of the License at 23 * 24 * http://www.apache.org/licenses/LICENSE-2.0 25 * 26 * Unless required by applicable law or agreed to in writing, software 27 * distributed under the License is distributed on an "AS IS" BASIS, 28 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 29 * See the License for the specific language governing permissions and 30 * limitations under the License. 31 */ 32 33 package java.lang.ref; 34 35 /** 36 * Implements a phantom reference, which is the weakest of the three types of 37 * references. Once the garbage collector decides that an object {@code obj} is 38 * phantom-reachable, it is being enqueued 39 * on the corresponding queue, but its referent is not cleared. That is, the 40 * reference queue of the phantom reference must explicitly be processed by some 41 * application code. As a consequence, a phantom reference that is not 42 * registered with any reference queue does not make any sense. 43 * <p> 44 * Phantom references are useful for implementing cleanup operations that are 45 * necessary before an object gets garbage-collected. They are sometimes more 46 * flexible than the {@link Object#finalize()} method. 47 */ 48 public class PhantomReference<T> extends Reference<T> { 49 50 /** 51 * Constructs a new phantom reference and registers it with the given 52 * reference queue. The reference queue may be {@code null}, but this case 53 * does not make any sense, since the reference will never be enqueued, and 54 * the {@link #get()} method always returns {@code null}. 55 * 56 * @param r the referent to track 57 * @param q the queue to register the phantom reference object with 58 */ 59 public PhantomReference(T r, ReferenceQueue<? super T> q) { 60 super(r, q); 61 } 62 63 /** 64 * Returns {@code null}. The referent of a phantom reference is not 65 * accessible. 66 * 67 * @return {@code null} (always) 68 */ 69 @Override 70 public T get() { 71 return null; 72 } 73 } 74
