parameters

• Overview
• Attributes
• Child Elements
• Rendering Operations
• Examples
• Nested Element Definition
  • Param
    • Attributes
    • Rendering Operations
    • Param Examples

Overview

The <parameters> element defines a group of parameters (child <param> elements). The rationale behind this element is to be able to associate all the variables it contains to a given profile - thus making it profile-aware.

The profile is specified with the profile attribute. This attribute is optional. If it is not specified, then all the variables the element contains are considered "global" and they are always rendered and available. If the profile attribute is specified, the variables the element contains will only be rendered and made available if the attribute matches the profile that is specified at startup.

Attributes

The following lists the xml attributes of the <parameters> element:

Child Elements

The following lists the possible child xml elements the <parameters> element can hold:

Rendering Operations

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

1. Renders each param definition it contains. A param will be rendered only if the evaluation of the conditionnal attributes if or unless is true; otherwise the param is skipped and the rendering process goes on to the next one.
2. Adds each param to the Magnet's context or to the system properties (depending on the scope).

Examples

This first example defines a parameters element that would contains global variables.

<magnet xmlns:magnet="http://schemas.sapia-oss.org/magnet/"
        name="ParametersExample1"
        description="This is a simple example.">
...
    <parameters>
        ...
    </parameters>
...
</magnet>

This second example defines a parameters element that would contain variables associated to a "dev" profile.

<magnet xmlns:magnet="http://schemas.sapia-oss.org/magnet/"
        name="ParametersExample2"
        description="This is a second example.">
...
    <parameters profile="dev">
        ...
    </parameters>
...
</core:magnet>

Nested Element Definition

Param

The <param> element defines a parameter (which can later be referred to as a variable) containing a value that may be referenced in a Magnet configuration file. This element is always nested within a <parameters> element and basically consists of a name-value pair. Because it is alway within a <parameters> element, the value of a variable will be assigned (or not) according to the profile specified for that element; variables of "default" parameters will always be rendeder and variables of a specific profile will only be rendered if that profile was specified at startup.

If a variable is defined more than once for different <parameters>, the value of that variable can be overridden, meaning the value of the variable will change according to the profile in the context of which the Magnet configuration is run. If a variable is defined globally (not associated to a profile) and the same variable is defined for a specific profile, the value of the variable will be the one corresponding to the profile - if it matches it profile name specified at startup.

The value of a variable can contain another variable name using the notation ${variable_name}. The only care to take in that situation is to make sure that the variable it refers to is already defined. Since the variables are processed sequentially in Magnet, you would need to define your <param> element before you use the variable in the value of another.

Each variable that is defined in a Magnet configuration file can "reside" in virtually two places. The scope attribute of the <param> element provides a way to define where we want a variable to reside. Two values are possible for that attribute:

• magnet - The variable will be added to the Magnet's context and the value will only be accessible from within that Magnet.
• system - The variable will be added to the Java system properties and the value will be accessible using System.getProperty(...).

Attributes

The following lists the xml attributes of the <param> element:

Rendering Operations

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

1. Resolves the value, scope, if and unless attributes (using variable interpolation).

Param Examples

This first example defines two sets of the same variables: foo and username. The example shows how to use Magnet's variable overload feature. If that Magnet would be run under the "dev" profile, the value of the foo variable would be bar2, otherwise the value of the variable would be bar.

<magnet xmlns="http://schemas.sapia-oss.org/magnet/core/"
        name="ParamExample1"
        description="This is a simple example.">
...
    <parameters>
        <param name="foo"      value="bar" />
        <param name="username" value="scott" />
    </parameters>

    <parameters profile="dev">
        <param name="foo"      value="bar2" />
        <param name="username" value="developer" />
    </parameters>
...
</magnet>

This second example shows how to export variables to the Java system properties using the scope attribute. In that example the hostname variable would be added the the system properties. The result is the same as adding the argument -Dhostname=myhost.mydomain.com to the command line when invoking a java VM.

<magnet xmlns:magnet="http://schemas.sapia-oss.org/magnet/"
        name="ParamExample2"
        description="This is a second example.">
...
    <parameters>
        <param name="hostname" value="myhost.mydomain.com" scope="system" />
        <param name="port"     value="80" />
    </parameters>
...
</magnet>

In this third example we see that the server.url variable incorporates other variables in its own value. When we run that magnet for the dev profile, the server.url variable would have the value http://192.168.57.100:80.

<magnet xmlns:magnet="http://schemas.sapia-oss.org/magnet/"
        name="ParamExample3"
        description="This is a third example.">
...
    <parameters>
        <param name="server.port" value="80" />
    </parameters>

    <parameters profile="dev">
      <param name="server.ip"  value="192.168.57.100" />
      <param name="server.url" value="http://${server.ip}:${server.port}" />
    </parameters>
...
</magnet>

In this fourth example we are using the if and unless attributes to perform conditional variable assignment. The first variable, magnet.home, will be assigned the value of user.dir only if it was not previously set and a msg variable will be assigned the value "Using the provided magnet.home" if the variable magnet.home is set.

<magnet xmlns:magnet="http://schemas.sapia-oss.org/magnet/"
        name="ParamExample3"
        description="This is a third example.">
...
    <parameters>
        <param name="magnet.home" value="${user.dir}"
               unless="magnet.home" scope="system"/>
        <param name="msg" value="Using the provided magnet.home"
               if="magnet.home" scope="system"/>
    </parameters>
...
</magnet>