Touring Language APIs - Beginning Java 7 - page 336

• boolean enqueue() adds the Reference object on which this method
is called to the associated reference queue. This method returns true when
this Reference objecthasbecomeenqueued;otherwise,thismethodreturns
false—this Reference object was already enqueued or was not associated
withaqueuewhencreated.(Thegarbagecollectorenqueues Reference ob-
jects directly; it does not call enqueue() . Instead, this method is called by
applications.)
• T get() returnsthis Reference object'sstoredreference.Thereturnvalue
isnullwhenthestoredreferencehasbeencleared,eitherbytheapplicationor
by the garbage collector.
• boolean isEnqueued() returns true when this Reference object has
beenenqueued,eitherbytheapplicationorbythegarbagecollector.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,onlyclassesinthe java.lang.ref packagecansubclass Refer-
ence . This restriction is necessary because instances of Reference 's subclasses
must work closely with the garbage collector.
ReferenceQueue is declared as generic type ReferenceQueue<T> , where T
identifies the referent's type. This class declares the following constructor and methods:
• ReferenceQueue() initializes a new ReferenceQueue instance.
• Reference<? extends T> poll() polls this queue to check for an
available Reference object. If one is available, the object is removed from
thequeueandreturned.Otherwise,thismethodreturnsimmediatelywithanull
value.
• Reference<? extends T> remove() removesthenext 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 milli-
seconds have elapsed—passing 0 to timeout causes the method to wait in-
definitely. If timeout 's value expires, the method returns null. This method
throws java.lang.IllegalArgumentException when timeout 's