Eclipse is a modular architecture which is often associated with GUI applications, but in fact applications can be run in a headless environment from the command line as well. In this instalment, we'll look at the new IApplication and associated extension points to provide a runtime application mechanism.

In Eclipse 3.2, you could use IPlatformRunnable , but it's been replaced with IApplication in Eclipse 3.3. If you're still developing and supporting Eclipse 3.2, then you can take the concepts and use them against the older extension points and interface names; the principles are the same. The code assumes an Eclipse 3.3 runtime.

It's possible to write an OSGi application so that it can be started from the command line. The advantage of using an OSGi environment instead of a simple main method is that you get the full advantage of the modular bundle architecture, the ability to contribute extensions using either the Equinox extension registry or OSGi services, and all the benefits that a managed versioned system gives you. There's two ways of doing this; contribute an application extension which the OSGi environment can start, or have a main method that kicks off an OSGi environment via EclipseStarter. We'll just be looking at the IApplication variant here.

An eclipse application implements the IApplication extension point. An application can be started or stopped (like a bundle) and has access to a context for acquisition of arguments etc. A simple application looks like this:

import org.eclipse.equinox.app.IApplication;
import org.eclipse.equinox.app.IApplicationContext;
public class HelloWorld implements IApplication {
  public Object start(IApplicationContext context) throws Exception {
    System.out.println("Hello world!");
    return IApplication.EXIT_OK;
  }
  public void stop() {
  }
}

The bundle's manifest needs org.eclipse.core.runtime as a requirement; at run-time, it will also need the org.eclipse.equinox.app and org.eclipse.equinox.common bundles.

In order to run it, we need to select it as an application to run. We do this on the command line with the -application flag, or via PDE's 'Run an application' launch dialog:



However, it won't show up in either of those places until there's an extension point for the application. This gives our application an ID (which we use from the command line) and associates it with the class:


<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.2"?>
<plugin>
<extension
id="helloworld"
point="org.eclipse.core.runtime.applications">
<application>
<run
class="HelloWorld">
</run>
</application>
</extension>
</plugin>


This will allow us to run the application with -application org.example.helloworld from the command line; it will also display it in the pop-up menu for the launch application. If you run it, you should see Hello world! being printed.

Often, you'll want to be able to process arguments as part of the application. Instead of being passed a String[] directly, as you get from a Java main method, you have to obtain it from the IApplicationContext . Helpfully, it supplies a getArguments() call which you can use to find out what arguments have been passed. Unhelpfully, it doesn't actually give you the arguments; instead, you have to look up a random key application.args to obtain a String array which you can then process:

String[] args = (String[])context.getArguments().get("application.args")));

Thus, you can run and interact with your application like:

eclipse -application org.example.helloworld Hello World

Unfortunately, not all is well. If you run your application with the PDE bundles installed (which is more than likely, if you're developing bundles) then PDE automatically (and somewhat randomly) adds a -pdelaunch argument. This means that if you're developing an application, and you want to test it out with arguments (such as building an OSGi 'copy' or 'tar' type command) then you can't easily do this with PDE. It's even worse if you're building a command like 'tar', which uses - to signify command-line flags, one character at a time; the -pdelaunch would be interpreted as 'some permissions, diff, one file-system, update, norecurse, create, dereference'. Not very helpful. And there's no way you can get rid of it from the launch whilst the PDE plugins are installed in the runtime. You can voice your concern at bug 195454 , because at the moment, it doesn't look like it will be addressed as it's more important for PDE to work than for applications to work.

You can also start your application from the Equinox OSGi console. If you run the application with -console -noExit , you get an OSGi console prompt that you can use to start your application:

osgi> startApp org.example.helloworld
Launched application helloworld.0
Hello world!

Unfortunately, you have to chant magic incantations before you can do this. The first is that you need to tell Eclipse to register IApplication descriptors for each of the applications, which you do with:

-Declipse.application.registerDescriptors=true -Declipse.ignoreApp=false

For reasons only known to the Eclipse team, it actually ignores any application you pass in and doesn't register application descriptors by default. These issues just go out of their way to make writing applications difficult, and certainly not the kind of thing that is easy to debug. Without both of these, you can't start apps in the OSGi console.

Secondly, there's an interesting quirk in the way applications are hosted. If you don't specify an application with -application on the command line, then it runs the org.eclipse.equinox.app.error application, which does nothing.

However, when you run applications, you can either run them on the main thread or any thread. The command line runs on the main thread, and thus any other main apps can't run from the equinox console ; they just hang if tried. So you need to have applications that run under the any thread, which you do by modifying the plugin.xml :


<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.2"?>
<plugin>
<extension
id="helloworld"
point="org.eclipse.core.runtime.applications">
<application thread="any">
<run
class="HelloWorld">
</run>
</application>
</extension>
</plugin>


This will allow you to start the application under the OGSi console. If you want to be able to run it more than once, then you can also add cardinality="*" to the application element; that can be useful if you want to host multiple servers via the OSGi console.

There's also a bug (which may be fixed and released for 3.3.1 ) in which an application under the any thread can't be started from the command line. This means that some systems provide two different applications , one which is started on the 'main' thread (and therefore can be used from the command line) and one on the 'any' thread (which can be run from the OSGi console).

The other OSGi commands that you can use include stopApp and apps , which allow you to see what other applications are installed and enable you to start and stop them.

Even though there's a few workarounds which need to be done to make the IApplication code work, it's the way that applications will be handled in the 3.3 timeframe and in the future, so it's worth learning about the issues and workarounds now to apply to your code.