equinox
Eclipse RCP: HowTo

 
Summary

This first prototype of the Eclipse Rich Client Platform is the result of the work of Olivier Gruber and Woody Huang, also from IBM Research who joined early spring 2003. This prototype is based on Eclipse RC3, in which OSGi has been integrated. It demonstrate a full dynamic stack: OSGi, dynamic Eclipse registry, and dynamic Workbench. This document describes the HowTo, especially how to get started.

Getting Started

The Equinox prototype is based on Eclipse RC3, Version: 2.1.0, Build id: 200303192032. We strongly suggest that you get that version for hosting your development. Once you have installed that version, you need access to the CVS repostory: dev.eclipse.org:/home/technology.

Once the location is establish in the CVS perspective in your host Eclipse, you need to configure the branches. Open the versions folder in the CVS repository (below HEAD and Branches folders), right-click on the org.eclipse.equinox folder, and select "Configure Branches and Versions...". Open the plugins folder, and then org.apache.ant folder. Select the ant.jar file. Many new tags appear on the right-hand pane, all selected. Go in the pane named "Remembered tags for these projects" and click on the button Add Checked Tags.

Ok, you can now go back to the CVS repository view, open up the Branches folder and see all the branches. One is called OSGi_Olivier, this is where this prototype lives. You will need to check out the following projects:

  • Minimal OSGi & Eclipse registry
    • org.eclipse.core.boot
    • org.eclipse.core.runtime
  • Standard Widget Toolkit (SWT)
    • org.eclipse.swt
    • org.eclipse.swt.win32
    • org.eclipse.swt.examples.controleexample (optional)
  • OSGi/Eclipse Admin Interface
    • org.eclipse.jface
    • org.eclipse.jface.text
    • org.eclipse.core.update
  • Eclipse Workbench & Workplace
    • org.apache.ant
    • org.apache.lucene
    • org.apache.xerces
    • org.eclipse.ant.core
    • org.eclipse.core.resources
    • org.eclipse.core.resources.win32
    • org.eclipse.help
    • org.eclipse.help.appserver
    • org.eclipse.search
    • org.eclipse.ui
    • org.eclipse.ui.win32
    • org.eclipse.ui.editors
    • org.eclipse.ui.views
    • org.eclipse.ui.workbench
    • org.eclipse.ui.workbench.texteditor
    • org.eclipse.update.core
    • org.eclipse.update.core.win32

Once you checked out all those projects, only one fix is needed to compile:

  • SWT, copy .classpath-win32 to .classpath

You will see errors in the following plugins:

  • org.eclipse.ant.core
  • org.eclipse.core.runtime plugins
These are normal. Just ignore them.

Once you compile everything, you need to create a Workbench launcher. Go in Debug window that allows you to create and manage configurations. Create a new Runtime-Workbench configuration. Select the tab for plugins and fragments, and make sure all plugins and fragments you just downloaded and compiled are selected. That's all. You can launch that configuration... but to go slowing, first insert a break point at the end of the method InternalPlatform.loaderStartup(...) in the package org.eclipse.core.internal.runtime in the org.eclipse.core.runtime plugin.

Once you hit the breakpoint, you can hit return in the console and you will see an "OSGi" prompt. Type the command status, and check that all bundles are INSTALLED and RESOLVED, except for the PluginA24.Fragment1. If this is the case, you can resume the suspended thread... and you should see you workbench appear. If it does not, you suffer from a deadlock between Eclipse host console and SWT (un-explained so far). You will have to hit return in the console for a little while... until you see the workbench window appearing in the Windows taskbar. Open it, and you should see you regular workbench.

Going back to the host Eclipse, in the console, you can retype status command so to get at the bundle number for the bundle org.eclipse.core.update. Should be bundle 36, but it could be something else. We will assume 36 in the following explaination. Once you have the numeric id of that bundle, start it at the OSGi level. The command is the following:

OSGi> start 36

You should see a window appearing in the Windows taskbar, open it and maximize it. Three tab panes are available.

  • Platform
  • OSGi
  • Registry

The platform tab allows you to see what is installed on disk. The OSGi tab allows you to introspect the OSGi framework. You see the two state: current and future. Until you start installing bundles, the two are identical. The Registry tab allows you to see the Eclipse registry.

Samples

Here follows the list of samples.

  • org.eclipse.swt.examples.controleexample
  • PluginA
  • PluginA24
  • PluginA24.Fragment1
  • PluginB
  • PluginC
  • TestPlugin

They should compile without any problem. Once compiled, make sure they are selected in the configuration of your target Eclipse Workbench. There are three global scenario for those samples to play with.

Independent OSGi Layer, SWT Example

One allows to test SWT, directly at the OSGi layer. You only need the org.eclipse.swt.examples.controleexample bundle. Once on the target environment, in the OSGi console, you can start the corresponding bundle. Remember, find its id using the status command and start using the start command.

It is possible you suffer from the deadlock between the Eclipse console and SWT... so keep hitting return in the host Eclipse console... you will see the window appear in the Windows taskbar. That window demonstrates all the SWT widgets available. It demonstrate the availability of the OSGi layer independently of the Eclipse registry and Workbench.

Testing OSGi Dynamic Nature

The second scenario relates to the following bundles: PluginA, PluginA24, PluginB, PluginC, and TestPlugin. They are for playing around with the new dynamic behavior. Look at their META-INF/MANIFEST.MF file to see their imports/exports in terms of Java packages. You will see that B depends on A, and C depends on both A and B. You will also see that we have two versions of A: 2.1 and 2.4. In the version 2.4, the package PluginA.PackageP has been moved to the fragment PluginA24.Fragment1.

Now, play around in installing PluginA, version 2.1 or 2.4, and see what happens. Remember to install by right-click on the bundle in the Platform tab. See the effects in the Future pane of the OSGi tab. Don't forget to ask for a Refresh, for accurate results. Sometimes, the UI does not respond well, you can refresh its contents with Refresh UI. Finally, commit you changes with right-click on any bundle in the OSGi tab, and selecting Commit in the popup menu.

Also play with starting Bundle B, which as a very simple bunble activator, printing out which class it sees for the class PluginA.PackageP.ClassP. You will see that if PluginA is updated as PluginB is running, you will see in the OSGi console which class is picked up after each update is commited and the bundle PluginB is stopped and restarted automatically.

Testing Workbench Dynamic Behavior

The plugin TestPlugin is a Workbench plugin, it provides a simple view. Go open that view through the Window menu and the Show views submenu. Once the view is up, go start the OSGi admin window at the OSGi console (see above). Go to the OSGi tab, and right-click on the TestPlugin bundle, asking to uninstall it. Commit you changes right away (right-click on a bundle in the OSGi tab and choose Commit).

Switch to the Workbench window, you will see that the TestPlugin view has disappeared. As well as any other extensions from the TestPlugin. For instance, go back in the Windows-Show view menu and notice that there is no trace left of the TestPlugin view. The plugin is not longer visible by the Eclipse registry and the UI plugins have reacted by cleaning their data structures about all the extensions that the TestPlugin was providing.

You can confirm that the Eclipse Registry does not know about TestPlugin anymore in the Admin window in the Registry tab. Find the UI plugin, open up the view extension point and see that TestPlugin no longer contributes its view. Also, TestPlugin is no longer visible in the registry as a known plugin.

Reinstall TestPlugin, by going to the Platform tab in the Admin window and commit your changes in the OSGi tab. See in the Registry tab, how the Eclipse registry has dynamically added the plugin and matched all its extensions with the corresponding extension points. Also, go back to the Workbench window and notice how everything is back as if TestPlugin had never been uninstalled, even the view is recreated!

That's all folks, have fun and let us know what you think!