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.

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.

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).

Basic command that will list all available commands. In Equinox 3.8 it is not helpful in anyway anymore and just flood your terminal with unpaginated many screen long list of commands without any practical usage information.

ss

Short status. Lists installed bundles and their statuses.

ss virtage

Same but lists only bundles containing “virtage” in their name.

start <bundle-id>|<bundle-name>

Starts bundle of specified ID.

stop <bundle-id>|<bundle-name>

Stops bundle of specified ID.

diag <bundle-id>|<bundle-name>

Reports any resolution problems for the bundle with the given numeric or symbolic id.

install URL

Installs the bundle from the given URL like install file:\path\to\somebundle_1.2.3.20120931.jar.

uninstall <bundle-id>|<bundle-name>

Uninstalls bundle specified by ID or bundle symbolic name.

bundle <bundle-id>|<bundle-name>

Prints information of bundle like registered and used services.

services [<filter>]

Lists all available services or only services matching to LDAP-style filter (e.g. services (objectClass="*virtage*") will print only services having “virtage” in their class name.

platform-specific library (e.g. eclipse_1503.dll for Windows or eclipse_1502.so for Linux) living in <equinox-sdk>/plugins/org.eclipse.equinox.launcher.<os>.<ws>.<arch>.jar fragment .

Launcher itself is small executable program written in C. In Windows, it has a .exe extension. Launcher filename is usually branded to match your application name in product definition editor:

Why launcher if we’ve seen how to easily launch OSGi Framework? Launcher adds more platform-specific feel and convenience. Double click on ourApp.exe is surely more to attracting to users then $ java -jar .....

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

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 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.

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”

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!

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.

Archives

Latest tweet

About us

We're small team of enthusiasts doing big things. Developing desktop and web application using Eclipse and OSGi in Java. Also providing consultancy and training. And this is our day-to-day developer blog.