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:

2016-11-15 12:01:51 JRebel:  JRebel Agent 7.0.0 (201611081555)
2016-11-15 12:01:51 JRebel:  (c) Copyright ZeroTurnaround AS, Estonia, Tartu.

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:

2016-11-15 12:01:51 JRebel:  JRebel Agent 7.0.0 (201611081555)
2016-11-15 12:01:51 JRebel:  (c) Copyright ZeroTurnaround AS, Estonia, Tartu.