Using Eclipse Ganymede to Develop for the Desktop, Web and Mobile

Using Eclipse Ganymede to develop for the desktop, Web and mobile devices, Part 2: Developing for the Rich Client Platform, the Ganymede way RAP: The new way to the Web

Skill Level: Intermediate

Suresh Krishna ([email protected]) Software Developer Freelance Developer

Trebor Fenstermaker ([email protected]) Software Consultant Sunnyside Avenue Software, LLC

09 Sep 2008

The Ganymede release of the Eclipse IDE includes 24 separate projects, covering a wide range of technologies. Many of these projects are mature, and this release provides incremental improvements to those. But Ganymede also includes a number of new projects that introduce new technologies to the Eclipse platform. In this three-part "Using Eclipse Ganymede to develop for the desktop, Web and mobile devices" tutorial series, we will cover the following new Ganymede features: RCP, RAP, and eRCP, which allow you to develop software for the desktop, Web, and mobile platforms, respectively, with one common code base; Subversion for version control; and p2 for update and installation. Here in Part 2, we will take the personal organizer developed in Part 1 and modify it to use the new Rich Ajax Platform (RAP) to package and distribute the application on the Web.

Section 1. Before you start

This tutorial is for any Eclipse developer who wants to learn how to take code written using the mature Rich Client Platform (RCP) and modify it to use the new Rich Ajax Platform (RAP) to allow for a rich-client experience distributed over the Web. You should have an understanding of the Eclipse platform and some familiarity with the idea of Rich Internet Applications (RIAs). Also, you should have knowledge of how to configure a servlet container and deploy applications on it.

About this series

Part 1 provides an introduction to the new features of the RCP, the new Subversion Eclipse integration, and the p2 packaging and distribution system. Part 2 introduces the Rich Ajax Platform (RAP) to write applications for the Web. And Part 3 discusses how to use the embedded Rich Client Platform (eRCP) to develop an application for a mobile device.

About this tutorial

The Ganymede release of the Eclipse IDE bundles more than 20 new and existing projects under the Eclipse umbrella. In Part 1 of this three-part series, you looked at some features added to make development easier, including support for Subversion and a new distribution model for plug-ins called p2. You also saw some incremental improvements in the mature Rich Client Platform (RCP) by developing a simple personal task organizer plug-in application, then storing it in Subversion and deploying it via p2.

Another exciting addition to Ganymede is the inclusion of the Rich Application Platform (RAP). RAP is a way to build rich client applications — stateful GUI applications similar to those developed for a desktop — and deploy them for use on the Web. RAP brings the Eclipse programming model to the Web, allowing you to reuse much of your existing RCP code when building RAP-based applications. This is done using Ajax, but Eclipse makes it simple to build on the knowledge you already have of developing desktop applications with the RCP. To demonstrate, you will modify the personal organizer developed in Part 1 to use RAP.

Topics include:

• How to download and install the RAP environment to Eclipse • How to migrate your existing RCP code to RAP • How to factor your code for the Web • How to package and deploy your code to a Web server

System requirements

Eclipse Ganymede Find Eclipse Ganymede at the Eclipse Foundation.

Java 2 Standard Edition The Java™ 2 Standard Edition V5 or greater is available from Sun Microsystems.

Eclipse RAP The Eclipse RAP plug-in is available in the Eclipse Foundation RAP section at Eclipse.org.

Apache Tomcat For deploying the finished RAP application to a stand-alone servlet container, this tutorial uses Apache Tomcat. Download the latest stable version.

Section 2. Getting started with RAP

Before you can start developing with RAP, you need to download it from the Eclipse Web site and set up your target platform to use it.

Developing with RAP

RAP allows you to build Ajax-enabled Web applications using the Eclipse development model. If you're already familiar with developing desktop applications with the Eclipse RCP, you have the expertise to develop with RAP. In fact, much of the code written for an RCP application can be reused for RAP. This means you can use the full power of Java technology and the Eclipse APIs to develop Web-based applications. Your users can then experience a full GUI application with no page refreshes, like a typical Web application, but they can do so without having to download and install your application on their desktop. RAP achieves this by providing a special implementation of the Standard Widget Toolkit (SWT), JFace, and Workbench, and, as such, is actually a subset of RCP.

Because the base architecture of the RCP and RAP are similar (see Figure 1), plug-in reuse is possible with minimal changes in the source code. RAP applications are accessed via standard browsers in the same way RCP applications are executed on the desktop environment. This is achieved by the RAP Widget Toolkit (RWT), a replacement for SWT used in RCP.

Browser-side widget rendering is done with the qooxdoo Ajax library (see Resources). qooxdoo is a comprehensive Ajax framework leveraging the object-oriented JavaScript that enables users to build cross-browser applications. RAP abstracts the details about the JavaScript, allowing you to work with the Java APIs to build the Rich Internet Applications (RIAs). Custom widget developers need to have JavaScript, qooxdoo, and RAP knowledge. Client-side development allows for the embedding of client-side technologies like other JavaScript frameworks, Flash, and applets.

Figure 1. Comparing RAP and RCP architectures

Downloading RAP

Because RAP is an RCP subset, it cannot co-exist in the same Eclipse instance as RCP; you must download and install the RAP environment for Eclipse separately.

Point your browser to www.eclipse.org/rap/downloads (see Figure 2).

Note: If you would like to migrate the RCP source code to RAP, a target platform download for RAP is recommended. This enables the existing RCP code to get compiled and run against the target RAP code. If you intend to develop new Web applications using RAP and would like to have the development platform, it's recommended to get the RAP SDK from the p2 update mechanism, covered in Part 1.

Figure 2. The Eclipse RAP home page

Select the V1.1rRelease with the words "target platform" in the filename and choose an appropriate mirror.

Figure 3. The Eclipse RAP download page

Download the ZIP file to a temporary directory on your local hard drive, one that is accessible to your Eclipse installation. Once transferred, unzip it in that temp

directory. Open your instance of Eclipse Ganymede and ensure that your workspace points to where you've stored the personal-organizer project from Part 1, then open your Eclipse desktop to the plug-in development perspective. Open the Preferences panel for Eclipse. How you do this depends on your operating system — for example, on Windows®, it's Window > Preferences (see Figure 4); on Mac OS X, it's Eclipse > Preferences). Navigate to Plug-in Development > Target Platform.

Figure 4. Specifying the target platform

Change the value of the location box to the directory where you unzipped the download and click Reload.

Figure 5. Making the target platform RAP

This will load the plug-ins associated with the RAP and switch your target platform from the RCP. You're ready to start making the changes to the personal organizer to take advantage of RAP, which you'll do in the next section.

Section 3. Moving from RCP to RAP

Follow along to see how to migrate the personal-organizer example from RCP to RAP. And along the way, get a feel for some of the differences between the two environments.

Follow the errors to spot the differences

You may notice that since you've switched target platforms, Eclipse is complaining

there are errors in your personal task-organizer code.

Figure 6. Compiler errors for the personal organizer after switching to RAP

One reason for this is because your existing project was meant to use RCP, but by switching targets, the plug-ins used to resolve some of the elements used in the personal organizer are now missing from your build path. Some of these have equivalents in RAP, but some do not. So you will have to do a few small modifications to get things to compile. This will give you some insight into some of the differences between RCP and RAP.

In the dependencies window, remove org.eclipse.ui from the list of required plug-ins by highlighting it, then clicking Remove.

Figure 7. Deleting the unneeded plug-in

In its place, you'll add the RAP equivalent. Click Add and select org.eclipse.rap.ui.

Figure 8. Adding the RAP plug-in to the project

You will see that this alone will resolve many of the compilation errors. Let's look at the remaining errors, one by one. First, edit PersonalTaskViewer.java.

Figure 9. Editing the errors out of PersonalTaskViewer.java

In RCP, it's possible to create a shell with a default no-args constructor, but RAP requires you to explicitly specify that you want no style or display added to the shell at its creation. Change the line Shell shell = new Shell(); to Shell shell = new Shell(SWT.NONE);. Then go to the next error in PersonalTaskViewer.java.

Figure 10. Deleting the SWT.HIDE_SELECTION attribute

SWT.HIDE_SELECTION does not exist in RAP's SWT implementation, so simply delete that reference. CellEditors are not supported by RAP's JFace implementation, so you must remove all references to CellEditor. Simply search through the code and delete these, such as in the createTableViewer class.

Listing 1. The modified createTableViewer class, without CellEditor references

/** * Create the TableViewer */ private void createTableViewer() { tableViewer = new TableViewer(table); tableViewer.setUseHashlookup(true); tableViewer.setColumnProperties(columnNames); tableViewer.setSorter(new PersonalTaskSorter(PersonalTaskSorter.TASK_DESC)); }

Since we don't have CellEditor anymore, we can delete the TaskCellModifer class. Go to the Package Explorer, and delete TaskCellModifier.java.

Figure 11. Deleting the TaskCellModifier class

With the changes implemented in Listing 1 and Figure 11, the compilation errors should be resolved. Here is a summary of the changes made in the process of migrating the RCP code to RAP:

• Organized the RAP application plug-in dependencies. • Looked for the compile errors and corrected them with compatible APIs, constants, etc. • Modified or removed the functionality currently not supported in RAP (e.g., CellEditors).

Defining an entry point

RAP starts applications differently than RCP. RCP uses an implementation of the interface IApplication; the equivalent interface in RAP is called IEntryPoint. As the name implies, RAP identifies a point where an application can be started, and there can be multiple entry points to an application (each distinguished by a unique identifier, which is passed as a parameter on the URL used to start the application — for example, :/rap?startup=).

An EntryPoint represents the main entry point for a RAP application. It can be compared with the main() method in SWT applications. EntryPoint creates the UI with the help of the WorkbenchAdvisor, Initial Perspective, and ApplicationActionBarAdvisor.

Define an EntryPoint to the personal organizer by opening plugin.xml and selecting the Extensions tab (see Figure 12). An entry point is added to the application as an extension point. The Extensions tab displays the list of the extensions this plug-in augments from other plug-ins in the workspace or target platform. Thus, this extension can be considered as an implementation of the interface provided by other plug-ins.

Figure 12. Adding the EntryPoint for the RAP application

Click Add to see a list of extension points and find org.eclipse.rap.ui.entrypoint.

Figure 13. Selecting the EntryPoint extension

Click Finish, and you will see the Extension Point Details listed in plugin.xml.

Figure 14. Setting the EntryPoint properties

The class property is asking for the Java class in the project that implements the IEntryPoint interface. You can create one right from the plugin.xml editor screen. Rename the default class name in the field to POEntryPoint and click the hyperlink for class. Eclipse will respond with a New Java Class wizard.

Figure 15. Creating the IEntryPoint implementation via New Java Class wizard

The class wizard creates the POEntryPoint class that implements IEntryPoint. This class will define the basic life cycle of your RAP application. Click Finish and edit the file to see what's involved.

Listing 2. The IEntryPoint implementation

package com.devworks.tutorial.po; import org.eclipse.rwt.lifecycle.IEntryPoint; import org.eclipse.swt.widgets.Display; import org.eclipse.ui.PlatformUI; import org.eclipse.ui.application.WorkbenchAdvisor; public class POEntryPoint implements IEntryPoint { public POEntryPoint() { } public int createUI() { Display display = PlatformUI.createDisplay(); WorkbenchAdvisor advisor = new ApplicationWorkbenchAdvisor(); return PlatformUI.createAndRunWorkbench(display, advisor); } }

The createUI() method, as the name implies, is responsible for creating the display and the WorkbenchAdvisor, and passing these to the Workbench to be run.

Creating a launch configuration

To launch the application from inside Eclipse, you need to define a launch configuration to tell Eclipse what kind of environment to run it in. You could do this manually each time you want to run it, but it's more convenient to create a launch configuration and save it with the project for reuse.

Using the Package Explorer, create a directory called launch directly under com.devworks.tutorial.po.

Figure 16. Creating the launch directory

From the menu bar, select Run > Run Configuration and select the OSGi framework. Name it PO_RAP_OSGI (see Figure 17). The Equinox's OSGi framework component is the full implementation to the OSGi Core framework R4 specification. In addition, the OSGi framework produces launchers, bootstrap infrastructure, and application models that facilitate the use of Equinox OSGi in end-user product scenarios. As RAP uses the OSGi as the server-side framework, you will want to launch the application with the OSGi framework to make sure that the application works.

Note: The application can be launched and tested either with OSGi Launcher or RAP Launcher. RAP Launcher is based on the OSGI Launcher with the addition of a Main tab. Having the application run on Equinox via OSGi Launcher ensures that it will also run on the servlet container with Equinox, which is why we went that route in this tutorial.

Figure 17. Creating the launch configuration

Select com.devworks.tutorial.po from the workspace and click Add Required Bundles. For good measure, click Validate Bundles to ensure that everything that's needed has been included.

The OSGi framework you've configured includes a Jetty server. Jetty is a lightweight open source Web server and servlet container, and will be used by Eclipse to launch your RAP application when you deploy it from within the workbench. You can configure the start-up values for Jetty from the Arguments tab.

Figure 18. Setting the Jetty arguments

For example, by default Jetty listens on port 9090. If you'd like to change this, you can modify the VM argument that sets this to a different port. If you are developing on OS X, add -Djava.awt.headless=true to the VM arguments. To save this launch configuration, select the Common tab, then edit the Shared file value to be directory com.devworks.tutorial.po/launch. Click Apply, then Run. By setting the shared file, Eclipse will save the configuration at the time it's run.

Figure 19. Running the launch configuration

Of course, clicking Run will also launch the Jetty server and start the OSGi framework with the selected bundles. You can see that activity in the Eclipse console.

Figure 20. Watching the environment start

Your personal-organizer application is now running locally on the port you specified in the launch configuration (in our example, we kept the default of 9090). Browse to http://localhost:9090/rap and see your personal-organizer application run.

Figure 21. Running the personal organizer in your browser

You made virtually no code changes to get here, so you can see that much of what you already know from developing RCP applications is applicable to RAP. However, you did lose some functionality when you had to delete the references to CellEditor; in this version of the personal organizer, you cannot edit task details.

Restoring editing capabilities

Since RAP has no cell editor, let's edit the task detail information with a dialog. We'll invoke the dialog when a user double-clicks on a task and when a new task is added. Open the PersonalTaskViewer.java class in the editor and modify the createTableViewer method.

Listing 3. Replacing the CellEditor functionality in the PersonalTaskViewer class

private void createTableViewer(final Composite composite) { tableViewer = new TableViewer(table); tableViewer.setUseHashlookup(true); tableViewer.setColumnProperties(columnNames); // Enable Task Editing by Invoking the PersonalTaskDialog

tableViewer.addDoubleClickListener(new IDoubleClickListener() { public void doubleClick(DoubleClickEvent event) { if (tableViewer.getSelection() != null) { PersonalTask task = (PersonalTask) ((IStructuredSelection) tableViewer.getSelection()).getFirstElement(); openPersonalTaskDialog(composite.getShell(), task, POUtilities.DIALOG_MODE_EDIT); } } }); // Set the default sorter for the viewer tableViewer.setSorter(new PersonalTaskSorter(PersonalTaskSorter.TASK_DESC));

Whenever the user double-clicks a Task, the task is retrieved from the selection and passed to the PersonalTaskDialog, which is included in the source for this tutorial.

Figure 22. Running the CellEditor replacement in the personal task organizer

Add similar code for the double-clicked event for the Add button, so the dialog is invoked when the user clicks Add. The PersonalTaskDialog class, in turn, has a method on the clicked event of its OK button to update or add the task to the PersonalTaskModel.

Listing 4. OKSelection method that adds data to the PersonalTaskModel

public class OKSelection extends SelectionAdapter { public void widgetSelected(SelectionEvent e) { super.widgetSelected(e); personalTask = getModifiedTask(); if (dialogMode.equals(POUtilities.DIALOG_MODE_EDIT)) { taskModel.taskChanged(personalTask); } else if (dialogMode.equals(POUtilities.DIALOG_MODE_NEW)) taskModel.addTask(personalTask); } taskDialogShell.dispose(); } }

We've added a new utility class, POUtilities, for global constants, images, and the SWT Center and Pack utilities. This is also included in the source for this tutorial.

You now have a fully functional RAP application, composed almost entirely of code you wrote for RCP. In the next section, you'll refactor this code so it has a look and feel suitable for the Web.

Section 4. Refactoring for the Web

With minimal effort, you ported an RCP application to RAP, but the look and feel isn't quite what you'd want in a Web-based application. RAP has a mechanism for customizing an application: Theming and Branding. Theming builds on Cascading Style Sheets (CSS) to customize the look and feel, and Branding is used for customizing the application-specific settings in the browser.

Branding the personal task organizer

At the moment, the personal task organizer is launched using a default URL (http:localhost:9090/rap) that tells the user nothing about the application he's running. The title in the browser, shown in Figure 23, is also a rather bland RAP startup page.

Figure 23. Examining the default values of a RAP deployment

Branding will allow you to modify these to something more meaningful for your application and will also provide a mechanism for dealing with what to do if the user closes the browser while running the personal organizer. This branding is similar to that done for an RCP application, but it provides additional properties useful for the Web.

To brand the personal organizer, open plugin.xml and navigate to the Extensions tab.

Figure 24. Adding the branding extension point

Click Add and select org.eclipse.rap.ui.branding.

Figure 25. Selecting the branding extension point

Click Finish, and the branding extension point will be added to the plugin.xml. You can now set the properties on the property pane, shown in Figure 26, as such:

id: com.devworks.tutorial.po.branding This provides a unique ID to the extension.

servletName: taskOrganizer Allows a user to access the application via localhost:9090/taskOrganizer, rather than /rap.

title: Personal Task Organizer Will be displayed as the title of the Web page in the browser, either in the title bar or the tab.

favicon: icons/alt_window_16.gif Available for use as part of the work done in Part 1, but if you have a logo of your own in an .ico file, use that, as many browsers only accept .ico for the favicon.

exitConfirmation: Do you want to Exit Personal Task Organizer? Will display in a dialog when the user closes his browser or navigates to another URL while running the application.

Figure 26. Setting the branding properties

This will add the code from Listing 5 to the plugin.xml.

Listing 5. The properties added by branding to plugin.xml

Save the file, and re-launch the application. You can now browse to it via localhost:9090/taskOrganizer, and you'll see the title now matches what you entered.

Figure 27. Examining branded properties in the running personal organizer

Depending on your browser, you may also see the favicon has changed from the default to the image you selected. Try closing the browser. You should see a dialog appear asking you to confirm your exit from the application.

Figure 28. Confirming your exit from the application

You've branded your application. Now you can change its look and feel with RAP's theming feature.

Theming the personal organizer

Theming is based on CSS and allows you to define colors, fonts, borders, margins, and images for the widgets. The widgets themselves define what attributes are customizable, with some being more flexible than others. Unfortunately, there is no documentation on what properties can be set on what widgets, so you must examine the RAP source code, available from the CVS site at http:/www.eclipse.org/rap/cvs.php. (You can import this source as a separate project in Eclipse.) Look for files named *.theme.xml in the org.eclipse.rap.rwt package.

Figure 29. Examining the RAP widget properties for theming

For example, the menu has its theme listed in Menu.theme.xml, the List in List.theme.xml; etc. These files define what properties can be themed via CSS for each of their respective widgets. For the personal organizer, we'll theme the text, the toolbar, and the table. Using the package explorer, create a directory directly under the root for the theme and call it po_theme. In that directory, create a file called po.css and add the following CSS definitions.

Listing 6. po.css containing theming properties for the personal organizer

/* Text */ Text[BORDER] { border: 1px solid #1080ee; } /* Toolbar */ ToolItem:hover { background-color: rgb( 200, 200, 200 ); } /* Table */ TreeColumn:hover, TableColumn:hover { background-color: #8cc0ea; }

You need to register this file as the one to use for theming. Open the plugin.xml and select the Extensions tab. Click Add and select org.eclipse.rap.ui.themes.

Figure 30. Adding the themes extension point

Click Finish to add this extension point to the plugin.xml. Edit the value of the file property to point to the po_theme/po.css file. Name this the Personal Task Organizer Theme via the name property and give it the ID com.devworks.tutorial.po.theme.

Figure 31. Setting the theming properties

This registers your theme, but you need to activate it by letting the branding extension point know about it. Select org.eclipse.rap.ui. branding from the list of extensions, and in the property for themeId, enter the ID of the Personal Task Organizer Theme: com.devworks.tutorial.po.theme.

We want to make sure Eclipse knows where to find this file at compile time, so navigate to the plugin.xml Build tab. In the Binary Build directory, be sure to check the box for po_theme.

Figure 32. Adding po_theme to the build

Save the plugin.xml file and browse to the application to see the results of your theming.

Figure 33. Viewing the themed personal organizer

With very little coding and a few property changes, you've modified your application to exploit the additional features of deploying over the Web. But to make the code available to the world, you can't rely on the built-in Jetty server of the OSGi framework. In the next section, you'll see how to package and deploy the application for consumption outside of Eclipse.

Section 5. Packaging and deploying to the server

Now that you've modified the personal organizer to migrate it to RAP, and have adjusted its look and feel to take advantage of its deployment on the Web, it's time to see how to package your application in a way to make it suitable for Web deployment. In this section, you'll learn the steps necessary to do this.

Breaking out of Eclipse

The Jetty HTTP server and servlet container is a convenient tool for testing your application during development, but once you're ready to deploy to the world, you

need to do a little preparation to duplicate what Eclipse is doing for you in the launch configuration you created.

You will want to deploy your application to a servlet container. For this example, we'll use the ever-popular open source Apache Tomcat, available at tomcat.apache.org. You can use this, or another standard servlet container, but before beginning this section, be sure whatever you intend to use is installed and properly configured, and that you are sufficiently familiar with how to deploy an application on it.

There is a sequence of steps to follow, and it's important that each be done correctly for a clean deployment.

Importing required plug-ins

First, you need additional plug-ins that must be bundled in with the personal-organizer deployment. To launch the application in an existing servlet container, it is necessary to have the ServlerBridge plug-ins. These plug-ins launch the OSGi framework in a servlet container and support the OSGi HTTP service, servlet, and HTTP extension points. In short, the ServletBridge is the connection between the OSGi framework and servlet container. To get the plug-ins, you will import a project definition file from the Eclipse Web site that will add the required plug-ins to the project workspace.

Download http://www.eclipse.org/equinox/server/downloads/servletbridge-anon.psf to a temp location on your computer. This happens to define all the plug-ins needed by the OSGi framework (the Eclipse implementation of this is called Equinox — thus, the name in the URL) and we can use it to let Eclipse get what it needs without manual entry.

From the menu, select File > Import. From the Import screen, select Team > Team Project Set, and click Next. Enter the location and name of the servletbridge-anon.psf file you downloaded in the file name and click Finish.

Figure 34. Importing the servletbridge-anon.psf file for required plug-ins

This will import four projects into the workspace:

org.eclipse.equinox.servletbridge Launches the framework and provides a place for the framework to hook back into the servlet container.

org.eclipse.equinox.servletbridge.http Hooks back into the servlet bridge and proxies requests through to the servlet container to provide an OSGi HttpService.

org.eclipse.equinox.http.servlet Provides the HttpServiceServlet used by http.servletbridge that when initialized registers an OSGi HttpService.

org.eclipse.equinox.http.registry Provides servlet, resource, and HTTP context extension points based on an OSGi HttpService.

javax.servlet The bundled version of the standard servlet API.

Once these have all downloaded, your project organizer will have everything it needs to be built and deployed on its own, including the RAP source code, custom plug-ins, and the OSGi (aka Equinox) server code.

Figure 35. Examining the packages added

Creating a deploy script

The application build can be performed with a series of Ant scripts and resource templates. As always with these, it's easiest to start with an example. Look at the structure for org.eclipse.rap.demo.feature.

Figure 36. Looking at an existing build structure

The directory structure of the deploy script and templates:

src\org.eclipse.rap.tools\ConfigIniCreator.java This creates the content of a simple config.ini file. Run this after the Ant build scripts (webappBuilder.xml and the pde.exportFeatures) have finished, then replace the content of the config.ini file in the build.

deployment\rapdemo.war This is the final to-be deployed application WAR file.

script\webappBuilder.xml The Web application build script for a RAP application that uses the equinox servlet bridge to run in a servlet container. This script assumes that the servlet bridge project is available in the current workspace.

templates\WEB-INF\eclipse\configuration\config.ini The Eclipse runtime configuration file used to identify the associated bundles that need to be started.

templates\WEB-INF\eclipse\launch.ini

templates\WEB-INF\web.xml

Copy the templates and scripts folders from here to the package com.devworks.tutorial.po.feature.

Configure the deploy scripts

Open the feature.xml from the com.devworks.tutorial.po.feature and add the required plug-ins that should be packaged with the feature:

• com.devworks.tutorial.po • com.ibm.icu • org.eclipse.core.commands • org.eclipse.core.contenttype • org.eclipse.core.databinding • org.eclipse.core.databinding.beans • org.eclipse.core.expressions • org.eclipse.core.jobs • org.eclipse.core.runtime • org.eclipse.equinox.app • org.eclipse.equinox.common • org.eclipse.equinox.http.registry • org.eclipse.equinox.http.servlet • org.eclipse.equinox.http.servletbridge • org.eclipse.equinox.preferences

• org.eclipse.equinox.registry • org.eclipse.equinox.servletbridge • org.eclipse.osgi • org.eclipse.osgi.services • org.eclipse.rap.jface • org.eclipse.rap.jface.databinding • org.eclipse.rap.rwt • org.eclipse.rap.rwt.q07 • org.eclipse.rap.ui • org.eclipse.rap.ui.forms • org.eclipse.rap.ui.views • org.eclipse.rap.ui.workbench Figure 37 shows the list of plug-ins to be added.

Figure 37. Adding the plug-ins

Open the webappBuilder.xml from the script folder. This builds with the help of the templates folder, targets, and Eclipse's PDE export feature. You must change the servletbridge.dir property to the appropriate path of where that package has been downloaded and stored on your local file system (in this example, C:/temp/eclipse/workspace/org.eclipse.equinox.servletbridge). You must also change the value of the webapp.name property to the folder that appears after the feature build.

Figure 38. Setting the servletbridge.dir property

Save the file. You're now ready to build the application.

Build the application

From the Package Explorer, open the context menu for webappBuilder.xml, and select Run As > Ant Build.

Figure 39. Building the plug-ins

Eclipse will display the Edit configuration and launch window. Give it the name Task Organizer, then select the JRE tab. Be sure the radio button is selected for "Run in the same JRE as the workspace." This will give the build access to all the required plug-ins in the workspace.

Click Run, then wait as all the required plug-ins are built. You can monitor the progress from the console.

Figure 40. Watching the plug-ins build

When all the builds are complete, refresh the com.devworks.tutorial.po.feature project from the Package Explorer by pressing F5, or selecting Refresh from the context menu. You will now see the directory structure that's been created by the build.

Figure 41. Seeing the build results in the Package Explorer

Config.ini contains the bundles loaded during the application's initialization. You need to update this file before deploying. A simple way to do this is to run the ConfigIniCreator.java class included in org.eclipse.rap.demo.feature. Open this file and edit the file path to the plug-in directory to represent where your plug-ins will be deployed. In this example, we use C:\temp\eclipse\workspace\com.devworks.tutorial.po.feature\build\PersonalTaskOrganizer\WEB-INF\eclipse\plugins.

Figure 42. Modifying the helper class

Bring up the context menu for this file in the Package Explorer and select Run to compile and run it. It will print the configuration you'll need in the console.

Figure 43. The output of the helper class

Open the config.ini file in the editor and copy the contents from the console into it. Be sure to save. You're now ready to create a WAR file for deployment.

Creating a WAR file

A WAR is a Web Archive file, a compact way to bundle a Web application for simple deployment to a servlet container. Eclipse makes it simple to package any Web-based application in a WAR, including RAP applications. To create a WAR for the personal organizer, select the WEB-INF directory from com.devworks.tutorial.po.feature project and bring up the context menu. Select Export > General > Archive File.

Figure 44. Packaging the application as a WAR file

Call the file po.war and place it in a temp directory of your choice. Be sure the entire com.devworks.tutorial.po.feature tree is checked, and be sure to select the Create only selected directories radio button, then click Finish.

You now have a self-contained WAR file called po.war, suitable for deployment in the servlet container of your choice. In the next section, we show how to deploy it in Tomcat.

Deploy on Tomcat

In our configuration, Tomcat is running on port 1234, though it is common for it to be running on port 8080. You can use the built-in Tomcat manager to deploy the po.war file. Browse to http:localhost:1234/manager/html.

Figure 45. Deploying the WAR via the Tomcat manager

In the section labeled "WAR file to deploy," enter the path and file name for the po.war you just created and click Deploy. Once Tomcat has finished deploying the WAR, you can run the personal organizer by browsing to localhost:1234/po/taskOrganizer.

Figure 46. The personal task organizer running from Tomcat

You have now built a stand-alone version of your personal task organizer successfully and deployed it on your local servlet container. (Just to prove it's completely free-standing, close Eclipse and try it.)

If you wanted to make this a live application, you would need only move that same WAR to a publicly available Web server (but remember: For the sake of showing off the features of Ganymede, we've kept this simple, so your tasks aren't currently stored between sessions, although a task organizer that forgets what you had to do yesterday may be just what the world needs. The same application, boasting full desktop-like functionality, will run flawlessly on any platform (Windows, Mac OS X, or Linux®) and any brand of browser (Internet Explorer, Firefox, Safari, or Opera) with no modification on your part, and with no special plug-in installations or software downloads on the part of your users.

Summary

The Eclipse IDE Ganymede project release includes an exciting technology called the Rich Ajax Platform (RAP) that allows you to build and deploy rich Internet applications using the skills you already have from developing RCP desktop applications. These Internet applications have all the features of a desktop application, but with the powerful distribution model and platform independence of

the Web.

RAP is a subset of the RCP, so it must be downloaded and installed as a separate target platform in your Eclipse environment. But as a subset, it allows you to take existing applications you've developed with RCP, and, with minimal modification, turn them into Web applications. With one common code base for business logic, you can easily maintain separate deployment environments for the life of a project without completely different UI logic.

Eclipse RAP achieves this bridge between RCP and the Web by leveraging the Standard Widget Toolkit (SWT), JFace, and the Workbench.

You can use the Eclipse OSGi implementation (Equinox) and its built-in Jetty server for testing. But for deployment, you need to follow a process to build a stand-alone application packaged as a WAR and suitable for deploying to a servlet container.

In Part 3 of this "Using Eclipse Ganymede to develop for the desktop, Web and mobile devices" tutorial series, you'll again modify the personal organizer to use the exciting new embedded Rich Client Platform (eRCP) project of Ganymede for developing for mobile devices.

Downloads

Description Name Size Download method Personal-organizer sample, Part 2 os-eclipse-ganymede-pt2.zip132KB HTTP

Information about download methods

Resources

Learn • Read "Eclipse Ganymede at a glance" get an overview of the Ganymede release. • For more information on the RCP, see the Eclipse wiki. • For running the Equinox implementation of OSGi on the Web, see Equinox in a Servlet Container. • More information on deploying a RAP application can be found in RAP Deployment -- Part 1: Deploying your application with Jetty and RAP Deployment -- Part 2: Deploying your application as a .war file of the RAP Insights Blog from Innopract. • You can read more about Eclipse Theming and Branding from the online Eclipse help. • The Eclipse help also has more information on RAP deployment. •"Rich Ajax Platform, Part 1: An introduction" and "Rich Ajax Platform, Part 2: Developing applications" is a two-part article series covering an earlier release of RAP. • Read "Expose plug-ins as Web services with Eclipse" to get more information about Equinox and the Web. •"Developing your first Eclipse RCP application" provides a good introduction on getting started with RCP. • Check out "Brand your Eclipse RCP applications" for more information on branding your RCP application. •"Introducing Subversion: Version control for the third millennium" offers a primer on Subversion. • Subversion server code can be obtained from subversion.tigris.org. • For information on setting up Subversion with Apache, see Setting Up A Subversion Repository Using Apache, With Auto Updatable Working Copy. • Understanding the Eclipse p2 Provisioning System by James Sugrue features a Q&A on p2. • Details on the Equinox p2 provisioning system can be found at the Eclipse wiki on Equinox. • There is also a review of p2 by Ryan Slobojan called Eclipse Ganymede: An in-depth look at Equinox p2 (Provisioning Platform).

• Check out the extensive documentation, tutorials, presentations, and screencasts that illuminate the Eclipse Test & Performance Tools Platform (TPTP). • Learn about qooxdoo, a comprehensive and innovative Ajax application framework. • Check out the "Recommended Eclipse reading list." • Browse all the Eclipse content on developerWorks. • New to Eclipse? Read the developerWorks article "Get started with Eclipse Platform" to learn its origin and architecture, and how to extend Eclipse with plug-ins. • Expand your Eclipse skills by checking out IBM developerWorks' Eclipse project resources. • To listen to interesting interviews and discussions for software developers, check out developerWorks podcasts. • Stay current with developerWorks' Technical events and webcasts. • Watch and learn about IBM and open source technologies and product functions with the no-cost developerWorks On demand demos. • Check out upcoming conferences, trade shows, webcasts, and other Events around the world that are of interest to IBM open source developers. • Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products. Get products and technologies • The Java 2 Standard Edition V5 or greater is available from Sun Microsystems. • Eclipse Ganymede is at the Eclipse Foundation. • The Subversive plug-in can be downloaded from Eclipse.org/subversive. • The Subversive connectors are hosted at Polarion.com. • Check out the latest Eclipse technology downloads at IBM alphaWorks. • Download Eclipse Platform and other projects from the Eclipse Foundation. • Download IBM product evaluation versions, and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®. • Innovate your next open source development project with IBM trial software, available for download or on DVD.

Discuss • RAP news portal: Discuss RAP with the Eclipse community. • The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this will launch your default Usenet news reader application and open eclipse.platform.) • The Eclipse newsgroups has many resources for people interested in using and extending Eclipse. • Participate in developerWorks blogs and get involved in the developerWorks community.

About the authors

Suresh Krishna Suresh Krishna has been a programmer since 2000 and has been working on the domain modeling, IDEs, and productivity tools. Inspired by the IDE evolution and developer productivity, he works primarily on the Eclipse plug-ins and RCP applications. Extreme Programming and Scrum are his favorites, along with evangelizing Eclipse to the user, developer, and corporate communities. He enjoys his free time writing blogs and product evaluations.

Trebor Fenstermaker Although he's programmed in Java since 1999, Trebor Fenstermaker was, for much of that time, highly suspicious of Java IDEs and was a die-hard command-line user, even doing all his code editing in vi -- until a colleague showed him that he really could be more efficient with Eclipse. He now evangelizes his fellow UNIX command-line refugees on its wonders and enjoys exploring its more powerful features -- including its endless possibilities for expansion through custom plug-ins.