Using Eclipse Ganymede to develop for thedesktop Web and mobile devices Part 2Developing for the Rich Client Platform theGanymede wayRAP The new way to the Web

Skill Level Intermediate

Suresh Krishna (sureshmadhuvarsugmailcom)Software DeveloperFreelance Developer

Trebor Fenstermaker (tcfsunnysideavecom)Software ConsultantSunnyside Avenue Software LLC

09 Sep 2008

The Ganymede release of the Eclipse IDE includes 24 separate projects covering awide range of technologies Many of these projects are mature and this releaseprovides incremental improvements to those But Ganymede also includes a numberof new projects that introduce new technologies to the Eclipse platform In thisthree-part Using Eclipse Ganymede to develop for the desktop Web and mobiledevices tutorial series we will cover the following new Ganymede features RCPRAP and eRCP which allow you to develop software for the desktop Web andmobile platforms respectively with one common code base Subversion for versioncontrol and p2 for update and installation Here in Part 2 we will take the personalorganizer 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

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 1 of 57

This tutorial is for any Eclipse developer who wants to learn how to take code writtenusing the mature Rich Client Platform (RCP) and modify it to use the new Rich AjaxPlatform (RAP) to allow for a rich-client experience distributed over the Web Youshould have an understanding of the Eclipse platform and some familiarity with theidea of Rich Internet Applications (RIAs) Also you should have knowledge of how toconfigure 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 SubversionEclipse integration and the p2 packaging and distribution system Part 2 introducesthe Rich Ajax Platform (RAP) to write applications for the Web And Part 3 discusseshow to use the embedded Rich Client Platform (eRCP) to develop an application fora mobile device

About this tutorial

The Ganymede release of the Eclipse IDE bundles more than 20 new and existingprojects under the Eclipse umbrella In Part 1 of this three-part series you looked atsome features added to make development easier including support for Subversionand a new distribution model for plug-ins called p2 You also saw some incrementalimprovements in the mature Rich Client Platform (RCP) by developing a simplepersonal task organizer plug-in application then storing it in Subversion anddeploying it via p2

Another exciting addition to Ganymede is the inclusion of the Rich ApplicationPlatform (RAP) RAP is a way to build rich client applications mdash stateful GUIapplications similar to those developed for a desktop mdash and deploy them for use onthe Web RAP brings the Eclipse programming model to the Web allowing you toreuse much of your existing RCP code when building RAP-based applications Thisis done using Ajax but Eclipse makes it simple to build on the knowledge youalready have of developing desktop applications with the RCP To demonstrate youwill modify the personal organizer developed in Part 1 to use RAP

Topics include

bull How to download and install the RAP environment to Eclipse

bull How to migrate your existing RCP code to RAP

bull How to factor your code for the Web

bull How to package and deploy your code to a Web server

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 2 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

System requirements

Eclipse GanymedeFind Eclipse Ganymede at the Eclipse Foundation

Java 2 Standard EditionThe Javatrade 2 Standard Edition V5 or greater is available from SunMicrosystems

Eclipse RAPThe Eclipse RAP plug-in is available in the Eclipse Foundation RAP section atEclipseorg

Apache TomcatFor deploying the finished RAP application to a stand-alone servlet containerthis 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 EclipseWeb site and set up your target platform to use it

Developing with RAP

RAP allows you to build Ajax-enabled Web applications using the Eclipsedevelopment model If youre already familiar with developing desktop applicationswith the Eclipse RCP you have the expertise to develop with RAP In fact much ofthe code written for an RCP application can be reused for RAP This means you canuse the full power of Java technology and the Eclipse APIs to develop Web-basedapplications Your users can then experience a full GUI application with no pagerefreshes like a typical Web application but they can do so without having todownload and install your application on their desktop RAP achieves this byproviding a special implementation of the Standard Widget Toolkit (SWT) JFaceand 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 applicationsare accessed via standard browsers in the same way RCP applications areexecuted on the desktop environment This is achieved by the RAP Widget Toolkit(RWT) a replacement for SWT used in RCP

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 3 of 57

Browser-side widget rendering is done with the qooxdoo Ajax library (seeResources) qooxdoo is a comprehensive Ajax framework leveraging theobject-oriented JavaScript that enables users to build cross-browser applicationsRAP abstracts the details about the JavaScript allowing you to work with the JavaAPIs to build the Rich Internet Applications (RIAs) Custom widget developers needto have JavaScript qooxdoo and RAP knowledge Client-side development allowsfor the embedding of client-side technologies like other JavaScript frameworksFlash 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 asRCP you must download and install the RAP environment for Eclipse separately

Point your browser to wwweclipseorgrapdownloads (see Figure 2)

Note If you would like to migrate the RCP source code to RAP a target platformdownload for RAP is recommended This enables the existing RCP code to getcompiled and run against the target RAP code If you intend to develop new Webapplications using RAP and would like to have the development platform itsrecommended to get the RAP SDK from the p2 update mechanism covered in Part1

Figure 2 The Eclipse RAP home page

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 4 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

Select the V11rRelease with the words target platform in the filename and choosean appropriate mirror

Figure 3 The Eclipse RAP download page

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

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 5 of 57

directory Open your instance of Eclipse Ganymede and ensure that your workspacepoints to where youve stored the personal-organizer project from Part 1 then openyour Eclipse desktop to the plug-in development perspective Open the Preferencespanel for Eclipse How you do this depends on your operating system mdash forexample on Windowsreg its Window gt Preferences (see Figure 4) on Mac OS Xits Eclipse gt Preferences) Navigate to Plug-in Development gt Target Platform

Figure 4 Specifying the target platform

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

Figure 5 Making the target platform RAP

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 6 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

This will load the plug-ins associated with the RAP and switch your target platformfrom the RCP Youre ready to start making the changes to the personal organizer totake advantage of RAP which youll 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 toRAP And along the way get a feel for some of the differences between the twoenvironments

Follow the errors to spot the differences

You may notice that since youve switched target platforms Eclipse is complaining

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 7 of 57

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 byswitching targets the plug-ins used to resolve some of the elements used in thepersonal organizer are now missing from your build path Some of these haveequivalents in RAP but some do not So you will have to do a few smallmodifications to get things to compile This will give you some insight into some ofthe differences between RCP and RAP

In the dependencies window remove orgeclipseui from the list of requiredplug-ins by highlighting it then clicking Remove

Figure 7 Deleting the unneeded plug-in

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 8 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

In its place youll add the RAP equivalent Click Add and selectorgeclipserapui

Figure 8 Adding the RAP plug-in to the project

You will see that this alone will resolve many of the compilation errors Lets look atthe remaining errors one by one First edit PersonalTaskViewerjava

Figure 9 Editing the errors out of PersonalTaskViewerjava

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 9 of 57

In RCP its possible to create a shell with a default no-args constructor but RAPrequires you to explicitly specify that you want no style or display added to the shellat its creation Change the line Shell shell = new Shell() to Shell shell= new Shell(SWTNONE) Then go to the next error inPersonalTaskViewerjava

Figure 10 Deleting the SWTHIDE_SELECTION attribute

SWTHIDE_SELECTION does not exist in RAPs SWT implementation so simplydelete that reference CellEditors are not supported by RAPs JFaceimplementation so you must remove all references to CellEditor Simply searchthrough the code and delete these such as in the createTableViewer class

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 10 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

Listing 1 The modified createTableViewer class without CellEditor references

Create the TableViewerprivate void createTableViewer()

tableViewer = new TableViewer(table)tableViewersetUseHashlookup(true)tableViewersetColumnProperties(columnNames)tableViewersetSorter(new PersonalTaskSorter(PersonalTaskSorterTASK_DESC))

Since we dont have CellEditor anymore we can delete the TaskCellModiferclass Go to the Package Explorer and delete TaskCellModifierjava

Figure 11 Deleting the TaskCellModifier class

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 11 of 57

With the changes implemented in Listing 1 and Figure 11 the compilation errorsshould be resolved Here is a summary of the changes made in the process ofmigrating the RCP code to RAP

bull Organized the RAP application plug-in dependencies

bull Looked for the compile errors and corrected them with compatible APIsconstants etc

bull Modified or removed the functionality currently not supported in RAP(eg CellEditors)

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 12 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

Defining an entry point

RAP starts applications differently than RCP RCP uses an implementation of theinterface IApplication the equivalent interface in RAP is called IEntryPointAs the name implies RAP identifies a point where an application can be started andthere can be multiple entry points to an application (each distinguished by a uniqueidentifier which is passed as a parameter on the URL used to start the applicationmdash for example lthostgtltportgtrapstartup=ltentrypointnamegt)

An EntryPoint represents the main entry point for a RAP application It can becompared with the main() method in SWT applications EntryPoint creates theUI with the help of the WorkbenchAdvisor Initial Perspective andApplicationActionBarAdvisor

Define an EntryPoint to the personal organizer by opening pluginxml andselecting the Extensions tab (see Figure 12) An entry point is added to theapplication as an extension point The Extensions tab displays the list of theextensions this plug-in augments from other plug-ins in the workspace or targetplatform Thus this extension can be considered as an implementation of theinterface provided by other plug-ins

Figure 12 Adding the EntryPoint for the RAP application

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 13 of 57

Click Add to see a list of extension points and findorgeclipserapuientrypoint

Figure 13 Selecting the EntryPoint extension

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 14 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 15 of 57

Click Finish and you will see the Extension Point Details listed in pluginxml

Figure 14 Setting the EntryPoint properties

The class property is asking for the Java class in the project that implements theIEntryPoint interface You can create one right from the pluginxml editor screenRename the default class name in the field to POEntryPoint and click thehyperlink for class Eclipse will respond with a New Java Class wizard

Figure 15 Creating the IEntryPoint implementation via New Java Class wizard

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 16 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

The class wizard creates the POEntryPoint class that implements IEntryPointThis class will define the basic life cycle of your RAP application Click Finish andedit the file to see whats involved

Listing 2 The IEntryPoint implementation

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 17 of 57

package comdevworkstutorialpo

import orgeclipserwtlifecycleIEntryPointimport orgeclipseswtwidgetsDisplayimport orgeclipseuiPlatformUIimport orgeclipseuiapplicationWorkbenchAdvisor

public class POEntryPoint implements IEntryPoint

public POEntryPoint()

public int createUI() Display display = PlatformUIcreateDisplay()WorkbenchAdvisor advisor = new ApplicationWorkbenchAdvisor()return PlatformUIcreateAndRunWorkbench(display advisor)

The createUI() method as the name implies is responsible for creating thedisplay and the WorkbenchAdvisor and passing these to the Workbench to berun

Creating a launch configuration

To launch the application from inside Eclipse you need to define a launchconfiguration to tell Eclipse what kind of environment to run it in You could do thismanually each time you want to run it but its more convenient to create a launchconfiguration and save it with the project for reuse

Using the Package Explorer create a directory called launch directly undercomdevworkstutorialpo

Figure 16 Creating the launch directory

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 18 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

From the menu bar select Run gt Run Configuration and select the OSGiframework Name it PO_RAP_OSGI (see Figure 17) The Equinoxs OSGi frameworkcomponent is the full implementation to the OSGi Core framework R4 specificationIn addition the OSGi framework produces launchers bootstrap infrastructure andapplication models that facilitate the use of Equinox OSGi in end-user productscenarios As RAP uses the OSGi as the server-side framework you will want tolaunch the application with the OSGi framework to make sure that the applicationworks

Note The application can be launched and tested either with OSGi Launcher orRAP Launcher RAP Launcher is based on the OSGI Launcher with the addition of aMain tab Having the application run on Equinox via OSGi Launcher ensures that itwill also run on the servlet container with Equinox which is why we went that routein this tutorial

Figure 17 Creating the launch configuration

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 19 of 57

Select comdevworkstutorialpo from the workspace and click Add RequiredBundles For good measure click Validate Bundles to ensure that everything thatsneeded has been included

The OSGi framework youve configured includes a Jetty server Jetty is a lightweightopen source Web server and servlet container and will be used by Eclipse to launchyour RAP application when you deploy it from within the workbench You canconfigure the start-up values for Jetty from the Arguments tab

Figure 18 Setting the Jetty arguments

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 20 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

For example by default Jetty listens on port 9090 If youd like to change this youcan modify the VM argument that sets this to a different port If you are developingon OS X add -Djavaawtheadless=true to the VM arguments To save thislaunch configuration select the Common tab then edit the Shared file value to bedirectory comdevworkstutorialpolaunch Click Apply then Run Bysetting the shared file Eclipse will save the configuration at the time its run

Figure 19 Running the launch configuration

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 21 of 57

Of course clicking Run will also launch the Jetty server and start the OSGiframework with the selected bundles You can see that activity in the Eclipseconsole

Figure 20 Watching the environment start

Your personal-organizer application is now running locally on the port you specifiedin the launch configuration (in our example we kept the default of 9090) Browse tohttplocalhost9090rap and see your personal-organizer application run

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 22 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

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 whatyou already know from developing RCP applications is applicable to RAP Howeveryou did lose some functionality when you had to delete the references toCellEditor in this version of the personal organizer you cannot edit task details

Restoring editing capabilities

Since RAP has no cell editor lets edit the task detail information with a dialog Wellinvoke the dialog when a user double-clicks on a task and when a new task isadded Open the PersonalTaskViewerjava class in the editor and modify thecreateTableViewer method

Listing 3 Replacing the CellEditor functionality in the PersonalTaskViewerclass

private void createTableViewer(final Composite composite) tableViewer = new TableViewer(table)tableViewersetUseHashlookup(true)tableViewersetColumnProperties(columnNames)

Enable Task Editing by Invoking the PersonalTaskDialog

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 23 of 57

tableVieweraddDoubleClickListener(new IDoubleClickListener() public void doubleClick(DoubleClickEvent event)

if (tableViewergetSelection() = null) PersonalTask task = (PersonalTask) ((IStructuredSelection)

tableViewergetSelection())getFirstElement()openPersonalTaskDialog(compositegetShell() task

POUtilitiesDIALOG_MODE_EDIT)

) Set the default sorter for the viewertableViewersetSorter(new PersonalTaskSorter(PersonalTaskSorterTASK_DESC))

Whenever the user double-clicks a Task the task is retrieved from the selection andpassed to the PersonalTaskDialog which is included in the source for thistutorial

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 isinvoked when the user clicks Add The PersonalTaskDialog class in turn has amethod on the clicked event of its OK button to update or add the task to thePersonalTaskModel

Listing 4 OKSelection method that adds data to the PersonalTaskModel

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 24 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

public class OKSelection extends SelectionAdapter public void widgetSelected(SelectionEvent e)

superwidgetSelected(e)personalTask = getModifiedTask()if (dialogModeequals(POUtilitiesDIALOG_MODE_EDIT))

taskModeltaskChanged(personalTask) else if (dialogModeequals(POUtilitiesDIALOG_MODE_NEW))

taskModeladdTask(personalTask)taskDialogShelldispose()

Weve added a new utility class POUtilities for global constants images andthe 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 codeyou wrote for RCP In the next section youll refactor this code so it has a look andfeel 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 isntquite what youd want in a Web-based application RAP has a mechanism forcustomizing an application Theming and Branding Theming builds on CascadingStyle Sheets (CSS) to customize the look and feel and Branding is used forcustomizing 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(httplocalhost9090rap) that tells the user nothing about the application hesrunning The title in the browser shown in Figure 23 is also a rather bland RAPstartup page

Figure 23 Examining the default values of a RAP deployment

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 25 of 57

Branding will allow you to modify these to something more meaningful for yourapplication and will also provide a mechanism for dealing with what to do if the usercloses the browser while running the personal organizer This branding is similar tothat done for an RCP application but it provides additional properties useful for theWeb

To brand the personal organizer open pluginxml and navigate to the Extensionstab

Figure 24 Adding the branding extension point

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 26 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

Click Add and select orgeclipserapuibranding

Figure 25 Selecting the branding extension point

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 27 of 57

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 28 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

Click Finish and the branding extension point will be added to the pluginxml Youcan now set the properties on the property pane shown in Figure 26 as such

id comdevworkstutorialpobrandingThis provides a unique ID to the extension

servletName taskOrganizerAllows a user to access the application via localhost9090taskOrganizer ratherthan rap

title Personal Task OrganizerWill be displayed as the title of the Web page in the browser either in the titlebar or the tab

favicon iconsalt_window_16gifAvailable for use as part of the work done in Part 1 but if you have a logo ofyour own in an ico file use that as many browsers only accept ico for thefavicon

exitConfirmation Do you want to Exit Personal Task OrganizerWill display in a dialog when the user closes his browser or navigates toanother URL while running the application

Figure 26 Setting the branding properties

This will add the code from Listing 5 to the pluginxml

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 29 of 57

Listing 5 The properties added by branding to pluginxml

ltextension point=orgeclipserapuibrandinggtltbranding defaultEntrypointId=comdevworkstutorialporapEntrypoint

exitConfirmation=Do you want to Exit Personal Task Organizer favicon=iconsalt_window_16gifid=comdevworkstutorialpobrandingservletName=taskOrganizertitle=Personal Task Organizergt

ltbrandinggtltextensiongt

Save the file and re-launch the application You can now browse to it vialocalhost9090taskOrganizer and youll 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 thedefault to the image you selected Try closing the browser You should see a dialogappear asking you to confirm your exit from the application

Figure 28 Confirming your exit from the application

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 30 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

Youve branded your application Now you can change its look and feel with RAPstheming feature

Theming the personal organizer

Theming is based on CSS and allows you to define colors fonts borders marginsand images for the widgets The widgets themselves define what attributes arecustomizable with some being more flexible than others Unfortunately there is nodocumentation on what properties can be set on what widgets so you must examinethe RAP source code available from the CVS site athttpwwweclipseorgrapcvsphp (You can import this source as a separate projectin Eclipse) Look for files named themexml in the orgeclipseraprwtpackage

Figure 29 Examining the RAP widget properties for theming

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 31 of 57

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 32 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

For example the menu has its theme listed in Menuthemexml the List inListthemexml etc These files define what properties can be themed via CSS foreach of their respective widgets For the personal organizer well theme the text thetoolbar and the table Using the package explorer create a directory directly underthe root for the theme and call it po_theme In that directory create a file calledpocss and add the following CSS definitions

Listing 6 pocss containing theming properties for the personal organizer

Text Text[BORDER] border 1px solid 1080ee

Toolbar ToolItemhover background-color rgb( 200 200 200 )

Table TreeColumnhover TableColumnhover background-color 8cc0ea

You need to register this file as the one to use for theming Open the pluginxml andselect the Extensions tab Click Add and select orgeclipserapuithemes

Figure 30 Adding the themes extension point

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 33 of 57

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 34 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

Click Finish to add this extension point to the pluginxml Edit the value of the fileproperty to point to the po_themepocss file Name this the Personal TaskOrganizer Theme via the name property and give it the IDcomdevworkstutorialpotheme

Figure 31 Setting the theming properties

This registers your theme but you need to activate it by letting the brandingextension point know about it Select orgeclipserapui branding from the list ofextensions and in the property for themeId enter the ID of the Personal TaskOrganizer Theme comdevworkstutorialpotheme

We want to make sure Eclipse knows where to find this file at compile time sonavigate to the pluginxml Build tab In the Binary Build directory be sure to checkthe box for po_theme

Figure 32 Adding po_theme to the build

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 35 of 57

Save the pluginxml file and browse to the application to see the results of yourtheming

Figure 33 Viewing the themed personal organizer

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 36 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

With very little coding and a few property changes youve modified your applicationto exploit the additional features of deploying over the Web But to make the codeavailable to the world you cant rely on the built-in Jetty server of the OSGiframework In the next section youll see how to package and deploy the applicationfor consumption outside of Eclipse

Section 5 Packaging and deploying to the server

Now that youve modified the personal organizer to migrate it to RAP and haveadjusted its look and feel to take advantage of its deployment on the Web its time tosee how to package your application in a way to make it suitable for Webdeployment In this section youll learn the steps necessary to do this

Breaking out of Eclipse

The Jetty HTTP server and servlet container is a convenient tool for testing yourapplication during development but once youre ready to deploy to the world you

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 37 of 57

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

You will want to deploy your application to a servlet container For this example welluse the ever-popular open source Apache Tomcat available at tomcatapacheorgYou can use this or another standard servlet container but before beginning thissection be sure whatever you intend to use is installed and properly configured andthat you are sufficiently familiar with how to deploy an application on it

There is a sequence of steps to follow and its important that each be done correctlyfor a clean deployment

Importing required plug-ins

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

Download httpwwweclipseorgequinoxserverdownloadsservletbridge-anonpsfto a temp location on your computer This happens to define all the plug-ins neededby the OSGi framework (the Eclipse implementation of this is called Equinox mdash thusthe name in the URL) and we can use it to let Eclipse get what it needs withoutmanual entry

From the menu select File gt Import From the Import screen select Team gt TeamProject Set and click Next Enter the location and name of theservletbridge-anonpsf file you downloaded in the file name and click Finish

Figure 34 Importing the servletbridge-anonpsf file for required plug-ins

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 38 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

This will import four projects into the workspace

orgeclipseequinoxservletbridgeLaunches the framework and provides a place for the framework to hook backinto the servlet container

orgeclipseequinoxservletbridgehttpHooks back into the servlet bridge and proxies requests through to the servletcontainer to provide an OSGi HttpService

orgeclipseequinoxhttpservletProvides the HttpServiceServlet used by httpservletbridge thatwhen initialized registers an OSGi HttpService

orgeclipseequinoxhttpregistryProvides servlet resource and HTTP context extension points based on anOSGi HttpService

javaxservletThe bundled version of the standard servlet API

Once these have all downloaded your project organizer will have everything itneeds to be built and deployed on its own including the RAP source code customplug-ins and the OSGi (aka Equinox) server code

Figure 35 Examining the packages added

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 39 of 57

Creating a deploy script

The application build can be performed with a series of Ant scripts and resourcetemplates As always with these its easiest to start with an example Look at thestructure for orgeclipserapdemofeature

Figure 36 Looking at an existing build structure

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 40 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

The directory structure of the deploy script and templates

srcorgeclipseraptoolsConfigIniCreatorjavaThis creates the content of a simple configini file Run this after the Ant buildscripts (webappBuilderxml and the pdeexportFeatures) have finished thenreplace the content of the configini file in the build

deploymentrapdemowarThis is the final to-be deployed application WAR file

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 41 of 57

scriptwebappBuilderxmlThe Web application build script for a RAP application that uses the equinoxservlet bridge to run in a servlet container This script assumes that the servletbridge project is available in the current workspace

templatesWEB-INFeclipseconfigurationconfiginiThe Eclipse runtime configuration file used to identify the associated bundlesthat need to be started

templatesWEB-INFeclipselaunchini

templatesWEB-INFwebxml

Copy the templates and scripts folders from here to the packagecomdevworkstutorialpofeature

Configure the deploy scripts

Open the featurexml from the comdevworkstutorialpofeature and addthe required plug-ins that should be packaged with the feature

bull comdevworkstutorialpo

bull comibmicu

bull orgeclipsecorecommands

bull orgeclipsecorecontenttype

bull orgeclipsecoredatabinding

bull orgeclipsecoredatabindingbeans

bull orgeclipsecoreexpressions

bull orgeclipsecorejobs

bull orgeclipsecoreruntime

bull orgeclipseequinoxapp

bull orgeclipseequinoxcommon

bull orgeclipseequinoxhttpregistry

bull orgeclipseequinoxhttpservlet

bull orgeclipseequinoxhttpservletbridge

bull orgeclipseequinoxpreferences

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 42 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

bull orgeclipseequinoxregistry

bull orgeclipseequinoxservletbridge

bull orgeclipseosgi

bull orgeclipseosgiservices

bull orgeclipserapjface

bull orgeclipserapjfacedatabinding

bull orgeclipseraprwt

bull orgeclipseraprwtq07

bull orgeclipserapui

bull orgeclipserapuiforms

bull orgeclipserapuiviews

bull orgeclipserapuiworkbench

Figure 37 shows the list of plug-ins to be added

Figure 37 Adding the plug-ins

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 43 of 57

Open the webappBuilderxml from the script folder This builds with the help of thetemplates folder targets and Eclipses PDE export feature You must change theservletbridgedir property to the appropriate path of where that package hasbeen downloaded and stored on your local file system (in this exampleCtempeclipseworkspaceorgeclipseequinoxservletbridge) You must alsochange the value of the webappname property to the folder that appears after thefeature build

Figure 38 Setting the servletbridgedir property

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 44 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

Save the file Youre now ready to build the application

Build the application

From the Package Explorer open the context menu for webappBuilderxml andselect Run As gt Ant Build

Figure 39 Building the plug-ins

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 45 of 57

Eclipse will display the Edit configuration and launch window Give it the name TaskOrganizer then select the JRE tab Be sure the radio button is selected for Runin the same JRE as the workspace This will give the build access to all the requiredplug-ins in the workspace

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

Figure 40 Watching the plug-ins build

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 46 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

When all the builds are complete refresh the comdevworkstutorialpofeatureproject from the Package Explorer by pressing F5 or selecting Refresh from thecontext menu You will now see the directory structure thats been created by thebuild

Figure 41 Seeing the build results in the Package Explorer

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 47 of 57

Configini contains the bundles loaded during the applications initialization Youneed to update this file before deploying A simple way to do this is to run theConfigIniCreatorjava class included in orgeclipserapdemofeature Open this fileand edit the file path to the plug-in directory to represent where your plug-ins will bedeployed In this example we useCtempeclipseworkspacecomdevworkstutorialpofeaturebuildPersonalTaskOrganizerWEB-INFeclipseplugins

Figure 42 Modifying the helper class

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 48 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

Bring up the context menu for this file in the Package Explorer and select Run tocompile and run it It will print the configuration youll need in the console

Figure 43 The output of the helper class

Open the configini file in the editor and copy the contents from the console into itBe sure to save Youre 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 simpledeployment to a servlet container Eclipse makes it simple to package anyWeb-based application in a WAR including RAP applications To create a WAR forthe personal organizer select the WEB-INF directory fromcomdevworkstutorialpofeature project and bring up the context menu SelectExport gt General gt Archive File

Figure 44 Packaging the application as a WAR file

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 49 of 57

Call the file powar and place it in a temp directory of your choice Be sure theentire comdevworkstutorialpofeature tree is checked and be sure to select theCreate only selected directories radio button then click Finish

You now have a self-contained WAR file called powar suitable for deployment inthe servlet container of your choice In the next section we show how to deploy it inTomcat

Deploy on Tomcat

In our configuration Tomcat is running on port 1234 though it is common for it to berunning on port 8080 You can use the built-in Tomcat manager to deploy the powarfile Browse to httplocalhost1234managerhtml

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 50 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

Figure 45 Deploying the WAR via the Tomcat manager

In the section labeled WAR file to deploy enter the path and file name for thepowar you just created and click Deploy Once Tomcat has finished deploying theWAR you can run the personal organizer by browsing tolocalhost1234potaskOrganizer

Figure 46 The personal task organizer running from Tomcat

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 51 of 57

You have now built a stand-alone version of your personal task organizersuccessfully and deployed it on your local servlet container (Just to prove itscompletely free-standing close Eclipse and try it)

If you wanted to make this a live application you would need only move that sameWAR to a publicly available Web server (but remember For the sake of showing offthe features of Ganymede weve kept this simple so your tasks arent currentlystored between sessions although a task organizer that forgets what you had to doyesterday may be just what the world needs The same application boasting fulldesktop-like functionality will run flawlessly on any platform (Windows Mac OS Xor Linuxreg) 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 softwaredownloads on the part of your users

Summary

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

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 52 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

the Web

RAP is a subset of the RCP so it must be downloaded and installed as a separatetarget platform in your Eclipse environment But as a subset it allows you to takeexisting applications youve developed with RCP and with minimal modificationturn them into Web applications With one common code base for business logicyou can easily maintain separate deployment environments for the life of a projectwithout completely different UI logic

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

You can use the Eclipse OSGi implementation (Equinox) and its built-in Jetty serverfor testing But for deployment you need to follow a process to build a stand-aloneapplication 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 andmobile devices tutorial series youll again modify the personal organizer to use theexciting new embedded Rich Client Platform (eRCP) project of Ganymede fordeveloping for mobile devices

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 53 of 57

Downloads

Description Name Size Download method

Personal-organizer sample Part 2 os-eclipse-ganymede-pt2zip132KB HTTP

Information about download methods

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 54 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

Resources

Learn

bull Read Eclipse Ganymede at a glance get an overview of the Ganymederelease

bull For more information on the RCP see the Eclipse wiki

bull For running the Equinox implementation of OSGi on the Web see Equinox in aServlet Container

bull More information on deploying a RAP application can be found in RAPDeployment -- Part 1 Deploying your application with Jetty and RAPDeployment -- Part 2 Deploying your application as a war file of the RAPInsights Blog from Innopract

bull You can read more about Eclipse Theming and Branding from the onlineEclipse help

bull The Eclipse help also has more information on RAP deployment

bull Rich Ajax Platform Part 1 An introduction and Rich Ajax Platform Part 2Developing applications is a two-part article series covering an earlier releaseof RAP

bull Read Expose plug-ins as Web services with Eclipse to get more informationabout Equinox and the Web

bull Developing your first Eclipse RCP application provides a good introduction ongetting started with RCP

bull Check out Brand your Eclipse RCP applications for more information onbranding your RCP application

bull Introducing Subversion Version control for the third millennium offers a primeron Subversion

bull Subversion server code can be obtained from subversiontigrisorg

bull For information on setting up Subversion with Apache see Setting Up ASubversion Repository Using Apache With Auto Updatable Working Copy

bull Understanding the Eclipse p2 Provisioning System by James Sugrue features aQampA on p2

bull Details on the Equinox p2 provisioning system can be found at the Eclipse wikion Equinox

bull There is also a review of p2 by Ryan Slobojan called Eclipse Ganymede Anin-depth look at Equinox p2 (Provisioning Platform)

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 55 of 57

bull Check out the extensive documentation tutorials presentations andscreencasts that illuminate the Eclipse Test amp Performance Tools Platform(TPTP)

bull Learn about qooxdoo a comprehensive and innovative Ajax applicationframework

bull Check out the Recommended Eclipse reading list

bull Browse all the Eclipse content on developerWorks

bull New to Eclipse Read the developerWorks article Get started with EclipsePlatform to learn its origin and architecture and how to extend Eclipse withplug-ins

bull Expand your Eclipse skills by checking out IBM developerWorks Eclipse projectresources

bull To listen to interesting interviews and discussions for software developerscheck out developerWorks podcasts

bull Stay current with developerWorks Technical events and webcasts

bull Watch and learn about IBM and open source technologies and productfunctions with the no-cost developerWorks On demand demos

bull Check out upcoming conferences trade shows webcasts and other Eventsaround the world that are of interest to IBM open source developers

bull Visit the developerWorks Open source zone for extensive how-to informationtools and project updates to help you develop with open source technologiesand use them with IBMs products

Get products and technologies

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

bull Eclipse Ganymede is at the Eclipse Foundation

bull The Subversive plug-in can be downloaded from Eclipseorgsubversive

bull The Subversive connectors are hosted at Polarioncom

bull Check out the latest Eclipse technology downloads at IBM alphaWorks

bull Download Eclipse Platform and other projects from the Eclipse Foundation

bull Download IBM product evaluation versions and get your hands on applicationdevelopment tools and middleware products from DB2reg Lotusreg RationalregTivolireg and WebSpherereg

bull Innovate your next open source development project with IBM trial softwareavailable for download or on DVD

developerWorksreg ibmcomdeveloperWorks

Developing for the Rich Client Platform the Ganymede wayPage 56 of 57 copy Copyright IBM Corporation 1994 2008 All rights reserved

Discuss

bull RAP news portal Discuss RAP with the Eclipse community

bull The Eclipse Platform newsgroups should be your first stop to discuss questionsregarding Eclipse (Selecting this will launch your default Usenet news readerapplication and open eclipseplatform)

bull The Eclipse newsgroups has many resources for people interested in using andextending Eclipse

bull Participate in developerWorks blogs and get involved in the developerWorkscommunity

About the authors

Suresh KrishnaSuresh Krishna has been a programmer since 2000 and has been working on thedomain modeling IDEs and productivity tools Inspired by the IDE evolution anddeveloper productivity he works primarily on the Eclipse plug-ins and RCPapplications Extreme Programming and Scrum are his favorites along withevangelizing Eclipse to the user developer and corporate communities He enjoyshis free time writing blogs and product evaluations

Trebor FenstermakerAlthough hes programmed in Java since 1999 Trebor Fenstermaker was for muchof that time highly suspicious of Java IDEs and was a die-hard command-line usereven doing all his code editing in vi -- until a colleague showed him that he reallycould be more efficient with Eclipse He now evangelizes his fellow UNIXcommand-line refugees on its wonders and enjoys exploring its more powerfulfeatures -- including its endless possibilities for expansion through custom plug-ins

ibmcomdeveloperWorks developerWorksreg

Developing for the Rich Client Platform the Ganymede waycopy Copyright IBM Corporation 1994 2008 All rights reserved Page 57 of 57