Using HotswapAgent to Speed Up Development

As a Java EE developer, I sometimes envy how fast it's possible to see the result of a code change in a running application with interpreted languages like PHP or JavaScript. With Java, it's always necessary to rebuild the source code in a bytecode, which can then be safely updated only by restarting the whole application. And all developers know that restoring the desired state of the application after a fresh restart takes time and is tedious.

Many developers know that JRebel can help a lot with updating the code on the fly. There's been a lot of effort put into it to support all sorts of code and resource changes and refresh them with virtually any Java framework used by the application. But the downside is that it's pretty expensive for a casual developer, doing just some hacking on his/her own or working on a non-commercial project. I have some experience with JRebel and I liked it a lot, but I was using it on a commercial project where I didn't pay for the license. A while ago I'd come across an open source alternative called HotswapAgent, which has worked very well for me for my personal Java EE projects. I'm going to write up how I got it running in my IDE and my Java EE server of choice - Payara Server.

Getting Started With HotswapAgent

Hotswap Agent itself is just a Java agent which has to be attached to the application. It essentially scans the classpath to detect the presence of known frameworks and tries to refresh the frameworks after a code or resource change is detected. It's also possible to write custom plugins for any project or even specifically for your application. However, getting the most of Hotswap Agent requires installing an alternative DCEVM engine into your JRE installation, which does a much better job of reloading code changes than the standard VM engine in the HotSpot VM. The alternative VM engine is basically a patched version of the standard engine, which improves code hot swap via the debugging interface, without impacting other functions of the JVM.

So to summarize, we are going to do this to work with HotSwap from our IDE of choice:

1. Install the DCEVM engine into a Java installation (JRE or JDK).
2. Configure the IDE to start the application with the HotswapAgent JAR as a Java agent and using the DCEVM engine instead of the standard JVM engine.
3. Configure the IDE to refresh plain text resources like XML, property files, in the running application (this has to be done by the IDE because it's not supported by Java debugger).
4. Start the application in debug mode and connect to it via the debugger interface from within the IDE.
5. Continue coding and see the changes in your app immediately.

Installing the DCEVM Engine

First, download the DCEVM installer for your Java installation. The project is pretty quick to release new versions for new Java updates. At the time of writing this blog post, there was a build for Java 8 update 144 available, released 12 days ago, just a month after the actual Java 8 update 144 had been released. There aren't releases of DCEVM for every Java update, but I always just used the latest version with my Java installation and never had any issues.

The installer is a plain executable JAR file, which you can start with java -jar DCEVM-installer.jar. In Linux, I usually start this with admin privileges (using sudo), because it will add/modify files in the Java installation, which is usually read-only for standard users if installed system-wide: sudo java -jar DCEVM-installer.jar 

The installer will open a window, which lists all the detected Java installations on the system.

It's possible to install the DCEVM engine in 2 ways:

• Replace the current VM engine with DCEVM.
• As an alternative engine into a Java installation, which won't affect the standard behavior of the JVM.

If you install DCEVM as an alternative engine, you can enable it by passing the-XXaltjvm=dcevm command line option to the java command along with the other options, like:

java -XXaltjvm=dcevm -Xmx500m -jar application.jar

I was usually successful with installing DCEVM as an alternative engine, which is less intrusive and very transparent. The DCEVM engine can then be enabled by a command line option only if you want it and you can have the same Java installation for both running third-party Java programs and development. The second option of replacing the current VM engine with DCVEM is convenient if you can't pass additional command line arguments to the Java program. In that case, I recommend using a separate Java installation to replace the default engine by DCEVM and use it only during development.

The second option for replacing the current VM engine with DCVEM is convenient if you can't pass additional command line arguments to the Java program. In that case, I recommend using a separate Java installation to replace the default engine by DCEVM and use it only during development.

Configure the IDE to Use HotswapAgent

In order to enable the HotswapAgent, it has to be passed to the Java program as an agent, via the  -javaagent command line parameter. Then you have to pass additional parameters to enable the debug mode. Before configuring the IDE, I'll explain how to start an application from command line, which is essentially what you need to configure in any IDE.

First, download the HotswapAgent JAR to some shared location. The JAR file will remain there and will be referenced by the -javaagent command line parameter. Additionally, we'll enable remote debugging on port 9009, with suspend=n so that the application doesn't wait for the debugger to be attached. We can then attach a debugger at any time we want to update the application with code changes. This is an example of the command line to start an application with the HotswapAgent JAR located in /development/hotswap-agent.jar:

java -XXaltjvm=dcevm -javaagent:/development/hotswap-agent.jar \
  -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=9009 \
  -jar application.jar

If you haven't installed DCEVM as an alternative JVM but replaced the default JVM engine, you should omit the -XXaltjvm=dcevm argument.

To configure HotswapAgent in your IDE, you have to do the following steps:

1. Make sure that the IDE can apply your code changes via the debugger. In most IDEs, this means that:
   • Automatic compile on saving is turned on.
   • Compiled classes are automatically replaced in the running application if it's attached to the IDE via the debug interface.
2. Make sure that the IDE uses the Java installation with the DCEVM engine.
   • If DCEVM was installed as an alternative engine, the IDE has to pass the -XXaltjvm=dcevm argument when starting the application in debug mode.
3. Turn off any restart/redeployment of the application on code change (this applies mostly when using application servers via an IDE server plugin).

Detailed instructions how to do it in major Java IDEs can be found on the HotswapAgent Wiki.

Using HotswapAgent With Payara Server

Some frameworks or application servers require additional configuration. This is mostly because the hotswap-agent.jar has to be added to the classpath and the agent isn't able to modify the classloader to add the required classes automatically, or the framework or server spawns additional JVM processes and has to be configured to use a JVM with DCEVM.

To use HotswapAgent with DCEVM while developing applications with Payara Server, you need to make the following changes:

1. Copy the hotswap -agent.jar  into the lib/ext folder in the Payara Server’s domain directory. If you’re using the default  domain1 domain, it would be glassfish/domains/domain1/lib/ext/hotswap-agent.jar (this is required to add HotswapAgent JAR to the server’s classpath, at least until HotswapAgent can do it automatically in Payara Server).
2. Point Payara Server to the Java installation with the DCEVM engine, if it’s not the default system installation.
   • Open the glassfish/config/asenv.conf file (or  glassfish/config/asenv.bat on Windows) and specify AS_JAVA environment variable to point to the Java installation.
3. Modify the JVM options:
   • Remove any  -client or -server JVM options (they would prevent using DCEVM as an alternative engine even if the-XXaltjvmoption is present).
   • Add the -XXaltjvm option.
   • Add the -javaagentoption with the path to the hotswap-agent.jar, e.g. -javaagent:/development/hotswap-agent.jar. It can reference the same JAR file which is in the lib/ext folder, even using a relative reference to the domain folder, like this: -javaagent:${com.sun.aas.instanceRoot}/lib/ext/hotswap-agent.jar 

If starting the Payara Server from an IDE, you may have to apply steps 2 and 3 in the configuration of your IDE, because the Payara Server plugin in most IDEs bypasses the standard Payara Server configuration and starts Payara Server with the Java runtime and command line parameters specified in the IDE. Mind that in that case, you have to use the full path to the hotswap-agent.jar and avoid using the ${com.sun.aas.instanceRoot} variable.

In the IDE, you should also disable automatic redeployment of the application on code change. Most IDE plugins do that by default because under normal circumstances, it's the only reliable way to change/update the application to reflect code changes. As with HotSwapAgent and DCEVM, the usual class reloading is enough, automatic redeploy isn't necessary and should be disabled.

Using HotswapAgent With Payara Micro

Payara Micro is an application runtime that, unlike application servers, is packaged as a single executable JAR file and can be started as such. It deploys applications passed as command line parameters, within the same JVM process. Therefore it's very easy to start it with the HotswapAgent in the same way as any other executable JAR:

java -XXaltjvm=dcevm -javaagent:/development/hotswap-agent.jar \
  -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=9009 \
  -jar payara-micro.jar --deploy application-war

After it's started like this, it listens on port 9009 for debugger requests and any IDE can attach its debugger to it.

The web application is deployed from an exploded directory called application-war  (not to be confused with a war file package) so that changes in resources like XML or JSF pages are also picked up automatically. Most IDEs support building a web application as an exploded directory. Maven also stages the application in a directory in the target folder before creating the WAR file and you can deploy your application from that directory using Payara Micro.

Summary: Using HotswapAgent in Netbeans With Payara Server

I'll quickly summarize the steps required to get HotswapAgent running with Payara Server from the Netbeans IDE.

Install DCEVM

• Use the DCEVM installer to install DCEVM as an alternative VM into a Java installation (you may need to run the installer as administrator)

Configure Payara Server

• Download the HotswapAgent JAR into the  lib/ext folder in the Payara Server’s domain directory as lib/ext/hotswap-agent.jar

• modify the JVM options:
  • remove any -client or-server JVM options.
  • add the-XXaltjvm option.
  • add the-javaagent:${com.sun.aas.instanceRoot}/lib/ext/hotswap-agent.jar   option.

Configure Netbeans

• In Netbeans, open the configuration of the Payara Server service.
  • Ensure that the Java installation with the DCEVM is selected as the Java Platform.
  • There's no way to configure JVM options - the plugin reads the standard Payara Server configuration which we modified earlier.
• Open the project properties
  • In Build -> Compile, ensure that the Compile On Save option is enabled.
  • In Run, ensure that the Deploy on Save option is disabled.
• In Netbeans Options (Tools -> Options), in Java -> Java Debugger, ensure that Apply code changes after save is enabled.

Now, you can debug the application in a standard way from within Netbeans. The IDE will automatically compile all classes, update them in the server. It will also copy all changed resources into an exploded directory which it used to deploy the application so that these resources are refreshed too because Payara Server monitors them for changes.

Summary: Using HotswapAgent in Netbeans with Payara Micro

The following steps will get you to get HotswapAgent running with Payara Micro and the Netbeans IDE:

java -XXaltjvm=dcevm -javaagent:hotswap-agent.jar \
  -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=9009 \
  -jar payara-micro.jar --deploy application-war