The message information model

Everything within the baltrad messaging framework is dependent of varioustypes of messages.

These messages can be anything from simple keep alive message to complex variants like product generation messages and run job messages. Some messages are only used within the framework itself and is not intended for going outside the core software and other messages are intended for sending to other nodes or other modules like the product generation frameworks.

Below is the list of currently supported messages. It should be observed that there is no actual HTTP-label since the HTTP protocol is supposed to be supported by external adaptors. Instead the XML-structure is shown as well as the XMLRPC protocol since this is included in the beast framework.

Here all current messages are listed and a brief explanation on what their purpose is.

Alert message

See also: eu::baltrad::beast::message::mo::BltAlertMessage

As the name hints, the alert message is used for sending alert messages within and outside the system.

Usage

BltAlertMessage msg = new BltAlertMessage();
msg.setCode("E0001");
msg.setMessage("Communication error");

XML

<?xml version="1.0" encoding="UTF-8"?>
<bltalert>
  <code>ABC</code>
  <message>server failure</message>
</bltalert>

XMLRPC

method = "alert"
objects = {String(code), String(message)}

Command message

See also: eu::baltrad::beast::message::mo::BltCommandMessage

This message is used for sending command-like strings around, for example runscript.sh. It is mostly used for communicating with product generators.

Usage

BltCommandMessage msg = new BltCommandMessage();
msg.setCommand("ls -l");

XML

<?xml version="1.0" encoding="UTF-8"?>
<bltcommand>
  <command>runscript.sh</command>
</bltcommand>

XMLRPC

method = "execute"
objects = {String(command)}

Data message

See also: eu::baltrad::beast::message::mo::BltDataMessage

Internal message used for passing on information that there is a file available. Usually this message is passed on by an external data exchange mechanism. The file is the metadata structure that is provided by the baltrad-db apis. I.e. there is no XML or XMLRPC associated with the data message.

Usage

import eu.baltrad.fc.oh5.File;
...
File h5file = catalog.catalog(...);
BltDataMessage msg = new BltDataMessage();
msg.setFile(h5file);

but the usage that probably is going to be used the most is actually in the router rules.

  public IBltMessage handle(IBltMessage msg) {
    IBltMessage result = null;
    if (msg instanceof BltDataMessage) {
      File ohfile = ((BltDataMessage)msg).getFile();
      ...
    }
    return result;
  }

Dex data message

See also: eu::baltrad::beast::message::mo::BltDexDataMessage

This message is an oddball message and can be used for transmitting a h5file to another node. However, it does not contain the actual binary data or even the filename. This information must be added by the supporting adaptor in the same way as the receiving end must specifically set the file name.

Usage

BltDexDataMessage msg = new BltDexDataMessage();
msg.setFilename("/tmp/somefile.h5");

XML

<?xml version="1.0" encoding="UTF-8"?>
<bltdexdata/>

XMLRPC

Not supported

Generate message

See also: eu::baltrad::beast::message::mo::BltGenerateMessage

The generation message is probably going to be one of the more used messages message since it is the message for product generation.

It is up to the product generation frameworks to provide the name of the algorithm and how the arguments are supposed to be passed on. For example, rave takes a list of arguments while rack on the other hand takes one string containing all metadata. However, if a product generator is going to be used as default by beast, they must obey the format of the beast-specific rules for a number of algorithms. (see beast-algorithm table TBD).

Usage

BltGenerateMessage msg = new BltGenerateMessage();
msg.setAlgorithm("eu.baltrad.beast.VolumeComposite");
msg.setFiles(new String[]{"x1.h5", "x2.h5"});
msg.setArguments(new String[]{"--area=nrd2km", "--height=500", "--method=PCAPPI"});

XML

<?xml version="1.0" encoding="UTF-8"?>
<bltgenerate>
  <algorithm>eu.baltrad.beast.VolumeComposite</algorithm>
  <filelist>
    <file>x1.5</file>
    <file>x2.h5</file>
  </filelist>
  <arguments>
    <arg>--area=nrd2km</arg>
    <arg>--height=500</arg>
    <arg>--method=PCAPPI</arg>
  </arguments>
</bltgenerate>

XMLRPC

method = "generate"
objects = {String(algorithm), Array(String(file), String(file),..), Array(String(argument), String(argument),..)}

Multi routed message

See also: eu::baltrad::beast::message::mo::BltMultiRoutedMessage

If you for example want to explicitly specify several routes you can use the multi routed message. This is a good way to override the router rules but you need to be aware that if the route changes name you will have to modify the message as well. However, it can be quite useful if you want to ensure that you get the messages to specific nodes.

Since this is an internal message used for routing there is no XML or XMLRPC protocol.

Usage

BltMultiRoutedMessage msg = new BltMultiRoutedMessage();
List<String> destinations = new ArrayList<String>();
destinations.add("XMLRPC_1");
destinations.add("OTHERNODE");
msg.setDestinations(destinations);
msg.setMessage(msgtosend);

Routed message

See also: eu::baltrad::beast::message::mo::BltRoutedMessage

This is more or less like Multi Routed Message but used for specifying one individual route.

Since this is an internal message used for routing there is no XML or XMLRPC protocol.

Usage

BltRoutedMessage msg = new BltRoutedMessage();
msg.setDestination("XMLRPC_1");
msg.setMessage(msgtosend);

Trigger job message

See also: eu::baltrad::beast::message::mo::BltTriggerJobMessage

A quite useful message if you know the names of the registered rules and want to trigger a specific rule. This message is for example used by the scheduler.

Usage

BltTriggerJobMessage msg = new BltTriggerJobMessage();
msg.setId("abc");
msg.setName("rulename");
msg.setArguments(new String[]{"a1","a2"});

XML

<?xml version="1.0" encoding="UTF-8"?>
<blttriggerjob>
  <id>abc</id>
  <name>rulename</name>
  <arguments>
    <arg>a1</arg>
    <arg>a2</arg>
  </arguments>
</blttriggerjob>

If you want to react specically on a trigger in a rule, you can implement it like this

  public IBltMessage handle(IBltMessage msg) {
    if (msg instanceof BltTriggerJobMessage) {
      ...
    }
    ...
  }

XMLRPC

The usage of xmlrpc for job triggering is quite obscure but it is possible. It could for example for knowing that a specific trigger has been run or similar.

method = "triggerjob"
objects = {String(id), String(jobname), Array(String(argument), String(argument),..)}