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 bytecode, which can be then 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 came across an open source alternative called HotswapAgent,  which has worked very well for me for my personal Java EE projects. In this post, I’m going to write up how I got it running in my IDE and Payara Server.

Getting started with HotswapAgent

HotswapAgent 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 HotswapAgent requires installing an alternative DCEVM engine into your JRE installation, which does a much better job in 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.

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 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 withing 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 use the latest version with my Java installation and never had any issues with it.

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 bahavior 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.

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 -javaagentcommand 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 the 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 process and has to be configured to use a JVM with DCEVM.

To use HotswapAgent with DCEVM while developing applications with Payara Server, the following changes are required:

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 file glassfish/config/asenv.conf  (or glassfish/config/asenv.bat  on Windows) and specify that the AS_JAVA  environment variable points 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 --XXaltjvm  option is present)
   • add the  --XXaltjvm  option
   • add the  -javaagent option 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 Payara Server from IDE, you may have to apply the step 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 update the application to reflect code changes. Since 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
  • you can also force applying code changes manually with the Apply Code Changes button in the debug toolbar while debugging

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:

• Install the DCEVM as an alternative VM (the same step as for Payara Server)
• In NetBeans, open the project properties
  • in Build -> Compile, ensure that the Compile On Save option is enabled
• In NetBeans Options (Tools -> Options), in Java -> Java Debugger, ensure that Apply code changes after save is enabled
  • you can also force applying code changes manually with the Apply Code Changes button in the debug toolbar while debugging
• Find out where NetBeans outputs the exploded directory of your application (before it packages it as a WAR file)
  • for maven projects, it’s in the  target  folder and has the same name as the final WAR file, without the WAR extension
• Download the HotswapAgent JAR into the same folder that contains your exploded application
• Run the application from the exploded directory, with the following command line (assuming that the exploded application directory is called application-war  and that payara-micro.jar is in the same folder):

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

• Attach NetBeans debugger to the application – menu Debug -> Attach Debugger, use the port 9009 as the debug port