This post is out of date for RAP 1.2 (Galileo). You’ll find the most recent deployment instructions here.

—

This part is about deploying a RAP application in a .war file. In Part 1 we explored how to deploy a RAP application with Jetty.

Part 2: Deploying a Servlet Bridge .war on an Existing Server

In this part we will create a .war file containing our application, its dependencies, RAP, Equinox and the Servlet Bridge. This allows us to run Equinox (and our application) in a servlet container. The Servlet Bridge plays a central part behind the covers, as it allows the RAP Runtime to handle the HTTP requests originally sent to the application server.

To create the .war file we start with a working example (the org.eclipse.rap.demo.feature from the Eclipse CVS) and create a copy of it (the calc.ui.war.feature). We then follow the WAR Deployment instructions from the RAP Help to produce a .war for the calculator application.

The .war file can then be uploaded to a regular app server — I used Tomcat in the screencast.

Watch the screencast (approx. 11 minutes) or read on for more details.

Below are the steps shown in the screencast. You can download the finished example here (just after step 9). This a different download than the one from part 1!

1. Start with a working example by checking out the org.eclipse.rap.demo.feature from the Eclipse CVS.Step-by-step instructions:
   • Copy this string: :pserver:anonymous@dev.eclipse.org:/cvsroot/technology
   • Open the CVS Repositories View.
   • Right click > Paste Connection.
   • Expand the nodes “:pserver…”, “HEAD” and “org.eclipse.rap” in the tree. Select org.eclipse.rap.demo.feature and choose “Check Out”.
   • You should now have org.eclipse.rap.demo.feature in your workspace.
2. Obtain the servlet bridge.Open the URL below in your Browser and save the contents: http://www.eclipse.org/equinox/server/downloads/servletbridge-anon.psf
   Then use the Team Project Set import wizard to add the projects to your workspace (File > Import > Team Project Set > enter the path to the file you saved > Finish). You should now have these additional projects in your workspace:
   • javax.servlet (v2_4)
   • org.eclipse.equinox.http.registry
   • org.eclipse.equinox.http.servlet
   • org.eclipse.equinox.http.servletbridge
   • org.eclipse.equinox.servletbridge
   • org.eclipse.equinox.servletbridge.feature
3. Import the org.eclipse.update.configurator plug-in from your eclipse installation (not the target!).Choose File > Import > Plug-ins and Fragments. In the “Import From” group uncheck the option “The target platform (as specified in the Preferences”). Under “Plug-in Location” enter the path to your plugins directory (for example: c:tempeclipseplugins). Next. Select org.eclipse.update .configurator. Add. Finish.
4. Make a copy of the org.eclipse.rap.demo.feature and name it calc.ui.war.feature
5. Adjust the copied feature.xml.Change the id to “calc.ui.war.feature“. Change the fields Version, Name and Provider to your liking. Then modify the list of Plug-ins and Fragments: remove org.eclipse.rap.demo; add calc.ui.rap. Save.(Alternatively you can start with an empty list of plug-ins and add: calc.ui.rap and all its dependencies using the Dependency Analysis tool as shown in Part 1. Then add org.eclipse.update.configurator (for auto-discovery of bundles). Then add the org.eclipse.equinox.http.servlet and org.eclipse.equinox.http.servletbridge. At the end you should have 20 plugins in the feature)
6. Adjust the copied ant script under scriptwebappBuilder.xml.
   • Change the servletbridge.dir property to point to the absolute location of the org.eclipse.equinox.servletbridge plugin on your machine. Remember to use ‘/’ as the path delimiter.
   • Change the features property to “calc.ui.war.feature“. This determines which feature the script will export.
   • Save.
7. Configure and run the ant task.
   • Select webappBuilder.xml and open the External Tools Dialog (Run > External Tools > Open External Tools Dialog).
   • Double click on “Ant Build”.
   • Select the new entry (calc.ui.war.feature webappBuilder.xml).
   • In the JRE Tab adjust “Runtime JRE” to “Run in the same JRE as the workspace” (otherwise the script will not be able to use the PDE Ant Task for exporting our feature).
   • Run.
   • You should see a “BUILD SUCCESSFUL” message on the console. Notice that the PDE Export task is still running in the background (progress indicator). Wait until it finishes.
8. Select the calc.ui.war.feature and hit Refresh (F5).You should now have a build directory in that project with the following content:
   • buildrapdemoWEB-INFeclipseconfiguration
   • buildrapdemoWEB-INFeclipsefeatures
   • buildrapdemoWEB-INFeclipseplugins
   • buildrapdemoWEB-INFeclipse.eclipseproduct
   • buildrapdemoWEB-INFeclipselaunch.ini
   • buildrapdemoWEB-INFlibservletbridge.jar
   • buildrapdemoWEB-INFweb.xml
9. Open the Equinox config.ini file (in buildrapdemoWEB-INFeclipseconfiguration). Check that the osgi.bundles attribute has these values:osgi.bundles=org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@start, org.eclipse.equinox.http.servletbridge@start, org.eclipse.equinox.http.registry@startAt this point I skipped the “Adjust the config.ini” file section in the RAP WAR Deployment instructions. From my understanding this is not necessary if the org.eclipse.update.configurator plug-in is part of the .war, since it will auto-discover the other plug-ins. However we need to start the above plug-ins when launching to “bootstrap” our application.
10. Zip the whole WEB-INF directory into a .war file, for example calc.war. Make sure that WEB-INF is included in the archive, like shown in this example:

    C:tempworkspacecalc.ui.rap.war.featurebuildrapdemo>unzip -l calc.war | head
    
    Archive:  calc.warLength     Date   Time    Name--------    ----   ----    ----0  12-06-07 15:32   WEB-INF/0  12-06-07 15:32   WEB-INF/eclipse/0  12-06-07 15:32   WEB-INF/eclipse/.eclipseproduct[...]

11. Deploy calc.war on your webserver. In my example I us
    ed the Manager Webapp that comes with Tomcat.
12. Go to http://yourserver:yourport/calc/rap in your browser. Assuming everything went smoothly you should see the calculator application.
13. Troubleshooting: If you don not see the calculator go to the shell that is running tomcat. Here you should see an “osgi>” prompt. This is the osgi console. Type “ss”. If you have unresolved (=INSTALLED) bundles, you missed some dependencies. Also check the .log file under tomcatworkCatalinalocalhostcalceclipseworkspace.metadata. If you see something other than “Authorization infrastructure (org.eclipse.core.runtime.compatibility.auth) not installed” you probably missed some dependencies. In my case I ignored the aforementioned message because I don’t need that optional plug-in in my deployment.Important Note: For production deployments I recommend disabling the osgi console. For example if you type “exit” on it, you’ll bring down the whole app server . The command line arguments for our app are defined in the file templatesWEB-INFweb.xml. Remove or comment out the following lines:<init-param>
    <param-name>commandline</param-name>
    <param-value>-console</param-value>
    </init-param>

Happy deploying!

Tags: deployment, rap, tips

This post is out of date for RAP 1.2 (Galileo).

—

When it comes to deploying your RAP Application you have two options: you can either put the web server inside the OSGi runtime (Equinox + Jetty + RAP + your app) or you can put the OSGi runtime inside an existing server (.war file with the Servlet Bridge + Equinox + RAP + your app).

I recently spent some time exploring both options and found the process of “getting it right” intimidating (at least the first time). To give you a head start I’ll share my experiences. If you find a simpler way of doing this let me know .

Update 2008/8/11: note that this instructions are NOT accurate for deploying RAP 1.1 with Eclipse 3.4. According to the mailing list there are at least two changes: These projects should not be opened in your workspace: javax.servlet, org.apache.commons.logging, org.eclipse.equinox.http.jetty, org.eclipse.equinox.http.registry, org.eclipse.equinox.http.servlet, org.mortbay.jetty. And you now *have* to use the ConfigIniCreator to create a valid config.ini file. I will schedule some time to do an fully updated re-post of this tutorial in August.

Part 1: Deploy with Jetty inside Equinox

1. Create a feature for your application
2. Add the all dependencies of your application to it (e.g. RAP and all the plug-ins you use)
3. Add the Jetty server to your feature as explained in “Embedding an HTTP server in Equinox“. You ‘ll need these plug-ins:
   • org.eclipse.equinox.http.jetty
   • org.eclipse.equinox.http.servlet
   • org.mortbay.jetty
   • org.apache.commons.logging
   • javax.servlet
   • org.eclipse.equinox.http.registry
4. Export the feature using “File > Export > Deployable features”
5. Copy the Update Configurator (provides auto-discovery of plug-ins) and the Equinox Launcher to the deployment directory, as explained in the “Equinox Quickstart Guide“. You’ll need to copy those files to the locations listed below. You can get the files from your Eclipse installation.
   • your_deployment_direclipse.exe
   • your_deployment_dirpluginsorg.eclipse.equinox.launcher_…jar
   • your_deployment_dirpluginsorg.eclipse.equinox.launcher.win32.win32.x86_… (with sub-directories, this will be named different on other platforms)
   • your_deployment_dirpluginsorg.eclipse.update.configurator_…jar
6. Create the file your_deployment_dir configurationconfig.ini as shown:#bundles to start osgi.bundles=org.eclipse.equinox.common@2:start,org.eclipse.update.configurator@3:start,org.eclipse.rap.ui@4:start,org.eclipse.equinox.http.jetty@4:start# options for the equinox launcher
   # do not run an eclipse application
   eclipse.ignoreApp=true
   # don’t shutdown osgi after exiting (or not running) the application
   osgi.noShutdown=true
   
   # incoming port for the server
   org.osgi.service.http.port=7070
7. Go into your_deployment_dir and launch:eclipse -console
8. Type “ss” on the OSGi console. If you have unresolved (=INSTALLED) bundles, you missed some dependencies. Also check the .log file under your_deployment_dirworkspace.metadata.log. If you see something other than “Authorization infrastructure (org.eclipse.core.runtime.compatibility.auth) not installed” you probably missed some dependencies. In my case I ignored the aforementioned message because I don’t need that optional plug-in in my deployment.
9. Your app should now be reachable under:http://localhost:7070/rap

Come back next week to find out how to deploy this application as a .war file.

Tags: deployment, rap, tips