---

IDEA::AgentRelay Class Reference
[Agent handle classes]

The singleton AgentRelay is responsible for relaying messages through the system. More...

#include <AgentRelay.hh>

List of all members.

Public Methods
	AgentRelay (const AgentTimingService *ats, const PslDatabase *db)
	Constructor, creates an instance of the AgentRelay.
	AgentRelay (const AgentTimingService *ats)
	Constructor, creates an instance of the AgentRelay.
	~AgentRelay ()
	Destructor.
void	stop ()
	Stops the invoking agent relay.
const PslDatabase *	getDatabase () const
	Returns the PslDatabase instance associated with the invoking agentrelay.
void	initialize ()
	Initializes the invoking agent relay.
void	registerComRelay (ComRelay *relay, const std::string &name, bool deleteInstance)
	Registers the ComRelay instance with key name and will activate the ComRelay instance by invoking ComRelay::activate. See Goal Timelines how the name has to match the target name in channel definition in the XIDDL model.
void	registerReactor (Reactor *reactor, const std::string &object, const std::string &timeline, const std::string &token, bool deleteInstance)
	Registers reactor to be notified of an incoming message if it is coming from the invoking agent, object, timeline and token.
void	registerShutdown (const std::string &objectClass, const std::string &attribute, const std::string &predicate)
	Registers to invoke the shutdown mechanism of the invoking agent for an incoming message for a token instance of predicate on the timeline attribute and class objectClass.
Reactor *	setDefaultReactor (Reactor *reactor, bool deleteInstance)
	Sets the default Reactor of the invoking AgentRelay.
Reactor *	getDefaultReactor () const
	Returns the default Reactor instance of the invoking AgentRelay. If no default Reactor has been set (AgentRelay::setDefaultReactor) this method will return 0.
void	sendStart (const PslToken *token) const
	Will send a start message for the token.
void	sendStop (const PslToken *token) const
	Will send a stop message for the token.
void	sendValue (const PslToken *token, int index) const
	Will send the value of parameter at position index (index counter starts with 1) for token.
void	sendStatus (const PslToken *token) const
	Will send the status of token.
void	receiveStart (MessageHandle msg) const
	Gate for receiving start messages.
void	receiveStop (MessageHandle msg) const
	Gate for receiving stop messages.
void	receiveTelemetry (MessageHandle msg) const
	Gate for receiving telemetry messages.
void	receiveObject (MessageHandle msg) const
	Gate for receiving object messages.
void	receiveValue (MessageHandle msg) const
	Gate for receiving value messages.
void	receiveStatus (MessageHandle msg) const
	Gate for receiving status messages.
void	receiveUserDefined (MessageHandle msg) const
	Gate for receiving user-defined messages.
void	sendMessage (MessageHandle message, const ComRelay *comRelay, bool isSubMessage=false) const
	Gate for sending out messages.
MessageFactory *	setMessageFactory (MessageFactory *factory, bool deleteInstance)
	Will set the message-factory used to create messages to factory.
const ComRelay *	getComRelay (const std::string &key) const
	Returns an instance of ComRelay registered under the name key using AgentRelay::registerComRelay.
const AgentTimingService *	getAgentTimingService () const
Private Types
typedef std::set< MessageObserver * >	MessageObserverSet
typedef std::map< std::string, MessageObserver * >	String2MessageObserverMap
typedef std::set< std::string >	StringSet
typedef std::map< std::string, StringSet >	String2StringSetMap
Private Methods
void	receiveMessage (MessageHandle msg, Reactor *reactor) const
	Gate for receiving messages will first notify the reactor and than all MessageObserver instances attached to the AgentRelay (in order of attaching).
	AgentRelay (const AgentRelay &)
	Copy constructor, not implemented by design.
AgentRelay &	operator= (const AgentRelay &)
	Assignment operator, not implemented by design.
const ComRelay *	getComRelay (const PslToken *token) const
	Returns the ComRelay instance to be used to send messages out.
Reactor *	getReactor (MessageHandle msg) const
	Will return the reactor which needs to be notified of message msg.
void	shutDown ()
	Shuts down the invoking agent-relat and all the observers and communication relays.
void	registerMessageObserver (MessageObserver *observer, const std::string &key, String2MessageObserverMap &container, bool deleteInstance)
MessageObserver *	getMessageObserver (const std::string &key, const String2MessageObserverMap &container) const
Static Private Methods
std::string	createKey (const std::string &str1, const std::string &str2, const std::string &str3)
	Creates a string out of three strings.
Private Attributes
MessageObserverSet	m_DeleteObservers
String2MessageObserverMap	m_RegisteredComRelay
String2MessageObserverMap	m_RegisteredReactors
MessageFactory *	m_MessageFactory
bool	m_DeleteMessageFactory
bool	m_DeleteDefaultReactor
Reactor *	m_DefaultReactor
Reactor *	m_ShutdownReactor
const AgentTimingService *	m_AgentTimingService
const PslDatabase *	m_Database
std::string	m_Name
ComRelay *	m_Boomerang
Friends
class	AgentImpl
class	ComRelay

---

Detailed Description

The singleton AgentRelay is responsible for relaying messages through the system.

Author:

David Rijsman rijsman@email.arc.nasa.gov

The AgentRelay is a (ACE) singleton which means there can be at most one instance of an AgentRelay and there is only one global API to access it. The global API for accessing is TheAgentRelay::instance() which returns a pointer to the instance of AgentRelay.

Sending messages

To send messages the following methods can be used:

• AgentRelay::sendStart, will create a StartMessage and send it out by notifying the correct communication relay
• AgentRelay::sendStop, will create a StopMessage and send it out by notifying the correct communication relay
• AgentRelay::sendValue, will create a ValueMessage and send it out by notifying the correct communication relay
• AgentRelay::sendStatus, will create a StatusMessage and send it out by notifying the correct communication relay

The MessageFactory is responsible for collecting all the necesarry data from the database (PslDatabase) and compose the correct data-structure for the required message.

Receiving messages

The AgentRelay should be invoked by ComRelay instances when a message has been received. The AgentRelay will update all the registered MessageObserver to the invoking AgentRelay using the following rule. All but messages of type Message::START go straight into the reactive-planner that has been set with the API AgentRelay::setReactivePlanner. For messages of type Message::START we check if a reactor has been set with the API AgentRelay::registerReactor and if the target location if the msg corresponds with the parameters passed when the reactor was registered. That is the object name of the target has to correspond with the object parameter passed, the attribute name of the target has to correspond with the timeline parameter and the source-token field of the message has to correspond with the token parameter. If no such reactor has been registered the reactive planner will be notified of the message.

---

Member Typedef Documentation

typedef std::set< MessageObserver* > IDEA::AgentRelay::MessageObserverSet [private]

typedef std::map< std::string, MessageObserver* > IDEA::AgentRelay::String2MessageObserverMap [private]

typedef std::map< std::string, StringSet > IDEA::AgentRelay::String2StringSetMap [private]

typedef std::set< std::string > IDEA::AgentRelay::StringSet [private]

---

Constructor & Destructor Documentation

IDEA::AgentRelay::AgentRelay (  const AgentTimingService *    ats, const PslDatabase *    db )

Constructor, creates an instance of the AgentRelay.

IDEA::AgentRelay::AgentRelay (  const AgentTimingService *    ats )

Constructor, creates an instance of the AgentRelay. This AgentRelay instance does not have an PslDatabase instance associated with it. This will disable the AgentRelay::registerReactor API.

IDEA::AgentRelay::~AgentRelay (    )

Destructor.

IDEA::AgentRelay::AgentRelay (  const AgentRelay &    )  [private]

Copy constructor, not implemented by design.

---

Member Function Documentation

std::string IDEA::AgentRelay::createKey (  const std::string &    str1, const std::string &    str2, const std::string &    str3 )  [static, private]

Creates a string out of three strings.

const AgentTimingService * IDEA::AgentRelay::getAgentTimingService (    )

const ComRelay * IDEA::AgentRelay::getComRelay (  const PslToken *    token )  const [private]

Returns the ComRelay instance to be used to send messages out.

const ComRelay * IDEA::AgentRelay::getComRelay (  const std::string &    key )  const

Returns an instance of ComRelay registered under the name key using AgentRelay::registerComRelay. Returns 0 if no such ComRelay has been registered under this name.

const PslDatabase * IDEA::AgentRelay::getDatabase (    )

Returns the PslDatabase instance associated with the invoking agentrelay.

Reactor* IDEA::AgentRelay::getDefaultReactor (    )

Returns the default Reactor instance of the invoking AgentRelay. If no default Reactor has been set (AgentRelay::setDefaultReactor) this method will return 0.

MessageObserver * IDEA::AgentRelay::getMessageObserver (  const std::string &    key, const String2MessageObserverMap &    container )  const [private]

Reactor * IDEA::AgentRelay::getReactor (  MessageHandle    msg )  const [private]

Will return the reactor which needs to be notified of message msg. All but messages of type Message::START go straight into the reactive-planner that has been set with the API AgentRelay::setReactivePlanner. For messages of type Message::START we check if a reactor has been set with the API AgentRelay::registerReactor and if the target location if the msg corresponds with the parameters passed when the reactor was registerd. That is the object name of the target has to correspond with the object parameter passed, the attribute name of the target has to correspond with the timeline parameter and the source-token field of the message has to correspond with the token parameter. If no such reactor has been registered the reactive planner will be notified of the message.

void IDEA::AgentRelay::initialize (    )

Initializes the invoking agent relay.

AgentRelay& IDEA::AgentRelay::operator= (  const AgentRelay &    )  [private]

Assignment operator, not implemented by design.

void IDEA::AgentRelay::receiveMessage (  MessageHandle    msg, Reactor *    reactor )  const [private]

Gate for receiving messages will first notify the reactor and than all MessageObserver instances attached to the AgentRelay (in order of attaching).

void IDEA::AgentRelay::receiveObject (  MessageHandle    msg )  const

Gate for receiving object messages.

void IDEA::AgentRelay::receiveStart (  MessageHandle    msg )  const

Gate for receiving start messages.

void IDEA::AgentRelay::receiveStatus (  MessageHandle    msg )  const

Gate for receiving status messages.

void IDEA::AgentRelay::receiveStop (  MessageHandle    msg )  const

Gate for receiving stop messages.

void IDEA::AgentRelay::receiveTelemetry (  MessageHandle    msg )  const

Gate for receiving telemetry messages.

void IDEA::AgentRelay::receiveUserDefined (  MessageHandle    msg )  const

Gate for receiving user-defined messages.

void IDEA::AgentRelay::receiveValue (  MessageHandle    msg )  const

Gate for receiving value messages.

void IDEA::AgentRelay::registerComRelay (  ComRelay *    relay, const std::string &    name, bool    deleteInstance )

Registers the ComRelay instance with key name and will activate the ComRelay instance by invoking ComRelay::activate. See Goal Timelines how the name has to match the target name in channel definition in the XIDDL model. The argument deleteInstance indicates if the registered relay should be deleted by the invoking AgentRelay at the end of it's lifecycle.

void IDEA::AgentRelay::registerMessageObserver (  MessageObserver *    observer, const std::string &    key, String2MessageObserverMap &    container, bool    deleteInstance )  [private]

void IDEA::AgentRelay::registerReactor (  Reactor *    reactor, const std::string &    object, const std::string &    timeline, const std::string &    token, bool    deleteInstance )

Registers reactor to be notified of an incoming message if it is coming from the invoking agent, object, timeline and token. This will override the notification of a ComRelay if the model specified to notify the ComRelay for this timeline (~relay-info file)

void IDEA::AgentRelay::registerShutdown (  const std::string &    objectClass, const std::string &    attribute, const std::string &    predicate )

Registers to invoke the shutdown mechanism of the invoking agent for an incoming message for a token instance of predicate on the timeline attribute and class objectClass.

void IDEA::AgentRelay::sendMessage (  MessageHandle    message, const ComRelay *    comRelay, bool    isSubMessage = false )  const

Gate for sending out messages. Will send out the message using the ComRelay instance. Will first send out sub-messages of message before sending the message itself. This will update all the MessageObserver instances attached to the invoking AgentRelay.

void IDEA::AgentRelay::sendStart (  const PslToken *    token )  const

Will send a start message for the token.

void IDEA::AgentRelay::sendStatus (  const PslToken *    token )  const

Will send the status of token.

void IDEA::AgentRelay::sendStop (  const PslToken *    token )  const

Will send a stop message for the token.

void IDEA::AgentRelay::sendValue (  const PslToken *    token, int    index )  const

Will send the value of parameter at position index (index counter starts with 1) for token.

Reactor * IDEA::AgentRelay::setDefaultReactor (  Reactor *    reactor, bool    deleteInstance )

Sets the default Reactor of the invoking AgentRelay. The argument deleteInstance indicates if the registered reactor should be deleted by the invoking AgentRelay at the end of it's lifecycle.

MessageFactory * IDEA::AgentRelay::setMessageFactory (  MessageFactory *    factory, bool    deleteInstance )

Will set the message-factory used to create messages to factory. If deleteInstance is true the invoking class will release the memory at the end of it's life-cycle. Will return the old instance if is not deleted.

void IDEA::AgentRelay::shutDown (    )  [private]

Shuts down the invoking agent-relat and all the observers and communication relays.

void IDEA::AgentRelay::stop (    )

Stops the invoking agent relay.

---

Friends And Related Function Documentation

friend class AgentImpl [friend]

friend class ComRelay [friend]

---

Member Data Documentation

const AgentTimingService* IDEA::AgentRelay::m_AgentTimingService [private]

ComRelay* IDEA::AgentRelay::m_Boomerang [private]

This is used to boomerang messages back to the AgentRelay if they are for registered Reactors AgentRelay::registerReactor(..)

const PslDatabase* IDEA::AgentRelay::m_Database [private]

Reactor* IDEA::AgentRelay::m_DefaultReactor [private]

bool IDEA::AgentRelay::m_DeleteDefaultReactor [private]

bool IDEA::AgentRelay::m_DeleteMessageFactory [private]

boolean indicating if the agent-relay should delete the factory

MessageObserverSet IDEA::AgentRelay::m_DeleteObservers [private]

all message observers we want to delete at the end of the agent-relay

MessageFactory* IDEA::AgentRelay::m_MessageFactory [private]

Factory class for message instances

std::string IDEA::AgentRelay::m_Name [private]

String2MessageObserverMap IDEA::AgentRelay::m_RegisteredComRelay [private]

Comunication relays registered using keys defined in the model

String2MessageObserverMap IDEA::AgentRelay::m_RegisteredReactors [private]

Registerd Reactor instances

Reactor* IDEA::AgentRelay::m_ShutdownReactor [private]

---

Contact information © IDEA