20 August 2012

New OSGi Console in Equinox 3.8.0

Equinox 3.8.0, the OSGi framework running Eclipse Juno, comes with a new console built on top of Apache Felix Gogo Shell.

It is debatable whether or not this is an improvement. Veteran Equinox users are greeted with the following message when trying to activate the console:


$ java -Declipse.ignoreApp=true -jar org.eclipse.osgi_3.8.0.v20120529-1548.jar -console -consoleLog

!SESSION 2012-08-20 20:50:05.728 -----------------------------------------------
eclipse.buildId=unknown
java.version=1.7.0_06
java.vendor=Oracle Corporation
BootLoader constants: OS=linux, ARCH=x86_64, WS=gtk, NL=de_DE
Command-line arguments:  -console -consoleLog

!ENTRY org.eclipse.osgi 4 0 2012-08-20 20:50:06.182
!MESSAGE Could not find bundle: org.eclipse.equinox.console
!STACK 0
org.osgi.framework.BundleException: Could not find bundle: org.eclipse.equinox.console
        at org.eclipse.osgi.framework.internal.core.ConsoleManager.checkForConsoleBundle(ConsoleManager.java:211)
        at org.eclipse.core.runtime.adaptor.EclipseStarter.startup(EclipseStarter.java:297)
        at org.eclipse.core.runtime.adaptor.EclipseStarter.run(EclipseStarter.java:176)
        at org.eclipse.core.runtime.adaptor.EclipseStarter.main(EclipseStarter.java:151)
And it's not only org.eclipse.equinox.console, the new console requires a total of four additional bundles:
id State       Bundle
0 ACTIVE      org.eclipse.osgi_3.8.0.v20120529-1548
1 ACTIVE      org.apache.felix.gogo.shell_0.8.0.v201110170705
2 ACTIVE      org.eclipse.equinox.console_1.0.0.v20120522-1841
3 ACTIVE      org.apache.felix.gogo.runtime_0.8.0.v201108120515
4 ACTIVE      org.apache.felix.gogo.command_0.8.0.v201108120515

It is rather sad that Equinox appears to have given up one of its most useful features: the built-in console which is an indispensable tool for debugging startup issues, unsatisfied imports or unavailable services.

Actually, this is precisely the reason why I never liked working with Felix or Knopflerfish: you are totally blind without additional bundles, which are usually missing in the system you are trying to debug.

The good news is, Equinox has an undocumented option to enable the built-in console:
-Dosgi.console.enable.builtin=true
It would have been so easy to mention this option in the reference or the What's New overview...

Talking about undocumented features, the Gogo Shell itself is virtually undocumented, referring to an unpublished OSGi RFC-147 draft which is only briefly mentioned in the OSGi community wiki with a kafkaesque reference to Apache Felix Gogo...

Now let's have a look at the new Equinox console, based on Gogo shell. What is the first command to try in any shell?

Correct: help

In Equinox, this command floods your screen with more than 500 lines of partially redundant
sta - start the specified bundle(s)
   scope: equinox
   parameters:
      Bundle[]   bundle(s) to start

start - start the specified bundle(s)
   scope: equinox
   parameters:
      Bundle[]   bundle(s) to start
and partially meaningless information:
gosh
   scope: gogo
   parameters:
      CommandSession   
      String[]   
Fortunately, all traditional Equinox console commands have been ported to Gogo and are still available. My personal survival kit of Equinox commands is:
  • ss: short status of all bundles
  • diag: tells you why a bundle fails to resolve
  • bundle: all imports and exports and services registered or used by a bundle
  • services: list services, optionally filtered.
Now there is a whole lot of additional commands from Gogo, but I can't say there is anything I have been waiting for.

The most useful features of the new console are tab completion and command history via arrow keys. Unfortunately,  this only works via telnet and not from the Eclipse IDE Console View. To enable telnet access, add a port number argument to the -console option.

There is some user and design documentation about the new console in the Equinox incubator. I don't know if this is up to date, and I wonder why none of this made it into the Juno release documentation.

All in all, the new Equinox console is yet another example of usability impaired by featuritis.

3 comments:

Libor Jelinek said...

Absolutely agreed! Equinox 3.8 improvements aren't always improvements. Thank you for this post!

Unknown said...

Even more frustrating that the equinox shell hangs in state "starting" when I put it into karaf "deploy" folder. All imports resolve still it hangs. Too bad.

Unknown said...

Thank you for the tip concerning builtin console. You made my day :D