OSGi with Equinox for beginners: console, launcher and configuration

Equinox is Eclipse’s implementation of OSGi modular environment. It’s one existing implementation developed by Eclipse Foundation for its Eclipse IDE 3.0. Originally was OSGi designed to be used in resource-constrained environments like set-top boxes, car computers etc. Despite this “minimalism” origin, OSGi is during the years recognized as the one of the most influencing technology in Java and Equinox has became of the most prominent implementation today.

Equinox parts ∞

Equinox is quite large project comprised of number domain areas implementing OSGi specifications but also Equinox-specific features.

• OSGi Framework itself (org.eclipse.osgi_<version>.jar)– main part of our interest, implementation of OSGi Core
• OSGi Compendium services — Log Service, HTTP Service, Configuration Admin Service, User Admin Service, Declarative Services, Event Admin service, …
• native launchers — Equinox-only enhancement producing platform-specific executables to run Equinox (yourApp.exe for Windows, …).
• p2 (provisioning platform) — Equinox-only tools for automated installing, uninstalling and updating bundles or group of bundles (features, products) in OSGi-based applications.

This and the following posts assume you have downloaded “All of Equinox” (aka equinox-SDK-<version>.zip from Equinox download page.

Equinox versioning ∞

Equinox has been versioned in accordance with Eclipse IDE, thus Eclipse IDE 3.7 (Indigo) has been shipped with Equinox 3.7 etc.

While current Eclipse release 4.2 (Juno) is being shipped with Equinox 3.8. The planned further Eclipse Kepler will contain Equinox 3.9.

Starting OSGi framework ∞

Single jar file org.eclipse.osgi_<version>.jar is enough to run core OSGi framework:

$java -jar org.eclipse.osgi_<version>.jar but issuing this does nothing at first sight. This is because framework is not configured what to do yet. There is a bunch of commandline arguments like -console and system properties like osgi.bundles. All available arguments are documented in (Juno) online help. $ java -jar org.eclipse.osgi_<version>.jar -console

Many arguments can be also be specified as a system property from commandline and vice-versa. For example, an equivalent of -console argument is osgi.console property:

$java -Dosgi.console -jar org.eclipse.osgi_<version>.jar Although this will start console, all valuable messages will go into .log files under configuration/ folder created by Equinox for that purpose. So another “survival” argument is -consoleLog that send logs also to stdout. $ java -jar org.eclipse.osgi_<version>.jar -console -consoleLog

Update for Equinox 3.8 console (part of Eclipse 4.2 (Juno)) ∞

Equinox 3.8 has a brand new console that isn’t part of core org.eclipse.osgi_<version>.jar framework anymore, thus above instruction will fail for Equinox 3.8 (unfortunately without any helpful errors).

It’s necessary to start framework with additional bundles comprising console feature:

• org.apache.felix.gogo.command_0.8.0v<version>.jar
• org.apache.felix.gogo.runtime_0.8.0v<version>.jar
• org.apache.felix.gogo.shell_0.8.0v<version>.jar
• org.eclipse.equinox.console_1.0.0v<version>.jar

These bundles have to be specified with osgi.bundles property from commandline (change versions to match your installation):

Configuration ∞

Above described system property or commandline argument to configure are good for learning or testing. For real-life scenarios, there is just one another way. Launcher will look for configuration/ subfolder (called configuration area) in the current working directory. In this subfolder might be config.ini file that is searched for properties and processed as they would specified in commandline.

Note that configuration area folder may be also located outside workdir of org.eclipse.osgi_<version>.jar using argument -configuration <location>. Actually, nearly everything described bellow can be customized with properties listed in (Juno) online help

|-- configuration/
|    \-- config.ini
|-- bundleA.jar
|-- bundleB.jar
|-- ...
\-- bundleN.jar

Bare OSGi application’s config.ini may look akin to this:

osgi.bundles.defaultStartLevel=4
osgi.bundles=bundleA.jar, bundleB.jar@start,\
bundleC.jar,\
bundleN.jar
osgi.noShutdown=true
eclipse.ignoreApp=true

We’ve used some common properties. Let’s review them.

osgi.bundles.defaultStartLevel ∞

Every bundle is run when certain start level becomes active. Applications should generally not depend on start levels. When it is necessary, you can change Equinox default start level 4 to something else with this osgi.bundles.defaultStartLevel property.

osgi.bundles ∞

osgi.bundles is key property and you remember it from section about launching console in Equinox 3.8 above. As you likely already assume, this property tells to OSGi Framework what bundles should be installed or started when framework itself is started.

Minimal Equinox-based application must define list these bundles

osgi.bundles=org.eclipse.equinox.common,\
org.eclipse.core.runtime,\
org.eclipse.equinox.launcher,\
org.eclipse.core.jobs,\
org.eclipse.equinox.registry,\
org.eclipse.equinox.preferences,\
org.eclipse.core.contenttype,\
org.eclipse.equinox.app

In this and previous snipped you’ve also seen how to specify bundles in more lines with \ (backslash) to improve legibility for your human colleagues.

osgi.bundles accepts various formats of input

<URL | simple bundle location>[@ [<start-level>] [":start"]]

If you omit start level, bundle will be run in default start level. If you omit start, bundle will not be started until you do it yourself with start <bundleId> console command.

This often causes a lot of troubles when you’re asking yourself why your application doesn’t run in the same manner like launched within PDE using Run Configuration.

Here are some examples of bundle specification value:

Bundle specification Description
com.acme.someapp Bundle from plugins/ subfolder will installed only when default start level is reached.
com.acme.someapp@start Bundle from plugins/ will be started in default start level.
com.acme.someapp@3:start Bundle from plugins/ will be started in start level 3.
file:\path\to\com.acme.someapp.jar Bundle \path\to\com.acme.someapp.jar will be started in default start level (note this time we used .jar).

osgi.noShutdown ∞

Property osgi.noShutdown specifies whether Framework should exit after Eclipse application terminates. Because we don’t develop Eclipse Platform application at this moment (we haven’t any org.eclipse.equinox.app.IApplication child bind to org.eclipse.core.runtime.applications extension point), Framework will otherwise shutdown immediately.

eclipse.ignoreApp ∞

Last property eclipse.ignoreApp hints launcher to don’t complain about missing application that is otherwise normally launched after bootstrapping. If you omit this you will get error

!ENTRY org.eclipse.osgi 4 0 2012-09-02 16:07:57.949
!MESSAGE Application error
!STACK 1
java.lang.IllegalStateException: Unable to acquire application service. Ensure that the org.eclipse.core.runtime bundle is resolved and started (see config.ini).
...

Enthusiastic Eclipse, OSGi and Java desktop programmer, happy Ubuntu Linux user, early adopter and open source believer. He's living in small town near to Prague (Czech Republic) and splitting free time among yoga, vegetarian cooking and dog. See more.

6 thoughts on “OSGi with Equinox for beginners: console, launcher and configuration”

• Fan Guogang says on December 5, 2012, 1:16 pm | Reply

• Redhuan D. Oon says on December 25, 2012, 2:09 am | Reply

Was just passing through on the search for some sort of OSGI bundles GUI manager, was not originally intending to comment but was trying out if the image captcha below works!
Nevertheless the eclipse.noApp tip is something i enjoyed reading and knowing. Thanks and Merry Xmas!

• college term paper says on April 9, 2013, 10:31 am | Reply

Thanks for sharing this nice informative site. I like it very much.

• f says on May 13, 2013, 4:50 pm | Reply

I had to use following config.ini file in order for it to work:

osgi.bundles=org.eclipse.equinox.app_1.3.100.v20120522-1841.jar@start,org.eclipse.core.contenttype_3.4.200.v20120523-2004.jar@start,org.eclipse.equinox.preferences_3.5.1.v20121031-182809.jar@start,org.eclipse.equinox.registry_3.5.200.v20120522-1841.jar@start,org.eclipse.core.jobs_3.5.300.v20120912-155018.jar@start,org.eclipse.equinox.common_3.6.100.v20120522-1841.jar@start,org.apache.felix.gogo.runtime_0.8.0.v201108120515.jar@start,org.apache.felix.gogo.command_0.8.0.v201108120515.jar@start,org.apache.felix.gogo.shell_0.8.0.v201110170705.jar@start,org.eclipse.equinox.console_1.0.0.v20120522-1841.jar@start,org.eclipse.core.runtime_3.8.0.v20120912-155025.jar@start
eclipse.ignoreApp=true

Best!

• SA says on February 11, 2014, 4:10 pm | Reply

It seems the launcher route is broken, on Windows at least – unless it is only meant to be used with Eclipse? Kinda confusing, this ‘Equinox SDK’ doesn’t have much in it by way of ‘tools’, its a library if anything.

• Moreaux Patrice says on February 14, 2014, 11:31 pm | Reply

Thanks a lot for these information!
I tried to start the equinox OSGI plateform but I fail since the first information I got on the Equinox site is not up to date!
Best regards