JRebel Maven plugin

The JRebel Maven plugin is designed to generate the rebel.xml configuration file for your projects.

Tip

When using a JRebel IDE plugin, it is recommended to generate rebel.xml using the IDE plugin. Generating rebel.xml using the JRebel Maven plugin is intended for situations when generation using the IDE plugin is not available.


Download

Download the JRebel Maven plugin at GitHub: https://github.com/zeroturnaround/maven-jrebel-plugin. The source is available under Apache License 2.0.


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>
      <fallback>default</fallback>
      <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>
          <!--
            An absolute path is used here.
           -->
          <jar>C:\projects\myProject\3rdpartyLibs\myLibrary.jar</jar>
        </resource>
        <resource>
          <jarset>app/3rd-party-lib</jarset>
          <excludes>
            <exclude>apache*.jar</exclude>
          </excludes>
        </resource>
        <resource>
          <dirset>C:\projects\project1Root\</dirset>
          <excludes>
            <exclude>**\build\classes</exclude>
          </excludes>
        </resource>
      </resources>
    </classpath>

    <war>
      <path>C:\projects\myProject\dist\myProject.war</path>
    </war>

    <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 - default is false
      Required if the resource directories are to be added to rebel.xml
    -->
    <addResourcesDirToRebelXml>true</addResourcesDirToRebelXml>


    <!--
      alwaysGenerate - default is false
      If 'false' - rebel.xml is generated if timestamps of pom.xml and the current rebel.xml file are not equal.
      If 'true' - rebel.xml will always be generated
    -->
    <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.