My first steps with Eclipse RAP [step7]

In [step6] we have seen how to manage UI with SWT Java code (no need to code Javascript). When I started « My first steps with Eclipse RAP » articles, I used Eclipse Helios which provides RAP 1.3. Since June 2011 Eclipse Indigo has been released and provides RAP (runtime and tooling) 1.4 which improves RAP. So, I decided to start over my articles with Eclipse Indigo to benefit from New & Noteworthy of RAP 1.4. In this article we will :

• create an Eclipse RAP with PDE Template « RAP Application with a view » which generates this WEB Application :
  
• create an Eclipse RCP with PDE Template « RCP Application with a view » which generates this Fat client Application :
  

At the end of this article we will compare the two generated RAP and RCP Application code to see the differences between RCP and RAP Application. We will use this comparison in the [step8] to manage RAP (WEB Application) and RCP (Fat client) application with the same code (Single Sourcing).

Prerequisite

Before starting this article, Download Eclipse for RCP and RAP Developers distribution of Eclipse Indigo to benefit from New & Noteworthy of RAP 1.4.

Download

You can download rap_step7.zip which contains the following explained projects :

• sample.application.rap which is the generated Eclipse « RAP Application with a view » explained in this article. To use this project you must unzip it and copy/paste in your Eclipse workspace. Import the Eclipse Plugin Project sample.application.rap with File/Import … menu. Go at General/Existing Projects Into Workspace and select sample.application.rap. This action will import the project in your workspace. It requires you to install RAP Target Platform to avoid compilation problems.
• sample.application.rcp which is the generated Eclipse « RCP Application with a view » explained in this article. To use this project you must unzip it and copy/paste in your Eclipse workspace. Import the Eclipse Plugin Project sample.application.rcp with File/Import … menu. Go at General/Existing Projects Into Workspace and select sample.application.rcp. This action will import the project in your workspace. It requires you to use RCP Target Platform (by default if you create a new Workspace).

RAP Application with a view

In this section we will generate a basic RAP application with a view with the PDE template RAP Application with a view with RAP 1.4. The new RAP tooling will install the RAP Target Platform.

Generate sample.application.rap

RAP application is an Eclipse Plugin. To create a RAP Application we need to create an Eclipse Plugin. To do that, go to the File/New/Other… menu :

Select Plug-in Development/Plug-in Project node :

Click on Next button, the wizard page which gives the choice to create OSGi Bundle or Eclipse Plugin is displayed :

• fill in the Project name field with sample.application.rap.
• select the radio button Eclipse version because we would like to develop RAP application which is an Eclipse Plugin.

Click on Next button, the wizard page which configures the Eclipse Plugin is displayed :

• ID field is the Bundle identifier (Bundle-SymbolicName: sample.application.rap).
• Version field is the Bundle version (Bundle-Version: 1.0.0.qualifier).
• Name field is the Bundle name (Bundle-Name: RAP Application).
• Execution Environment sets the minimal version of the JRE in order to execute the bundle (Bundle-RequiredExecutionEnvironment: JavaSE-1.6).
• you can unselect generate an activator, a Java class that controls the plug-in’s life cycle to avoid generating a Bundle Activator
• select This plug-in will make contributions to the UI because we want to generate RAP application
• select no for Would you like create a rich client application? because we want to generate a RAP application and not RCP application.

Click on Next button, the wizard page which shows several PDE templates is displayed :

Select RAP Application with a view template to generate RAP application with a view. When you select this template, you can notice on the right view a description of this PDE template « This code will need the RAP target to compile. At this step RAP target is not installed, but RAP 1.4 Tooling will propose to install it at the end of this wizard.

Click on Next button, the wizard page which gives you the capability to customize package names, class names of the RAP project to generate is displayed :

Don’t change default values and click on Finish Button to generate the RAP application. This action will generate the RAP Application but before the dialog box « Install RAP Target PLatform » is displayed :

Click on OK button to install RAP Target Platform (in our case RAP 1.4). This action opens a dialog box to download and install the RAP Target Platform :

When generation is done, your workspace looks like this :

RAP Target Platform

If you go to the Window / Preferences menu and Plug-in Development / Target Platform, you can check that RAP Target Platform is installed and selected for the workspace :

Launch RAP Application

In this section we can start the generated RAP Application. To do that open MANIFEST.MF and click on Overview tab.

Click on Launch a RAP Application link on Testing section. This action starts the RAP WEB application by starting Jetty server and open Browser view with the first home page of the WEB Application :

Jetty 404 error

If you use Eclipse Browser, sometimes when you start the RAP Application, you can have a 404 error :

Don’t panic with that, wait a moment and refresh the browser. This errors comes from when the Eclipse browser is refreshed before that RAP Application is started.

Set Jetty Port

In the last screen, RAP application is available with the URL :

http://127.0.0.1:3828/view?startup=sample.application.rap.viewapp but each time you will restart your RAP application, port will change (ex : http://127.0.0.1:3829/view?startup=sample.application.rap.viewapp). To set a port go to the Run/Run Configurations… menu :

Select the RAP Application launch, go to the Main tab and set the port value to 8080 in the Runtime Settings/Manual Port configuration :

Now your RAP application will be available every time with the URL http://127.0.0.1:8080/view?startup=sample.application.rap.viewapp. Next articles will use this URL.

RAP Application – Code

Here I will not explain each component (Java, plugin.xml, MANIFEST.MF…) of the generated RAP Application, because I have already done that in the [step5]. However, there are few differences that it’s interesting to explain :

• RAP 1.4 application can use IApplication instead of IEntryPoint.
• RAP 1.4 tooling generate branding which manage theme (color….) of the RAP Application.
• generate View class : s we have chosen the PDE template which generates a view, the RAP Application generates a View class with SWT Table.

IApplication instead of IEntryPoint

Since RAP 1.4, RAP Application can define the main entry with org.eclipse.equinox.app.IApplication instead of using org.eclipse.rwt.lifecycle.IEntryPoint which is specific RAP interface. This feature is very interesting because RCP Application use too org.eclipse.equinox.app.IApplication and facilitate the Single sourcing.

plugin.xml

Instead of declaring the main entry with RAP entrypoint :

<extension
         point="org.eclipse.rap.ui.entrypoint">
      <entrypoint
            class="sample.application.rap.Application"
            parameter="view"
            id="sample.application.rap.Application">
      </entrypoint>
   </extension>

the RAP Application which is based on RAP 1.4, declares the application like this :

<extension
      id="viewapp"
      point="org.eclipse.core.runtime.applications">
   <application
         thread="main"
         cardinality="singleton-global"
         visible="true">
      <run
            class="sample.application.rap.Application">
     </run>
   </application>
</extension>

Application

The application declaration is based on the sample.application.rap.Application class which looks like this :

package sample.application.rap;

import org.eclipse.equinox.app.IApplication;
import org.eclipse.equinox.app.IApplicationContext;
import org.eclipse.swt.widgets.Display;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.application.WorkbenchAdvisor;

/**
 * This class controls all aspects of the application's execution
 * and is contributed through the plugin.xml.
 */
public class Application implements IApplication {

	public Object start(IApplicationContext context) throws Exception {
		Display display = PlatformUI.createDisplay();
		WorkbenchAdvisor advisor = new ApplicationWorkbenchAdvisor();
		return PlatformUI.createAndRunWorkbench(display, advisor);
	}

	public void stop() {
		// Do nothing
	}
}

Branding

RAP Tooling 1.4 generates an extension point with branding. What is branding? If you look at the RAP Application you have a green color for the title of the RAP Application :

Here is the declaration of the branding :

<extension
      point="org.eclipse.rap.ui.branding">
   <branding
         servletName="view"
         themeId="org.eclipse.rap.design.example.fancy.theme"
         defaultEntrypointId="sample.application.rap.viewapp"
         title="RAP Single View"
         id="sample.application.rap.branding">
    </branding>
</extension>

org.eclipse.rap.rwt.theme.Default

You can select another branding if you wish. To know the available branding, use completion (Ctrl+Space) in the plugin.xml :

If you select for instance org.eclipse.rap.rwt.theme.Default

<extension
      point="org.eclipse.rap.ui.branding">
   <branding
         servletName="view"
         themeId="org.eclipse.rap.rwt.theme.Default"
         defaultEntrypointId="sample.application.rap.viewapp"
         title="RAP Single View"
         id="sample.application.rap.branding">
    </branding>
</extension>

and you restart your RAP Application, the WEB application will look like this:

View

The View class was generated to display Table with 3 items. Here is the generated code sample.application.rap.View class :

package sample.application.rap;

import org.eclipse.jface.viewers.IStructuredContentProvider;
import org.eclipse.jface.viewers.ITableLabelProvider;
import org.eclipse.jface.viewers.LabelProvider;
import org.eclipse.jface.viewers.TableViewer;
import org.eclipse.jface.viewers.Viewer;
import org.eclipse.swt.SWT;
import org.eclipse.swt.graphics.Image;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.ui.ISharedImages;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.part.ViewPart;

public class View extends ViewPart {
	public static final String ID = "sample.application.rap.view";

	private TableViewer viewer;

	/**
	 * The content provider class is responsible for providing objects to the
	 * view. It can wrap existing objects in adapters or simply return objects
	 * as-is. These objects may be sensitive to the current input of the view,
	 * or ignore it and always show the same content (like Task List, for
	 * example).
	 */
	class ViewContentProvider implements IStructuredContentProvider {
		public void inputChanged(Viewer v, Object oldInput, Object newInput) {
		}

		public void dispose() {
		}

		public Object[] getElements(Object parent) {
			return new String[] { "One", "Two", "Three" };
		}
	}

	class ViewLabelProvider extends LabelProvider implements
			ITableLabelProvider {
		public String getColumnText(Object obj, int index) {
			return getText(obj);
		}

		public Image getColumnImage(Object obj, int index) {
			return getImage(obj);
		}

		public Image getImage(Object obj) {
			return PlatformUI.getWorkbench().getSharedImages()
					.getImage(ISharedImages.IMG_OBJ_ELEMENT);
		}
	}

	/**
	 * This is a callback that will allow us to create the viewer and initialize
	 * it.
	 */
	public void createPartControl(Composite parent) {
		int style = SWT.MULTI | SWT.H_SCROLL | SWT.V_SCROLL;
		viewer = new TableViewer(parent, style);
		viewer.setContentProvider(new ViewContentProvider());
		viewer.setLabelProvider(new ViewLabelProvider());
		viewer.setInput(getViewSite());
	}

	/**
	 * Passing the focus request to the viewer's control.
	 */
	public void setFocus() {
		viewer.getControl().setFocus();
	}
}

This code shows you how to manage a list of items with Java code by using SWT Table and JFace content/label provider.

RCP Application

RCP Application with a view

In this section we will generate a basic RCP application with a view with the PDE template RCP Application with a view.

RAP Target Platform

Open a new workspace where RAP Target Platform is not installed. If you go to the Window / Preferences menu and Plug-in Development / Target Platform, you can check RCP Target Platform is installed and selected for the workspace :

Generate sample.application.rcp

RCP application is an Eclipse Plugin. To create a RCP Application we need to create an Eclipse Plugin. To do that, go to the File/New/Other… menu :

Select Plug-in Development/Plug-in Project node :

Click on Next button, the wizard page which gives the choice to create OSGi Bundle or Eclipse Plugin is displayed :

• fill in the Project name field with sample.application.rcp.
• select the radio button Eclipse version because we would like to develop RCP application which is an Eclipse Plugin.

Click on Next button, the wizard page which configure the Eclipse Plugin is displayed :

• ID field is the Bundle identifier (Bundle-SymbolicName: sample.application.rcp).
• Version field is the Bundle version (Bundle-Version: 1.0.0.qualifier).
• Name field is the Bundle name (Bundle-Name: RCP Application).
• Execution Environment sets the minimal version of the JRE in order to execute the bundle (Bundle-RequiredExecutionEnvironment: JavaSE-1.6).
• you can unselect generate an activator, a Java class that controls the plug-in’s life cycle to avoid generating a Bundle Activator
• select This plug-in will make contributions to the UI because we want to generate RCP application
• select yes for Would you like create a rich client application? because we want to generate a RCP application.

Click on Next button, the wizard page which show several PDE templates is displayed :

Select RCP Application with a view template to generate RCP application with a view.

Click on Next button, the wizard page which gives you the capability to customize package names, class names of the RCP project to generate is displayed :

When generation is done, your workspace looks like this :

Launch RCP Application

In this section we can start the generated RCP Application. To do that open MANIFEST.MF and click on Overview tab.

Click on Launch an Eclipse Application link on Testing section. This action starts the RCP fat client application :

Comparison between RAP and RCP Application with a view

If you compare the generated code between the RAP and RCP Application with a view you can notice that the code is almost the same. The main difference between RAP/RCP Application (in our case) is the dependencies :

For RAP Application, we have RAP dependencies :

Require-Bundle: org.eclipse.rap.ui
...
Import-Package: javax.servlet;version="2.4.0",
 javax.servlet.http;version="2.4.0"

For RCP Application we have RCP dependencies :

Require-Bundle: org.eclipse.core.runtime,
 org.eclipse.ui

As we use RAP 1.4, there is no difference for the the main entry which use org.eclipse.equinox.app.IApplication instead of using org.eclipse.rwt.lifecycle.IEntryPoint which is a specific RAP interface.

Conclusion

In this article we have used RAP (runtime and tooling) 1.4 to generate RAP Application with a view. We have generated a RCP Application with a view and we have compared it with RAP Application. The main difference between RAP Application/ RCP Application (for this case) is the dependencies (RAP/RCP dependencies) managed with MANIFEST.MF file. In [step8] we will explain how to manage RAP (WEB Application) and RCP (Fat client) application with the same code. This feature is called Single Sourcing.