launcher

Overview
Attributes
Child Elements
Rendering Operations
Execution Operations
Nested Element Definitions
- Profile
Examples

Overview

The system <launcher> element defines a system process to be started by Magnet. Based on the provided configuration, Magnet will create a command string and execute the command at the OS level using the Java Runtime.getRuntime().exec(). You can also define environment variables that will be available to your system process.

Attributes

The following lists the xml attributes of the system launcher element:

Name	Description	Required	Interpolation
type	Defines the type of launcher. This attribute must have the system value.	yes	no
name	The name of this system launcher.	yes	no
command	The name of the system command to execute by this launcher.	yes	yes
workingDirectory	The directory in which the system process will be started.	yes	yes
os	Defines a simple operating name pattern that Magnet will use to filter the launcher's execution. If the value of this attribute is found in the os.name system properties, the launcher will be executed; otherwise it will be ignored.	no	no
default	The name of the default profile of this launcher. This is optionnl and allows specifying which profile of the launcher will be executed in the case that no launcher profile matches the execution profile.	no	no
waitTime	Tells Magnet how many milliseconds it needs to wait after launching this system process before resuming its execution. This can be used to insert some delay between launches when you magnet file contains many launchers.	no	no

Child Elements

The following list the possible child xml elements the system launcher element can hold:

Name	Cardinality	Description
profile	1 or *	Defines how the launcher is configured, by profile.

Rendering Operations

When a system <launcher> element is rendered, it performs the following operations in order:

Renders the appropriate <profile> child element.
Adds all the rendered parameters by the profile in the current Magnet context (for variable interpolation).
Renders the command and workingDirectory attributes (using variable interpolation).

Execution Operations

Once a system <launcher> element is rendered with success, it is executed with the following operations in order:

Performs the validation of the os attribute (if specified) with the os.name system property. The launcher is skipped if the two don't match.
Prepares all the environment variables to be passed to the system process.
Validates the working directory of the system process.
Creates a new thread and calls the system command using Runtime.getRuntime().exec().

Once the system process starts, the launcher's thread within Magnet is used to read any data coming from the standard output or the error output of the process. This polling loop is performed until the system process terminates.

Nested Element Definitions

Profile

The system <profile> element defines the configuration of the launcher for a given profile. It provides a way to define parameters specific to this launcher and the environment variable to use to call the system command - this can vary by profile.

Attributes

Name	Description	Required	Interpolation
name	The name of this profile.	yes	no

Child Elements

The following lists the possible child xml elements that can hold the system profile element:

Name	Cardinality	Description
parameters	0 or 1	Defines specific parameters that must be used (or overridden) for the launcher's execution.
environment	0 or 1	Defines the environment variables that can be passed to the system process.

Rendering Operations

When a system <profile> element is rendered, it performs the following operations in order:

Renders the <parameters> child element if provided.
Renders the <environment> child element if provided.

Examples

This first example shows a basic system launcher that calls a 'ls -la ./lib' command:

<magnet xmlns:magnet="http://schemas.sapia-oss.org/magnet/"
        name="SystemLauncherExample1"
        description="This is a first system launcher example.">
        
    <launcher type="system" name="list files" command="ls -la ${param.dir}"
              default="local" workingDirectory="${user.home}">
        
        <profile name="local">
            <parameters>
                <param name="param.dir" value="./lib" />
            </parameters>
            <environment>
                <variable name="USER_NAME" value="${user.name}" />
            </environment>
        </profile>
    </launcher>
</magnet>

This second example shows how to start a web browser on a Windows box:

<magnet xmlns:magnet="http://schemas.sapia-oss.org/magnet/"
        name="SystemLauncherExample2"
        description="This is a second system launcher example.">

    <parameters>
        <param name="SystemRoot" value="C:\Windows" />
    </parameters>

    <environment id="windows_env">
        <variable name="windir" value="${SystemRoot}" />
        <variable name="ComSpec" value="${SystemRoot}\system32\cmd.exe" />
        <variable name="CommonProgramFiles"
                  value="&quot;C:\Program Files\Common Files&quot;" />
    </environment>

    <launcher type="system" os="windows" name="startBrowser"
              command="cmd /C start /B IEXPLORE.EXE ${url}"
              workingDirectory="${user.home}" default="google" >
        
        <profile name="google">
            <parameters>
                <param name="url" value="http://www.google.com" />
                <param name="iexplorePath"
                       value="&quot;C:\Program Files\Internet Explorer&quot;" />
            </parameters>
            <environment parent="windows_env">
                <variable name="PATH"
                          value="${SystemRoot}\system32;${SystemRoot};${iexplorePath}"/>
            </environment>
        </profile>
        
        <profile name="yahoo">
            <parameters>
                <param name="url" value="http://www.yahoo.com" />
                <param name="iexplorePath"
                       value="&quot;C:\Program Files\Internet Explorer&quot;" />
            </parameters>
            <environment parent="windows_env">
                <variable name="PATH"
                          value="${SystemRoot}\system32;${SystemRoot};${iexplorePath}"/>
            </environment>
        </profile>
        
    </launcher>
</magnet>