wiki:APIOverview

SEMAINE API Overview

It is advisable to set up and try out the DummySystem first. This page explains the code structure.

Introduction

The API is an abstraction of a Message-Oriented-Middleware (MOM), the Java Messaging System (JMS) implemented by !ActiveMQ. The purpose is to have logically separate components, which may or may not run in the same process, on the computer, or in the same operating system. Therefore, the API provides support for the following concepts, which will be described in detail below.

  • ComponentRunner the main program, which runs the components listed in a config file.
  • Component is the main abstraction of a processing unit, which can receive messages, send messages, and act spontaneously or react to incoming messages.
  • Receivers provide incoming information in the form of SEMAINEMessages. There are many specific types of Receiver and SEMAINEMessage for the various data types that are needed in the SEMAINE system.
  • Senders are the counterpart of Receivers for sending information to the JMS system. Again, many specific subtypes provide higher-level abstractions.
  • StateInfos and the corresponding StateReceivers provides a transparent way of sending and receiving "current best guess" variables, without having to worry about the XML encoding.

ComponentRunner

It reads config info from a config file, and starts all components listed, each as a separate thread. It is possible to start several ComponentRunner instances as separate processes, e.g. on separate machines.

Here is an example config file:

# SEMAINE component runner config file

semaine.components = \
    |eu.semaine.components.meta.SystemManager| \
    |eu.semaine.components.dummy.DummyFeatureExtractor| \
    |eu.semaine.components.dummy.DummyAnalyser| \
    |eu.semaine.components.dummy.DummyInterpreter| \
    |eu.semaine.components.dummy.DummyFMLActionProposer| \
    |eu.semaine.components.dummy.DummyBMLActionProposer| \
    |eu.semaine.components.dummy.DummyActionSelection| \
    |eu.semaine.components.dummy.DummyFML2BML| \
    |eu.semaine.components.dummy.DummyBMLRealiserAndPlayer| \
    |eu.semaine.components.MessageLogComponent($semaine.messagelog.topic, $semaine.messagelog.messageselector)| \

    
# Show messages in all topics:
semaine.messagelog.topic = semaine.data.>
# Show only dialog state messages:
#semaine.messagelog.topic = semaine.data.state.dialog

# Show all messages, i.e. periodic and event-based ones:
#semaine.messagelog.messageselector =
# Show only event-based messages:
semaine.messagelog.messageselector = event IS NOT NULL

It can be seen (MessageLogComponent) that constructors with String arguments can be used. The values for these strings can be either entered directly, as in

   |my.subclass.of.Component(direct value here, another one, and a third one)| \

or it is possible to refer to a property in the config file, by prepending the property name with a $, as in

   |my.subclass.of.Component($my.subclass.config.setting.one) | \

...

my.subclass.config.setting.one = the value to pass as argument to the constructor

Note that exactly one ComponentRunner attached to an !ActiveMQ server must start a eu.semaine.components.meta.SystemManager, which will keep track of which components are running and give components the "go" when all components are ready.

Component

Each Component runs as a separate thread. It circles through a main loop, as follows:

  • call act(), giving the component the chance to do something proactively;
  • wait for new messages, for a maximum number of milliseconds given in waitingTime (default: 100). During that waiting time, the thread does nothing, until either the waiting time is elapsed or a message arrives via one of the component's Receivers.
  • call react(SEMAINEMessage) with the message obtained from a Receiver, if there is one.

Subcomponents can change the waitingTime to suit their needs, see e.g. the constructor of !DummyFeatureExtractor.

Generally, subclasses of Component will want to do the following:

  • create senders and/or receivers in their constructors, and add them to the lists senders and receivers, respectively;
  • implement act() and/or react(SEMAINEMessage) according to their needs.

The dummy components in the package eu.semaine.component.dummy provide a wide range of examples for doing this.

Last modified 11 years ago Last modified on 08/26/08 17:39:21