Develop with HotSwapAgent

Introduction

Goal

Use DCEVM and HotSwapAgent in your development environment to update a running Bloomreach Experience Manager web application when the project source code changes.

Background

Building your web application and redeploying it every time you want to see the effects of the changes you made to your project's source code can be a time consuming process. If you want to speed up this development cycle, then HotSwapAgent is a great tool to make that happen.

Updating a running web application when the project source code changes is made possible with DCEVM and HotSwapAgent. DCEVM realizes hotswap on the JVM level. HotSwapAgent realizes hotswap for Java frameworks (such as Spring & Hibernate) and servlet containers.

Installation

Install DCEVM

1. Make sure you have the latest (OpenJDK or Oracle JVM) 8 JDK supported by DCEVM found on the DCEVM releases page.
2. Download the installer JAR matching your JDK version.
3. DCEVM will modify the JDK installation. To keep your original JDK you can make a copy of the JDK. For example:

    cp -rf jdk1.8.0_181 jdk1.8.0_181_dcevm

4. Run the installer. For example:

   java -jar DCEVM-8u181-installer.jar

5. Select the JDK folder to use and click Install DCEVM as altjvm. This will allow switching between the normal JDK and the alternative using a parameter.

Alternatively, follow the Install section on http://hotswapagent.org/mydoc_quickstart.html.

Install HotSwapAgent

1. Download latest release of HotSwapAgent to your local filesystem. The example in step two loads the JAR from the project root folder so to follow this step put it in the project root folder.

2. Open your Bloomreach Experience Manager project's root pom.xml, find the cargo.run profile, and set the <javaagent> property to the path to the HotSwapAgent JAR. The example below assumes the JAR is in the project root folder:

       <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

HotSwapAgent is configured through a hotswap-agent.properties file. This file must be available on the classpath. To hotswap a webapp, add the configuration to the webapp classpath by putting it in /src/main/resources/hotswap-agent.properties.

Multiple configuration files can be used for different webapps. For site components development, use site/components/src/main/resources/hotswap-agent.properties.

The most important properties to configure are extraClasspath and watchResources as they specify what must be hot-swapped. For proper configuration, read the documentation about:

• The default annotated hotswap-agent.properties
• Configuration of hotswap-agent.properties

An example in a typical Bloomreach Experience Manager project is below:

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

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

Use Maven Properties in the Hotswap Properties Files

You can define properties in the project POM and use those in the hotswap configuration files as ${..}. To do this, the configuration files must be in a resource folder and filtering must be enabled. If not already in the build section of the relevant module POM, add the resource definition as:

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

Trigger Hot-swap Reloads

To hot-swap the classes and resources you have two options:

1. Use the internal Hotswapper to watch for changed class files on the watchResources path and reload class definitions in the running application:
   • Add autoHotswap=true to hotswap-agent.properties.
2. Launch a debugging session from your IDE and use the standard hotswap feature:
   • Internally this uses the Java Instrumentation API to reload class bytecode. If you need to use the JPDA API, instead, specify autoHotswap.port with the JPDA port.

If everything is set up correctly, changes in your Java classes will trigger a hotswap and you'll see a log message similar to the one below:

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