JRebel Maven plugin

When should you use this plugin?

To enable JRebel for a project, you need to add the rebel.xml configuration file to it. The rebel.xml configuration file has to be added to the deployed WAR or JAR archive. This will let the JRebel agent know which workspace paths to monitor for class and resource updates.

The purpose of the JRebel Maven plugin is to generate the rebel.xml file for your project during the Maven build.

When using a JRebel IDE plugin, it is recommended to generate rebel.xml files using the IDE plugin. If you do so, there is no need to use the JRebel Maven plugin. Generating rebel.xml using the JRebel Maven plugin is intended for situations when generation using the IDE plugin is not available or produces inaccurate results.

Refer to application configuration using rebel.xml for details on rebel.xml file format.


Using the JRebel Maven plugin

In case of Maven projects – especially in case of multi-module projects – it is handy to use JRebel Maven plugin for generating the rebel.xml configuration file(s). Add the following snippet to your parent pom.xml. The rebel.xml configuration file will be generated for each individual sub-module of your Maven project.

<plugin>
  <groupId>org.zeroturnaround</groupId>
  <artifactId>jrebel-maven-plugin</artifactId>
  <version>1.1.7</version>
  <executions>
    <execution>
      <id>generate-rebel-xml</id>
      <phase>process-resources</phase>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>

This will automatically generate the JRebel configuration file rebel.xml on every build. If you just want to generate the rebel.xml, run:

mvn jrebel:generate

You can specify the target folder with the -Drebel.xml.dir=OUTPUT_DIRECTORY parameter (by default, OUTPUT_DIRECTORY is set to target/classes). Adding -Drebel.generate.show=true will print out generated rebel.xml at info level, so you can immediately see what was generated.


Absolute vs relative paths in rebel.xml files

Let us assume that you have a project with the following structure in the folder C:\projects\:

my-maven-project1
  \my-jar1
  \my-war1

The generated rebel.xml files contain absolute paths to your workspace by default. This is the simplest option when every developer builds the project in his own machine and generates rebel.xml files with absolute paths to his workspace.

The generated rebel.xml for module my-jar1 for this example could contain:

<?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>
    <dir name="C:\projects\my-maven-project1\my-jar1\target\classes"/>
  </classpath>

</application>

However, if you want to commit rebel.xml files into SCM and share them between developers, you should use relative paths and make your rebel.xml files configurable with a custom property. To do this, you can make the workspace root folder a configurable custom variable. All paths in rebel.xml files would then be defined as relative paths with respect to the workspace root.

  • rootPath – The root folder which will be made configurable using the custom property. Set to the name of the custom property you want to use.
  • relativePath – relative path from module’s directory to the rootPath folder. Usually a number of directories up (../../).

In the current example, the following configuration could be used:

<configuration>
  <!--
    relativePath defines the relative path from child module's folder up to rootPath folder.
    In the current example, workspace root is 2 directories up from the jar/war modules.
  -->
  <relativePath>../../</relativePath>

  <!--
    Specify a custom property name for specifying the root directory (note the double '$').
    Set the property in JRebel configuration. JRebel will replace it at runtime.
  -->
  <rootPath>$${my.workspace.root}</rootPath>
</configuration>

This generates the following rebel.xml file for module my-jar1:

<?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>
    <dir name="${my.workspace.root}\my-maven-project1\my-jar1\target\classes"/>
  </classpath>

</application>

This rebel.xml no longer contains absolute paths and can be shared between developers via SCM. In order to use it, each developer needs to define the my.workspace.root variable in JRebel configuration or set it via a JVM flag. In this particular environment, the developer would use -Dmy.workspace.root=C:/projects/.


Excluding modules from rebel.xml generation

When working with multiple modules in a single project, you can choose to skip generating rebel.xml for specific modules. Simply add the following to their pom.xml:

<plugin>
  <groupId>org.zeroturnaround</groupId>
  <artifactId>jrebel-maven-plugin</artifactId>
  <version>1.1.7</version>
  <configuration>
    <skip>true</skip>
  </configuration>
</plugin>

Advanced configuration

<plugin>
  <groupId>org.zeroturnaround</groupId>
  <artifactId>jrebel-maven-plugin</artifactId>
  <version>1.1.7</version>
  <configuration>
    <!--
     If your project uses custom packaging that is not recognized
     set this to jar or war.
     -->
    <packaging>war</packaging>
    <classpath>
      <resources>
        <resource>
          <!-- A relative path. -->
          <directory>target/special-classes </directory>
          <!--
            You may use includes and excludes as with any other
            resource.
          -->
          <includes>
            <include>com/yourapp/include/package1/**</include>
            <include>com/yourapp/include/package2/**</include>
          </includes>
          <excludes>
            <exclude>com/yourapp/exclude/package1/**</exclude>
            <exclude>com/yourapp/exclude/package2/**</exclude>
          </excludes>
        </resource>
        <resource>
          <!--
            Empty resource element marks default configuration. By
            default it is placed first in generated configuration.
          -->
        </resource>
        <resource>
          <dirset>C:\projects\project1Root\</dirset>
          <excludes>
            <exclude>**\build\classes</exclude>
          </excludes>
        </resource>
      </resources>
    </classpath>

    <web>
      <resources>
        <resource>
          <target>gfx/</target>
          <directory>C:\projects\myProject\static\gfx</directory>
        </resource>
        <resource>
          <!--
            Empty resource element marks default configuration. By
            default it is placed first in generated configuration.
          -->
        </resource>
      </resources>
    </web>

    <!--
      addResourcesDirToRebelXml - Defines whether resource directories will be added to rebel.xml.
      It is more recommended to map target/classes folder instead and rely on IDE or Maven to update resources under target/classes.
      Defaults to 'false'.
    -->
    <addResourcesDirToRebelXml>true</addResourcesDirToRebelXml>


    <!--
      alwaysGenerate - If true, rebel.xml will be re-generated even if the existing rebel.xml is newer than project's pom.xml.
      Defaults to 'false'.
    -->
    <alwaysGenerate>true</alwaysGenerate>

  </configuration>
</plugin>

You can also leverage build profiles in order to keep the JRebel configuration separate from the main configuration.

<profiles>
  <profile>
    <id>jrebel</id>
    <build>
      <plugins>
        <plugin>
          <groupId>org.zeroturnaround</groupId>
          <artifactId>jrebel-maven-plugin</artifactId>
          <executions>
            <execution>
              <id>generate-rebel-xml</id>
              <phase>process-resources</phase>
              <goals>
                <goal>generate</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

Executing the example above with the command mvn -Pjrebel clean package will trigger JRebel plugin to generate the rebel.xml file.