How to Deploy a RAP Application to a Servlet Container?

The current eclipse build tools and wizards do not directly support building this style of application so for the time being the build can be performed with a series of Ant scripts and resource templates. The org.eclipse.rap.demo.feature shows how to create a WAR that contains the org.eclipse.rap.demo project as RAP application.

Note: As with RCP applications there are a wide variety of possible configurations. What's given in org.eclipse.rap.demo.feature is just one possibility.

As prerequisites we assume that you are familiar with the bundles- and build information section of the Equinox in a Servlet Container document. We also assume that you checked out the servlet bridge and demo feature bundles in your workspace. The link points to a 'team project set' file. In case you haven't done that so far, use File > Import > Team Project Set and enter the location of the downloaded file. Press Finish and the necessary projects will be imported from CVS.

Prepare the build script

Create the build content

Adjust the config.ini

The osgi.bundles property from the config.ini tells Equinox, the OSGi framework, which plug-ins there are in the system. The sole fact that a plug-in is located in the right folder (i.e. eclipse/plugins) doesn't make it known to the running OSGi framework.
For futher information on the config.ini and related configuration options, please read the Eclipse Runtime Options chapter. The latest version can also be viewed from within the IDE. From the menu, chose Help > Help Contents. In the upcoming help window, chose Platform Plugin Developer Guide > Other Reference Information > Runtime Options

After that, pack the WAR of the application build available in the build folder (in our case the content of build/rapdemo). Deploy the WAR to a servlet container to see whether the build was successful :-)


(screenshot shows application running with OSGi-console. See web.xml in the templates directory for more infos on how activating the console)

How to deploy my own application?

To deploy your own application like described above you will have to create your own feature. The feature should contain the same plug-in references as the demo feature (except the demo-plug-in of course!) plus the plug-ins that make up your application. It is important that your plug-ins reference the Servlet API by using the Import-Package directive instead of the Require-Bundle directive. See the MANIFEST.MF of the demo project for an example.

Copy the script and templates folder to the feature and modifiy them according to your project structure. Following the steps above should lead to a fully functional WAR of your application.

Note: If you encounter problems during the build, you may consider to use the PDE-Export (available from the feature editor) before exporting the whole WAR at once. This proved helpful for trouble-shooting as the export may show problem-relevant dialogs that are suppressed in the Ant export.

Note also: Besides the application server log files there also exists an Equinox framework log that can be found under the webapp's work directory, e.g. on Tomcat:

  <tomcat-installation>/work/Catalina/localhost/demo/eclipse/workspace/.metadata/.log
  
In case Equinox isn't able to start at all, you may also look for log files at:
  <tomcat-installation>/work/Catalina/localhost/demo/eclipse/configuration
  

Troubleshooting

You can use the following checklist to find errors when your exported application does not work:

Further hints can be found in the RAP FAQ