4 - The Broker API

Table of Contents

• 4.1 Subclassing DtBroker
• 4.2 The Broker Initializer
• 4.3 Translators and MAK-Supplied Brokers
  • 4.3.1 Enabling Translators

The Broker API is in the libBroker library.

It is built on top of the Portal API as a framework for building brokers. The various protocol-specific broker APIs provided by MAK, such as the HLA broker API or the DIS broker API, are built on top of the broker API. For details, please see:

• The HLA Broker API
• The DIS Broker API
• The DDS Broker API
• The TENA Broker API

WebLVC includes an example broker, SimpleBroker, that shows how to use the broker API.

The only things that a broker must do are create an instance of DtPortalConnection and process shutdown requests. However, to be useful, a broker should do the following:

• Connect to the exercise for which it is translating
• Register callbacks for the messages it wants to receive from the Portal (object updates, interactions, and control messages)
• Create new message types for objects it needs to translate that are not part of the Portal's predefined objects
• Process input from its exercise
• Translate input and send it to the Portal
• Tick the Portal
• Translate updates from the Portal and send them to its exercise.

4.1 Subclassing DtBroker

Most WebLVC brokers start by subclassing DtBroker (broker.h). This class manages connections to the Portal through a DtPortalConnection. The DtBroker class manages the lifetime of the application, and passes callbacks from the Portal requesting that a GUI be launched. Please see the SimpleBroker example to see how this is done.

4.2 The Broker Initializer

The broker initializer (DtBrokerInitializer, in brokerInitializer.h) initializes a DtBroker instance by reading a configuration file and command line options. This class provides a consistent configuration file format and consistent command line options among brokers.

4.3 Translators and MAK-Supplied Brokers

All brokers supplied by MAK are built around translators. A translator is a class that is responsible for translating some discrete protocol component, either an object or an interaction. Some translators translate several tightly related interactions or objects, for example both Emitter Systems and Emitter Beams are translated by the Emitter System Translators. Each broker supplied by MAK has built-in translators. You can add new translators for new PDUs, interactions, objects, or messages.

Even though translators are fundamental to the MAK broker architecture, there is no requirement to use translators in user-written brokers. Nor is there a requirement to group some objects together into a single translator. There is no base object called DtTranslator in libBroker. Translators are used in WebLVC brokers more as an architectural component than a specific object instance, even though the HLA, DIS, DDS, and TENA brokers all contain base DtTranslator object classes. Because of the fluid definition of a translator, and the different requirements of translating different protocols, there is no universal DtTranslator class that meets the needs of all brokers.

4.3.1 Enabling Translators

Every HLA, DIS, DDS, and TENA translator requires the enableTranslator() member function:

virtual void enableTranslator(bool enabled)

This function should connect your callback functions to and from the network and the Portal. It provides the ability to enable and disable a translator in real time. When a translator is created, it should start disabled. Here is an example of using enableTranslator():

void DtEntityTranslator::enableTranslator(bool enabled)
{
   if(enabled)
   {
      myHlaReflectedList->addEntityAdditionCallback(
         DtEntityTranslator::hlaObjectAddedCb, this );
      myPortalReflectedManager->addAdditionCallback(
         DtEntityTranslator::portalObjectAddedCb, this );
   }
   else
   {
      myHlaReflectedList->removeEntityAdditionCallback(
         DtEntityTranslator::hlaObjectAddedCb, this );
      myPortalReflectedManager->removeAdditionCallback(
         DtEntityTranslator::portalObjectAddedCb, this );
   }
}

[<< The Portal API] [Home] [Top of Page] [The HLA Broker API >>]