Defining a rich client application

The definition of a rich client application plug-in starts out similarly to the other plug-ins we've been studying. The only difference in the MANIFEST.MF file is that the list of required plug-ins is much smaller than we've been used to!

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: %pluginName
Bundle-SymbolicName: org.eclipse.ui.examples.rcp.browser; singleton:=true
Bundle-Version: 3.3.0.qualifier
Bundle-ClassPath: browser.jar
Bundle-Activator: org.eclipse.ui.examples.rcp.browser.BrowserPlugin
Bundle-Vendor: %providerName
Bundle-Localization: plugin
Require-Bundle: org.eclipse.core.runtime,
 org.eclipse.ui
Eclipse-LazyStart: true

Up to now, we've contributed function to the platform workbench by declaring extensions that add elements to the workbench. In all of the plugin.xml content that we've reviewed so far, we've only looked at individual contributions to a workbench that is assumed to be there. On the rich client platform, there is no application already defined. Your rich client plug-in is the one responsible for specifying the class that should be executed when the platform is started. This is done in the org.eclipse.core.runtime.applications extension.

   <extension
         point="org.eclipse.core.runtime.applications"
         id="app"
         name="%appName">
      <application>
         <run
            class="org.eclipse.ui.examples.rcp.browser.BrowserApp">
         </run>
      </application>
   </extension>

In this extension, we specify the class that should be run when the platform is first started. This class must implement IApplication , which simply means that it must implement a start and stop method. The start method is responsible for creating the SWT display and starting up a workbench. The class PlatformUI implements convenience methods for performing these tasks.

	public Object start(IApplicationContext context) throws Exception {
		Display display = PlatformUI.createDisplay();
		try {
			int code = PlatformUI.createAndRunWorkbench(display,
					new BrowserAdvisor());
			// exit the application with an appropriate return code
			return code == PlatformUI.RETURN_RESTART
					? EXIT_RESTART
					: EXIT_OK;
		} finally {
			if (display != null)
				display.dispose();
		}
	}

The call to createAndRunWorkbench will not return until the workbench is closed. The SWT event loop and other low-level logistics are handled inside this method. At this stage, it's not so important that you understand the underlying mechanics in running an SWT application.

The stop method is used to force the application to shutdown. In the browser example the workbench is closed to force the application to shutdown.

	public void stop() {
		final IWorkbench workbench = PlatformUI.getWorkbench();
		if (workbench == null)
			return;
		final Display display = workbench.getDisplay();
		display.syncExec(new Runnable() {
			public void run() {
				if (!display.isDisposed())
					workbench.close();
			}
		});
	}

The call to syncExec will not return until the workbench is closed. This will force the application to exit and the call to createAndRunWorkbench to return.

This code can be copied to your rich client application with minimal changes. In fact, the hook for you to add your own functionality is the WorkbenchAdvisor that is passed as an argument when the workbench is created. Let's take a closer look.