Wallaroo Wiring Files

Wallaroo can load the description of your software from a configuration file in XML, JSON or WAL format (WAL is a synthetic custom format explicitly designed for wallaroo applications). You can use the file to specify the following:

which objects instantiate
the concrete class of each object
set the object attributes
the wiring between the objects
shared libraries to load

However, you can use more than one configuration file, or you can decide to specify only a part of your application with the configuration file.

Loading a wiring file

Once you have a Catalog object in your application, you can fill it by using the classes Configuration, XmlConfiguration or JsonConfiguration.

To load a wal file:

Catalog catalog;
...
Configuration file( "wiring.wal" );
file.Fill( catalog );
...
catalog.CheckWiring(); // throws a WiringError exception if any collaborator is missing

To load a xml file:

Catalog catalog;
...
XmlConfiguration file( "wiring.xml" );
file.Fill( catalog );
...
catalog.CheckWiring(); // throws a WiringError exception if any collaborator is missing

To load a json file:

Catalog catalog;
...
JsonConfiguration file( "wiring.json" );
file.Fill( catalog );
...
catalog.CheckWiring(); // throws a WiringError exception if any collaborator is missing

If there are classes defined in shared libraries, you should load them by using the code:

// create file as XmlConfiguration or JsonConfiguration class
XmlConfiguration file( "myFile.xml" );
// or JsonConfiguration file( "myFile.json" );
...
file.LoadPlugins(); // load the shared libraries specified in configuration file

XML Wiring file syntax

The XML file is composed by three sections:

the shared libraries to load (tag plugins)
the object instances definition (tag parts)
the objects wiring specification (tag wiring)

<wallaroo>

  <plugins>
    ...
  </plugins>

  <parts>
    ...
  </parts>

  <wiring>
    ...
  </wiring>

</wallaroo>

Shared Libraries Section

If you want to load classes implemented in shared libraries you must write a section plugins where you specify every shared library to load:

<plugins>
  <shared>shared_lib_1</shared>
  <shared>shared_lib_2</shared>
</plugins>

Please note that the library name does not include the file extension: wallaroo add the os specific extension (.dll on windows, .so on linux).

Parts Section

For each object you want to be created, you must write a section part, where you specify the instance name (the id you will use to refer to this object) and the class of the object:

<part>

  <name>object_name</name>
  <class>class_name</class>

  <attribute> <!-- optional -->
    <name>attribute1_name</name>
    <value>attribute1_value</value>
  </attribute>
  <attribute> <!-- optional -->
    <name>attribute2_name</name>
    <value>attribute2_value</value>
  </attribute>
  ...

  <parameter1> <!-- optional -->
    <type>string</type>
    <value>parameter_value</value>
  </parameter1>
  <parameter2> <!-- optional -->
    <type>int</type>
    <value>3</value>
  </parameter2>

</part>

The parameter type currently supported are:

char
unsigned char
int
unsigned int
long
double
bool
string

Wiring Section

For each relation between the instances you created, you must write a section wire, where you specify the two object you want to link (source and destination) and the name of the collaborator in the source object:

<wire>
  <source>source_object</source>
  <dest>dest_object</dest>
  <collaborator>plut_in_source_object</collaborator>
</wire>

Example

This is an example of a XML wiring file:

<wallaroo>

  <plugins>
    <shared>car</shared>
    <shared>engine</shared>
  </plugins>

  <parts>

    <part>
      <name>ferrari_f430</name>
      <class>Car</class>
      <parameter1>
        <type>string</type>
        <value>red</value>
      </parameter1>
    </part>

    <part>
      <name>maserati_granturismo</name>
      <class>Car</class>
      <parameter1>
        <type>string</type>
        <value>black</value>
      </parameter1>
    </part>

    <part>
      <name>m139p</name>
      <class>Engine</class>
    </part>

    <part>
      <name>f136e</name>
      <class>Engine</class>
    </part>

  </parts>

  <wiring>

    <wire>
      <source>ferrari_f430</source>
      <dest>f136e</dest>
      <collaborator>mainEngine</collaborator>
    </wire>

    <wire>
      <source>maserati_granturismo</source>
      <dest>m139p</dest>
      <collaborator>mainEngine</collaborator>
    </wire>

  </wiring>

</wallaroo>

XML schema

Here you can find the XML Schema of wallaroo xml wiring files.

JSON Wiring file syntax

The syntax of JSON file is equivalent to the XML one.

Follows an example of a JSON wiring file:

{
  "wallaroo":
  {

    "plugins":
    { 
      "shared": "car",
      "shared": "engine"
    },

    "parts":
    [
      {
        "name": "ferrari_f430",
        "class": "Car",
        "parameter1":
        {
          "type": "string",
          "value": "red"
        }
      },

      {
        "name": "maserati_granturismo",
        "class": "Car",
        "parameter1":
        {
          "type": "string",
          "value": "black"
        }
      },

      {
        "name": "m139p",
        "class": "Engine"
      },

      {
        "name": "f136e",
        "class": "Engine"
      }

    ],

    "wiring":
    [

      {
        "source": "ferrari_f430",
        "dest": "f136e",
        "collaborator": "mainEngine"
      },

      {
        "source": "maserati_granturismo",
        "dest": "m139p",
        "collaborator": "mainEngine"
      }

    ]
  }
}

WAL Wiring file syntax

A WAL file is the recommended way to specify the wiring of an application. Compared to XML and JSON, a WAL file is much more compact; moreover, the parser does not have a dependency from boost libraries.

A WAL file is composed of a sequence of sentences. Each sentence is terminated by a semicolon, and can be one of the following:

a @load statement (load a shared library)
a new statement (create a new instance)
a dependency specification

This is an example of the three statements:

@load "plugin";  # load the dynamic library named "plugin.so" or "plugin.dll"

myObject = new MyClass( att1=5, att2=3.14 );   # create the instance myObject of class MyClass and assign the attributes att1 and att2

myObject.dependency = otherObject;    # assign a dependency

You can insert line comments by using the # character.

Example

This is an example of a WAL wiring file:

@load "car";
@load "engine";

ferrari_f430 = new Car( color="red" );
maserati_granturismo = new Car( color="black" );

m139p = new Engine;
f136e = new Engine;

ferrari_f430.mainEngine = f136e;
maserati_granturismo.mainEngine = m139p;

As you can see, with the new syntax you only need one line to set up a dependency, while in XML you need five. Of course, the improvement is not the less typing rather the fact that the wiring can now fit on one page of your editor so that you can better understand the whole object lattice.