Develop with HotSwapAgent

This page explains how to use DCEVM and HotSwapAgent to enable hot-swapping of code changes in a running Bloomreach Content web application. This documentation covers integration steps relevant to XM projects. Bloomreach maintains this guide on a best-effort basis and cannot guarantee alignment with the latest versions of DCEVM or HotSwapAgent. For the most current instructions, refer to the official documentation for DCEVM and HotSwapAgent.

Introduction

Goal

Enable hot-swapping in your development environment so that changes to your Bloomreach Content project source code are reflected immediately in the running web application, without requiring a full rebuild or redeployment.

Background

Rebuilding and redeploying your web application for every code change slows down development. DCEVM and HotSwapAgent together allow you to update class definitions and resources in a running JVM, reducing feedback time during development.

DCEVM (Dynamic Code Evolution VM) extends the JVM to support enhanced class redefinition.
HotSwapAgent integrates with Java frameworks (such as Spring and Hibernate) and servlet containers to reload classes and resources at runtime.

Installation

Install DCEVM

Download the latest supported JDK 8 (OpenJDK or Oracle) version from the DCEVM releases page.
Download the DCEVM installer JAR that matches your JDK version.
DCEVM modifies the JDK installation. To avoid altering your original JDK, create a copy:
```
cp -rf jdk1.8.0_181 jdk1.8.0_181_dcevm
```
Run the DCEVM installer:
```
java -jar DCEVM-8u181-installer.jar
```
When prompted, select the JDK directory and choose Install DCEVM as altjvm. This allows you to switch between the standard and DCEVM-enabled JVM using a command-line parameter.

For additional installation details, see the HotSwapAgent quickstart guide.

Install HotSwapAgent

Download the latest HotSwapAgent release and save the JAR file to your local filesystem. To follow the example below, place it in your project root directory.

Edit your project's root pom.xml. In the cargo.run Maven profile, set the <javaagent> property to reference the HotSwapAgent JAR. For example:

<profile>
  <id>cargo.run</id>
  <properties>
    <javaagent>-XXaltjvm=dcevm -javaagent:${basedir}/hotswap-agent-1.3.0.jar</javaagent>
    <!-- ... -->
  </properties>
  <!-- ... -->
</profile>

Configure a Project for Hotswap

hotswap-agent.properties

Configure HotSwapAgent using a hotswap-agent.properties file. This file must be available on the classpath. To enable hot-swapping for a web application, add the file to the webapp's classpath, typically at /src/main/resources/hotswap-agent.properties.

For site component development, place the file at site/components/src/main/resources/hotswap-agent.properties.

Key properties to configure include:

extraClasspath: Specifies additional classpath entries to monitor.
watchResources: Defines which resource directories to watch for changes.

Refer to the following resources for detailed configuration options:

Example configuration for a typical Bloomreach Content project:

site/components/src/main/resources/hotswap-agent.properties

extraClasspath=${basedir}/target/classes
watchResources=${basedir}/src/main/webapp
autoHotswap=true

Note: Add hotswap-agent.properties to your .gitignore file to ensure it remains local to your development environment and is not committed to version control or deployed to production.

Use Maven Properties in Hotswap Properties Files

You can reference Maven properties in your hotswap configuration files using ${...} syntax. To enable this, the configuration files must reside in a resource directory with filtering enabled. If not already present, add the following resource definition to the relevant module's pom.xml:

<build>
  ...
  <resources>
    <resource>
      <directory>src/main/resources</directory>
      <filtering>true</filtering>
    </resource>
  </resources>
  ...
</build>

Trigger Hot-swap Reloads

You can trigger hot-swapping of classes and resources in two ways:

Automatic hotswap:
Enable automatic detection of changes by setting autoHotswap=true in hotswap-agent.properties. HotSwapAgent will monitor the watchResources path and reload changed classes in the running application.
IDE debugging session:
Start a debugging session from your IDE and use the standard Java hotswap feature. This uses the Java Instrumentation API to reload class bytecode. If you need to use the JPDA API, specify the autoHotswap.port property with the appropriate JPDA port.

When configured correctly, modifying and saving a Java class will trigger a hotswap. You should see a log message similar to:

HOTSWAP AGENT: 09:49:39.978 RELOAD (org.hotswap.agent.config.PluginManager) - Reloading classes [org.example.components.MyComponent] (autoHotswap)