Better hotswap when remote debugging a JVM

https://blog.payara.fish/using-hotswapagent-to-speed-up-development

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:

Install the DCEVM engine into a Java installation (JRE or JDK)
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
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)
Start the application in debug mode and connect to it via the debugger interface from withing IDE
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.

Hotswap agent blog 1.png

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:

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

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)
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
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