The References API consists of five classes located in the java.lang.ref package. Central to this package are Reference and ReferenceQueue.
Reference is the abstract superclass of this package's concrete SoftReference, WeakReference, and PhantomReference subclasses.
ReferenceQueue is a concrete class whose instances describe queue data structures. When you associate a ReferenceQueue instance with a Reference subclass object (Reference object, for short), the Reference object is added to the queue when the referent to which its encapsulated reference refers becomes garbage.
NOTE: You associate a ReferenceQueue object with a Reference object by passing the ReferenceQueue object to an appropriate Reference subclass constructor.
Reference is declared as generic type Reference<T>, where T identifies the referent's type. This class provides the following methods:
■ void clear() assigns null to the stored reference; the Reference object on which this method is called is not enqueued (inserted) into its associated reference queue (if there is an associated reference queue). (The garbage collector clears references directly; it does not call clear(). Instead, this method is called by applications.)
■ boolean enqueue() adds the Reference object on which this method is called to the associated reference queue. This method returns true when this Reference object has become enqueued; otherwise, this method returns false—this Reference object was already enqueued or was not associated with a queue when created. (The garbage collector enqueues Reference objects directly; it does not call enqueue(). Instead, this method is called by applications.)
■ T get() returns this Reference object's stored reference. The return value is null when the stored reference has been cleared, either by the application or by the garbage collector.
■ boolean isEnqueued() returns true when this Reference object has been enqueued, either by the application or by the garbage collector. Otherwise, this method returns false—this Reference object was not associated with a queue when created.
NOTE: Reference also declares constructors. Because these constructors are package-private, only classes in the java.lang.ref package can subclass Reference. This restriction is necessary because instances of Reference's subclasses must work closely with the garbage collector.
ReferenceOueue is declared as generic type ReferenceOueue<T>, where T identifies the referent's type. This class declares the following constructor and methods:
■ ReferenceOueue() initializes a new ReferenceOueue instance.
■ Reference<? extends T> poll() polls this queue to check for an available Reference object. If one is available, the object is removed from the queue and returned. Otherwise, this method returns immediately with a null value.
■ Reference<? extends T> remove() removes the next Reference object from the queue and returns this object. This method waits indefinitely for a Reference object to become available, and throws java.lang.InterruptedException when this wait is interrupted.
■ Reference<? extends T> remove(long timeout) removes the next Reference object from the queue and returns this object. This method waits until a Reference object becomes available or until timeout milliseconds have elapsed—passing 0 to timeout causes the method to wait indefinitely. If timeout's value expires, the method returns null. This method throws java.lang.IllegalArgumentException when timeout's value is negative, or InterruptedException when this wait is interrupted.
Was this article helpful?