Using the Framesoc Bus

Summary

This page describes how to use the Framesoc Bus. This bus is used to send messages to the different parts of Framesoc and is based on the publish/subscribe pattern. This means that a message is not addressed to specific receivers but instead the message is published with a topic and every parts that subscribed to that topic will receive that message. Then each part decides how to process the received message.

This tutorial has been written with the version 1.0.10 of Framesoc. More technical explanations of the Framesoc bus can be found in section 3.2 of the technical report FrameSoC Workbench: Facilitating Trace Analysis through a Consistent User Interface (INRIA RT-447).

Messages

The type (or topic) of the messages sent on the bus is defined as a member of the enumeration FramesocBusTopic. The complete list of the currently supported topics, along with their descriptions, is specified in that enumeration. Each topic corresponds to a specific notification and can optionally have data associated with it. In order to keep the system generic, data are transmitted with the type Object, and it is therefore important to check that it is of the expected type (e.g. with the instanceof operator) before performing a cast.

Extend the list of topics

In order to add a new topic to the list of supported topics, simply add a new value to the enumeration in FramesocBusTopic. Please provide a description of its use and of the expected data argument.

Subscribe to a topic

To specify the types of messages a Framesoc part want to receive, it must subscribe to the corresponding topics. For a Framesoc part to be able to subscribe to a topic, it must have a class (typically the one corresponding to the view) that must become a listener of the bus by implementing the IFramesocBusListener interface. Currently, this means that the class will need to implement the method handle(FramesocBusTopic topic, Object data). This method will be called each time a message for a topic the class has subscribed to is sent and thus contains the code to process the received message. Its arguments are the topic, which is the type of message that is received, and the optional data (i.e. data can be null) that is associated to the message.

Subscribe using FramesocBusTopicList (recommended)

The easiest way to subscribe to a topic is to use a FramesocBusTopicList. As stated above, the class provided as argument when instantiating the FramesocBusTopicList must be a bus listener, i.e. must implement the IFramesocBusListener interface. Then it is possible to subscribe to all the topics it is interested in through the method addTopic(), before finally registering the subscription through the method registerAll(). Here is a small code example to illustrate how it works:

  // Register for all notifcations on traces
  topics = new FramesocBusTopicList(this);
  topics.addTopic(FramesocBusTopic.TOPIC_UI_TRACES_SYNCHRONIZED);
  topics.addTopic(FramesocBusTopic.TOPIC_UI_SYNCH_TRACES_NEEDED);
  topics.addTopic(FramesocBusTopic.TOPIC_UI_REFRESH_TRACES_NEEDED);
  topics.registerAll();

Then each time a message for one of those topics is sent on the bus, the handle() method of the class will be called.

When closing your application, do not forget to unregister from the topics that were subscribed. This is done through the method unregisterAll() of the FramesocBusTopicList.

  topics.unregisterAll();

Subscribe using the FramesocBus directly

Alternatively, it is also possible register/unregister topics directly to the FramesocBus. Since the FramesocBus is a singleton, you have to get the instance through the static method getInstance(). Then use the register()/unregister() methods for each topic you want to subscribe/unsubscribe. These methods takes as arguments the topic and the bus listener. For example, here is how you subscribe to a topic:

  FramesocBus.getInstance().register(FramesocBusTopic.TOPIC_UI_TRACES_SYNCHRONIZED, this);

Send a message on the bus

In order to send a message, you simply need to notify the bus you want to send a message through the method send(FramesocBusTopic topic, Object data). This method takes two arguments: the first one is the topic of the message, and the second one is the optional data that can be send along with the message. For example:

  FramesocBus.getInstance().send(FramesocBusTopic.TOPIC_UI_TRACES_SYNCHRONIZED, null);

##Example The code source of a simple tool example can be found in the directory fr.inria.soctrace.framesoc.tutorials.framesocbus. This simple example displays a list of the traces present in the Framesoc database. In order to keep the list up to date, it uses the Framesoc bus to get the notifications on any changes (addition, deletion...) performed on the traces.

Conclusion

In this tutorial we have seen how to use the Framesoc Bus to send a message, how to specify the type of messages we want to receive and how to handle the reception of the messages.