Developing your first Eclipse RCP application
Crafting a rich client application is easier than ever, thanks to Eclipse V3.1
Before you start
This tutorial is for developers who would like to learn how to use the Eclipse Rich Client Platform (RCP). Eclipse has evolved to become a platform that can host a wide range of applications serving a wide variety of end users. Consider RCP as an integration platform with the same raw function as Eclipse, but one with a smaller overall footprint and a more flexible user interface. RCP opens the door to achieving desktop applications written in the Java™ programming language.
About this tutorial
This tutorial builds an application using the Eclipse RCP. The example application is divided into four sections, each building on the previous one. You start by creating a basic RCP application with the help of one of the Eclipse-supplied RCP templates. Next, you add some actions, a preference page, a view, and Help to the basic RCP application. This is followed by branding and turning the basic RCP application into a product. The final step takes you through packaging and deploying the RCP product outside of Eclipse.
This tutorial assumes basic programming knowledge. Knowledge of the Java programming language and Eclipse is a plus, but not required.
The following tools are needed to follow along:
- Eclipse is the platform upon which RCP resides. Download Eclipse V3.1.x from Eclipse.org.
- Java technology
- Eclipse and all its plug-ins need Java technology. Download Java technology from Sun Microsystems or from IBM.
Be sure to read the installation section for helpful step-by-step instructions.
What is the Rich Client Platform?
Originally, the Eclipse platform was designed to serve as an open tools platform. However, starting with Eclipse V3.0, it was re-architected so that its components could be used to build just about any client application. The minimal set of plug-ins needed to build a rich client application is collectively known as the Rich Client Platform (RCP). These rich applications are still based on a dynamic plug-in model, and the GUI is built using the same toolkits and extension points. However, the key difference is that the workbench is under fine-grain control of the plug-in developer with RCP applications. Note that the Eclipse IDE is itself an RCP application.
What RCP requires
To build an RCP application with a GUI, you need the following plug-ins and their prerequisites: org.eclipse.ui and org.eclipse.core.runtime. As of Eclipse V3.1.1, the combined disk footprint for the RCP, including the above plug-ins, startup.jar and the eclipse.exe executable, is about 6.6 MB. Now, RCP applications are free to use any API deemed necessary, and they can require any plug-ins above the bare minimum, such as Help UI and Update Manager.
The workspace resource model provided by the org.eclipse.core.resources plug-in is not considered part of the RCP. While this is the underlying data model for the Eclipse IDE, the RCP makes no assumptions about the underlying data model of the application being built. The data model could be files in the local file system, a remote database, or anything else. If it makes sense for the application, org.eclipse.core.resources can be included and used as the application's data model, but this is not required.
The org.eclipse.ui.ide plug-in is layered on top of the generic workbench (org.eclipse.ui) and defines the application for the Eclipse IDE, on top of which sit the other IDE components, such as the Java Development Tools (JDT), Plug-in Development Environment (PDE), Debugger, and Team support. The IDE instantiates the generic workbench, configuring it with IDE-specific menu and toolbar items, and adding IDE-specific views, preference pages, and other extensions. The IDE uses the workspace resource model as its underlying data model. The org.eclipse.ui.ide plug-in and the extensions defined within it are not designed to be reused in other RCP applications.
The Eclipse runtime defines the plug-ins (org.eclipse.osgi and org.eclipse.core.runtime) on which all other plug-ins depend. The Open Services Gateway Initiative (OSGi) framework refers to plug-ins as bundles. Bundles together with the OSGi framework specify and implement the process for Java class-loading, prerequisite management, and the bundle's life cycle. The Eclipse core runtime is responsible for finding and executing the main Eclipse application and for maintaining a registry of plug-ins, their extensions, and extension points. In addition, the runtime also provides an assortment of utilities, such as logging, debug trace options, a preference store, and a concurrency infrastructure.
Hello World RCP application overview
Upon completion of the Hello World RCP application, you will end up with two plug-ins and three features.
Table 1. Description of Hello World RCP application plug-ins and features
|com.ibm.plte plug-in||Defines the RCP application |
Defines feature and product branding information
|com.ibm.plte.ui plug-in||Defines several Eclipse functions, including action, preference, view, and Help|
|com.ibm.plte feature||Defines the Hello World RCP application plug-ins |
Defines the two included features below
|com.ibm.plte.help feature||Defines the dependencies on Help plug-ins (eight total)|
|org.eclipse.rcp feature||Defines the dependencies on RCP plug-ins|
You will create the Hello World RCP application in Eclipse SDK V3.1.1. When you open the Eclipse workbench, you will already have com.ibm.plte.help feature added to your workspace.
This tutorial is divided into four sections:
- Create a minimal Hello World RCP application
- Add several Eclipse functions to the Hello World RCP application
- Create a Hello World RCP product
- Feature branding
- Deploy and run Hello World RCP product outside of Eclipse
Note that if the intent is to build Eclipse tools that will be integrated into an Eclipse IDE-based product, you do not create an RCP application or an RCP product. An Eclipse IDE-based product will already have defined an application and a product. However, you must still provide feature branding for your Eclipse tools.
Step 1: Create minimal Hello World RCP application
- Click Ctrl+N to open the New wizard.
- Select Plug-in Project and click Next.
com.ibm.pltein the Project name text field and click Next.
- Answer Yes to the question "Would you like to create a rich client application?" Click Next.
- Select Hello RCP template and click Finish.
- The Open Associated Perspective dialog box may pop up. Click Yes.
Your workbench should look similar to the following:
Figure 1. Plug-in com.ibm.plte's plugin.xml in the PDE perspective
The Hello RCP template is very powerful and performs many tasks behind the scenes. The template generates a plug-in project, and adds two extension points and six Java classes. Each extension point and Java class is described below.
Table 2. Description of artifacts generated by Hello RCP template
|org.eclipse.core.runtime.applications||This extension point tells the Eclipse runtime the name of
your main program and the class that implements
Note that since the Eclipse IDE is an RCP application, it also defines this extension point. In the Eclipse IDE, the application name is org.eclipse.ui.ide.workbench, and the class is org.eclipse.ui.internal.ide.IDEApplication.
|org.eclipse.ui.perspectives Perspective.java||A perspective is a set of visible views, editors, and
menus that include positions and sizes. In an RCP application,
you must define at least one perspective and make it the
default. Perspectives are created by implementing
|PltePlugin.java||This class is referred to as the plug-in class. An optional singleton class can be used to store global information for the plug-in. It is also a convenient place to put static utility functions used by other classes in the plug-in.|
|Application.java||Application.java is a class that acts as the RCP application's
main routine. It is similar to a Java class with
The workbench is declared and maintained as part of the RCP framework. There is only one workbench, but it can have more than one visible top-level workbench window. For example, in the Eclipse IDE, when you first start Eclipse, you will see one workbench window, but if you select Window > New Window, a second window pops up. So now there are two workbench windows, but only one workbench.
|ApplicationWorkbenchWindow.java ApplicationWorkbenchAdvisor.java ApplicationActionBarAdvisor.java||There are three advisor classes used to configure all aspects of the workbench, such as the title, menu bars, and so on. These are the most important classes for an RCP developer to understand. You extend the base version of the class -- for example, WorkbenchAdvisor -- in the RCP application and override one or more of the methods to set whatever options you want. See product documentation for details.|
Step 2: Run minimal Hello World RCP application
Make sure the overview page of the com.ibm.plte (plugin.xml) editor is open. Click Launch an Eclipse application from the Testing section. Your minimal Hello World RCP application should look like what is shown below.
Figure 2. Minimal RCP application
In two simple steps, you created and ran a minimal RCP application. At this point, the RCP application contains a single perspective, but no other Eclipse functions (no menus, actions, views, preference pages, Help books, etc.). You will add these functions as you continue.
Step 3: Add menus and actions to the minimal Hello World RCP application
Menus and actions can be added in two ways. Here, we add them to the RCP application programmatically. Later, you will add them via extension points.
Five menus are added:
- Window/Open perspective
- Window/Show view
And six actions are added:
- Window/Open perspective/Other
- Window/Show view/Other
- Help/Help contents
The actions you add here are pre-built actions normally included in the Eclipse IDE. However, the RCP provides them for your convenience. To understand how these menus and actions are defined, look at ApplicationActionBarAdvisor.java in the com.ibm.plte.help feature project. Note that using the actions framework, you can contribute your own actions. You will do this using extension points later.
Steps to take:
- Replace the com.ibm.plte plug-in's com.ibm.plte.ApplicationActionBarAdvisor.java with a file having the same name from the com.ibm.plte.help feature project.
- Ensure that you closed the RCP application you launched
previously. Go back to the overview page of the com.ibm.plte
(plugin.xml) editor and click Launch an Eclipse application
from the Testing section. Your RCP application should have several
Figure 3. RCP application with some menus
- Click Window > Open Perspective > Other. In the Select Perspective dialog box, you will see one perspective labeled Plte Perspective (default). This is the perspective you created using the Hello RCP template.
- Click Window > Show View > Other. You should see an empty Show View dialog box. This is because you have not added any views to the RCP application yet. We do this in the next section.
- Click Window > Preferences. You should see an empty Preferences dialog box. This is because you have not added any preferences to the RCP application yet. We do this in the next section.
- Click Help > About. The About dialog box will be empty, except for three buttons. The About dialog box gives information about the set of features and plug-ins installed in your RCP application. Since you have not added any features yet, the dialog box is empty.
- Click Plug-in Details. The dialog box will show the complete list of plug-ins that are part of this RCP application. We will see the 10 RCP plug-ins, plus the single plug-in we created.
- Click on com.ibm.plte plug-in in this dialog box and notice that
the More Info button is disabled. More Info provides
additional information about the plug-in. If you want to provide
additional information about your plug-in(s), you need to add it
in an about.html file. We do this in the next step.
Figure 4. Plug-ins included in the Hello World RCP application
The one action we did not execute is Help > Help Contents. This requires a number of Help plug-ins not included in the Hello World RCP application. Therefore, this action will not run until the necessary Help plug-ins have been added. We do this in the next section.
Step 4: Add plug-in information to the minimal Hello World RCP application
Here, you provide information about a plug-in via its about.html file:
- Move about.html from the com.ibm.plte.help feature project to the com.ibm.plte plug-in.
- Ensure that you closed the RCP application launched previously. Go back to the overview page of the com.ibm.plte (plugin.xml) editor and click Launch an Eclipse application from the Testing section.
- Click Help > About.
- Click Plug-in Details.
- Select the com.ibm.plte plug-in. The More Info button should be enabled.
- Click More Info, and about.html will open in a browser.
Figure 5. The com.ibm.plte plug-in's description
Add Eclipse functions to the Hello World RCP application
At this point, the Hello World RCP application is bare-bones, with the exception of a few menus, actions, and an about.html file. In this section, you contribute four Eclipse functions: menu/action, preference page, view, and a Help book. You will take the simple route and use PDE templates to generate these.
Step 1: Add a menu/action, preference page, view, and a Help book
- Click Ctrl+N to open the new wizard.
- Select Plug-in Project and click Next.
com.ibm.plte.uiin the Project name text field and click Next.
- Click Next.
- Select Custom plug-in wizard and click Next.
- Click Deselect All and click "Hello World" Action Set, Help Table of Contents, Preference Page and View. Click Finish.
Step 2: Run Hello World RCP application with the four Eclipse functions
Up to this point, you have been using the Launch an Eclipse application link from the overview page of the com.ibm.plte (plugin.xml) editor to launch the Hello World RCP application. In this step, you will use the Run dialog box to launch the RCP application because the RCP application requires additional plug-in dependencies for Help.
Steps to take:
- Ensure that you closed the RCP application launched previously. Select Run > Run to open the Run dialog box.
- Select Eclipse Application > Eclipse Application configuration.
- Switch to the Plug-ins tab.
- Select the com.ibm.plte.ui plug-in. Select Add Required
Plug-ins and add the following plug-ins under the External
- Click Run. Your application should come up with an
additional Sample Menu.
Figure 6. Hello World RCP application with Help menu
- Click Window > Show View > Other. Select Sample
View under the Sample Category folder. You
indirectly added the Help folder as a result of adding the
dependent Help plug-ins. Click OK to open the Sample View.
Figure 7. Hello World RCP application with a view
- Click Window > Preferences to open the preferences
dialog box. Check to see a Sample Preferences preference page in
the dialog box. You indirectly added the Help preference pages
because of adding the dependent Help plug-ins.
Figure 8. Hello World RCP application's preference dialog box
- Click Sample Menu > Sample Action. An information dialog box opens.
- Click Help > Help Contents. The Help browser will open
and display the Help book Test TOC.
Figure 9. Hello World RCP application Help content
Step 3: Enable Hello World RCP application toolbar
Actions can be added to the menu bar or the toolbar. To display actions in the toolbar, you first need to enable the toolbar in the RCP application. By default when an RCP application is generated using the Hello RCP template, it does not enable the toolbar. Enable the toolbar by completing the following:
- Open com.ibm.plte.ApplicationWorkbenchWindowAdvisor.java from the com.ibm.plte project.
- Modify the configurer.setShowCoolBar(false); to configurer.setShowCoolBar(true); and save the file.
- Ensure that you closed the RCP application launched previously. Go
back to the overview page of the com.ibm.plte editor. Click
Launch an Eclipse application from the Testing section.
You will now see the toolbar with a single action. Clicking this
will result in the same message dialog box appearing by clicking
Sample Action from the Sample Menu.
Figure 10. Hello World RCP application with toolbar
Step 4: Deploying the same four functions in the Eclipse IDE
The four functions created above are not exclusive to RCP applications. They can also be part of an Eclipse tool. This is the benefit of the Eclipse framework: You get to reuse the Eclipse components. In this step, add the same four features to the Eclipse IDE:
- Ensure that you closed the RCP application launched previously. Click Run > Run to open the Run dialog box.
- Create a new Eclipse Application configuration.
- Click Run. Another Eclipse IDE workbench will open. Verify that the same four functions added above appear in this runtime workbench.
Create an RCP product
Part 3: Create a Hello World RCP product
In Eclipse terms, a product is everything that goes with your application, including all the other plug-ins it depends on, features, a command to run the application (called the native launcher), and any branding (icons, etc.) that make your application distinctive.
There are two types of branding in Eclipse: feature- and product-level. No extension points exist for defining feature branding. The process involves placing feature-branding files in a plug-in, then defining this plug-in in the feature definition (feature.xml). If the feature ID is identical to the plug-in ID, it is not necessary to define the plug-in in the feature definition. In this section, you will brand a feature called com.ibm.plte. Note that this feature has the same ID as plug-in com.ibm.plte.
Product branding is done using the org.eclipse.core.runtime.product extension point. Eclipse provides a Product Configuration editor to help create the product extension point. One of the attributes you must set with this extension point is the product name. You will define the product name to be com.ibm.plte.product. Note that although the RCP was introduced in Eclipse V3.0, the Product Configuration function did not appear until Eclipse V3.1. You could still create an RCP product in V3.0 by manually defining the product extension point, but it is much more complicated.
Note that since the Eclipse IDE is an RCP application, it also defines this product extension point. The product name the Eclipse IDE defines is org.eclipse.sdk.ide.
To brand the Hello World RCP application, this tutorial provides a number of branding-specific files. The table below shows a mapping of the branding files to the branded RCP application.
Table 3. Description of sample branding files used to customize Hello World RCP application
|icons/jdg2eAbout.gif||Customize the About dialog box:|
|icons/jdg2eProd.gif||Customize the window system image:|
|splash.bmp||Customize the splash screen:|
|about.ini about.properties icons/jdg2eFeat.gif||These files customize feature branding. about.ini defines the
image and About information to display in the About dialog
boxes for com.ibm.plte feature. about.properties file extracts
the display text so it can be translated.|
Step 1: Brand a feature and create a Hello World RCP product
Steps to take:
- From the com.ibm.plte.help feature project, move the following
folder/files over to the com.ibm.plte plug-in project:
- icons folder
- Right-click on the com.ibm.plte project and select New > Product Configuration to open the New Product Configuration dialog box.
plte.productin the File name text field.
- Select the Use a launch configuration radio button and click Finish. The plte.product editor opens.
- On the overview page of the plte.product editor, click New next to Product ID. The New Product Definition dialog box opens.
- Select the com.ibm.plte project as the Defining Plug-in.
- Enter the product in the Product ID text field and click Finish.
PLTEin the Product Name text field.
- Select the Features radio button.
- Switch to the Configuration page.
- Click New Feature. The New Feature wizard opens.
com.ibm.plte-featurein the Project name text field and click Next.
- Modify the Feature ID to
com.ibm.plteand click Next.
- Select plug-ins com.ibm.plte and com.ibm.plte.ui, then click Finish. The com.ibm.plte (feature.xml) editor opens.
- Switch to the Information page, then switch to the License
Agreement page. Modify the Optional URL text field to
- Switch to the Included Features page of the editor and click Add.
- Select features com.ibm.plte.help and org.eclipse.rcp, then click OK. Save feature.xml.
- Go back to the plte.product editor and switch to the Branding page.
pltein the Launcher Name text field.
- Select the com.ibm.plte plug-in for the splash screen.
- For the 16x16 window image, select com.ibm.plte/icons/jdg2eProd.gif.
- For the About dialog box image, select com.ibm.plte/icons/jdg2eAbout.gif.
This is a sample PLTE applicationin the Text text field.
- Save plte.product.
- Move license.html from the com.ibm.plte.help feature project to the com.ibm.plte feature project.
Step 2: Run Hello World RCP product
Steps to take:
- Ensure that you closed the previous RCP application. Go to the
overview page of plte.product and click Launch the product.
You will see a splash screen before the RCP application opens.
Verify that the application looks like Figure 16. Notice the top
left corner of the RCP application has the image you specified in
Figure 16. Hello World RCP application
- Click Help > About PLTE. Originally, this Action name
was labeled About, but it now appends the product name you defined
in plte.product. Because the application now contains features,
the About dialog box provides additional information about your
application. The About dialog box should look like the following
figure. Note that due to a bug, the Feature Details button only
shows the org.eclipse.rcp feature and not the com.ibm.plte
feature. Only features that have been branded will show up in the
Feature Details dialog box, so you will not see the
com.ibm.plte.help feature. When you export and run this RCP
application in the next section, you will see the com.ibm.plte
Figure 17. Hello World RCP application's About dialog box
Deploying outside of Eclipse
After developing an application, the goal is to deploy and run stand-alone applications without the user having to know anything about the Java and Eclipse code being used underneath. For a real application, you will likely provide a self-contained executable generated by an installation program like InstallShield or NSIS. This is beyond the scope of this tutorial, so you will instead create a simplified version of the Eclipse installation directory. This directory has to contain the native launcher program, startup.jar, config.ini, and all the plug-ins and features required by the product.
Eclipse provides an Eclipse Product export wizard to help you build the Eclipse installation directory on your file system.
Step 1: Export Hello World RCP product to the file system
All plug-in and feature projects contain a build.properties file. This file is used by Eclipse to figure out what files should be exported. Before exporting the RCP application, you must update this file with the additional files or folder that were added to the com.ibm.plte plug-in and the com.ibm.plte feature. The build.properties file does not have to be updated manually. You can use the build page of the plugin.xml or feature.xml editor.
Steps to take:
- Go to the build page of the com.ibm.plte (plugin.xml) editor.
Select the following files or folder to export with the
com.ibm.plte plug-in and save the file:
- icons folder
- Go to the build page of the com.ibm.plte (feature.xml) editor. Select the file license.html to export with the com.ibm.plte feature and save the file.
- Go to the overview page of the plte.product editor and click Eclipse Product export wizard to launch Export wizard.
- Select Directory as the Export Destination. Specify a location on the file system to export the RCP application and click Finish.
Step 2: Run Hello World RCP product from the file system
Steps to take:
- Ensure that you closed the previously launched RCP application. Using a command prompt window, go to the location where you exported the application. Run the plte.exe command. The same RCP application you ran previously will open.
- Click Help > About PLTE to open the About dialog box.
Notice that the dialog box contains two icons above the Feature
Details button. The first represents the org.eclipse.rcp
feature, and the second represents the com.ibm.plte feature.
Figure 18. Hello World RCP application's About dialog box
- Click Feature Details to open the About Feature dialog box.
- Select the com.ibm.plte feature. Notice that the License button is enabled. This is because you added a license.html file earlier.
- Click License to open license.html in a browser.
Figure 19. Hello World RCP application's sample license
- Locate and open the com.ibm.plte plug-in's plugin.xml. Notice that
this plug-in defines three extension points:
- org.eclipse.core.runtime.applications -- Created in Part 1 using the Hello RCP template
- org.eclipse.ui.perspectives -- Created in Part 1 using the Hello RCP template
- org.eclipse.core.runtime.products -- Created in Part 3 using the Product Configuration editor
Figure 20. com.ibm.plte plug-in's plugin.xml
- Go back to the Eclipse workbench. Click Run > Run to
open the Run dialog box and select Eclipse Application >
Eclipse Application configuration. Notice that this
configuration contains the application com.ibm.plte.application
and product com.ibm.plte.product.
Figure 21. Launch Configuration dialog box
In this tutorial, we learned how to build a Java- and Eclipse-based rich client application. The new tooling in Eclipse V3.1 makes it easier to build RCP applications. In Eclipse V3.0, it was a much more manual process, but Eclipse V3.1 allows you to generate applications quickly from RCP templates, and package and brand your plug-ins with an easy-to-use UI. We also learned how to add Help to RCP applications.
- Check out Eclipse's Rich Client Platform information to expand your Eclipse RCP skills.
- Learn more about the Eclipse Foundation and its many projects.
- Check out the latest Eclipse technology downloads at alphaWorks®.
- Download Java technology from Sun Microsystems or from IBM®.
- Download the open source, freely available, and extensible Eclipse SDK.
- Expand your Eclipse skills by visiting IBM developerWorks' Eclipse project resources.
- Browse all of the Eclipse content on developerWorks.
- Innovate your next open source development project with IBM trial software, available for download or on DVD.