1 package java.lang.ref;
   2 
   3 /**
   4  * {@link Reference}(s) implementing this interface are automatically
   5  * {@link #clean() cleaned} by reference handling thread(s) after their referents
   6  * become appropriately (soft, weak or phantom) reachable.
   7  * <p>
   8  * Such references can not be associated with a {@link ReferenceQueue}. Attempts
   9  * to register a {@link SoftReference#SoftReference(Object, ReferenceQueue) soft},
  10  * {@link WeakReference#WeakReference(Object, ReferenceQueue) weak} or
  11  * {@link PhantomReference#PhantomReference(Object, ReferenceQueue) phantom}
  12  * reference implementing this interface with a non-null {@code ReferenceQueue}
  13  * throw {@link IllegalArgumentException}.
  14  *
  15  * @since 1.9
  16  */
  17 public interface Cleaner {
  18 
  19     /**
  20      * Invoked by one of the reference handling thread(s) some time after the
  21      * referent of a {@link Reference} implementing this interface becomes
  22      * appropriately (soft, weak or phantom) reachable and after the Reference
  23      * is cleared by the garbage collector.<p>
  24      * Implementations should put the clean-up code into this method.
  25      */
  26     void clean();
  27 
  28     /**
  29      * Always returns false. References implementing {@link Cleaner}
  30      * interface are never associated with a {@link ReferenceQueue}.
  31      *
  32      * @return false;
  33      */
  34     boolean isEnqueued();
  35 
  36     /**
  37      * Does nothing and returns false. References implementing {@link Cleaner}
  38      * interface are never associated with a {@link ReferenceQueue}.
  39      *
  40      * @return false
  41      */
  42     boolean enqueue();
  43 
  44     /**
  45      * Clears this Cleaner reference object.  Invoking this method will not cause
  46      * this object to be {@link #clean() cleaned}. It may prevent this object
  47      * from being cleaned in the future if it has not been discovered as a pending
  48      * reference by GC yet.
  49      * <p>This method is invoked only by Java code; when the garbage collector
  50      * clears references it does so directly, without invoking this method.
  51      */
  52     void clear();
  53 }