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.

Originally, the main purpose of this project used to be avoiding of infamous change code->restart and wait...->check development lifecycle. Lately this schema evolved to a new paradigm in the Java world, based on development of software in running application, that approach can be used even in closed enviroment like Docker.

Easy to start

Download and install latest jdk8-dcevm + HotswapAgent or download jdk11-dcevm with integrated HotswapAgent and install it as an alternative JDK. In case of dcevm8, launch your application with options -XXaltjvm=dcevm -javaagent:hotswap-agent.jar to get basic setup. Optionally you can add hotswap-agent.properties to your application to configure plugins and agent's behavior.

Plugins

Each application framework (Spring, Hibernate, Logback, ...) needs 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 ships 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 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 need for documentation improvement :-). Thank you for any help!

The sourcespy dashboard provides a high level overview of the repository including module dependencies, module hierarchy, external libraries, and other components of the system.

Issue triage Open Source Helpers

You can contribute by triaging issues which may include reproducing bug reports or asking for vital information, such as version numbers or reproduction instructions. If you would like to start triaging issues, one easy way to get started is to subscribe to hotswapagent on CodeTriage.

Quick start:

Install

  1. download latest release of DCEVM Java patch and launch the installer (e.g. java -jar installer-light.jar). Currently you need to select correct installer for Java major version (7/8).
  2. select java installation directory on your disc and press "Install DCEVM as altjvm" button. Java 1.7+ versions are supported.
  3. download latest release of Hotswap agent jar, unpack hotswap-agent.jar and put it anywhere on your disc. For example: C:\java\hotswap-agent.jar

Run your application

  1. add following command line java attributes: -XXaltjvm=dcevm -javaagent:PATH_TO_AGENT\hotswap-agent.jar (you need to replace PATH_TO_AGENT with an actual) directory. For example java -XXaltjvm=dcevm -javaagent:c:\java\hotswap-agent.jar YourApp. See IntelliJ IDEA and Netbeans forum threads for IDE specific setup guides. If your application is already running, you still can attach agent jar using the example code snippet.
  2. (optional) create a file named "hotswap-agent.properties" inside your resources directory, see available properties and default values: https://github.com/HotswapProjects/HotswapAgent/blob/master/hotswap-agent-core/src/main/resources/hotswap-agent.properties
  3. 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. save a changed resource and/or use the HotSwap feature of your IDE to reload changes

What is available?

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

This project is similar to JRebel. 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.

Configuration

The basic configuration set to reload classes and resources from classpath known to the running application (classloader). If you need a different configuration, add 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 following options:

How does it work?

DCEVM

Hotswap agent does the work of reloading resources and framework configuration (Spring, Hibernate, ...), but it depends on standard Java hotswap mechanism to actually reload classes. Standard Java hotswap allows only method body change , which makes it practically unusable. DCEVM is a JRE patch witch allows almost any structural class change on hotswap (with an exception of a hierarchy change). Although hotswap agent works even with standard java, we recommend to use 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 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 targeted towards a specific framework. For example Spring plugin uses agent services to:

Java frameworks plugins:

Servlet containers and application servers plugins:

JVM plugins - hotswapping enhancements:

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

Runtime overhead

It really 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>

(Note that the JAR is not yet in central maven repository - you need to build it from source first).

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 setup JAVA_HOME location directory manually. At least Java 7 and Java 8 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 directory representing repository root. In case DCEVM is named dcevm

mvn release:prepare
mvn release:perform

In case your DCEVM is named differently i.e. server

mvn release:prepare -Darguments="-Ddcevm=server"
mvn release:perform -Darguments="-Ddcevm=server"

Credits

Hotswap agent:

DCEVM: