| Eclipse Article |
The Rich Client Platform (RCP) is an exciting new way to build Java applications that can compete with native applications on any platform. This tutorial is designed to get you started building RCP applications quickly.
By Ed Burnette, SAS Institute Inc.
December 22, 2003 - Updated for 3.0 M6
Note that Eclipse 3 is undergoing constant change so the steps you need to take, the APIs, and the results may vary slightly (or not so slightly) from this description.
Try this experiment: Show Eclipse to some friends or co-workers who haven't seen it before and ask them to guess what language it is written in. Chances are, they'll guess VB, C++, or C#, because those languages are used most often for high quality client side applications. Then watch the look on their faces when you tell them it was created in Java, especially if they are Java programmers.
Because of its unique open source license, you can use the technologies that went into Eclipse to create your own commercial quality programs With previous version of Eclipse, this was possible but difficult, especially when you wanted to heavily customize the menus, layouts, and other user interface elements. That was because the "IDE-ness" of Eclipse was hard-wired into it. Version 3 introduces the Rich Client Platform, which is basically a refactoring of the fundamental parts of Eclipse's UI, allowing it to be used for non-IDE applications.
If you want to cut to the chase and look at the code you can download the Eclipse project here. Otherwise, let's take a look at how to construct an RCP application.
RCP applications are based on the familiar Eclipse plug-in architecture, (if it's not familiar to you, see the references section). Therefore, you'll need to create a plug-in to be your main program. Select New > Project > Plug-in Development > Plug-in Project to bring up the Plug-in Project wizard. On the subsequent pages, enter a Project name such as org.eclipsepowered.rcptest, and a Plug-in Id (this should match the project name). On the Code Generators page, select the Default Plug-in Structure, then click Next and Finish to generate the template.
The generated plug-in class needs a little surgery to be useable for RCP programs. In particular you need to remove the reference to ResourcesPlugin and the org.eclipse.core.resources import. Hopefully this will be addressed automatically by the PDE in the future. When you're done it should look like this:
package org.eclipsepowered.rcptest;
import java.util.MissingResourceException;
import java.util.ResourceBundle;
import org.eclipse.core.runtime.IPluginDescriptor;
import org.eclipse.ui.plugin.AbstractUIPlugin;
public class RcpTestPlugin extends AbstractUIPlugin {
private static RcpTestPlugin plugin;
private ResourceBundle resourceBundle;
public RcpTestPlugin(IPluginDescriptor descriptor) {
super(descriptor);
plugin = this;
try {
resourceBundle = ResourceBundle
.getBundle("org.eclipsepowered.rcptest.RcpTestPluginResources");
} catch (MissingResourceException x) {
resourceBundle = null;
}
}
public static RcpTestPlugin getDefault() {
return plugin;
}
public static String getResourceString(String key) {
ResourceBundle bundle = RcpTestPlugin.getDefault().getResourceBundle();
try {
return (bundle != null ? bundle.getString(key) : key);
} catch (MissingResourceException e) {
return key;
}
}
public ResourceBundle getResourceBundle() {
return resourceBundle;
}
}
The main program implements IPlatformRunnable, which just has a method called run(). Here is a simple implementation that shows you the minimum you have to do.
package org.eclipsepowered.rcptest;
import org.eclipse.core.boot.IPlatformRunnable;
import org.eclipse.swt.widgets.Display;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.application.WorkbenchAdvisor;
public class RcpApplication implements IPlatformRunnable {
public Object run(Object args) {
WorkbenchAdvisor workbenchAdvisor = new RcpWorkbenchAdvisor();
Display display = PlatformUI.createDisplay();
int returnCode = PlatformUI.createAndRunWorkbench(display,
workbenchAdvisor);
if (returnCode == PlatformUI.RETURN_RESTART) {
return IPlatformRunnable.EXIT_RESTART;
} else {
return IPlatformRunnable.EXIT_OK;
}
}
}
Next, you must define at least one perspective and make it the default. Perspectives are created by implementing IPerspectiveFactory. The important part of this interface is the createInitialLayout() method where you position and open any views and/or editors you'd like the user to start with. In this example we're not going to create any views so it will be a pretty boring perspective.
package org.eclipsepowered.rcptest;
import org.eclipse.ui.IPageLayout;
import org.eclipse.ui.IPerspectiveFactory;
public class RcpPerspective implements IPerspectiveFactory {
public RcpPerspective() {
}
public void createInitialLayout(IPageLayout layout) {
}
}
The Workbench Advisor class helps customize the workbench to add and subtract toolbars, perspectives, and so forth. The absolute minimum you have to do here is define which perspective is the default one.
package org.eclipsepowered.rcptest;
import org.eclipse.ui.application.WorkbenchAdvisor;
public class RcpWorkbenchAdvisor extends WorkbenchAdvisor {
public String getInitialWindowPerspectiveId() {
return "org.eclipsepowered.rcptest.RcpPerspective";
}
}
As usual, the plug-in manifest ties everything together. The class name in the plugin tag refers to the plug-in class defined earlier. The main program class name is defined with the org.eclipse.core.runtime.applications extension and the perspective with org.eclipse.ui.perspectives. Note you have to take out the reference to org.eclipse.core.resources by hand in current builds.
<?xml version="1.0" encoding="UTF-8"?> <?eclipse version="3.0"?> <plugin id="org.eclipsepowered.rcptest" name="%pluginName" version="0.0.0" provider-name="%providerName" class="org.eclipsepowered.rcptest.RcpTestPlugin"> <runtime> <library name="rcptest.jar"> <export name="*"/> </library> </runtime> <requires> <import plugin="org.eclipse.core.runtime.compatibility"/> <import plugin="org.eclipse.ui"/> </requires> <extension id="RcpApplication" point="org.eclipse.core.runtime.applications"> <application> <run class="org.eclipsepowered.rcptest.RcpApplication"> </run> </application> </extension> <extension point="org.eclipse.ui.perspectives"> <perspective name="%perspectiveName" class="org.eclipsepowered.rcptest.RcpPerspective" id="org.eclipsepowered.rcptest.RcpPerspective"> </perspective> </extension> </plugin>
The build.properties file will be needed when exporting the application for others to use.
bin.includes = plugin.xml,\
*.jar,\
rcptest.jar,\
plugin.properties
source.rcptest.jar = src/
Finally, the plugin.properties file contains natural language strings at the plug-in registry level (i.e., things the run-time has to know about your plug-in before even loading it). You could hard-code these into your plug-in manifest but it's best to get into the i18n habit from the start.
pluginName = RcpTest Plug-in providerName = eclipsepowered.org perspectiveName = RcpTest
Normally, when testing a plug-in you would select the project and then select Run > Debug > Debug As > Run-time Workbench. Go ahead and try that now. It will give you a full blown Eclipse IDE Workbench window because we haven't overridden the application name - it is still defaulting to the IDE application. To fix this, edit the launch configuration you just created (select Run > Debug > Debug..., and then select New_Configuration or create a new one). In the Arguments tab, add this to the end of the Program Arguments:
-application org.eclipsepowered.rcptest.RcpApplication
This name comes from the id specified on the org.eclipse.core.runtime.applications extension point.
Now switch over to the Plug-ins and Fragments tab. Select the option to Choose plug-ins and fragments, and select the following plug-ins. This is currently the absolute minimum that will work for a GUI RCP program.
Now press Debug. You should see a bare-bones Workbench start up.
If you don't see this, you should be able to find an error message in the run-time workbench's .log file (runtime-workspace/.metadata/.log). Simply bring it up in a text editor and look for the most recent errors. You may find it useful to delete the .log file before running the program so you won't get confused by older messages.
The whole point of all this is to be able to run stand-alone applications without the user having to know anything about the Java and Eclipse code being used under the covers. For a real application you will probably want to provide a self-contained executable generated by an install program like InstallShield. That's really beyond the scope of this article though, so we'll do something simpler.
We need to create a simplified version of the Eclipse install directory because the Eclipse plug-in loader expects things to be in a certain layout. Here are the steps to get started:
To complete the RcpTest directory, copy the startup.jar file from the Eclipse install directory into the top level, and copy the other org.eclipse plug-ins from the list of required plug-ins above into the plugins directory. When you're done you should have a structure that looks like this:
RcpTest | startup.jar +--- plugins +--- org.eclipse.core.runtime.compatibility_3.0.0 +--- org.eclipse.core.runtime_3.0.0 +--- org.eclipse.help_3.0.0 +--- org.eclipse.jface_3.0.0 +--- org.eclipse.osgi.services_3.0.0 +--- org.eclipse.osgi.util_3.0.0 +--- org.eclipse.osgi_3.0.0 +--- org.eclipse.swt.win32_3.0.0 +--- org.eclipse.swt_3.0.0 +--- org.eclipse.ui.workbench_3.0.0 +--- org.eclipse.ui_3.0.0 +--- org.eclipse.update.configurator_3.0.0 +--- org.eclipsepowered.rcptest
That's all you need to run an RCP application, but it would be difficult for anyone to use it without some kind of launching program. Eclipse uses eclipse.exe, but we'll just use a batch file. Create a Windows command file called rcptest.cmd and place it in the top level RcpTest directory. A Unix shell script version would be similar.
@echo off setlocal cd %~dp0 rem Check workspace\.metadata\.log for errors start javaw -cp startup.jar org.eclipse.core.launcher.Main -application org.eclipsepowered.rcptest.RcpApplication %* endlocal
The start command should be all on one line. As before, the -application option refers back to the id specified on the org.eclipse.core.runtime.applications extension point.
You can get as fancy as you want in this script file. Here's a variant that I like to use when debugging because it will display any error messages from the Eclipse loader in a separate window:
echo on setlocal cd %~dp0 rem Display workspace\.metadata\.log if there are errors del workspace\.metadata\.log java -cp startup.jar org.eclipse.core.launcher.Main -application org.eclipsepowered.rcptest.RcpApplication %* || type workspace\.metadata\.log && pause endlocal
The java command should be all on one line.
To eliminate the startup window on Windows, you can use a shortcut instead of a script file. Right click inside the RcpTest folder, select New > Shortcut and enter this as the location of the item (on one line):
%windir%\system32\javaw.exe -cp startup.jar org.eclipse.core.launcher.Main -application org.eclipsepowered.rcptest.RcpApplication
Enter a descriptive name on the next page and then press Finish. Then try double-clicking on your new shortcut to try it out. You may want to edit the shortcut (right click on it and select Properties) to change the default working directory.
In part 1 of this tutorial, we looked at what is necessary to create a bare-bones Rich Client application. The next part will delve into customizations using the WorkbenchAdvisor class, and adding some real views to the default Perspective. All the sample code may be downloaded here.
Rich Client Platform
Facilities
Bug 36967 - [Plan
Item] Enable Eclipse to be used as a rich client platform
Nick Edgar's Browser example
(zip file)
PDE
Does Plug-ins
How
to Internationalize your Eclipse Plug-in
Notes
on the Eclipse Plug-in Architecture
IBM is trademark of International Business Machines Corporation in the United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both.
Other company, product, and service names may be trademarks or service marks of others.