App runner

Previous  Top  Next

An app runner is a general runner that can trigger any executable process.

We will illustrate by defining an app runner for the flavor com.headway.examples.osgi. In the next section, we'll return to this flavor and show how the java runner is much simpler (only possible in cases where the runner is implemented in Java).

Here's what the runner.xml file looks like:

<runner type="app">
   <params>
      <!-- note: descriptions removed -->
      <param key="dir" name="Bundles directory" type="file" mode="dirOnly" required="true"/>
      <param key="eclipse" name="Include Eclipse extensions" type="boolean" default="true"/>
   </params>
   <app exe="java">
      <arg>-classpath</arg>
      <arg>${flavor.home}/lib/com.headway.examples.osgi.jar${path.separator}${flavor.home}/lib/jdom.jar${path.separator}${flavor.home}/lib/old-random-build-of-apache-felix.jar${path.separator}${flavor.home}/lib/structure101g-utils.jar</arg>
      <arg>com.headway.open.osgi.S101gOutputter4OSGi</arg>
      <arg>-out</arg>
      <arg>${s101g.tmpfile}</arg>
      <arg>-dir</arg>
      <arg>${params.dir}</arg>
      <arg condition="params.eclipse">-eclipse</arg>
   </app>
</runner>

The key is to specify runner type=app and then provide an app element.

The app element must specify a value for the exe attribute, pointing to some executable (e.g. exe/bat, so/sh) on the user's machine. The path can be relative or fully-qualified.

Here or in any of the argument strings that follow, value strings can include variables in the form ${varname}. The following variables are available:

·	s101g.home - application home directory

·	s101g.tmpfile - unique temporary file used for a single run instantiation

·	flavor.home - flavor home directory

·	flavor.name - flavor name e.g. com.headway.examples.osgi

·	params.<param-name> - maps to a parameter value collected from the user

·	Any system property - see http://java.sun.com/j2se/1.5.0/docs/api/java/lang/System.html#getProperties() for details

In this example runner, we have specified the value to be "java". This will pick up the default JRE on the system if there is one. Note that there is no guarantee that there is a public JRE on the system (Structure101g may be running off a private bundled JRE), nor is there any control over the JRE version.

The next step is to specify the command line args. Clearly, the required set of args (and their sequence) is entirely dependent on the executable in question. The only common theme is that there needs to be a way for Structure101g to tell the runner where the XML data should be written, so that it knows what file to read in when the runner is finished. The value passed for this should always be the in-built variable s101g.tmpfile.

In this example, the first bunch of command-line arguments is the standard Java stuff to specify classpath and main class. Note that the classpath construction part uses the variable flavor.home to determine the correct path to its jar files as well as the (system property) variable path.separator (maps to ";" on Windows, ":" on Unix/Linux, etc.).

The remaining arguments are specific to the outputter class (here "com.headway.open.osgi.S101gOutputter4OSGi"). This expects

-out <path-to-output-file> -dir <path-to-bundles-directory> [-eclipse]

Here are the key points to be aware of:

·	As indicated above, the <path-to-output-file> is specified via the variable s101g.tmpfile.

·	The <path-to-bundles-directory> is specified via the variable params.dir. This means that the actual substitution value will be the setting that was entered by the user as a runner parameter.

·	The final argument has a condition attached. This means that (a) the value (here "eclipse") must map to a boolean parameter and (b) the value (here "-eclipse") will only be output if that parameter is set to true.