API Note

The cleaning action is invoked only after the associated object becomes phantom reachable, so it is important that the object implementing the cleaning action does not hold references to the object. In this example, a static class encapsulates the cleaning state and action. An "inner" class, anonymous or not, must not be used because it implicitly contains a reference to the outer instance, preventing it from becoming phantom reachable. The choice of a new cleaner or sharing an existing cleaner is determined by the use case.

If the CleaningExample is used in a try-finally block then the close method calls the cleaning action. If the close method is not called, the cleaning action is called by the Cleaner when the CleaningExample instance has become phantom reachable.

public class CleaningExample implements AutoCloseable {
       // A cleaner (preferably one shared within a library,
       // but for the sake of example, a new one is created here)
       private static final Cleaner cleaner = Cleaner.create();

       // State class captures information necessary for cleanup.
       // It must hold no reference to the instance being cleaned
       // and therefore it is a static inner class in this example.
       static class State implements Runnable {

           State(...) {
               // initialize State needed for cleaning action
           }

           public void run() {
               // cleanup action accessing State, executed at most once
           }
       }

       private final State state;
       private final Cleaner.Cleanable cleanable;

       public CleaningExample() {
           this.state = new State(...);
           this.cleanable = cleaner.register(this, state);
       }

       public void close() {
           cleanable.clean();
       }
   }

The cleaning action could be a lambda but all too easily will capture the object reference, by referring to fields of the object being cleaned, preventing the object from becoming phantom reachable. Using a static nested class, as above, will avoid accidentally retaining the object reference.

Cleaning actions should be prepared to be invoked concurrently with other cleaning actions. Typically the cleaning actions should be very quick to execute and not block. If the cleaning action blocks, it may delay processing other cleaning actions registered to the same cleaner. All cleaning actions registered to a cleaner should be mutually compatible.