magnet

Overview
Attributes
Child Elements
Rendering Operations
Examples

Overview

The <magnet> element is the root element of a Magnet configuration file. We can set a name to the magnet file and we can associate a brief description. Note however that these two attributes are not used by Magnet ; they only provide some sort of documentation information to the programmers.

One interesting feature of the magnet element is the extension mechanism that allows a given Magnet configuration file to extend another Magnet configuration - somewhat like inheritance. A Magnet can only extend a single parent at a time. In such a scenario, the child Magnets can access all the parameters and values defined by the parent Magnet and all the Launchers (of the inheritance tree) are executed, starting by the root Magnet.

Attributes

The following list the xml attributes of the Magnet element:

Name	Description	Required	Interpolation
name	The unique name of this Magnet configuration file. The system does not require the name to be unique but as a rule, it keeps things simpler if we do that.	no	yes
description	The description of this Magnet configuration file ; purpose, what it does, usage, ...	no	no
extend	The name of the resource that this magnet configuration file extends. The name of the resource can be an absolute file name or a file relative to the directory defined by the Java user.dir system property. The resource can also be a URL of corresponding to the file or http protocol schemes.	no	no

Child Elements

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

Name	Cardinality	Description
protocolHandlerDef	0 or *	Extension point to plug in your own protocols to resolve and load resources. By default Magnet handles the file and http schemes - corresponding to the file system and HTTP protocols.
scriptHandlerDef	0 or *	Extension point to plug in your own scripting engine. Magnet comes with Beanshell integration built-in.
launchHandlerDef	0 or *	Extension point to plug in your own class that launches applications. Magnet offers a java and a system launcher (to start Java and native processes, respectively).
script	0 or *	A Magnet configuration can contain various script elements to perform intialization tasks. At runtime Magnet will render and execute the script that matches the execution profile. If no script is provided for the profile and a script exists for the default one, it will be executed. Only one script by profile can exist within a Magnet configuration.
parameters	0 or *	To define global parameters within the Magnet. Parameters can be specified for a given profile or for all profiles (called the default profile).
codebase	0 or *	To define the value of the java.rmi.server.codebase system property
classpath	0 or *	To define common classpaths that can be reused later in java launchers. Creating classpaths at this level provides a handy way to manage the classloader hierarchy of the Java VM.
environment	0 or *	To define environment variables when using a system launcher.
launcher (java)	0 or *	To start a Java VM calling the main() method of a given class.
launcher (system)	0 or *	To start a system process by calling a command line.

Rendering Operations

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

Renders the parameters of the default profile.
Renders the parameters of the profile specified when invoking the magnet command.
Resolves the name attribute (with variable interpolation).
Renders the handler definitions, if any.
Renders the script of the specified profile. If none is found it renders the script for the default profile - if any.
Renders all the other generic objects of the object graph.
Renders all the launchers.

Examples

This first example is a very basic Magnet configuration with a name and a description.

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

The following example shows a Magnet configuration that extends another Magnet configuration file called C:\magnet\main.xml

<magnet xmlns:magnet="http://schemas.sapia-oss.org/magnet/"
        name="MagnetExample2"
        description="This is an extend example."
        extend="C:\magnet\main.xml">
...
</magnet>

The third example shows a Magnet configuration that extends a resource called http://www.mycorp.com/magnet/main.xml

<magnet xmlns:magnet="http://schemas.sapia-oss.org/magnet/"
        name="MagnetExample3"
        description="This is another extens example."
        extends="http://www.mycorp.com/magnet/main.xml">
...
</magnet>