Explore Eclipse's OSGi console

Use and extend the console that drives Eclipse

Get acquainted with the hidden gem known as the OSGi (Equinox) console and find out how it can be added to an Eclipse developer's toolbox. And learn how to extend the console to further add to the toolbox.

Chris Aniszczyk (zx@redhat.com), Principal Software Engineer, Red Hat Inc.

Chris AniszczykChris Aniszczyk is the co-lead of the Eclipse Plug-in Development Environment (PDE) project and a Principal Software Engineer at Red Hat. He is the co-author of "The Eclipse Rich Client Platform" book and has been recognized by the Eclipse Community Awards as Top Ambassador and Top Committer. He tends to be all over the place inside the Eclipse community by committing on various Eclipse projects. He sits on the Eclipse Architecture Council, Eclipse Planning Council and has the honor to represent the committers on the Eclipse Foundation's Board of Directors. He's always available to discuss open source or Eclipse over a frosty beverage. You can read his blog and follow him on Twitter as @caniszczyk.

30 January 2007

Also available in Chinese Japanese

Starting with V3.0, Eclipse made a big leap by choosing Open Services Gateway Initiative (OSGi) to replace the rickety Eclipse plug-in technology found in earlier versions. This transition was almost transparent to users because plug-ins seemed to install and operate as plug-ins of yore.

Figure 1. Plug-ins inside Eclipse
Plug-ins inside Eclipse

Because Eclipse is now built on OSGi, the plug-ins we see in Figure 1 are full-fledged OSGi bundles. (Figure 2 shows the running bundles inside an Eclipse instance using the OSGi console.) By using OSGi, Eclipse supports an industry-endorsed open standard and can now take advantage of the facilities provided by OSGi, including security, HTTP service, useradmin, and others. It seems Eclipse's gamble on OSGi is paying off since we are seeing Eclipse use continue to grow while reported conflicts among plug-ins are decreasing.

Figure 2. OSGi bundles inside of Eclipse
OSGi bundles inside of Eclipse

Eclipse, Equinox, OSGi, oh my!

The OSGi Alliance is an independent, nonprofit corporation responsible for OSGi technology. It is akin to the Eclipse Foundation in function. The OSGi Alliance is responsible for producing specifications describing OSGi technology. In brief, OSGI technology provides a service-oriented component-based platform for application development. Various implementations are based on these specifications. One of the most popular implementations is Equinox, which is Eclipse's implementation of the specification. Another popular implementation of OSGi is Apache's Felix project.

Before we go any further, this article assumes you have a working knowledge of Eclipse and OSGi. If you don't, I suggest reading Scott Delap's article "Understanding how Eclipse plug-ins work with OSGi" before diving into the OSGi console.

Create your OSGi bundle

The first step on this adventure is to create a simple OSGi bundle in Eclipse using the Plug-in Development Environment (PDE). To do this, we need to create a new plug-in project using PDE (File > New > Project > Plug-in Project). In the process of creating your new plug-in project, make sure you set the proper options. First, select your plug-in target platform as an OSGi Framework, specifically Equinox. Finally, for the sake of brevity, use the Hello OSGi Bundle template provided by PDE (see Figure 3). We now have our bundle that we'll use throughout this article.

Figure 3. PDE Hello OSGi bundle wizard
PDE Hello OSGi bundle wizard

Hello OSGi console

Since we now have our Hello bundle, we can go ahead and launch the framework to get an OSGi console. To launch the framework, we can take advantage of PDE's OSGi Framework launch configurations. First, go to the launch configuration menu (Run > Run ...) and create an OSGi Framework launch configuration for our Hello bundle (see Figure 4). Also, make sure that only the required bundles needed to run the Hello bundle are selected. An easy way to accomplish this is to press Deselect All in the launch configuration and check off the Hello bundle, followed by pressing Add Required Plug-ins.

Figure 4. PDE's OSGi framework launch configuration
PDE's OSGi framework launch configuration

Plug-ins and bundles: What's the difference?

Wander by a basement where Eclipse developers are hacking together applications and you'll hear the magic words plug-ins and bundles bandied about. Is there a distinction? From a marketing vice president's perspective, the terms are synonymous. A bundle is a plug-in and a plug-in is a bundle. We are stuck with both terms, it seems. However, from an uber-nerd's perspective, there's some contention. To be accurate, an Eclipse plug-in is an OSGi bundle that takes advantage of the extension registry (i.e., have a plug-in.xml at the root of the bundle). An OSGi bundle is, well, an OSGi bundle.

After our launch configuration is completed and ready to go, we can launch our bundle using the Run button in the launch configuration dialog. Once this is completed, you should see a result similar to Figure 5.

In Figure 5, we see that our Hello bundle was started (using the HelloWorld message printed in the console indicating our bundle was started) and that we're presented with an osgi> prompt. The OSGi prompt is similar to a DOS or a Bash prompt in that you can enter commands that act on the OSGi instance. In this case, we issued the ss command, which displays a quick status of everything. I encourage you to try this command in a normal Eclipse instance to realize that everything is just an OSGi bundle under the covers. To get an OSGi console for a normal Eclipse instance, simply launch Eclipse with the -console parameter.

Figure 5. Our first launch
Our first launch

Starting and stopping bundles

In the OSGi dynamic environment, you can start and stop bundles easily. To test this, let's use our simple Hello bundle. Simply stop the bundle with the stop command, then start the bundle with the start command. You should see results similar to Figure 6.

Figure 6. Starting and stopping bundles
Starting and stopping bundles

Adding, removing and updating bundles

Another powerful aspect of an OSGi system is the ability to add, remove, and update bundles in a running OSGi instance -- all without restarting the Java™ Virtual Machine. Figure 7 demonstrates installing and uninstalling bundles.

Figure 7. Installing and uninstalling bundles
Installing and uninstalling bundles


There are times when a bundle or plug-in attempts to start but has errors during initialization. The OSGi console provides a useful command -- diag -- that helps you debug problems associated with bundle initialization. For an example, let's examine Figure 8, we see that in an attempt to start our Hello bundle, we get an error. To help diagnose the error, we run the diag command against our bundle and see that we are missing an imported package in our runtime environment.

Figure 8. Console diagnostics
Console diagnostics

Summary of useful console commands

Table 1. Useful console commands
startStarts a bundle given an ID or symbolic name
stopStops a bundle given an ID or symbolic name
installAdds a bundle given a URL for the current instance
uninstallRemoves a bundle given a URL for the current instance
updateUpdates a bundle given a URL for the current instance
activeLists all active bundles in the current instance
headersList the headers for a bundle given an ID or symbolic name
ssLists a short status of all the bundles registered in the current instance
services <filter>Lists services given the proper filter
diagRuns diagnostics on a bundle given an ID or symbolic name

There are many other OSGi commands available. The ones listed here are the ones I find most useful. To get a list of all the commands, just type help in the console.

Extending the console

People say that the beauty of Eclipse lies in its extensibility. The console is extensible in a similar manner. This is important because as a developer, you may provide a service of some kind to users. By extending the console, you can enable advanced users or administrators to debug problems regarding your service.

Instead of using familiar extension points, the console has a simple extensibility mechanism. Let's work through several examples to illustrate the extensibility of the console.

uname, OSGi style

Anyone who has worked with UNIX®-flavored systems is familiar with the uname command, which prints the name, version, and other information about the running operating system. In an OSGi context, there can be various implementations of OSGi console (such as Knopflerfish) in the same way there are various flavors of UNIX.

The most important part of extending the OSGi console is the CommandProviderinterface. Clients interested in extending the console must implement this. Once it is implemented, the next step is to start method names with a "_". These methods will represent the commands available in the console. It's that simple! See Listing 1 for an example.

Listing 1. OSGi uname
public class Activator implements BundleActivator, CommandProvider {

	private BundleContext context;

	public void start(BundleContext context) throws Exception {
		this.context = context;
		Hashtable properties = new Hashtable();
		(CommandProvider.class.getName(), this, properties);

	public String getHelp() {
		StringBuffer buffer = new StringBuffer();
		buffer.append("\tuname - returns framework information\n");
		return buffer.toString();

	public void stop(BundleContext context) throws Exception {}
	public void _uname(CommandInterpreter ci) throws Exception {
		String vendor = context.getProperty(Constants.FRAMEWORK_VENDOR);
		String version = context.getProperty(Constants.FRAMEWORK_VERSION);
		String osName = context.getProperty(Constants.FRAMEWORK_OS_NAME);
		String osVersion = context.getProperty(Constants.FRAMEWORK_OS_VERSION);
		System.out.println("\n " + vendor + " " 
				+ version + " (" + osName + " " 
				+ osVersion + ")");

Bundles and existentialism

Bundles may never question their existence, but here's a simple example that prints whether a bundle is a vanilla bundle or an Eclipse plug-in. (Remember, both are still bundles!) Listing 2 builds on the previous example by adding a new method and modifying the getHelp() method.

Listing 2. Modify getHelp()
public String getHelp() {
		StringBuffer buffer = new StringBuffer();
		buffer.append("\twhatami - \
		returns whether the bundle is a plug-in or not\n");
		return buffer.toString();
public void _whatami(CommandInterpreter ci) throws Exception {
		try {
			long id = Long.parseLong(ci.nextArgument());
			Bundle bundle = context.getBundle(id);
			URL url = bundle.getEntry("plugin.xml");
			if(url != null) {
				System.out.println("\n I'm \
				(" + bundle.getSymbolicName() + ") a plug-in");
			} else {
				System.out.println("\n I'm \
				(" + bundle.getSymbolicName() + ") not a plug-in");
		} catch (NumberFormatException nfe) {
			System.out.println("\n Error processing command");

The results of our labor can be seen in Figure 9.

Figure 9. Results from extending the console
Results from extending the console


This article demonstrates how to use the OSGi console and how to extend the console. Along the way, we've looked at the console and several examples on how to extend it. You now have greater familiarity with the console and have an idea how to use it in your day-to-day Eclipse development. Maybe using the console will even bring back memories of playing Doom and Quake.

Figure 10. The Quake console
The Quake console


Source codeos-ecl-osgiconsole.hello.zip49KB



Get products and technologies


  • The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this link will launch your default Usenet news reader application and open eclipse.platform.)
  • The Equinox newsgroups contain a plethora of information about Eclipse's OSGi implementation. (Selecting this link will launch your default Usenet news reader application and open eclipse.technology.equinox.)
  • Get involved in the developerWorks community by participating in developerWorks blogs.


developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password




All information submitted is secure.

Choose your display name



Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)



All information submitted is secure.

Dig deeper into Open source on developerWorks

Zone=Open source
ArticleTitle=Explore Eclipse's OSGi console