Getting To Grips With the Equinox Console

When developing Eclipse RCP applications, sometimes you'll find that your plug-in's capabilities don't seem to available. The Equinox OSGi console is one of the most useful tools to inspect the state of all the plug-ins in a running application. This article gives a brief introduction to the console, and how it can be used to help with your development of an OSGi based system.

To make the console available, just use the -console parameter in your run configuration. If you want to see the console for an "installed" Eclipse instance, you can just add -console to the list of parameters for running Eclipse (e.g. eclipse.exe -console). Having done that you'll see osgi> appear in the console output, similar to an MS-DOS window. 

The following is a list of commands that can be used in the osgi console: 

• help
  Lists all available commands.
  
  
• ss
  Provides a list of all the plug-ins and their current status. If you provide a string after ss, it will list all bundles containing that name. For example, if I used ss logging I would be presented with a list of plug-ins that contain logging in their name. ss here stands for short status.
• start
  Starts up a plug-in. You can either pass through the full name of the plug-in to this command, or else you can use the symbolic id, as displayed from the previous ss command.
  
• stop
  Stops a plug-in. Just like the start command, you can either pass through the full name of the plug-in or the symbolic id.
  
• install
  Paired with a URL , this installs the plug-in that the URL refers to into your system. There is also an update command, that allows you to update a plug-in using a URL.
  
• uninstall
  This command takes the symbolic id of a plug-in and uninstalls it from your running system
  
• diag
  Using the symbolic id, or the plug-in name, this command shows all resolution problems for a particular plug-in.
  
  
• active
  Lists all the active plug-ins in the running system.

So when you have an issue with your plug-in: 

• Make sure it's on the list of bundles, using the ss command. Or if you expect the plug-in to be running, use the active command.
  
• Using the id of your plug-in (usually easier than typing in the full name) check that the status of your plug-in is  ACTIVE. If not maybe you need to force the plug-in to start up using the start command.

Once you become familiar with the OSGi console, it becomes a very powerful utility for investigating the overall status of your OSGi based application.