8 - The TENA Broker API

The TENA Broker API is in the libTenaBroker library.

It is built on the Broker API. The TENA Broker Library is the full implementation of the TENA broker.

DtTenaBroker (tenaBroker.h) is the central class in libTenaBroker. It is a subclass of DtBroker that connects to a TENA execution using a VR-Link DtExerciseConn. The DtTenaBroker instance also opens a connection to Qt to process the broker's GUI. This instance is created by DtTenaBrokerApp (tenaBrokerApp.h).

The DtTenaBroker is responsible for creating object and interaction translators, configuring the TENA connection through a DtTenaBrokerInitializer (tenaBrokerInitializer.h) instance, and giving each translator processor time by calling tick().

The DtTenaBroker instance manages DtTranslator. There are two subclasses of DtTranslator: DtInteractionTranslator and DtObjectTranslator. The DtTenaBroker creates a translator for each message type. Each translator is responsible for translating its message type to a TENA class and back. Interaction translators register for updates for their interaction type. They translate the updates and pass them to their local TENA execution or the Portal, as appropriate.

Object translators register for object discovery, update, and removal messages, then translate and publish them to the Portal or TENA execution. A DtBrokerObject is maintained for every object the translator knows about. The broker object contains pointers to the reflected object, the publisher, and other data about the object, such as whether it has been discovered or filtered.

You can create translators in the following ways:

• Create translators that override existing translators. You would do this if you want to replace the functionality of an existing translator.
• Create a translator to add a new type of message to the broker.

When you create a translator class, you must create a static function called translatorName() that returns a c-string. For example, the DtAggregateTranslator class's code is equivalent to the following:

static const char* DtAggregateTranslator::translatorName()
{
   Return "Aggregate";
}

If you want to override this class, you add the same function to your class:

static const char* MyNewAggregateTranslator::translatorName()
{
   Return "Aggregate";
}

If you want to add a new type of translator, you provide a new name:

static const char* MyAppleTranslator::translatorName()
{
   Return "Apple";
}

The translator name is displayed on the Translators page of a connection's information dialog box.

Note

You must enable translators.

Brokers that want to replace a translator should register their translator with the factory after creating the DtTenaBroker. The broker should then tell the DtTenaBroker instance to load all its translators. For example, code to replace the Aggregate translator would look like this:

// Create a TENA broker application. This creates the DtTenaBroker 
// instance and registers all the default translators. It is initialized
// with a DtTenaBrokerInitializer object; in this case, tenaInit.
DtTenaBrokerApp  brokerApplication( tenaInit );

// Register a new translator creator for aggregates. Its factory knows 
// this class creates aggregates because the method translatorName() 
// returns a c-string called "Aggregate"
brokerApplication.tenaBroker()->objectTranslatorFactory()
->addCreator< MyNewAggregateTranslator >();

// run() calls the creator functions to load all required translators. It
// uses the creators registered in the previous lines of code.
brokerApplication->run();

[<< The DDS Broker API] [Home] [Top of Page] [The Broker Plug-in API >>]