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.2.1</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¶

Using relative paths with rebel.xml configuration files requires that all team members agree upon a reference directory (e.g. the project root directory or a directory some levels above it). This also requires defining the absolute path to the reference directory for the environment in the jrebel.properties file.

As of JRebel Maven plugin version 1.1.8, generating rebel.xml files with relative paths requires defining the variables <rootPath> and <rootRelativePath> in the parent project’s pom.xml. Note that <rootRelativePath> is not supported in earlier JRebel Maven plugin versions.

<rootPath> should define an absolute path of the reference directory. The best option is to use the project root directory or the IDE workspace directory one level above it. As this directory is resolved by JRebel during runtime, it has to be set to a metavariable name in pom.xml instead of the directory path itself. Every developer using this rebel.xml has to define this variable in their jrebel.properties using the absolute paths applicable for the local machine.
<rootRelativePath> should define the relative path from the Maven module’s parent directory to the absolute reference directory (the directory pointed to by the <rootPath>).
- When <rootPath> is pointing to the Maven parent module’s directory, use <rootRelativePath>.</rootRelativePath>.
- When <rootPath> is pointing to the IDE workspace directory one level above Maven parent module’s directory, use <rootRelativePath>..</rootRelativePath>.
- Other reference directories can be used. Keep in mind that the relative paths to the reference directory need to remain the same in all developer machines.

Sample configuration¶

For example: Eclipse workspace is located in /Users/john/eclipse-ws/. A multi-module Maven project that should be configured with relative path rebel.xml files is located in the folder /Users/john/eclipse-ws/myproject.

Define the following in the root pom.xml (/Users/john/eclipse-ws/myproject/pom.xml):

<rootPath>$$my.workspace.path</rootPath>
<rootRelativePath>..</rootRelativePath>

The JRebel Maven plugin will generate the following rebel.xml for a JAR sub-module myproject/module1 with this configuration:

<?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.path}\myproject\module1\target\classes"/>
  </classpath>

</application>

To use this configuration, define the absolute path to your reference point folder in jrebel.properties using the meta-variable defined above: my.workspace.path=/Users/john/eclipse-ws.

When another developer checks this project out at C:\projects\myproject, the following should be added to jrebel.properties: my.workspace.path=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.2.1</version>
  <configuration>
    <skip>true</skip>
  </configuration>
</plugin>

Generating rebel-remote.xml files¶

As of JRebel Maven plugin version 1.1.10, you can generate rebel-remote.xml configuration files for JRebel Remote Server support. Simply set the generateRebelRemote option to true to enable this:

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

Having the JRebel Maven plugin generate and package the rebel-remote.xml during the Maven build ensures a consistent generation across multiple environments and eliminates the need to manually have the JRebel IDE plugin generate them for you.

Note

Please use JRebel IDE plugin version 2019.2.0 or newer with this feature to assure that the generated module IDs match with the IDE generated ones.

Advanced configuration¶

<plugin>
  <groupId>org.zeroturnaround</groupId>
  <artifactId>jrebel-maven-plugin</artifactId>
  <version>1.2.1</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.

JRebel Maven plugin¶

When should you use this plugin?¶

Using the JRebel Maven plugin¶

Absolute vs relative paths in rebel.xml files¶

Sample configuration¶

Excluding modules from rebel.xml generation¶

Generating rebel-remote.xml files¶

Advanced configuration¶

Products

Resources

About