# Configuration Manual

1. Global configuration
2. Application configuration

### Global Configuration

JRebel can be configured using Java system properties or the SDK API. To find out more about the configuration API please visit the SDK home and the API Javadoc. A description of available system properties follows.

-Drebel.packages=PACKAGE1,PACKAGE2,...
  This should be set to a comma-separated list of Java packages. JRebel will then only reload classes in those packages and their subpackages. This is mainly used to restrict reloading to only a limited subset of classes, e.g. to improve performance.
-Drebel.packages_include=PACKAGE1,PACKAGE2,...
  This should be set to a comma-separated list of Java packages. JRebel will also reload classes in those packages and their subpackages. This is mainly used to enable JAR file reloading. JRebel will reload classes that are not in the exclude packages and are in an include package. By default all .class classes will be reloaded.
  For example `-Drebel.packages_include=com.mycompany.mypackage,com.thirdparty.theirpackage`.
-Drebel.packages_exclude=PACKAGE1,PACKAGE2,...
  This should be set to a comma-separated list of Java packages. JRebel will not reload classes in those packages and their subpackages. This is mainly used to exclude classes that produce errors with JRebel reloading. JRebel will reload classes that are not in the exclude packages and are in an include package. By default all .class classes will be reloaded.
-Drebel.allow_bytecode_proxy=true
  Enables support for bypassing bytecode-based proxies created with CgLib or Javassist.
-Drebel.load_embedded_plugins=[true|false]
  Controls whether embedded plugins are loaded. Set this to "false" if you're having troubles with embedded plugins.
-Drebel.plugins=jar1,jar2,jar3,...
  Set this to absolute path of the plugin jars to load and enable them. This property overrides the embedded plugins that come with JRebel.
-Drebel.reload_bundles=[true|false]
  Controls whether resource bundle monitoring and reloading is allowed. Set this to false if resource bundle reloading is causing problems.
-Drebel.stats=[true|false]
  Controls whether statistics gathering and display is allowed. Set this to false if you want to disable it (note that statistics is only collected locally and never reported to ZeroTurnaround).
-Drebel.log=true
  Enables debug logging to the jrebel.log file. Use when you are having some problems with the JRebel and you need to get more context.
-Drebel.log.perf=true
  Enables additional logging of the performance statistics to the jrebel.log file. Requires JDK1.5+.
-Drebel.log.trace=true
  Enables trace logging to the jrebel.log file. Generates a very detailed, but extremely big log.
-Drebel.log.stdout=false
  Disables all JRebel output to standard output, e.g. the console.
-Drebel.log.file=FILENAME
  Set to an absolute filename that JRebel should output log to.

### Application Configuration

Starting with JRebel 2.0 `rebel.xml` file must be used for web applications that use packaged deployment (i.e. WARs, JARs and EARs). Instead of the WAR/JAR/EAR file deployed all resources will be picked up from the locations provided in the `rebel.xml`. Also these directories and archives will be monitored for changes.

The `rebel.xml` must be placed in the `WEB-INF/classes` directory of the deployed WAR file, in a root directory of a JAR file or in the root of EJB JAR modules. A `rebel.xml` file should be provided per each module in the application that you want to change on-the-fly.

The contents of the `rebel.xml` is defined by the schema at http://www.zeroturnaround.com/alderaan/rebel-2_0.xsd . There is a full example at the end of this file.

JRebel will expand expressions like "${myProject.root}" in `rebel.xml` to a system property that you can pass to the application container as `-DmyProject.root=c:/myWorkspace/myProject`. This allows to use a single configuration for everyone and then customize it when starting the server.

### Tags reference

- application
- classpath
- dir
- dirset
- jar
- jarset
- war
- web
- link
- include
- exclude

#### application

Top level tag that defines the configuration with classpath, web and war tags.

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <application
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="http://www.zeroturnaround.com"
     xsi:schemaLocation="http://www.zeroturnaround.com/alderaan/rebel-2_0.xsd">
    ...
    </application>

#### classpath

Defines the mounted classpath of the application with nested dir, dirset, jar and jarset elements. The fallback attribute controls if classes and resources are also found from the original application classpath (e.g. `WEB-INF/classes`, `WEB-INF/lib/*.jar`, JAR root, etc).

Attribute | Description | Required
fallback | Values: `all`, `none` and `default` (default). If set to `all` classes and resources will always be found from both the original and mounted classpath. This mode may cause some resources to appear double in the application. If set to `none` classes and resources will only be found from the mounted classpath. This mode requires all classes and resources (including e.g. those in `WEB-INF/lib/*.jar`) to be fully mounted If set to `default` then classes and resources will be found from both original and mounted classpath, but resources present in both will be filtered out. This mode implies that classes and resources in the path that `rebel.xml` is in are fully present in the mounted classpath (e.g. all classes and resources in `WEB-INF/classes` should be mounted if `rebel.xml` is there). | No

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <application
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="http://www.zeroturnaround.com"
     xsi:schemaLocation="http://www.zeroturnaround.com/alderaan/rebel-2_0.xsd">
      <classpath>
     ...
      </classpath>
    </application>

#### dir

Directory on the filesystem that is added to classpath or link. Nested include / exclude tags can be used to limit the files included from the specified directory.

Attribute | Description | Required
name | A full path to a directory on the filesystem. | Yes
includes | Specifies a pattern that directs which resources will be included from the parent. | No
excludes | Specifies a pattern that directs which resources will be excluded from the parent. | No

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <application
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="http://www.zeroturnaround.com"
     xsi:schemaLocation="http://www.zeroturnaround.com/alderaan/rebel-2_0.xsd">
     <classpath>
     <!--
      Add a directory with class files to the classpath. The classes
      can also be excluded or included based on patterns.
      -->
     <dir name="c:\projects\myProject\classes\">
     <!-- Excluding everything from com/yourapp/package1-->
     <exclude name="com/yourapp/package1/**"/>
     <!-- Include the important subpackage of package1-->
     <include name="com/yourapp/package1/important/**"/>
     </dir>
     </classpath>
    </application>

#### dirset

Defines multiple subdirectories of a directory that can be added to classpath. Nested include / exclude tags can be used to limit the subdirectories included from the specified directory.

Attribute | Description | Required
dir | The parent directory from which subdirectories are found. By default all will be added. | Yes
includes | Specifies a pattern that directs which resources will be included from the parent. | No
excludes | Specifies a pattern that directs which resources will be excluded from the parent. | No

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <application
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://www.zeroturnaround.com"
    xsi:schemaLocation="http://www.zeroturnaround.com/alderaan/rebel-2_0.xsd">
     <classpath>
     <!--
     DIRSET enables you to add multiple directories to the classpath
     without specifying them one-by-one. For example if there are multiple
     MAVEN modules with a similar folder structure. The following configuration
     will include all modules from the directory of "c:\projects\project1Root\
     that adhere to the pattern "**\build\classes".
     -->
    <dirset dir="c:\projects\project1Root\">
     <include name="**\build\classes"/>
     </dirset>
    </classpath>
    </application>

#### jar

Defines a JAR file that is added to classpath or link. Nested include / exclude tags can be used to limit the resources included from the specified JAR.

Attribute | Description | Required
name | Full path to a JAR file that is added to the CLASSPATH. | Yes
includes | Specifies a pattern that directs which resources will be included from the parent. | No
excludes | Specifies a pattern that directs which resources will be excluded from the parent. | No

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <application
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://www.zeroturnaround.com"
    xsi:schemaLocation="http://www.zeroturnaround.com/alderaan/rebel-2_0.xsd">
     <classpath>
     <!--
     Adds a JAR file to the classpath. The classes from the
     JAR archive can also be excluded or included based on patterns.
     -->
    <jar name="c:\projects\myProject\3rdpartyLibs\myLibrary.jar">
     <!-- Excluding everything from com/yourapp/package1-->
    <exclude name="com/yourapp/package1/**"/>
     <!-- Include the important subpackage of package1-->
    <include name="com/yourapp/package1/important/**"/>
     </jar>
    </classpath>
    </application>

#### jarset

Defines multiple JAR files to be added to classpath. Nested include / exclude tags can be used to limit the JARS included from the specified directory.

Attribute | Description | Required
dir | JAR files from this directory on the filesystem are added to the CLASSPATH | Yes
includes | Specifies a pattern that directs which resources will be included from the parent. | No
excludes | Specifies a pattern that directs which resources will be excluded from the parent. | No

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <application
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://www.zeroturnaround.com"
    xsi:schemaLocation="http://www.zeroturnaround.com/alderaan/rebel-2_0.xsd">
     <classpath>
     <!--
     JARSET enables you to add multiple JAR files to the classpath without
     specifying them one-by-one. The following example includes JAR files
     from the app/3rd-party-lib directory that don't match the pattern apache*.jar.
     -->
    <jarset dir="app/3rd-party-lib">
     <exclude name="apache*.jar"/>
     </jarset>
    </classpath>
    </application>

#### war

Overrides the WAR file deployed to the container with a exploded directory or a WAR file on the filesystem. Needs to have either dir or file attribute.

Attribute | Description | Required
dir | Path to an exploded WAR directory on the filesystem. Resources and class files will be loaded from this directory. | Yes/No
file | Path to a WAR archive on the filesystem. Resources and class files will be loaded from this file. | Yes/No

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <application
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://www.zeroturnaround.com"
    xsi:schemaLocation="http://www.zeroturnaround.com/alderaan/rebel-2_0.xsd">
     <!--
     WAR tag with FILE attribute specifies the location of the WAR file.
     The contents of this WAR file will have higher priority as compared
     to the web application deployed. All resources in this file will be
     available in the web application just as they would be in the
     deployed WAR file.
     -->
    <war file="c:\projects\myProject\dist\myProject.war" />
    </application>

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <application
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://www.zeroturnaround.com"
    xsi:schemaLocation="http://www.zeroturnaround.com/alderaan/rebel-2_0.xsd">
     <!--
     WAR tag with DIR attribute specifies the location of the exploded
     directory. The contents of this directory will have higher priority
     as compared to the web application deployed to the container. All
     resources in this folder will be available in the web application
     just as they would be in the deployed web application.
     -->
    <war dir="c:\projects\myProject\dist\war" />
    </application>

#### web

Defines separate locations for static resources that can be referenced from the web application. With nested link tags it is possible to map different resources from the filesystem to the web context.

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <application
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://www.zeroturnaround.com"
    xsi:schemaLocation="http://www.zeroturnaround.com/alderaan/rebel-2_0.xsd">
     <!--
     WEB tag defines separate locations for static resources that can be referenced from
     the web application. Directories containing jsp, css, html, gif etc. files. These
     directories can be mapped to arbitrary locations for the web application.
     -->
    <web>
    ...
    </web>
    </application>

#### link

Can be added to web to link a nested dir or jar to the target URI. The mapped resource is made available from servlet context and also via HTTP.

Attribute | Description | Required
target | Mapping target. For example "gfx/" or "js/". | Yes

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <application
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://www.zeroturnaround.com"
    xsi:schemaLocation="http://www.zeroturnaround.com/alderaan/rebel-2_0.xsd">
     <!--
     WEB tag defines separate locations for static resources that can be referenced from
     the web application. Directories containing jsp, css, html, gif etc. files. These
     directories can be mapped to arbitrary locations for the web application.
     -->
    <web>
    <!--
     The location c:\projects\myProject\static\gfx will be accessible to the WEB
     application as http://yourhost/webapp/gfx folder. Adding static resources to
     that location will let you use them from your web application.
     -->
    <link target="gfx/">
     <dir name="c:\projects\myProject\static\gfx"/>
    </link>
    </web>
    </classpath>
    </application>

#### include

This element is used to filter resources in dir, dirset, jar and jarset elements. Resources named by this element will be included in the result.

Attribute | Description | Required
name | Name that will be filtered, can contain wildcards. See example for more information. | Yes

    <dirset dir="c:\projects\project1Root\">
     <exclude name="**\build\classes"/>
    </dirset>
    ...
    <jarset dir="app/3rd-party-lib">
     <exclude name="apache*.jar"/>
    </jarset>
    ...
    <jar name="c:\projects\myProject\3rdpartyLibs\myLibrary.jar">
     <!-- Include all of package1-->
     <include name="com/yourapp/package1/**"/>
     <!-- Except for internal subpackage-->
     <exclude name="com/yourapp/package1/internal/**"/>
    </jar>

#### exclude

This element is used to filter resources in dir, dirset, jar and jarset elements. Resources named by this element will be excluded from the result.

Attribute | Description | Required
name | Name that will be filtered, can contain wildcards. See example from include tag for more information. | Yes

### Example configuration

The following file can be copied to your project and appropriate sections deleted or customized.

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <application
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://www.zeroturnaround.com"
    xsi:schemaLocation="http://www.zeroturnaround.com/alderaan/rebel-2_0.xsd">

     <!--
     Classpath allows you to add DIRECTORIES and JAR files to your classpath. Your
     webapp will see these resources as resources inside the WAR archive or your
     exploded directory.

     The default value of fallback is true. When set to 'false' then if a resources
     is NOT found from the defined directories, it won't be looked for from the
     deployed resources.

     Example. Fallback is set to FALSE and you remove a styles.css file. Even though
     a styles.css file is deployed to the container, it will give a 404 on HTTP request
     or null on ServletContext lookup even though it exists in the deployed archive.

     If set to true, all resources will fallback to the deployed application, this is
     the default behavior.
     -->
    <classpath fallback="default">
     <!--
     Add a directory with class files to the classpath. The classes
     can also be excluded or included based on patterns.
     -->
    <dir name="c:\projects\myProject\classes\">
     <!-- Only include package1 and its subpackages -->
    <include name="com/yourapp/package1/**"/>
     <!-- Except com/yourapp/package1/package2 and its subpackages -->
    <exclude name="com/yourapp/package1/package2/**"/>
     </dir>
    <!--
     Adds a JAR file to the classpath. The classes from the
     JAR archive can also be excluded or included based on patterns.
     -->
    <jar name="c:\projects\myProject\3rdpartyLibs\myLibrary.jar">
     <!-- Only include package1 and its subpackages -->
    <include name="com/yourapp/package1/**"/>
     <!-- Except com/yourapp/package1/package2 and its subpackages -->
    <exclude name="com/yourapp/package1/package2/**"/>
     </jar>
    <!--
     JARSET enables you to add multiple JAR files to the classpath without
     specifying them one-by-one. The following example includes JAR files
     from the c:\projects\3rd-party-lib directory that don't match the pattern apache*.jar.
     -->
    <jarset dir="c:\projects\3rd-party-lib">
     <exclude name="apache*.jar"/>
     </jarset>
    <!--
     DIRSET enables you to add multiple directories to the classpath
     without specifying them one-by-one. For example if there are multiple
     MAVEN modules with a similar folder structure. The following configuration
     will include all modules from the directory of "c:\projects\project1Root\
     that adhere to the pattern "**\build\classes".
     -->
    <dirset dir="c:\projects\project1Root\">
     <exclude name="**\build\classes"/>
     </dirset>
    </classpath>
    <!--
     WAR tag with FILE attribute specifies the location of the WAR file. The contents
     of this WAR file will have higher priority as compared to the web application deployed.
     All resources in this file will be available in the web application just as they
     would be in the deployed WAR file.
     -->
    <war file="c:\projects\myProject\dist\myProject.war" />

     <!--
     WAR tag with DIR attribute specifies the location of the exploded directory. The
     contents of this directory will have higher priority as compared to the web application
     deployed to the container. All resources in this folder will be available in the
     web application just as they would be in the deployed web application.
     -->
    <war dir="c:\projects\myProject\dist\war"/>

     <!--
     WEB tag defines separate locations for static resources that can be referenced from
     the web application. Directories containing jsp, css, html, gif etc. files. These
     directories can be mapped to arbitrary locations for the web application.
     -->
    <web>
    <!--
     The location c:\projects\myProject\static\gfx will be accessible to the WEB
     application as http://yourhost/webapp/gfx folder. Adding static resources to
     that location will let you use them from your web application.
     -->
    <link target="gfx/">
     <dir name="c:\projects\myProject\static\gfx"/>
     </link>
    <!--
     The location c:\projects\jsProject\dist\js will be accessible to the WEB
     application as http://yourhost/webapp/js folder. Adding static resources to
     that location will let you use them from your web application.
     -->
    <link target="js/">
     <dir name="c:\projects\jsProject\dist\js"/>
     </link>
    </web>
    </application>