RAP Deployment - Part 2: Deploying your application as a .war file

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:\temp\eclipse\plugins). 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 script\webappBuilder.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:
   
   • build\rapdemo\WEB-INF\eclipse\configuration
   • build\rapdemo\WEB-INF\eclipse\features
   • build\rapdemo\WEB-INF\eclipse\plugins
   • build\rapdemo\WEB-INF\eclipse\.eclipseproduct
   • build\rapdemo\WEB-INF\eclipse\launch.ini
   • build\rapdemo\WEB-INF\lib\servletbridge.jar
   • build\rapdemo\WEB-INF\web.xml
     
     
9. Open the Equinox config.ini file (in build\rapdemo\WEB-INF\eclipse\configuration). 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@start
   
   
   At 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:\temp\workspace\calc.ui.rap.war.feature\build\rapdemo>unzip -l calc.war | head
    
    Archive:  calc.war
    Length     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 used 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 tomcat\work\Catalina\localhost\calc\eclipse\workspace\.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 :-P. The command line arguments for our app are defined in the file templates\WEB-INF\web.xml. Remove or comment out the following lines:
    
    <init-param>
    <param-name>commandline</param-name>
    <param-value>-console</param-value>
    </init-param>
    

Happy deploying!