JRebel with Hybris

Follow this guide to get JRebel up and running with Hybris.

Tip

This guide assumes that you have already downloaded and activated JRebel. You can download JRebel here. Head over here for activation instructions.

The steps include:

  • Startup configuration - adding JRebel Agent to your server runtime.

  • Project configuration - creating rebel.xml configuration files to specify which folders JRebel should monitor for changes.


Startup configuration

To enable JRebel for Hybris, the following JVM startup parameter needs to be added to $PLATFORM_HOME/config/local.properties.

Add the following to use the JRebel Agent:

JDK

Startup parameter

Windows 64-bit JDK

tomcat.javaoptions=-agentpath:[c:\path\to]\lib\jrebel64.dll

Windows 32-bit JDK

tomcat.javaoptions=-agentpath:[c:\path\to]\lib\jrebel32.dll

Mac OS X 64-bit JDK

tomcat.javaoptions=-agentpath:[path/to]/lib/libjrebel64.dylib

Mac OS X 32-bit JDK

tomcat.javaoptions=-agentpath:[path/to]/lib/libjrebel32.dylib

Linux 64-bit JDK

tomcat.javaoptions=-agentpath:[path/to]/lib/libjrebel64.so

Linux 32-bit JDK

tomcat.javaoptions=-agentpath:[path/to]/lib/libjrebel32.so

Tip

Run the command ant all after changing the properties file to apply the new configuration!

You can verify that JRebel is started by simply running Hybris:

./hybrisserver.sh run

Look for the following lines in the console log:

2019-04-02 14:23:55 JRebel:  JRebel Agent 2020.1.0 (202001051049)
2019-04-02 14:23:55 JRebel:  (c) Copyright 2007-2020 Perforce Software, Inc.

Project configuration

Configuring most modules

Extensions with web/webroot are deployed as exploded archives to the server. This means that Tomcat reads the classes from web/webroot/WEB-INF/classes for that module on startup.


Exception: configuring the backoffice extensions

Backoffice extensions are different from all other modules, as they are deployed as packaged JAR files. To enable reloading for this scenario, a configuration file called rebel.xml must be provided. rebel.xml will tell JRebel where to look for updated versions of the .class files for this JAR.

Newer versions of Hybris (6.x and later) can automatically generate a suitable rebel.xml for all backoffice extensions. To enable this functionality, open the $PLATFORM_HOME/bin/platform/resources/ant/compiling.xml build script and find this line:

<jar destfile="${ext.@{extname}.path}/resources/backoffice/@{extname}_bof.jar" basedir="${ext.@{extname}.path}/backoffice/classes" excludes="**/rebel.xml"/>

Remove exclusion of rebel.xml configuration files, i.e. replace the line with the following:

<jar destfile="${ext.@{extname}.path}/resources/backoffice/@{extname}_bof.jar" basedir="${ext.@{extname}.path}/backoffice/classes" />

This will make sure that rebel.xml is bundled into the extension JAR file on build.


Exception: configuring backoffice extensions with Hybris 5.x

For older Hybris versions it is necessary to manually add the rebel.xml files. Start by modifying the compiling.xml as described above. Next, do the following for all the backoffice extensions that you want to use with JRebel.

Make sure to replace $EXTENSION_NAME in the snippets below with your actual extension name.

  • Create a rebel.xml file in $EXTENSION_NAME/backoffice/resources with the following content:

    <?xml version="1.0" encoding="UTF-8"?>
    <application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.zeroturnaround.com" xsi:schemaLocation="http://www.zeroturnaround.com http://update.zeroturnaround.com/jrebel/rebel-2_1.xsd">
      <classpath>
        <!-- replace $EXTENSION_NAME below with your actual extension name -->
        <dir name="${HYBRIS_BIN_DIR}/custom/$EXTENSION_NAME/backoffice/classes"/>
      </classpath>
    </application>
    
  • Edit the $EXTENSION_NAME/buildcallbacks.xml file and add the following as a child of the project element:

    <!-- replace $EXTENSION_NAME below with your actual extension name -->
    <macrodef name="$EXTENSION_NAME_before_build">
      <sequential>
        <mkdir dir="${ext.$EXTENSION_NAME.path}/backoffice/classes" />
        <copy file="${ext.$EXTENSION_NAME.path}/backoffice/resources/rebel.xml" todir="${ext.$EXTENSION_NAME.path}/backoffice/classes/" failonerror="false" />
      </sequential>
    </macrodef>
    

Building and reloading changes

After making changes to source files, just recompile and reload the browser. The changed .class files are picked up by JRebel and reloaded on the fly.

  • When recompiling modules from command line with ant build, no changes are required. For backoffice extensions, the build locations should now be mapped by rebel.xml. For other modules, JRebel sees the updated classes in web/webroot/WEB-INF/classes and reloads them.

Tip

If you are modifying just one module, rebuild only the respective module for a faster build time.

  • To recompile in the IDE, set the compile output to where the classes are actually compiled to with ant build:

  • For backoffice extensions, change the IDE compile output path to $PLATFORM_HOME/bin/custom/$EXTENSION_NAME/backoffice/classes.

  • For all other modules, change the IDE compile output path to web/webroot/WEB-INF/classes.

Tip

If you use IntelliJ, the Hybris IntelliJ plugin will make it much easier to properly set up building in the IDE.


Debugging with JRebel

To enable JRebel for Hybris while debugging, the following JVM startup parameters need to be added to $PLATFORM_HOME/config/local.properties. We recommend using the JRebel IDE plugins for the best debugging experience.

  1. Add the following to use the JRebel Agent while debugging:

    JDK

    Startup parameter

    Windows 64-bit JDK

    tomcat.debugjavaoptions=-agentpath:[c:\path\to]\lib\jrebel64.dll

    Windows 32-bit JDK

    tomcat.debugjavaoptions=-agentpath:[c:\path\to]\lib\jrebel32.dll

    Mac OS X 64-bit JDK

    tomcat.debugjavaoptions=-agentpath:[path/to]/lib/libjrebel64.dylib

    Mac OS X 32-bit JDK

    tomcat.debugjavaoptions=-agentpath:[path/to]/lib/libjrebel32.dylib

    Linux 64-bit JDK

    tomcat.debugjavaoptions=-agentpath:[path/to]/lib/libjrebel64.so

    Linux 32-bit JDK

    tomcat.debugjavaoptions=-agentpath:[path/to]/lib/libjrebel32.so

  2. Add the tomcat.debugjavaoptions value to your $PLATFORM_HOME/bin/platform/project.properties file. It should also include -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000, otherwise the JVM will not start in debug mode.

    Example: tomcat.debugjavaoptions=-agentpath:c:\jrebel\lib\jrebel64.dll -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000

Tip

Run the command ant all after changing the properties file to apply the new configuration!

You can verify that JRebel is started by running Hybris with the debug command:

./hybrisserver.sh debug

Look for the following lines in the console log:

2019-04-02 14:23:55 JRebel:  JRebel Agent 2020.1.0 (202001051049)
2019-04-02 14:23:55 JRebel:  (c) Copyright 2007-2020 Perforce Software, Inc.