Different ways to start the Eclipse Equinox OSGi console

If you are reading this, then most probably you have already tried to follow the process from my previous article on how to start Equinox OSGi console from locally downloaded Equinox p2 repository. The final command line which you need to execute is quite long and you might be asking yourself if there is easier way to start the Equinox OSGi console.

Yes, there are easier ways to achieve this and we'll explore them! Get some coffee and continue reading! :)

First I have to mention that in the next examples I'll be using the most up to date Equinox p2 repository which at this time is Mars.1 from 04-Sep-2015.

Enhancement 1

We don't need to provide the version part of the bundle JAR files when we add them to the property osgi.bundles. All we need is to provide the first part of the bundle binary, before the version part. Our modified command line now looks like this:

java -Declipse.ignoreApp=true -Dosgi.bundles=org.eclipse.core.runtime@start,org.eclipse.equinox.common,org.eclipse.core.jobs,org.eclipse.equinox.registry,org.eclipse.equinox.preferences,org.eclipse.core.contenttype,org.eclipse.equinox.app,org.eclipse.equinox.console,org.apache.felix.gogo.runtime,org.apache.felix.gogo.shell,org.apache.felix.gogo.command -Declipse.buildId=abc123 -jar plugins\org.eclipse.osgi_3.10.101.v20150820-1432.jar -consoleLog -console

This command line is considerably shorter and easier to modify. Note that the only place where we still use explicit versioning is for the actual java -jar call of the org.eclipse.osgi bundle.

Enhancement 2

At this point we can remove @start and -Declipse.buildId. We have described all bundle dependencies and the OSGi console will start without issues. Our modified command now looks like this:

java -Declipse.ignoreApp=true -Dosgi.bundles=org.eclipse.core.runtime,org.eclipse.equinox.common,org.eclipse.core.jobs,org.eclipse.equinox.registry,org.eclipse.equinox.preferences,org.eclipse.core.contenttype,org.eclipse.equinox.app,org.eclipse.equinox.console,org.apache.felix.gogo.runtime,org.apache.felix.gogo.shell,org.apache.felix.gogo.command -jar plugins\org.eclipse.osgi_3.10.101.v20150820-1432.jar -consoleLog -console

If you execute the ss command you will notice that some of the bundles are now in STARTING state. They used to be ACTIVE because of the @start option but this is not a problem at all. Our OSGi console is still working fine.

Enhancement 3

Probably you have noticed that our command line execution has created additional folder called configuration in our already existing plugins folder. The newly created configuration folder is the place where the Equinox OSGi framework stores all its internal configuration elements. As you may have already guessed, the location of this folder should not be there. In fact inside the plugins folder there should be only bundle JAR files and nothing more. Obviously, there is nothing wrong for now and everything works perfectly fine. Nevertheless, the location of the configuration folder should be somewhere else. Our goal for now is to place the configuration folder directly in the root folder of the Equinox p2 repository.

Option 1) We can use the parameter -configuration and provide the folder location which we want to use. In this case the modified command line looks like this.

java -Declipse.ignoreApp=true -Dosgi.bundles=org.eclipse.core.runtime,org.eclipse.equinox.common,org.eclipse.core.jobs,org.eclipse.equinox.registry,org.eclipse.equinox.preferences,org.eclipse.core.contenttype,org.eclipse.equinox.app,org.eclipse.equinox.console,org.apache.felix.gogo.runtime,org.apache.felix.gogo.shell,org.apache.felix.gogo.command -jar plugins\org.eclipse.osgi_3.10.101.v20150820-1432.jar -consoleLog -console -configuration configuration

Option 2) We can specify the configuration folder as Java property by setting the osgi.configuration.area property. In this case the modified command line looks like this:

java -Dosgi.configuration.area=configuration -Declipse.ignoreApp=true -Dosgi.bundles=org.eclipse.core.runtime,org.eclipse.equinox.common,org.eclipse.core.jobs,org.eclipse.equinox.registry,org.eclipse.equinox.preferences,org.eclipse.core.contenttype,org.eclipse.equinox.app,org.eclipse.equinox.console,org.apache.felix.gogo.runtime,org.apache.felix.gogo.shell,org.apache.felix.gogo.command -jar plugins\org.eclipse.osgi_3.10.101.v20150820-1432.jar -consoleLog -console

In both cases the configuration folder is now placed directly in the root folder of the Equinox p2 repository. This enhancement didn't make our command line shorter but we learned a powerful way to customize the location of the configuration folder which comes handy for our next enhancements.

Enhancement 4

We can significantly shorten our command line by placing almost all configuration elements in a special configuration file. By default this file is called config.ini and its default location is in the configuration folder. This enhancement involves some manual steps.

Step 1) Create folder configuration directly in the root folder of the Equinox p2 repository.

Step 2) Inside this folder create the file config.ini.

Step 3) Save the following content in the config.ini file:

osgi.bundles=org.eclipse.core.runtime,org.eclipse.equinox.common,org.eclipse.core.jobs,org.eclipse.equinox.registry,org.eclipse.equinox.preferences,org.eclipse.core.contenttype,org.eclipse.equinox.app,org.eclipse.equinox.console,org.apache.felix.gogo.runtime,org.apache.felix.gogo.shell,org.apache.felix.gogo.command

eclipse.ignoreApp=true

eclipse.consoleLog=true

What we just put in the fie is the list of bundles we want to be installed when we run our command line. On the next lines we have put the corresponding key/value property entries to ignore applications and to log all messages to the console. Now our modified command line looks like this:

java -jar plugins\org.eclipse.osgi_3.10.101.v20150820-1432.jar -console -configuration configuration

So, we managed to put almost all our configuration in the config.ini file. That's great! We also should be able to remove the -console parameter from the command line and place it in config.ini with its equivalent property osgi.console but I couldn't make it work on my machine. Sorry...

Enhancement 5

This enhancement is related to the previous one. There is a way to specify the bundles in config.ini on separate lines. The modified content of the config.ini file looks like this:

osgi.bundles=\

org.eclipse.core.runtime,\

org.eclipse.equinox.common,\

org.eclipse.core.jobs,\

org.eclipse.equinox.registry,\

org.eclipse.equinox.preferences,\

org.eclipse.core.contenttype,\

org.eclipse.equinox.app,\

org.eclipse.equinox.console,\

org.apache.felix.gogo.runtime,\

org.apache.felix.gogo.shell,\

org.apache.felix.gogo.command

eclipse.ignoreApp=true

eclipse.consoleLog=true

There are no changes related to the command line and it still looks like this:

java -jar plugins\org.eclipse.osgi_3.10.101.v20150820-1432.jar -console -configuration configuration

Enhancement 6

Instead of using the bundle org.eclipse.osgi we can use the so called launcher. Under the hood this is just another bundle placed in the plugins directory. The launcher allows us to call p2 specific applications like the publisher and the director. We can launch these apps in many ways including via the OSGi console (startApp command), but when we talk about p2 provisioning we usually use the launcher.

The launcher bundle is org.eclipse.equinox.launcher and our modified command line looks like this:

java -jar plugins\org.eclipse.equinox.launcher_1.3.100.v20150511-1540.jar -console -noExit -configuration configuration

Note that we also added the the flag -noExit to the command line. The primary function of the launcher is to start product applications and if we try to start interactive console through the launcher, then we also need to tell the launcher that we don't want to exit it.

This is all for now. We had to go through this whole process because we'll use what we just learned when we create our own p2 agent configuration which will allow us to play around with Equinox p2 applications. I'll discuss all of this in details in my next publication.