"Hello World"

In this exercise we implement the usual "Hello World" example in OMS to introduce the concept of a component, a simulation file, the notion of a parameter, and parameter passing from the simulation file to the component. The one and only purpose of the component is to print out the "hello world" message.

Concept

The drawing below sketches the structure of the "Hello World" exercise. There are two files needed for this example, a Java class (Component.java) representing the component and a simulation file (ex00_HelloWorld.sim) that brings all pieces together. Elements in black describe the component parts, elements in red belong to the simulation.

Figure 1: "Hello World" simulation structure.

The simulation (1) defines the component c (2) that receives the parameter string "Hello World" (3) via its message field (4). On simulation execution the component c will print out the content of message (5), "Hello World...".

Implementation

Let's start with the component ex00.Component. The complete source code is shown below. Annotations are imported from the OMS Annotations API. It is defined in a package ex00.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

package ex00;

import oms3.annotations.*;

public class Component {

    @In public String message;

    @Execute
    public void run() {
        System.out.println(message);
    }
}

The component is an ordinary Java class. It is sometimes also called "plain old Java object" (POJO). Only the use of a few annotations (@...) make it OMS specific.

The annotated field message is defined as public String and represents the component's input. The @In annotation is used to provide that hint to the OMS framework.

The other annotation used in Component is @Execute. It points OMS to the method of this class that must be invoked on component execution. This method's name is run(). It could be any other method as long as it is a public void method with no arguments. Note that only one method on a class can be annotated with @Execute

The run() method prints out the message to the console as standard output.

The other file in this example is the simulation file. It encapsulates the component and the input data (parameter). It is listed.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

import static oms3.SimBuilder.instance as OMS3

/*
 * Classic 'Hello World'..
 * passing in a string message to an '@In' field of a component;  
 * the component just prints out the message.
 */
OMS3.sim {

    resource "$oms_prj/dist/*.jar"

    model() {
        components {
            // "componentname" -> "component class"
           "c" "ex00.Component"
        }

        parameter {
            // "componentname.@In_fieldname" -> object
             "c.message" "Hello World  ..."
        }
    }
}

The simulation file ex00_HelloWorld.sim is shown in Listing 2. A simulation file is a description of all the resources involved in a simulation. The import statement in line 1 defines the symbol OMS3 (Note: This line is the same in all types of OMS simulations)

From line 8 on all simulation (.sim) resources are listed in a structured way.

The resource element defines the executable file(s) belonging to this simulation. All jar files found in the dist folder if the project are added to the classpath of a simulation run. This way, the component ex00.Component (Line 15) is accessible in this script.

The model element (line 12-22) defines the parts of this example simulation with respect to components and their initial settings for parameters. The component c is declared in line 15 as of type ex00.Component. The string "Hello World ..." is passed to the field message of c in line 20.

Execution

The example ex00_HelloWorld.sim can be executed in different ways. The easiest way is probably by using OMSConsole. Load the whole examples-basic project and hit the run button on the Helloworld tab.

Another way to execute the Hello World example is by just using the command line as listed below.

1
2
3

$ java -Doms_prj=/prjs/oms3.prj.examples-basic  -jar $HOME/.oms/3.2/oms-all.jar -r ex00_HelloWorld.sim
Hello World  ...
$ _

Note

The command line above uses the Java property oms_prj for pointing to the project folder. Before OMS 3.2.1, this property must be named oms3.prj