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

Desktop applications with RCP, Subversion and p2

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 1, we will use the mature Rich Client Platform (RCP) to develop an application for the desktop using Subversion for source control, and we will package and distribute the application using p2.

Suresh Krishna, Software Developer, Freelance Developer

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, Software Consultant, Sunnyside Avenue Software, LLC

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.



02 September 2008

Also available in Vietnamese Portuguese

Before you start

Develop skills on this topic

This content is part of a progressive knowledge path for advancing your skills. See Open source development with Eclipse: Master the basics

This tutorial is for any Eclipse developer who wants to learn about some of the exciting new features available in Ganymede and for anyone interested in using these features to develop applications that can be deployed on multiple platforms with common code base. You should have an understanding of how to program in the Java programming language, and familiarity with the Eclipse platform and its model of using plug-ins.

About this series

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

About this tutorial

The RCP is an Eclipse architecture that allows a developer to pick and choose the Eclipse plug-ins needed — and only those needed — to build a client desktop application. To demonstrate some of the new features of Ganymede, you will develop a simple RCP application (a personal organizer). In doing so, you will see some of the changes to the RCP in Ganymede, and you will use this application to explore the new Subversion source control and p2 packaging and distribution systems.

Topics include:

  • How to download and install the Ganymede packages.
  • How to set up the Subversion client and store your source in Subversion.
  • How to set up the target platform and switch from one operating system to another (i.e., Mac OS X to Microsoft® Windows® Vista).
  • How to create an application model and user plug-ins.
  • How to create a product definition and package and distributing your application using p2.

System requirements

You need the following technologies to follow along:


Getting started with Ganymede

Before you begin developing your personal-organizer application, you need to download and install the Ganymede package of Eclipse. In this section, you'll see where to download it from and how to set it up to get you going.

Downloading Ganymede

The Ganymede package represents the next incremental release for Eclipse, and as such, means a new installation of the Eclipse platform. As with all Eclipse releases, there are a number of packages to choose from, depending on your development needs. The Eclipse Web site provides a comparison chart, which you can see in Figure 1.

Figure 1. Comparison of Eclipse packages
Comparison of Eclipse packages

For the purposes of this series, you can download the RCP/plug-in version, as it has everything you need to develop and deploy an RCP application (see Figure 2). Choose the version for your operating system, select an appropriate mirror, and download. (The file is quite large — close to 200 MB, depending on your platform — so be patient.)

Figure 2. Download page for RCP/plug-in package of Eclipse Ganymede
Download page for RCP/Plug-in Package of Eclipse Ganymede

Installing and running

When the download is complete, unzip the package where you want Eclipse to be installed, then double-click the Eclipse icon to run. Select a workspace, and Eclipse will take you to the welcome page. From here, choose the Workbench icon (the arrow on the far right of the welcome screen, shown in Figure 3).

Figure 3. Welcome screen for Eclipse setup
Welcome screen for Eclipse setup

So far, none of this is much different from previous releases of Eclipse, though in the next section, you will see some incremental improvements to one of the core components of Eclipse development: the Rich Client Platform.

You have now installed the Ganymede release. But, you may be surprised to learn you haven't installed every package that is part of Ganymede. Next, when you explore Subversion, you will have to separately download and install the relevant package. Although Subversion is considered part of the Ganymede release, licensing restrictions prevent it from being distributed automatically with the rest of the package, requiring you to perform a separate download from within Eclipse.


Subversion control using the Subversive plug-in

Source control is an essential part of any serious software development effort, especially one that supports development distributed across a geographically distributed team (this tutorial's co-authors, for example, are on opposite sides of a continent). Such a system allows for uncoordinated changes to a code base, without fear of one programmer making changes that will adversely affect another — yet without a central authority governing the entire process or the need of close and careful coordination between the programmers.

Subversion is an open source version-control system, similar to CVS, but widely considered its eventual successor. Subversion support for Eclipse has been available for many years using third-party plug-ins, the most popular of which was called Subversive. The Ganymede project took on development of Subversive and added it as a core library of Eclipse. However, outstanding legal issues prevent it from being distributed with the rest of Ganymede, so, for now at least, you must still separately install the Subversive plug-in from within Ganymede.

Follow along to see how we set up Subversive and used it to manage the source code for the personal-organizer application.

Install Subversive

Subversive consists of two parts, each of which must be separately installed. The first is the Subversive plug-in itself, which provides the UI elements to integrate Subversion support into Eclipse. The second part is the connector libraries, and these are separately developed and licensed. To install the Subversive plug-in from within Eclipse, navigate to Help > Software Updates.

Figure 4. Software Updates from the Help menu
Software Updates from the Help menu

Choose the Available Software screen, then click Add Site. For the Location, enter http://download.eclipse.org/technology/subversive/0.7/update-site/ and click OK.

Figure 5. Add Site for Subversive
Add site for Subversive

This will add a list of related plug-ins, but before installing those, click Add Site again, and add the location for the Subversive connectors. Enter http://www.polarion.org/projects/subversive/download/eclipse/2.0/update-site/ for the location and click OK.

Figure 6. Add site for Subversive connectors
Add site for Subversive connectors

You'll see that both update sites have added a number of different possible plug-ins. You can select them all, but the minimal required for now are the ones labeled SVN Team Provider and the Subversive SVN Connectors. Select it from the list and click Install.

Figure 7. Subversive plug-ins
Subversive plug-ins

Eclipse will take you through a standard set of screens for installing the plug-ins, including a screen asking you to review and accept the licensing terms. Work through these screens, and, when promoted, restart your Eclipse workbench. The Subversive plug-ins are now installed.

Set up a repository

Subversion, like CVS, is a server-based source-code repository, which makes it an excellent choice for collaborative software development across distributed teams. The server piece is not a part of Eclipse, and installing and setting up a Subversion server is beyond the scope of this tutorial. However, there are a number of ways to run one, including using Apache (see Resources for more information).

Once you have a Subversion server you can use, you can set up your project to store its source and configurations using the Subversive plug-in. Highlight the project name in the Package Explorer and display its context menu. From there, choose Team > Share Projects. Eclipse will display a screen offering you a choice of versioning systems: CVS, which has been available as a core feature of Eclipse for some time; and SVN, which is the short-hand notation for Subversion, which was enabled when you added Subclipse.

Figure 8. Sharing a project via SVN
Sharing a project via SVN

Select SVN and choose Next. You'll be presented with a screen (shown in Figure 9) where you'll enter the server URL and credentials for your Subversion server. Enter the information for your server. From here, you can accept the defaults for naming the repository that are set on the next screens and click Finish.

Figure 9. Share Project wizard
Share Project wizard

Eclipse will present you with the commit screen for your project (see Figure 10). All the files that are part of our project will be selected by default, but you can choose to keep some from being checked in at this time if you want. You will also be promoted for an initial check-in comment. It's good practice to enter comments on every check-in. Enter your comment and click OK. For the organizer application code, we have all of the files checked.

Figure 10. Subversion Check-in box
Subversion Check-in box

Eclipse has now added all of the files for our organizer to your Subversion repository. If you are using a WebDAV version of Subversion, such as through Apache as we did, you can explore the repository's structure using your Web browser. Simply enter the same URL and credentials you used to set up the repository in Subversive and navigate through the directory tree by way of the hyperlinks on each file or directory.

Figure 11. A view of the Subversion repository through the Web
A view of the Subversion repository through the Web

You can see that our project is now wired to Subversion in the Package Explorer. Each filed under Subversion control has a revision number next to it, and the project itself has the name of the repository next to its name.

Figure 12. The Package Explorer after being shared through Subversion
The Package Explorer after being shared through Subversion

Working with the code in the repository

Like CVS, we can now access the Subversion source-control functions from the Team context menu. To select a file from the Package Explorer that we want to update in the repository, bring up its context menu and select Team. This now shows all the Subversion features in this context menu.

Following is a list of the more common commands we'll use (see Figure 13):

Commit
To save your changes to the repository
Update
To refresh your local copy with the latest from the repository
Revert
To discard your changes and replace them with the latest in the repository
Add to Version Control
To mark newly created local files in the repository (you must then Commit the file to add it to the server).
Figure 13. The Subversion context menu
The Subversion context menu

To delete a file from the repository, delete it from the Package Explorer as you normally would (the Delete item on that file's context menu). Then commit the parent directory of that file. Prior to executing any commit on the server, you will have a chance to review all the changes; for a delete, you will see the name and location of the deleted file.

Subversion is also like CVS in that it uses optimistic locking — that is, rather than checking out a file for editing and locking it from others, code can be edited locally at will and checked in when finished. At the time of check-in, any conflicts are then resolved.


Creating an RCP application in Ganymede

In this section, you will create the organizer application — a simple, one-view RCP app — by using the Eclipse wizards to create the RCP framework, adding the code for the logic and running it.

Creating an RCP application framework

Start by creating a new project by selecting File > New > Project. Eclipse will display the New Project Wizard, as shown below.

Figure 14. The New Project wizard
The New Project wizard

Choose Plug-in Project and select Next. The next screen will allow you to enter details of the project. Because you'll be creating a personal-organizer application, name the project com.devworks.tutorial.po (for "personal organizer"). Use the default location for the project (Eclipse will create a folder under your workspace named after the project). Be sure the Create a Java Project checkbox in the Project Settings is selected, and keep the defaults of src and bin for the folder names. For the target platform, select the radio button for Eclipse version and choose 3.4 from the drop-down menu. Leave the checkbox for Add project to working sets empty and select Next.

The New Plug-in Project wizard shown in Figure 15 will continue to the Plug-in Content screen, where you'll enter information about the plug-in that will be added to the manifest file that describes the plug-in and allows you to set up options for your plug-in.

Figure 15. New Plug-in Project wizard screen
New Plug-in Project wizard screen

For the plug-in ID, choose the project name you used earlier (com.devworks.tutorial.po). Since this is the first release of your plug-in, leave the value of the plug-in version the default of 1.0.0. Likewise, you can leave the default values of Po Plug-in for the plug-in name and DEVWORKS for the plug-in provider.

The Execution Environment drop-down menu allows you to target a specific runtime environment for the plug-in, from a selection of environments know to Eclipse. For this tutorial, select JavaSE-1.6.

The next section sets the plug-in options. Be sure the box is checked for Generate an activator, a Java class that controls the plug-in's life cycle and change the default Activator class name, com.devworks.tutorial.po.Activator, to com.devworks.tutorial.po.Activator.

Because this plug-in will have a visual component, be sure to select the checkbox for This plug-in will make contributions to the UI. Leave the checkbox for Enable API Analysis blank. This is beyond the scope of this tutorial (see Resources for more information). Finally, since this is going to be a RCP application, select the Yes radio button for the question, Would you like to create a rich client application?, then select Next to continue with the wizard.

Figure 16. Plug-in content screen in the New Plug-in Project wizard
Plug-in content screen in the New Plug-in Project wizard

Figure 17 asks what kind of RCP template you'd like to use. Because our project is going to have a visual component, select the RCP Application with a View, then select Next.

Figure 17. Templates screen of New Plug-in Project wizard
Templates screen of New Plug-in Project wizard

On the final screen of the wizard shown in Figure 18, The Single View RCP application, you'll have an opportunity to enter information relevant to the template you just chose. Give your application window title the name Personal Organizer. Leave the Java™ package name the default of com.devworks.tutorial.po and name the application class TaskOrganizerApplication. Finally, select the Add branding tag, which will display a splash screen when your application starts. Click Finish.

Figure 18. Single-view RCP properties screen in New Project wizard
Single-view RCP properties screen in New Project wizard

Eclipse will ask if you want to switch your workbench view to the Plug-in Development perspective. This perspective will contain view of everything we need to see for this effort, so say Yes. The wizard finishes by generating template files related to a single-view RCP application in the project directory in your workspace, as well as a standard directory structure useful for plug-in development. It then presents you with your workbench screen in the Plug-in Development perspective.

Figure 19. Plug-in perspective of workbench after finishing the New Project wizard
Plug-in perspective of workbench after finishing the New Project wizard

The template files created by Eclipse are listed under src in the Package Explorer. Briefly, here are their functions:

Activator
The plug-in's launching point
TaskOrganizerApplication
The Application Activator that implements Application and defines the application's life cycle
ApplicationActionBarAdvisor
The class responsible for managing the life cycle of actions added to windows
ApplicationWorkbenchAdvisor
The class that initializes the perspective
ApplicationWorkbenchWindowAdvisor
The class responsible for many of the visual aspects of windows (size, statusline, menubars, etc.)
Perspective
The Views and Editor that will be visible in the application
View
A simple Table viewer with three elements

Also, the icons folder contains bitmap resources for icons associated with the application; and the splash.bpm is the graphic used for the application's splash screen.

These template files are an excellent start on creating an RCP plug-in, and you will build on these to create the organizer. But they, in fact, form a complete application of their own (albeit not one that does much) that you can run right now.

To see these work together, go to the Package Explorer window and highlight the project name, at the very top of the tree view, then bring up the context menu (right-click on Windows; control-click on Mac OS X, etc). Select Run As > Eclipse Application. You should shortly get a splash screen, followed by a tree view with three elements.

Figure 20. Organizer default tree view from template
Organizer default tree view from template

You have everything you need at this point to build out a simple organizer with a single list view.

Coding the organizer application

From here, you're ready to start coding the organizer application. The organizer will feature a single screen with a list of tasks. Each task will contain a description, a priority, an owner, and a place to record the percentage complete. There will be buttons to add or delete these tasks, as well as a button to close the entire application. To ensure that we have something to work with right away, the application will pre-populate the task manager with ten sample tasks with a variety of settings. To keep this simple, the data you enter will not be stored anywhere between sessions.

The details of this code aren't particularly interesting to what we're trying to demonstrate in this tutorial, so you are encouraged to download it. Many of the files, in fact, do not change from the template versions, but there are some changes you'll make to the view.

Create a new package under the project called View. Under here, you'll create files related to the visual elements of the application. Start by moving the current template-created View class under this new package and renaming it PersonalTaskView.

Because you have changed the View class name, you'll have to change the plug-in's definition of its main View class. To do this, open the META-INF/MANIFEST.MF file in the editor and switch to the Extensions tab, as shown in Figure 21. Expand the org.eclipse.ui.views extension in the list view and highlight the View class. Eclipse will display the properties of that class on the right side of the screen. Change the class to the new package and name: com.devworks.tutorial.po.view.PersonalTaskView. Change the name of the class to PersonalTaskView. Be sure to save your changes.

Figure 21. Changing the View class
Changing the View class

Because the organizer is really a collection of tasks, the model object will be called PersonalTaskModel (see Listing 1).

Listing 1. PersonalTaskModel class, representing a single task
package com.devworks.tutorial.po.view;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
import java.util.Set;
import java.util.Vector;

public class PersonalTaskModel {

    private final int COUNT = 10;
    private List<PersonalTask> tasks = new ArrayList<PersonalTask>(COUNT);
    private Set changeListeners = new HashSet();

    static final String[] OWNERS_ARRAY = { "-", "Bill", "Larry", "Jo", "Harry", 
"Hulk" };
    static final String[] PRIO_ARRAY = { "-", "Low", "Medium", "High" };
    
    public PersonalTaskModel() {
        super();
        this.initData();
    }
    
    private void initData() {
        PersonalTask personalTask;
        for (int i = 0; i < COUNT; i++) {
            personalTask = new PersonalTask("Sample Task "  + (i+1));
            personalTask.setTaskOwner(OWNERS_ARRAY[i % 5]);
            personalTask.setTaskPrio(PRIO_ARRAY[i % 3]);
            tasks.add(personalTask);
        }
    };

    public String[] getOwners() {
        return OWNERS_ARRAY;
    }
    
    public String[] getPrios() {
        return PRIO_ARRAY;
    }
    
    public List<PersonalTask> getTasks() {
        return tasks;
    }
    
    public void addTask() {
        PersonalTask task = new PersonalTask("New Sample Task");
        tasks.add(tasks.size(), task);
        Iterator iterator = changeListeners.iterator();
        while (iterator.hasNext())
            ((IPersonalTaskViewer) iterator.next()).addTask(task);
    }

    public void removeTask(PersonalTask task) {
        tasks.remove(task);
        Iterator iterator = changeListeners.iterator();
        while (iterator.hasNext())
            ((IPersonalTaskViewer) iterator.next()).removeTask(task);
    }

    public void taskChanged(PersonalTask task) {
        Iterator iterator = changeListeners.iterator();
        while (iterator.hasNext())
            ((IPersonalTaskViewer) iterator.next()).updateTask(task);
    }

    public void removeChangeListener(IPersonalTaskViewer viewer) {
        changeListeners.remove(viewer);
    }

    public void addChangeListener(IPersonalTaskViewer viewer) {
        changeListeners.add(viewer);
    }

You can see that Listing 1 defines the structure of a task, as well as methods that operate on it. It also, in this case, defines the sample data with which it's initially populated.

The PersonalTaskViewer class defines the TableViewer, which is the building block to hold the list of tasks. Creating the PersonalTaskViewer involves creating the TableViewer, adding the Content and Label Provider, finally initializing the PersonalTaskModel and setting this model as input to the TableViewer.

Listing 2. addChildControls() method fragment from PersonalTaskViewer
tableViewer = new TableViewer(table);
tableViewer.setUseHashlookup(true);
tableViewer.setColumnProperties(columnNames);

// Create the cell editors
CellEditor[] editors = new CellEditor[columnNames.length];

// Column 1 : Completed (Checkbox)
editors[0] = new CheckboxCellEditor(table);

// Column 2 : Description (Free text)
TextCellEditor textEditor = new TextCellEditor(table);
((Text) textEditor.getControl()).setTextLimit(60);
editors[1] = textEditor;

// Column 3 : Priority (Combo Box) 
editors[2] = new ComboBoxCellEditor(table, taskList.getPrios(), SWT.READ_ONLY);

// Column 4 : Owner (Combo Box) 
editors[3] = new ComboBoxCellEditor(table, taskList.getOwners(), SWT.READ_ONLY);

// Column 5 : Percent complete (Text with digits only)
textEditor = new TextCellEditor(table);
((Text) textEditor.getControl()).addVerifyListener(
    new VerifyListener() {
        public void verifyText(VerifyEvent e) {
            e.doit = "0123456789".indexOf(e.text) >= 0 ;
        }
    });
editors[4] = textEditor;

// Assign the cell editors to the viewer 
tableViewer.setCellEditors(editors);
// Set the cell modifier for the viewer
tableViewer.setCellModifier(new TaskCellModifier(this));
// Set the default sorter for the viewer 
tableViewer.setSorter(new PersonalTaskSorter(PersonalTaskSorter.TASK_DESC));

// Create and setup the TableViewer
tableViewer.setContentProvider(new PersonalTaskContentProvider());
tableViewer.setLabelProvider(new TaskLabelProvider());

// The input for the table viewer is the instance of PersonalTaskModel
taskList = new PersonalTaskModel();
tableViewer.setInput(taskList);

PersonalTaskContentProvider class has methods that would return the elements to display in the TableViewer, when its input is set to the given element. This class also defines basic operations on the PersonalTask like addTask(), removeTask(), and updateTask() from IPersonalTaskViewer.

PersonalTaskLabelProvider class provides labels and images for the table's column data.

Listing 3. getColumnText() from PersonalTaskLabelProvider
public String getColumnText(Object element, int columnIndex) {
    String result = "";
    PersonalTask task = (PersonalTask) element;
    switch (columnIndex) {
        case 0:
            break;
        case 1 :
            result = task.getTaskDesc();
            break;
        case 2 :
            result = task.getTaskPrio();
            break;
        case 3 :
            result = task.getTaskOwner();
            break;
        case 4 :
            result = task.getPercentComplete() + "";
            break;
        default :
            break;     
    }
    return result;
}

TaskCellModifier is used as a cell modifier to access the data model from the cell editor in an abstract way. It offers methods to check if TaskModel element's property can be edited, retrieve a value a TaskModel element's property and to store a cell editor's value back into the model element's property.

PersonalTaskSorter class takes the elements provided by the PersonalTaskContentProvider and sorts them in the given order. compare() method sorts the elements depending on the SortType.

Listing 4. compare() from PersonalTaskSorter
public int compare(Viewer viewer, Object o1, Object o2) {
    PersonalTask task1 = (PersonalTask) o1;
    PersonalTask task2 = (PersonalTask) o2;
    switch (sortType) {
        case TASK_DESC :
            return compareDescriptions(task1, task2);
        case TASK_PRIO :
            return comparePrios(task1, task2);
        case TASK_OWNER :
            return compareOwners(task1, task2);
        case TASK_COMPLETE :
            return comparePercentComplete(task1, task2);
        default:
            return 0;
    }
}

PersonalTaskView is the View class that extends ViewPart.

Listing 5. createPartControl() from PersonalTaskView
public void createPartControl(Composite parent) {
    viewer = new PersonalTaskViewer(parent);
    viewer.getCloseButton().addSelectionListener(new SelectionAdapter() {
        public void widgetSelected(SelectionEvent e) {
            handleDispose();
        }
    });
}

PersonalTaskOrganizer Application's Perspective uses this View to display in the perspective (see Listing 6). In doing this, you have established the connection between the code templates generated by RCP application wizard and the PersonalTaskView.

Listing 6. createInitialLayout() from perspective
public void createInitialLayout(IPageLayout layout) {
    String editorArea = layout.getEditorArea();
    layout.setEditorAreaVisible(false);
    layout.setFixed(true);
    layout.addStandaloneView(PersonalTaskView.ID,  false, IPageLayout.LEFT, 1.0f, 
editorArea);

Run your application the way you did before, by selecting Run > Eclipse Application from the context menu of the project in the Package Explorer. After the splash screen, you'll see the task manager, pre-populated with some sample tasks.

Figure 22. Organizer task manager view
Organizer task manager view

Congratulations! You've created a simple RCP plug-in that can now be targeted to run on a desktop environment of your choice.


Creating the product definition

In previous releases of the RCP in Eclipse, the plug-ins included in your application for distribution were limited to those available in the target directory. With Ganymede, you now have the ability to specify exactly what plug-ins you need, resulting in a more precise distribution. In this section, you'll package your application so it can be distributed in a tight package, containing only what's needed to run.

Setting up the target environment

To set up the target environment, highlight the project name in the Package Explorer and select New > Product Configuration from the context menu.

Figure 23. Product Configuration from context menu
Product Configuration from context menu

This will launch a wizard that allows you to edit the configuration of your RCP application (see Figure 24). In the first screen of the wizard, set the parent folder to com.devworks.tutorial.po and name the file TaskOrganizer.product. Select the radio button for Initialize the file content to Create a configuration file with basic settings, then select Finish.

Figure 24. The New Product Configuration wizard
The New Product Configuration wizard

Eclipse has created a file called TaskOrganizer.product that contains a template definition of the configuration, which will be displayed in the editor, defaulted to the Overview tab.

Specify the name that appears in the title bar of the application as Personal Organizer, and the product identifier is com.devworks.tutorial.po.product. The product version number is 1.0.0, and the application is com.devworks.tutorial.po.application. These latter two are selected from a drop-down list. Finally, your application's product configuration will be based on plug-ins, so select that as the radio button. Since you are editing a properties file, be sure to save your work from the file menu or with the shortcut key appropriate for your operating system.

Now select the Configuration tab, where you will add the plug-ins you need and only the plug-ins you need (see Figure 25). Start by adding the plug-in you just wrote, by clicking Add. A dialog will appear displaying all the known plug-ins; select com.devworks.tutorial.po and click OK.

Figure 25. Selecting a plug-in to use for configuration
Selecting a plug-in to use for configuration

Your plug-in will now appear in a list on the Configuration tab of the TaskOranizer.product editor (see Figure 26).

Figure 26. Taskorganizer.product editor view
Taskorganizer.product editor view

Having told Eclipse that this is one of the plug-ins you need for your distribution, it can now intuit all the dependent plug-ins and add them automatically. Click Add required plug-ins, and Eclipse will add the additional plug-ins needed to the list.

Figure 27. The additional plug-ins
The additional plug-ins

Save the changes, then navigate to the Launching tab (see Figure 28). Here, you can provide the name of the executable for the application. Enter PersonalOrganizer in the Launcher Name field.

Figure 28 also allows us to choose icons for the application. Each target OS has a different means of setting these, and you can set the icon for your operating system by choosing it from list of tabs and entering a file name. If you don't have an icon you'd like to use for now, you can leave it blank and a default will be provided.

Figure 28. The Launching tab
The Launching tab

Navigate to the Splash tab and click Browse to see a list of available plug-ins that may contain the splash bitmap. Recall that the templates created by the New Project wizard created a sample bitmap, and so, for this tutorial, you will navigate to this current project. It is possible, though, if you had a number of projects, that the branding would be identical for many of them and you would wish to reuse a bitmap from another plug-in you created, this would make that easy.

Figure 29. Selecting the splash-screen plug-in location
Selecting the splash-screen plug-in location

Select your plug-in, named com.devworks.tutorial.po, and it will be added to the Splash tab as the location of the splash screen.

Figure 30. Entering the splash-screen information
Entering the splash-screen information

Finally, select the Branding tag and add the two GIF files created by the New Project wizard under the icons directory. These are images that will display with the window when it runs. You may also create your own, either as GIF or PNG, and store them with your plug-in.

Figure 31. The Branding tab
The Branding tab

You can now run the application on your target environment. Select File > Export > Plug-in Development > Eclipse Product.

Figure 32. Export selection screen
Export selection screen

Select Next, and Eclipse will start the Export wizard shown in Figure 33.

Figure 33. The Eclipse Product Export screen
The Eclipse Product Export screen

Use Browse to select the TaskOrganizer.product configuration file shown in Figure 34. This is the file that contains the definition of your plug-in as a stand-alone product, and the export will use this to determine what should be included in the distribution.

Figure 34. Selecting the product configuration
Selecting the product configuration

For the Root Directory, enter TaskOrganizer Ensure the checkbox is selected for Synchronize before exporting. For the destination directory, choose a location where you would like to deploy this application (in the example here, we will just be using a temp directory, but you may choose to use an application deployment directory). Finally, under Export Options, select Include source code, then click Finish.

Figure 35. The completed Eclipse Product Export screen
The completed Eclipse Product Export screen

What Eclipse creates in the temp directory as a result of the export depends on your target platform. On Mac OS X, for example, it will look like Figure 36.

Figure 36. Files created by the export
Files created by the export

The executable it has created is called PersonalOrganizer. On Windows, it will create a PersonalOrganizer.exe. Double-click the executable, and the organizer application will run as a native application on your desktop.

Creating a distribution for another platform

What if you want to deploy your RCP on a desktop other than your current default? Suppose you're developing on Mac OS X, but would like your application to run on Windows Vista? This is one of the more exciting improvements to RCP development in Ganymede.

In previous releases of Eclipse, you had two choices: either switch your development to Windows or build your package with every known plug-in. This latter approach meant your distribution would have many more plug-ins than necessary for your target platform.

Ganymede solves this by allowing you to choose the plug-ins relevant to the platform of your choice, without having to move your development to that platform. To target a platform different from your current host environment, you define a new target platform. The target platform is, essentially, an Eclipse configuration that contains the minimal set of plug-ins that Eclipse will build an application against. By default, Eclipse is configured to use itself as the default target, which gives the RCP plug-ins potential access to everything loaded in the IDE. By setting up a special target platform, you can take direct control over the set of plug-ins your RCP application can potentially have access to and even have your RCP application target different plug-in versions than are currently loaded in your IDE environment.

To create a new target, highlight the project from the Package Explorer and display its context menu. Select New > Target Definition.

Figure 37. Target definition from the new context menu
Target definition from the new context menu

Select the project shown in the tree view as the parent folder (com.devworks.tutorial.po) and use the file name taskorganizer-other.target. Finally, select Use an existing target definition from the radio buttons for Initialize the file content and make sure the drop-down shows Base RCP (Binary Only), then click Finish.

Figure 38. The target definition creation screen
The target definition creation screen

A properties file will now open in the editor pane. Change the target name to an operating system different from your current one. In this example, since we are developing on Mac OS X, we'll choose Windows and name it as such.

If you wanted to deploy to a working set of plug-ins that were unique to an older version of Eclipse, you could select the target location by choosing Location and selecting the directory on your file system where that older version was stored, which his would restrict the available plug-ins to those used by that version. For now, you'll deploy to the current version of Eclipse, so select Use the same target location as the host (running) platform is using for the target location.

Figure 39. The target properties file editor
The target properties file editor

Navigate to the Environment tab. Here, enter the details on your target environment. Again, for this example, we're developing on Mac OS X, so we'll show settings that would be appropriate for a Windows deployment, but you can choose the settings for any of the supported platforms you'd like to try.

Figure 40. The target environment tab
The target environment tab

In this example, because the current default JRE for Mac OS X is V1.5, we show changing the JRE version to J2SE V1.6, since this is widely available on Windows systems.

When you're finished editing, be sure to save the file. You can now use this target definition to create the product.

Click the link in the upper right-hand that says Set as Target Platform. You have created a target platform that could be used to distribute your application with the plug-ins needed for a platform other than the one you're currently developing with. In the next section, you'll see how to package your application for distribution with the new p2 system in Ganymede.


Packaging and distributing RCP applications using p2

The last enhancement you'll look at in this tutorial is a new method of packaging and distributing plug-ins. In previous versions of Eclipse, the packaging was essentially creating a ZIP archive of all the relevant files, along with an appropriate manifest, and placing it on a publicly available server. These could then be installed either by using the Help > Updates feature from the menu, or many users simply opted to download and unzip the plug-in archive directly in the appropriate Eclipse installation folder. The p2 mechanism streamlines this process, allowing for a clean packaging and automated distribution. In this section, you'll create a p2 update site and package your plug-in for distribution through it.

Creating the feature list

Packages contain features, which themselves are composed of plug-ins. So to package your organizer plug-in for p2, you have to start by creating a feature list. You do this by using the new project wizard. From the Eclipse menu, select New > Project > Plug-in Development > Feature Project and click Next.

Figure 41. Creating a new feature project
Creating a new feature project

Name this project com.devworks.tutorial.po.feature and store it in the default location for simplicity. Leave the feature ID as its default of the project name, but change the feature name to Personal Task Organizer. Leave the rest of the fields at their defaults, then click Next.

Figure 42. Feature properties editor
Feature properties editor

Eclipse will display a screen asking for the plug-in that should be used to initialize this feature set. Since this feature set is all about your personal-organizer plug-in, select com.devworks.tutorial.po from the list, then Finish.

Figure 43. Selecting the plug-in that provides the definition of the feature
Selecting the plug-in that provides the definition of the feature

The wizard completes by creating a new project and populating a file called feature.xml. This contains information about the features, dependencies, licensing, and build instructions for your plug-ins — in short, everything needed to build a distribution.

Figure 44. The feature.xml shown in the editor
The feature.xml shown in the editor

The update site you'll create next will use this feature list.

Create the update site

Now that you have a feature set, you can use this create a site from which to distribute it. What is created is a set of files that can be made publicly available on the Internet or on a corporate intranet, or distributed on disc, or as a ZIP file. The files and structure created are simply made in a directory that you can then distribute as you wish.

Creating a new update site is simple. Once again, the New Project wizard steps in. From the Project Explorer, select New > Project > Plug-in Development > Update Site Project, then select Next.

Figure 45. Creating a new update site project
Creating a new update site project

This will start a wizard that will create a new project that represents your update site (see Figure 46). Enter com.devworks.tutorial.updatesite as the project name and save it on your local file system. (Selecting the default location will create the update site in your current workspace; choosing an external location will make this tutorial a bit clearer, but you decide.) Click Finish.

Figure 46. The update site project properties editor
The update site project properties editor

The wizard will create a project with a single site.xml file, displayed in the editor. It describes the package as the updater will see it.

Figure 47. The site.xml shown in the editor
The site.xml shown in the editor

You now need to configure that site.xml to add a category and features. This fleshes out the update site with the material you are intending it to distribute. Click New Category on the site.xml editor, and the right side of the editor will display properties you will edit (see Figure 48). Enter Personal Task Organizer for the name, and Tutorial for the label. You can enter a description of your choice; we used This is a Personal Task Organizer.

Figure 48. Adding the category
Adding the category

Now highlight the Personal Task Organizer on the left-side list box, then click Add Feature. Eclipse will display a list of available features, including the one you created earlier (see Figure 49). Select com.devworks.tutorial.po.feature from the list, then click OK.

Figure 49. Selecting the feature to add to the update site
Selecting the feature to add to the update site

This will add it to the list of features in your category.

Figure 50. Feature shown in the site.xml editor
Feature shown in the site.xml editor

You're ready to build out your distribution physically on your disk. Save your edits, then highlight the Personal Task Organizer again in the list of categories. Click Build All, and this will create an update site in your given path.

Congratulations! You have created a distribution of your organizer, suitable for publishing to the world. Let's see how it would look to a user seeking to download and install it in his Eclipse environment, by loading it into your own Eclipse environment.

Loading the local site

You will add your plug-in the same as you did the Subversive plug-in, by way of the Software Updates function. Navigate to Help > Software Updates, then click Add Site. This time, however, instead of a URL on the Web, click Local, and Eclipse will display a file browse box. Navigate to the directory where you created your update site, click OK, then OK again on the Add screen.

Figure 51. Adding the location of the new site in Software Updates
Adding the location of the new site in Software Updates

Your update site now appears in the list of available updates.

Figure 52. The organizer in the software update list
The organizer in the software update list

To install your plug-in, select it from the list, then click Install. You will see your plug-in listed in a standard plug-in install screen.

Figure 53. The organizer installation screen
The organizer installation screen

Click Next, and you will be presented with a license screen (see Figure 54). Since you didn't enter a license, you'll see a default message, but be sure to select I accept, then click Finish.

Figure 54. Licensing terms screen
Licensing terms screen

Eclipse will install the organizer plug-in and prompt for a restart. After the restart, you will find your plug-in under Window > Show View > Other > Other.

Figure 55. Opening the organizer
Opening the organizer

Click OK, and your personal organizer will load and run within the Eclipse workbench.

Figure 56. The organizer in the Eclipse workbench
The organizer in the Eclipse workbench

Your personal organizer is now a part of your Eclipse workbench ready for you to use alongside everything else that makes up the Eclipse experience.


Summary

The Ganymede release is an exciting addition to the long and rich tradition of Eclipse. This tutorial touched on some of the new features that will make developing plug-ins easier, and make their distribution cleaner and more efficient. The RCP now has the ability to package only those plug-ins you need or want. Subversion support is now standard with Eclipse and will continue to become more integrated with the workbench, giving you full support for this next-generation source-control system.

The p2 packaging and distribution system represents an evolutionary leap in the deployment model, allowing for a simple packaging and distribution, which is cleaner and more standardized than previous versions of Eclipse. You explored all these features by creating a simple one-screen RCP personal-organizer application, packaging it for deployment, and seeing how you could create an environment for deployment different from your current environment. You stored your source for this application Subversion through the Subversive plug-in, allowing you to track your changes and collaborate easily with others. And you learned how to package your plug-in for deployment using the new p2 distribution system, making it easy for others to download and install your work.

In Part 2 of this series, you'll expand on the work you did here by modifying the organizer to use the Rich Ajax Platform to run your application as a native application on the Web.


Download

DescriptionNameSize
Personal-organizer sampleos-eclipse-ganymede-pt1.zip102KB

Resources

Learn

Get products and technologies

Discuss

  • 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.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Open source on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Open source
ArticleID=333953
ArticleTitle=Using Eclipse Ganymede to develop for the desktop, Web and mobile devices, Part 1: Developing for the Rich Client Platform, the Ganymede way
publish-date=09022008