Hotswap is a Java library and Gradle plugin providing a lightweight and efficient hot reloading experience, similar to Spring Boot Devtools, for any JVM application during development.
Note
This library is relatively new, and feedback or contributions are welcome!
- Framework and language agnostic: Works seamlessly with any JVM application, including Java or Kotlin, and frameworks such as Http4k or Javalin.
- Faster iteration: Accelerates the development feedback loop by removing the need for manual restarts.
- Reduced startup time: Eliminates the overhead of restarting the JVM and reloading unchanged classes.
- Zero dependencies: Integrates easily without external dependencies.
- Non-intrusive: Designed exclusively for development and does not impact production deployments.
- Extendable: Provides a simple, flexible core that can be customized to your project's specific requirements.
- Browser LiveReload (coming soon): Supports automatic browser reloads for browser-connected applications.
Hotswap continuously monitors your classpath for changes, which are triggered by manual recompilation. When changes occur, Hotswap gracefully interrupts your running application, signaling it to shut down. Your application must handle this interruption by properly closing resources and stopping running services. Once the shutdown completes, Hotswap immediately restarts your application using updated classes.
This restart mechanism uses two class loaders, similar to Spring Boot Devtools. A base class loader manages unchanged classes, such as those from the JDK and third-party libraries, while a restart class loader specifically handles classes currently under development. On restart, the restart class loader is discarded and recreated.
If you encounter delays or inconsistencies during reloading, parameters like debounceDuration can be adjusted to better match your development environment.
Add the following to your build.gradle.kts:
plugins {
application
id("io.github.raphiz.hotswap")
}
application {
mainClass.set("your.main.class")
}
hotswap {
// optional configuration, see below
}Additional documentation will follow.
| Option | Type | Description | Required | Default |
|---|---|---|---|---|
taskName |
String |
Name of the gradle task used to run your application | no | run |
packagePrefixes |
List<String> |
Classes in this package namespace are hot swapped while all others are not | no | All classes that are not in one of these packages: java.*, jdk.*, com.sun.* and sun.*) |
classPath |
List<Path> |
Directories and Files to watch for changes | no | System.getProperty("java.class.path") |
shutdownPollingInterval |
Duration |
Interval before logging warnings during shutdown | no | 5s |
debounceDuration |
Duration |
Aggregation delay for rapid file changes | no | 100ms |
| Option | Type | Description | Required | Default |
|---|---|---|---|---|
mainClass |
String |
Your application's main class | yes | - |
packagePrefixes |
List<String> |
Classes in this package namespace are hot swapped while all others are not | no | All classes that are not in one of these packages: java.*, jdk.*, com.sun.* and sun.*) |
classPath |
Set<Path> |
Directories and Files to watch for changes | no | System.getProperty("java.class.path") |
shutdownPollingInterval |
Duration |
Interval before logging warnings during shutdown | no | 5s |
debounceDuration |
Duration |
Aggregation delay for rapid file changes | no | 100ms |
Hotswap does not include its own compiler or build system. Instead, it integrates seamlessly with your existing toolchain. To trigger restarts, you simply recompile your code - Hotswap will detect any resulting class file changes and restart the application accordingly.
The most common ways to trigger recompilation include:
- Using your IDE: Compile changes manually using your IDE (e.g., IntelliJ IDEA via Ctrl/Cmd + F9), or configure it to compile automatically on save.
- Using Gradle in continuous mode: Run
gradle -t classesor any other relevant task with the-tflag for continuous building.
Hotswap listens for changes in the compiled output (i.e., class files), not the source files themselves. As long as the build process updates class files in the directories Hotswap is watching, the reload will be triggered.
Hotswap uses Java's built-in logging infrastructure (java.util.logging).
If your application uses a different logging framework (e.g., SLF4J, Logback), additional libraries or bridges might be necessary.
For detailed guidance on integrating logging frameworks, see this article.
Recommended: Use nix and direnv for managing dependencies and your development environment.
Using Nix is recommended but not mandatory; it provides tooling, dependencies, and pre-commit configurations.
./gradlew checkThis project is licensed under the MIT License. See LICENSE for details.