search

HotswapProjects / HotswapAgent

Java unlimited redefinition of classes at runtime.
GNU General Public License v2.0
2.37k stars 493 forks source link

readme

Hotswap Agent

Maven Build Status License: GPL v2 Gitter follow on Twitter

This is an overview page, please visit hotswapagent.org for more information.

Overview

Java unlimited runtime class and resource redefinition.

The primary goal of this project was to eliminate the need for the traditional "change code -> restart and wait... -> check" development cycle. Over time, this concept has evolved into a new paradigm within the Java ecosystem, allowing for real-time software development within a running application. This approach is even feasible in restricted environments, such as Docker containers.

IntelliJ - try HotswapHelper

If you're an IntelliJ user, you can simplify setup of HA and DCEVM by using the IntelliJ HotSwapHelper plugin.

Easy to start

  1. Download and Install:

    • For Java 17/21: Download the latest JBR17 or JBR21. Since these versions do not include a built-in Hotswap Agent, you will need to manually copy hotswap-agent.jar to the lib/hotswap folder. You can find the latest Hotswap Agent here. Ensure that the file in the lib/hotswap folder is named hotswap-agent.jar without any version numbers in the filename.

    • For Java 11: Use TravaJDK, which has an integrated HotswapAgent, and install it as an alternative JDK. Alternatively, TravaJDK includes an embedded HotswapAgent.

    • For Java 8: Use jdk8-dcevm along with the HotswapAgent.

  2. HotswapAgent Modes:

    Starting with dcevm-11.0.9, the HotswapAgent is disabled by default. You can enable support for HotswapAgent using JVM options in one of three modes:

    • -XX:HotswapAgent=fatjar activates the internal fatjar HotswapAgent.
    • -XX:HotswapAgent=core activates the internal core HotswapAgent.
    • -XX:HotswapAgent=external configures JVM support for HotswapAgent and allows the user to supply an external hotswap-agent.jar using the -javaagent:<path>/hotswap-agent.jar option.

    The HotswapAgent=core mode operates without additional plugins, except for core JVM plugins, resulting in faster performance due to reduced scanning and class copying tasks. To use additional plugins, you need to configure them as Maven dependencies in your pom.xml file. On the other hand, the HotswapAgent=fatjar mode includes all plugins by default, which may slightly slow down application startup.

3.Launching:

3.Run your application:

Start the application in debug mode, check that the agent and plugins are initialized correctly:

    HOTSWAP AGENT: 9:49:29.548 INFO (org.hotswap.agent.HotswapAgent) - Loading Hotswap agent - unlimited runtime class redefinition.
    HOTSWAP AGENT: 9:49:29.725 INFO (org.hotswap.agent.config.PluginRegistry) - Discovered plugins: [org.hotswap.agent.plugin.hotswapper.HotswapperPlugin, org.hotswap.agent.plugin.jvm.AnonymousClassPatchPlugin, org.hotswap.agent.plugin.hibernate.HibernatePlugin, org.hotswap.agent.plugin.spring.SpringPlugin, org.hotswap.agent.plugin.jetty.JettyPlugin, org.hotswap.agent.plugin.tomcat.TomcatPlugin, org.hotswap.agent.plugin.zk.ZkPlugin, org.hotswap.agent.plugin.logback.LogbackPlugin]
    ...
    HOTSWAP AGENT: 9:49:38.700 INFO (org.hotswap.agent.plugin.spring.SpringPlugin) - Spring plugin initialized - Spring core version '3.2.3.RELEASE'

4.Check redefinition

Save a changed resource and/or use the HotSwap feature of your IDE to reload changes

Plugins

Each application framework (Spring, Hibernate, Logback, ...) needs a special reloading mechanism to keep up-to-date after class redefinition (e.g. Hibernate configuration reload after new entity class is introduced). Hotswap agent works as a plugin system and is shipped preconfigured with all major framework plugins. It is easy to write your custom plugin even as part of your application.

Contribute

This project is very complex due to a lot of supported frameworks and various versions. Community contribution is mandatory to keep it alive. You can start by creating a plugin inside your application or by writing an example/integration test. There is always a need for documentation improvement :-). Thank you for any help!

What is available?

Should you have any problems or questions, ask at HotswapAgent forum.

This project is similar to JRebel. The main differences are:

Examples

See HotswapAgentExamples GitHub project. The purpose of an example application is:

Feel free to fork/branch and create an application for your setup (functional, but as simple as possible). General setups will be merged into the master.

IDE support

None needed :) Really! All changes are transparent and all you need to do is to download patch+agent and setup your application/application server. Because we use standard java hotswap behaviour, your IDE will work as expected. However, we work on IDE plugins to help with download & configuration.

Some plugins are already available:

IntelliJ HotSwapHelper

  1. Add two action next to the "Debug" button in intellij, Run with hotswap, Debug with hotswap.
  2. When click the action,will set vm parameters for you,no need to set vm parameters manually.
  3. Source code and documentation: https://github.com/gejun123456/HotSwapHelper.

Configuration

The basic configuration is set to reload classes and resources from the classpath known to the running application (classloader). If you need a different configuration, add the hotswap-agent.properties file to the classpath root (e.g. src/main/resources/hotswap-agent.properties).

Detail documentation of available properties and default values can be found in the agent properties file

Hotswap agent command-line options

Full syntax of command line options is:

-javaagent:[yourpath/]hotswap-agent.jar=[option1]=[value1],[option2]=[value2]

Hotswap agent accepts the following options:

Disable some plugins by vm option.

How does it work?

DCEVM

Hotswap agent does the work of reloading resources and framework configuration (Spring, Hibernate, ...), but it depends on the standard Java hotswap mechanism to reload classes. Standard Java hotswap allows only method body change, which makes it practically unusable. DCEVM is a JVM (Hotspot) patch that allows almost any structural class change on hotswap (with an exception to a hierarchy change). Although hotswap agent works even with standard java, we recommend using DCEVM (and all tutorials use DCEVM as target JVM).

Hotswap Agent

Hotswap agent is a plugin container with plugin manager, plugin registry, and several agent services (e.g. to watch for class/resource change). It helps with common tasks and classloading issues. It scans the classpath for class annotated with @Plugin annotation, injects agent services, and registers reloading hooks. Runtime bytecode modification is provided by javaasist library.

Plugins

Plugins administered by Hotswap Agent are usually focused on a specific framework. For example, Spring plugin uses HA services to:

Java frameworks plugins:

Servlet containers and application servers plugins:

JVM plugins - hotswapping enhancements:

Find detailed documentation of each plugin in the plugin project main README.md file.

Runtime overhead

It depends on how many frameworks you use and which caches are disabled. Example measurements for a large, real-world enterprise application based on Spring + Hibernate, run on Jetty.

Setup                        | Startup time
-----------------------------|-------------
Run (plain Java)             | 23s
Debug (plain Java)           | 24s
Debug (plain DCEVM)          | 28s
Agent - disabled all plugins | 31s
Agent - all plugins          | 35s

How to write a plugin

You can write plugin directly as a part of your application. Set pluginPackages=your.plugin.package inside your hotswap-agent.properties configuration to discover @Plugin annotated classes. You will also need agent JAR dependency to compile, but be careful NOT to add the JAR to your application; it must be loaded only as a javaagent. Maven dependency:

    <dependency>
        <groupId>org.hotswapagent</groupId>
        <artifactId>HotswapAgent</artifactId>
        <version>${project.version}</version>
        <scope>provided</scope>
    </dependency>

See ExamplePlugin (part of TestApplication) to go through a commented simple plugin. Read agent readme to understand agent concepts. Check existing plugins source code for more examples.

Creating Release

Launch run-tests.sh script in the main directory. Currently, you have to set up JAVA_HOME location directory manually. At least Java 11 with DCEVM should be checked before a release. All automatic tests are set to fail the whole script in case of any single test failure.

Go to the directory representing repository root. In case DCEVM is named dcevm

mvn release:prepare
mvn release:perform

Credits

Hotswap agent:

DCEVM: