JRebel Tutorial: JRebel Remoting with Eclipse IDE

JRebel can be applied in order to update the applications that are deployed to a remote environment from developers workstation. In this tutorial we’re going to walk through JRebel Remoting configuration in Eclipse IDE. The screencast below demonstrates how can JRebel be used to update an application that is deployed in Tomcat running in Amazon micro instance.

There are two parts involved in communication between the developer’s machine and the remote host:

  1. The IDE plugin, that is responsible for uploading the resources into the remote application
  2. The JRebel agent itself that installs an HTTP filter inside of the application for talking to the IDE plugin.

Getting Started

To get started, you need to install JRebel plugin for Eclipse. The plugin is available either from Eclipse Marketplace, or from the update site: http://zeroturnaround.com/update-site/

Server Configuration

To enable JRebel agent for the container that the application is deployed to, you need to add a -javaagent parameter to the JVM arguments list. For that you need to modify your server startup script as described in the reference manual.

By default, Remoting plugin is disabled and therefore you need to add the special JVM argument to activate it. Here’s how the argument list will look like:

-javaagent:/path/to/jrebel.jar -Drebel.remoting_plugin=true

For example, in case of Tomcat, we should set CATALINA_OPTS environment variable when running in Amazon instance as follows:

[ec2-user@aws bin]$ export CATALINA_OPTS="-javaagent:/home/ec2-user/jrebel/jrebel.jar -Drebel.remoting_plugin=true"
[ec2-user@aws bin]$ ./catalina.sh run
Using CATALINA_BASE:   /home/ec2-user/tomcat
Using CATALINA_HOME:   /home/ec2-user/tomcat
Using CATALINA_TMPDIR: /home/ec2-user/tomcat/temp
Using JRE_HOME:        /usr/lib/jvm/jre
Using CLASSPATH:       /home/ec2-user/tomcat/bin/bootstrap.jar:/home/ec2-user/tomcat/bin/tomcat-juli.jar

 #############################################################

 JRebel 5.1.0 (201210161346)
 (c) Copyright ZeroTurnaround OU, Estonia, Tartu.

 Over the last 11 days JRebel prevented
 at least 9 redeploys/restarts saving you about 0.4 hours.

 This product is licensed to ZeroTurnaround (ZeroTurnaround)
 until June 8, 2014

 ...
 #############################################################

 JRebel: A newer version '5.1.1' is available for download 
 JRebel: from http://zeroturnaround.com/software/jrebel/download/

 ...
Dec 11, 2012 10:30:35 PM org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["http-bio-8080"]
Dec 11, 2012 10:30:35 PM org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["ajp-bio-8009"]
Dec 11, 2012 10:30:35 PM org.apache.catalina.startup.Catalina start
INFO: Server startup in 109824 ms

Where do I find jrebel.jar?

JRebel plugin for Eclipse bundles the latest stable version of JRebel agent. The jrebel.jar sits deep inside the Eclipse plugins folder in org.zeroturnaround.eclipse.embedder plugin. It might be too troublesome to find it so there’s always a workaround: you can download the ZIP distribution of JRebel and extract jrebel.jar from the archive.

Where do I find my JRebel license?

If you just applied for evaluation license and activated it with the key via Activation view of the Eclipse plugin, then you probably don’t realize that you actually have a license file. It is stored in {user.home}/.jrebel directory as jrebel.lic file. If you purchased the license and just received the file by email, then you already have.

NB! The license file is required at the remote machine when you use JRebel Remoting feature. The license file should be uploaded to the remote machine to the {user.home}/.jrebel directory of the user which is used to run the application container (e.g. Tomcat).

Application Configuration

There are two configuration files that are required in order for JRebel Remoting feature to work: rebel.xml and rebel-remote.xml.

rebel.xml

Normally, rebel.xml is used in order to map the deployed application to the IDE workspace so that JRebel could monitor the directories specified in the configuration file. In case of remote environment rebel.xml is used to emulate the local file system at the remote machine.

In Eclipse, the configuration file is generated automatically when you enable JRebel nature for the project.

Once JRebel nature is enabled, the plugin generates rebel.xml file and saves it to src/ folder of the project.

The configuration file should end up in your WEB-INF/classes directory in the case of a web module and in the root of the archive in case of JAR dependency or an EJB module. Please see the reference manual for the information on how to generate rebel.xml configuration file.

rebel-remote.xml

Remoting functionality of JRebel specifically requires rebel-remote.xml configuration file to be able to synchronize the local resources from IDE into the remote application. You can generate this configuration file by enabling the “Remoting” feature from the right-click menu for the Eclipse project.

The IDE plugin will automatically generate rebel-remote.xml configuration file to the src/ folder. As in case with rebel.xml, rebel-remote.xml should also be deployed with the application.

rebel-remote.xml sample contents:

<?xml version="1.0" encoding="UTF-8"?>
<rebel-remote>
    <id>myapp</id>
    <publicKey>...</publicKey>
</rebel-remote>
  • id is the unique id of the deployment module, i.e. WAR, JAR or EJB archive.
  • publicKey is the public key for securing the updates for the application. The key pair is generated by the IDE plugin.

Eclipse Configuration

The Eclipse plugin is set up as a project builder. It only works on Java or JavaEE projects as it depends on java classes being compiled first.

Once Remoting feature is enabled, the plugin will notify you that you should set up the URL where the application is deployed to:

By clicking on the provided link in the popup, the plugin opens the JRebel configuration window for the project where you can enter the URL:

Note that the synchronization is enabled by default. It means that the changes will be uploaded automatically once the project is built. If you prefer to control the synchronization process yourself, uncheck Synchronize on build checkbox in the same configuration view.

To start synchronization, you can then use the dedicated button from the toolbar, by selecting which project should be synchronized:

Here’s what the plugin prints to the console view when the synchronization is performed:

Starting synchronization for project: myapp
Connecting to http://ec2.amazonaws.com:8080/myapp/
Uploading resource WebContent/index.jsp
Transaction commited!

Last part – how did it go?

We’re really excited about this feature in JRebel, and we hope you are too. Please let us know about your experience at support@zeroturnaround.com, and thanks!