Cleanup

public interface Cleanup

This is an interface to add cleanup actions to any type. The method registerCleanup(Consumer, Object) must be run at the end of or after construction (code run after that could invalidate the object, which could lead to problems). The configured cleanup action is run when this does not exist anymore. Therefore the value must not contain any references to this.

You can use addExceptionHandler(Consumer) to handle exceptions (e.g. send exceptions to your logging system).

Pros and Cons and Pitfalls:

You don't need to manually chain the cleanup actions.
Cleanup is done when the objects is already removed.
Less risk of OutOfMemoryError during GC.
Very obvious mistakes in usage are detected.
Exceptions can be handled by registered exception handlers.
runCleanupOnExit(boolean) is available, while Runtime.runFinalizersOnExit(boolean) is deprecated.*

Does not work if you leak a reference to this to the cleanup action. References are often implicit and not visible in the code. Many of such mistakes can not be detected and the object is never garbage collected (memory leak).
No guarantee that the code runs when the JVM exits.
Invocations are not ordered and you could close the resources in the wrong order.
There is still a risk that cleanup is done for incompletely constructed objects.
Memory visibility problems, as the cleanup is performed in a daemon thread.
Use of locks or other synchronization-based mechanisms within a cleanup can cause deadlock or starvation.

* Cleanup actions are always only run for discarded objects. You should use Runtime.addShutdownHook(Thread) for all code that must run on shutdown.

A note from the author:
I decided to use the name Cleanup because it is simple to understand. However, there is the try-with-resource statement which is much better if you actually need to close something. Cleanup should be used for code that isn't critical, such as logging and debugging.
I recommend using static methods instead of lambdas:
foo.registerCleanup(Foo::cleanup);
This is shown in the Example, which you can find in the test-folder. It is very safe and easy to understand for others, as you can include the static method in your API documentation.

Author:: Claude Martin

Method Summary

All Methods Static Methods Instance Methods Default Methods
Modifier and Type	Method and Description
`static void`	`addExceptionHandler(Consumer<Throwable> handler)` Adds a handler for Exceptions thrown during cleanup.
`default void`	`registerAutoClose(AutoCloseable... resources)` Easy registration of `auto-closeable` resources.
`static void`	`registerAutoClose(Object object, AutoCloseable... resources)` Register any object and its resources for cleanup.
`default <V> void`	`registerCleanup(Consumer<V> cleanup, V value)` Register method to clean up after garbage collection removed `this`.
`static <V> void`	`registerCleanup(Object object, Consumer<V> cleanup, V value)` Register any object and a value for cleanup.
`default void`	`registerCleanup(Runnable cleanup)` Convenience method for cleanup actions that does not need any value.
`static void`	`runCleanup()` Runs the pending cleanup actions.
`static void`	`runCleanupOnExit(boolean value)` Runs cleanup code by the use of `Runtime.addShutdownHook(Thread)`.
`static void`	`setCleanupPriority(int newPriority)` Changes the priority of the cleanup thread.

- Method Detail
  - addExceptionHandler
```
static void addExceptionHandler(Consumer<Throwable> handler)
```
    Adds a handler for Exceptions thrown during cleanup. This includes all exceptions thrown in the daemon-thread used to perform cleanup. All added handlers are executed until one throws an unchecked exception. Unchecked exceptions thrown by exception handlers are lost and they prevent other handlers to run. Make sure that does not happen.
    It is recommended that you use this for logging, to be able to find problems in the cleanup actions.
    
    Parameters:
    
    handler - a handler for all cleanup exceptions.
  - registerCleanup
```
default <V> void registerCleanup(Consumer<V> cleanup,
                                 V value)
```
    Register method to clean up after garbage collection removed this.
    The value is any data structure that holds everything you need for the cleanup.
    Examples: Database connection to be closed. Stream to be closed. ID to be logged. etc.
    But it must not hold any references to this. Note that instances of inner / anonymous classes also hold implicit references to the outer instance. However, you can reference fields directly in the lambda, instead of using value, as long as the objects do not reference this.
    Multiple actions can be registered and each time a new PhantomReference will be created.
    Cleanup is synchronized on it's value, but multiple cleanup actions use different values. So you might want to use some Lock to ensure visibility.
    
    Type Parameters:
    
    V - generic type of the value
    
    Parameters:
    
    cleanup - A consumer that defines the cleanup action
    
    value - All data needed for cleanup, or null
    
    Throws:
    
    IllegalArgumentException - thrown if value is obviously holding a reference to this
  - registerCleanup
```
default void registerCleanup(Runnable cleanup)
```
    Convenience method for cleanup actions that does not need any value.
    Make sure you do not capture a reference to this in your expression. However, you may capture other values, like objects from local, effectively final variables.
    This is especially useful for static cleanup actions:
    foo.registerCleanup(Foo::cleanup);
    All you need is a static, void, no-args method in your class:
    class Foo { public static void cleanup() { ... } }
    
    Parameters:
    
    cleanup - runnable cleanup action
    
    See Also:
    
    registerCleanup(Consumer, Object)
  - registerAutoClose
```
default void registerAutoClose(AutoCloseable... resources)
```
    Easy registration of auto-closeable resources.
    The resources are closed as they are listed, from first to last. Therefore you should list them in the opposite order of their creation.
    The documentation of AutoCloseable.close() states that it is not required to be idempotent. But for a cleanup action it is recommended to always use resources with an idempotent close method (cf. Connection.close(), Closeable.close()).
    
    Parameters:
    
    resources - auto-closeable resources.
    
    Throws:
    
    NullPointerException - if null is passed as a resource
    
    IllegalArgumentException - if this is passed as a resource
  - registerCleanup
```
static <V> void registerCleanup(Object object,
                                Consumer<V> cleanup,
                                V value)
```
    Register any object and a value for cleanup. See the non-static method for more information.
    
    Type Parameters:
    
    V - generic type of the value
    
    Parameters:
    
    object - object for which a PhantomReference will be created
    
    cleanup - A consumer to clean up the value
    
    value - All data needed for cleanup, or null
    
    Throws:
    
    IllegalArgumentException - thrown if value is obviously holding a reference to this
    
    See Also:
    
    registerCleanup(Consumer, Object)
  - registerAutoClose
```
static void registerAutoClose(Object object,
                              AutoCloseable... resources)
```
    Register any object and its resources for cleanup. See the non-static method for more information.
    
    Parameters:
    
    object - object for which a PhantomReference will be created
    
    resources - auto-closeable resources.
    
    Throws:
    
    NullPointerException - if null is passed as the object or a resource
    
    IllegalArgumentException - if any resource is the object
    
    See Also:
    
    registerAutoClose(AutoCloseable...)
  - runCleanupOnExit
```
static void runCleanupOnExit(boolean value)
```
    Runs cleanup code by the use of Runtime.addShutdownHook(Thread). This is an alternative to the deprecated Runtime.runFinalizersOnExit(boolean). But note that only cleanup actions of discarded objects are run. For objects that live until shutdown the action needs to be registered by Runtime.addShutdownHook(Thread) additionally. Such an action will run when the object might still be in use by any threads. Cleanup actions, on the other hand, are designed to run for discarded objects only.
    
    Parameters:
    
    value - true to enable cleanup on exit, false to disable
    
    See Also:
    
    Thread.setDaemon(boolean)
  - setCleanupPriority
```
static void setCleanupPriority(int newPriority)
```
    Changes the priority of the cleanup thread. Default is Thread.MIN_PRIORITY.
    
    Parameters:
    
    newPriority - priority to set thread to
    
    Throws:
    
    IllegalArgumentException - If the priority is not in the range MIN_PRIORITY to MAX_PRIORITY.
    
    SecurityException - if the current thread cannot modify the cleanup thread.
    
    See Also:
    
    Thread.setPriority(int), Thread.MAX_PRIORITY, Thread.MIN_PRIORITY
  - runCleanup
```
static void runCleanup()
```
    Runs the pending cleanup actions.
    Cleanup actions are processed automatically as needed, if the runCleanup method is not invoked explicitly.
    This does not invoke System.gc(); and therefore only blocks until all objects are handled that were already discarded.
    
    See Also:
    
    Runtime.runFinalization()

Interface Cleanup

Method Summary

Method Detail

addExceptionHandler

registerCleanup

registerCleanup

registerAutoClose

registerCleanup

registerAutoClose

runCleanupOnExit

setCleanupPriority

runCleanup