RAP Deployment - Part 1: Deploying your application with Jetty

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 ;-).


Part 1: Deploy with Jetty inside Equinox

This is the same technique used by the RAP launcher to start your application when you launch it from inside Eclipse (a.k.a "self-hosting" deployment). We will create a set of plug-ins containing Equinox (OSGi)pl, Jetty, RAP, your application and the Equinox launcher.

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

Below are the steps shown in the screencast. You can also download the calculator's source code here.

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_dir\eclipse.exe
   • your_deployment_dir\plugins\org.eclipse.equinox.launcher_...jar
   • your_deployment_dir\plugins\org.eclipse.equinox.launcher.win32.win32.x86_... (with sub-directories, this will be named different on other platforms)
   • your_deployment_dir\plugins\org.eclipse.update.configurator_...jar


6. Create the file your_deployment_dir\configuration\config.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_dir\workspace\.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.

RAP at a DemoCamp near you?

A series of Eclipse DemoCamps are currently being organized by Eclipse enthusiasts around the world. These events are an opportunity to showcase / learn about cool stuff build by the Eclipse community and to meet other Eclipse enthusiasts in an informal setting.

If you are interested in the Rich Ajax Platform (RAP) consider attending one of the following events - all of which have a RAP-related demo:

• Dec 6th, Karlsruhe, Germany, 16:00-20:00; Location: Innoopract GmbH, Stephanienstr. 20 — Benjamin Muskalla, RCP goes Web 2.0 - The Rich Ajax Platform
  
• Dec 7th, Stuttgart, Germany, 19:00; Location: Café Stella, Hauptstätter Strasse 57 — Innoopract will present the Rich Ajax Platform and talk about the technology used
• Dec 8th (tentative), Austin, USA, @noon; Location: North by Northwest Restaurant and Brewery — Chris Aniszczyk, An Introduction to the Rich Ajax Platform (RAP)
• Dec 10th, Portland, USA, 19:00-21:00+; Location: McMenamins Kennedy School — Elias Volanakis, Java-based web-apps with the Rich Ajax Platform - The DemoCamp is happening, but I won't be able to make it.

Be sure to check the wiki pages shortly before for each event, as the details may change.

Image: (c) Copyright 2003, RILHADKOA/photocase.de

How to Embed a RAP Application in a Web Page

A slightly overlooked aspect of RAP Applications is that they do *not* have to take the whole page in your browser. Instead they can also be embedded into an existing web page. The calculator example below is embedded into this blog post and is fully usable. My pet-term for such an application is "RAPplet" - kinda like an applet but without the need for a JVM in the browser.

Embedding a RAP Application in a Web Page

A straightforward iframe element will do the trick, as shown in the snippet below:

<iframe src="http://rap.eclipse.org/maildemo/rap?startup=maildemo" width="400" height="400" frameborder="0" name="maildemo"> <p>Sorry your browser does not support iframes.</p> </iframe>

Happy hacking,
Elias.

Hiding the Window in RAP Applications

One of the frequently asked questions while showing RAP is "how can I hide the window"? Personally, I also find the window-in-a-window metaphor (shown above) somewhat confusing and unusual for a browser based application. Fortunately it is really easy to take care of that by configuring the Shell widget associated with that window, as explained in the rest of the article.


Maximized Window with No Title

To get the result shown above we need to apply the following changes to our WorkbenchWindowAdvisor implementation:

1. we use the style-bit SWT.NO_TRIM before creating the Shell. This will remove the title-bar, the minimize/maximize/close buttons and the ability for manually resizing the window.
   
   
2. we overwrite the WorkbenchWindowAdvisor.postWindowCreate() method. Here we set the state of the Shell to maximized.
   
   
3. optional: depending on the requirements and complexity of our application it may be desirable to hide the menu bar by calling getWindowConfigurer().setShowMenuBar( false ). This is usually a good choice for small applications where the menu bar may not be needed.
   
   

   public class ApplicationWorkbenchWindowAdvisor extends WorkbenchWindowAdvisor { // ... public void preWindowOpen() { // ... getWindowConfigurer().setShellStyle( SWT.NO_TRIM ); getWindowConfigurer().setShowMenuBar( false ); } public void postWindowCreate() { Shell shell = getWindowConfigurer().getWindow().getShell(); shell.setMaximized( true ); } }

Maximized Window with Plain Title

This is a slight variation of the previous example. We have kept the window maximized but added a title bar. Note that the title bar is missing the usual minimize / maximize / close buttons which do not make much sense in a browser-based application that has only a single workbench window. To get the result shown we used SWT.TITLE style-bit instead of SWT.NO_TRIM:

public void preWindowOpen() { // ... getWindowConfigurer().setShellStyle( SWT.TITLE ); }

Note that is it possible to customize the font and colors in the title bar using the RAP Theming extension point (org.eclipse.rap.ui.themes). So if you don't like the blue background you can change it. Theming will be a topic in a future blog post.