Magnet in 5 Steps

Overview

This section provides a basic example on how to create a Magnet file to run a Java standalone app. It uses the same basic example as the usage section of the Magnet home page. In five little steps you will have a quick understanding of the basics (it should not take more than 2 minutes).

For more details on how Magnet works or how you can adapt Magnet to you specific needs you can read the project home page, or you can look at the Magnet Reference for complete documentation on the xml configuration.

Step 1: Java Class

The first step: determining a Java class that you whish to run (it must have a main() method. For the current purpose we suggest the following HelloWorldApp class. It consists of a main() method that displays a simple "Hello" message to standard output. The exact message varies based on the first argument passed in. Have a look at the following code:

package org.sapia.magnet.example;
  
  public class HelloWorldApp{
  
    static final String DEFAULT_MSG = "Everyone";
    
    public static void main(String[] args){
      String msg;
      if(args.length == 0){
        msg = DEFAULT_MSG;
      }
      else{
        msg = args[0];
      }
      
      System.out.println("Hello " + msg);
    }
  }

Step 2: Base XML configuration

Now that you have determined which Java class you'll run, you can write Magnet xml configuration file. As a second step, we're creating the skeleton for that xml file. So let's start with the main magnet element along with the namespace declaration and some basic attributes that describes the purpose of the Magnet config.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE magnet PUBLIC "-//SAPIA OSS//Magnet DTD 2.0//EN"
                 "http://www.sapia-oss.org/dtd/magnet-2.1.dtd"> 

<magnet xmlns:magnet="http://schemas.sapia-oss.org/magnet/"
        name="HelloMagnet" 
        description="A very simple HelloWorld application">
        
</magnet>

Step 3: Java Launcher

Now let's add the configuration necessary to start the HelloWorldApp. We first add a launcher element of typejava. We pass the name of the main class (Java class with a main() method) we wish to run (mainClass attribute) along with the arguments we want to pass to the main() method (args attribute).

Because Magnet is based on the "profile" concept, we are not hardcoding the value passed to the main() method but simply use a variable that called here ${msg}. In the parameters child element we define the value of the msg variable, which will be passed to the main() method at runtime.

Finally we need to define the classpath that will contain our class that we wish to run. The classpath child element defines a simple path element that includes all the jar files of a given directory. The classpath definition being within the profile definition gives the flexibility of having different classpath based on the profile executed.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE magnet PUBLIC "-//SAPIA OSS//Magnet DTD 2.0//EN"
                 "http://www.sapia-oss.org/dtd/magnet-2.1.dtd"> 

<magnet xmlns:magnet="http://schemas.sapia-oss.org/magnet/"
        name="HelloMagnet" 
        description="A very simple HelloWorld application">
        
  <launcher type="java"
            name="helloWorld" 
            mainClass="org.sapia.magnet.examples.HelloWorldApp"
            args="${msg}">
            
      <profile name="english">
          <parameters>
              <param name="msg" value="world" />
          </parameters>
          <classpath>
              <path directory="${magnet.home}/examplelib">
                  <include pattern="*.jar" />
              </path>
          </classpath>
      </profile>
  </launcher>
  
</magnet>

Step 4: Execute our Magnet

We now have a first complete xml configuration file. We can now run the magnet with the following command and see what happens (assuming the xml file is named helloWorld.magnet.xml). For this first execution we use the english profile we have defined in our magnet file (denoted with the -p parameter in the magnet call).

magnet -f helloWorld.magnet.xml -p english

As you might expect magnet will parse the xml file and call our main method with the 'world' argument. Our main method will use the passed in string to diplay the message 'Hello world' on the system output.

Step 5: Adding Other Profiles

Now that we have something running, why not adding new profiles to change the runtime behavior of our main() method. We will add new profile in our launcher to display a greetings in different languages (Spanish and French). Each new profile simply changes the value of the msg parameter.

Another thing we changed in this step is the classpath definition. We can copy the same path element in each profile with the include pattern: it works just fine. For the sake of clarity, Magnet give us a way to "design" our classpaths and reuse them in various launchers. We do that with a classpath element that lives in the main magnet element: it defines a classpath (with some jar files) and we give it a name for future reference. We can now go back in our profiles and remove the duplicated path elements with the identifier or our main classpath. For this purpose we use the parent attribute.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE magnet PUBLIC "-//SAPIA OSS//Magnet DTD 2.0//EN"
                 "http://www.sapia-oss.org/dtd/magnet-2.1.dtd"> 

<magnet xmlns:magnet="http://schemas.sapia-oss.org/magnet/"
        name="HelloMagnet" 
        description="A very simple HelloWorld application">
        
  <classpath id="hello_cp">
      <path directory="${magnet.home}/examplelib">
          <include pattern="*.jar" />
      </path>
  </classpath>

  <launcher type="java"
            name="helloWorld" 
            mainClass="org.sapia.magnet.examples.HelloWorldApp"
            args="${msg}"
            default="english">
            
      <profile name="english">
          <parameters>
              <param name="msg" value="world" />
          </parameters>
          <classpath parent="hello_cp" />
      </profile>
      
      <profile name="spanish">
          <parameters>
              <param name="msg" value="el mundo" />
          </parameters>
          <classpath parent="hello_cp" />      
      </profile>
      
      <profile name="french">
          <parameters>
              <param name="msg" value="le monde" />
          </parameters>
          <classpath parent="hello_cp" />
      </profile>
  </launcher>

</magnet>

Now that we've centralized the classpath definition and created new profiles for the Spanish and French languages we can have some fun and run our magnet with the various profiles:

  • magnet -f helloWorld.magnet.xml -p english will output "Hello world"
  • magnet -f helloWorld.magnet.xml -p spanish will output "Hello el mundo"
  • magnet -f helloWorld.magnet.xml -p french will output "Hello le monde"

Further Reading

This section showed an oversimplified example, but the purpose was to show the base xml configuration and to give a first introduction to the concept of profiles in Magnet. For more details we suggest to read: