GarbageDisposal is a Java library for registering callbacks when one or more specific objects are Garbage Collected, without incurring the penalty for implementing the finalize method. Usage of finalize is discouraged, and now deprecated as of Java 9.
This library uses the decorator pattern to decorate an object, wrapping the specified callback in a PhantomReference, and invoking the callback in its own thread. Optionally, you may specify an ExecutorService to be used for the invocation of the callback.
Please see here and here for more details on why it is problematic to implement the finalize method directly.
The standard usage pattern of GarbageDisposal.java is to decorate() an object and provide a Runnable callback:
import club.wodencafe.decorators.GarbageDisposal;
...
Object objectToWatch = new Object();
GarbageDisposal.decorate(objectToWatch, () ->
System.out.println("Object is eligible for Garbage Collection"));
This callback will be invoked when the JVM Garbage Collection cycle runs, and the object is Phantom Reachable.
If for some reason you later decide to remove the callback, you may undecorate() the decorated object:
GarbageDisposal.undecorate(objectToWatch);
You can also use the CompletableFuture decorator methods to get a CompletableFuture handle:
Object objectToWatch = new Object();
GarbageDisposal.decorateAsync(objectToWatch).thenRunAsync(
() -> System.out.println("Object is eligible for Garbage Collection"));
This CompletableFuture handle may be cancelled if you choose, which will internally call undecorate.
This project is in the process of being hosted on Maven Central, when this is complete this artifact will be available and this section will be updated with the Maven Coordinates.
If you would like to start using this library in your Maven projects, please add the following to your pom.xml:
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<!-- https://jitpack.io/#wodencafe/GarbageDisposal -->
<dependency>
<groupId>com.github.wodencafe</groupId>
<artifactId>GarbageDisposal</artifactId>
<version>master-SNAPSHOT</version>
</dependency>
If you would like to start using this library in your Gradle projects, please add the following to your build.gradle:
repositories {
maven { url "https://jitpack.io" }
}
dependencies {
// https://jitpack.io/#wodencafe/GarbageDisposal
compile 'com.github.wodencafe:GarbageDisposal:master-SNAPSHOT'
}
For customizing and playing with the source for yourself, please see the Grab the source section.
- Version 0.3
- Better logging, better background service for dequeing PhantomReferences.
- Added additional decorator methods, utilizing CompletableFuture, and may be cancelled.
- Added several new tests to test the new decorator methods.
- Version 0.2
- Added support for undecorate().
- Added license explicitly to individual source files.
- Version 0.1
- GarbageDisposal GitHub Repository is created, initial commits.
- Added initial support for hosting on JitPack.io.
To grab a copy of this code for yourself, please run the following commands in your workspace or a directory of your choosing:
git clone https://github.com/wodencafe/GarbageDisposal
cd GarbageDisposal
./gradlew build
This will build the jar in:
./build/libs/GarbageDisposal.jar
You can then reference this jar for your own projects.
- Gradle - Dependency Management and Build System.
- JitPack.io - Easy to use package repository for Git.
- Guava - A useful a set of core libraries for Java, developed by Google.
- SLF4J - A simple facade or abstraction for various logging frameworks.
- JUnit (Unit Testing) - The de facto unit testing framework for Java.
- Awaitility (Unit Testing) - A small Java DSL for synchronizing asynchronous operations.
This project is licensed under the BSD-3 License - see the LICENSE.md file for details
You can find more information about the deprecation of Object.finalize() here.