fipa::acl::Conversation Class Reference

#include <conversation.h>

Inherits fipa::acl::ConversationObservable.

Public Member Functions
	Conversation (const std::string &owner, const fipa::acl::ConversationID &conversationId=fipa::acl::ConversationID())
	Conversation (const std::string &owner, const fipa::acl::ACLMessage &initiator)
	Conversation (const Conversation &other)
virtual	~Conversation ()
void	setProtocol (const fipa::acl::Protocol &protocol)
fipa::acl::Protocol	getProtocol () const
void	setContentLanguage (const fipa::acl::ContentLanguage &language)
fipa::acl::ContentLanguage	getContentLanguage () const
void	setNumberOfSubConversations (int amount)
void	update (const fipa::acl::ACLMessage &msg)
std::vector< fipa::acl::ACLMessage >	getMessages () const
fipa::acl::ACLMessage	getLastMessage () const
bool	hasEnded () const
bool	hasMessages () const
std::string	getOwner () const
std::string	toString () const
Public Member Functions inherited from fipa::acl::ConversationObservable
	ConversationObservable ()
	ConversationObservable (const ConversationObservable &other)
	ConversationObservable (const fipa::acl::ConversationID &conversationId)
virtual	~ConversationObservable ()
void	setConversationId (const fipa::acl::ConversationID &conversationId)
fipa::acl::ConversationID	getConversationId () const
void	addObserver (const ConversationObserverPtr &observer)
void	removeObserver (const ConversationObserverPtr &observer)
void	notify (const fipa::acl::ACLMessage &msg, conversation::EventType eventType)
conversation::Status	getStatus () const
ConversationObserverList	getObservers () const
void	detachObservers ()
bool	hasObservers () const

Static Public Member Functions
static fipa::acl::ConversationID	generateConversationID (const std::string &topic="")
static std::string	toString (const std::vector< fipa::acl::ACLMessage > &messages)

Additional Inherited Members
Protected Attributes inherited from fipa::acl::ConversationObservable
fipa::acl::ConversationID	mConversationId

Detailed Description

A Conversation represents a flow of messages which have the conversation id and (commonly) the protocol in common

A conversation can be observed and observers will be notified when the conversation is updated

Definition at line 257 of file conversation.h.

Constructor & Destructor Documentation

Conversation() [1/3]

fipa::acl::Conversation::Conversation	(	const std::string &	owner,
		const fipa::acl::ConversationID &	conversationId = fipa::acl::ConversationID()
	)

Constructor of an empty conversation Owner and conversation id need to be provided

Parameters

owner	Owner of the conversation will be the current agent
conversationId	Conversation id - If no conversation id is provided, one will automatically be generated

Definition at line 100 of file conversation.cpp.

   : ConversationObservable(conversationId)
   , mOwner(owner)
   , mNumberOfSubConversations(0)
{
    if(mConversationId.empty())
    {
        mConversationId = generateConversationID();
    }
    LOG_DEBUG("Conversation created with id: %s\n", conversationId.c_str());
}

Conversation() [2/3]

fipa::acl::Conversation::Conversation	(	const std::string &	owner,
		const fipa::acl::ACLMessage &	initiator
	)

Constructor of a Conversation that requires an iniating message, i.e. includes a call to update

Definition at line 112 of file conversation.cpp.

   : ConversationObservable()
   , mOwner(owner)
   , mNumberOfSubConversations(0)
{
    update(initiator);
    LOG_DEBUG("Conversation created with id: %s\n", initiator.getConversationID().c_str());
    assert(!mConversationId.empty());
}

Conversation() [3/3]

fipa::acl::Conversation::Conversation

(

const Conversation &

other

)

Definition at line 122 of file conversation.cpp.

    : ConversationObservable(other)
    , mOwner(other.mOwner)
    , mProtocol(other.mProtocol)
    , mContentLanguage(other.mContentLanguage)
    , mNumberOfSubConversations(other.mNumberOfSubConversations)
    , mMessages(other.mMessages)
    , mStateMachine(other.mStateMachine)
{
}

~Conversation()

fipa::acl::Conversation::~Conversation ( )

virtual

Conversation destructor cleans also all related commands in the command controller

Definition at line 133 of file conversation.cpp.

{
}

Member Function Documentation

generateConversationID()

fipa::acl::ConversationID fipa::acl::Conversation::generateConversationID ( const std::string &  topic = "" )

static

Create a new ConversationID

Definition at line 285 of file conversation.cpp.

{
    uuid_t uuid;
    uuid_generate(uuid);

    char conversationId[37];
    uuid_unparse(uuid, conversationId);
    return std::string(conversationId) + "--" + topic + "--" + base::Time::now().toString();
}

getContentLanguage()

std::string fipa::acl::Conversation::getContentLanguage

(

)

const

Get content language (which is set by the initiating message)

Returns

ContentLanguage

Definition at line 137 of file conversation.cpp.

{
    return mContentLanguage;
}

getLastMessage()

fipa::acl::ACLMessage fipa::acl::Conversation::getLastMessage

(

)

const

Get the last message of a conversation

Returns

Last message of the conversation

Definition at line 245 of file conversation.cpp.

{
     boost::unique_lock<boost::mutex> lock(mMutex);
     return mMessages.back();
}

getMessages()

std::vector<fipa::acl::ACLMessage> fipa::acl::Conversation::getMessages ( ) const

inline

Get all messages in order of this conversation

Definition at line 322 of file conversation.h.

{ return mMessages; }

getOwner()

std::string fipa::acl::Conversation::getOwner

(

)

const

Get the name of the owner of this conversation, this is equal to the agent name of the system

Definition at line 280 of file conversation.cpp.

{
    return mOwner;
}

getProtocol()

fipa::acl::Protocol fipa::acl::Conversation::getProtocol ( ) const

inline

Get protocol (which is set by the initiating message)

Returns

Protocol

Definition at line 291 of file conversation.h.

{ return mProtocol; }

hasEnded()

bool fipa::acl::Conversation::hasEnded

(

)

const

Check if conversation has ended. This is closely related to the interaction protocol flow, i.e. only when the protocol has been validated the conversation will end

Returns

true if conversation ended, false otherwise

Definition at line 251 of file conversation.cpp.

{
    try
    {
        if(!mStateMachine.inFinalState())
        {
            LOG_DEBUG("Conversation did not end");
            return false;
            
        }
        LOG_DEBUG("Conversation ended");
        return true;
    }
    catch(const std::runtime_error& e)
    {
        // This very probably means the state machine has not been initialized properly,
        // as there was no message yet to know the protocol. Therefore, technically
        // the conversation did not end!
        LOG_WARN_S << "Runtime error when testing if conversation ended. Therefore not ended. Message: " << e.what();
        return false;
    }
}

hasMessages()

bool fipa::acl::Conversation::hasMessages

(

)

const

Check if this is an active conversation

Returns

true if conversation is active and has messages, false if is not active, i.e. has not started (yet)

Definition at line 274 of file conversation.cpp.

{
    boost::unique_lock<boost::mutex> lock(mMutex);
    return !mMessages.empty();
}

setContentLanguage()

void fipa::acl::Conversation::setContentLanguage ( const fipa::acl::ContentLanguage &  language )

inline

Set content language

Definition at line 296 of file conversation.h.

{ mContentLanguage = language; }

setNumberOfSubConversations()

void fipa::acl::Conversation::setNumberOfSubConversations ( int  amount )

inline

For protocols requiring a proxy/propagate behaviour, the number of sub conversations to be started needs to be known in order to monitor the end of the conversation correctly. E.g. a broker would set this to m, as soon as he knows that m agents will be contacted.

This MUST be called BEFORE an actual message of a sub conversation is sent.

Definition at line 311 of file conversation.h.

{ mNumberOfSubConversations = amount; }

setProtocol()

void fipa::acl::Conversation::setProtocol ( const fipa::acl::Protocol &  protocol )

inline

Set the protocol for this conversation

Definition at line 285 of file conversation.h.

{ mProtocol = protocol; }

toString() [1/2]

std::string fipa::acl::Conversation::toString ( const std::vector< fipa::acl::ACLMessage > &  messages )

static

Convert message list to string

Definition at line 295 of file conversation.cpp.

{
    std::stringstream ss;
    std::vector<fipa::acl::ACLMessage>::const_iterator cit = messages.begin();
    for(; cit != messages.end(); ++cit)
    {
        ss << cit->toString() << std::endl;
    }
    return ss.str();
}

toString() [2/2]

std::string fipa::acl::Conversation::toString

(

)

const

Convert conversation to string

Definition at line 306 of file conversation.cpp.

{
    std::stringstream ss;
    ss << "Conversation: " << std::endl;
    if(!mMessages.empty())
    {
        ss << "    id: " << mMessages.front().getConversationID();
    }
    ss << std::endl;
    ss << "    owner:              " << mOwner << std::endl;
    ss << "    protocol:           " << mProtocol << std::endl;
    ss << "    language:           " << mContentLanguage << std::endl;
    ss << "    # subconversations: " << mNumberOfSubConversations << std::endl;
    ss << "    # messages          " << mMessages.size() << std::endl;
    ss << "BEGIN " << std::endl;
    ss << toString(mMessages) << std::endl;
    ss << "END" << std::endl;

    return ss.str();
}

update()

void fipa::acl::Conversation::update

(

const fipa::acl::ACLMessage &

msg

)

Update a conversation using an incoming message

Parameters

msg	incoming or outgoing message

Definition at line 142 of file conversation.cpp.

{
    boost::unique_lock<boost::mutex> lock(mMutex);

    LOG_INFO("Update conversation: id '%s'", msg.getConversationID().c_str());
    LOG_INFO("Update message: performative: '%s' content: '%s'", msg.getPerformative().c_str(), msg.getContent().c_str());


    bool newConversation = false;
    try {
        // If protocol is unset we don't have a valid message
        // Thus at this point the conversation is not yet initialized
        if(mProtocol.empty())
        {
            std::string protocol = msg.getProtocol();
            try {
                if(!protocol.empty())
                {
                    mStateMachine = msStateMachineFactory.getStateMachine(protocol);
                    mStateMachine.setSelf( fipa::acl::AgentID(mOwner) );

                    mProtocol = protocol;
                    mContentLanguage = msg.getLanguage();
                    mConversationId = msg.getConversationID();

                } else {
                    LOG_ERROR("Protocol not set");
                    throw std::runtime_error("Protocol not set");
                }
            } catch(const std::runtime_error& e)
            {
                LOG_FATAL("Conversation could not retrieve statemachine for protocol '%s'. Check if protocol specification was loaded -- '%s'", protocol.c_str(), e.what());
                throw;
            }

            newConversation = true;

        } else if( mProtocol != msg.getProtocol())
        {
            // This probably means, it's a subProtocol message
            try {
                mStateMachine.consumeSubStateMachineMessage(msg, msStateMachineFactory.getStateMachine(msg.getProtocol()), mNumberOfSubConversations);
            } catch(const std::runtime_error& e)
            {
                std::string errorMsg = "Conversation: unexpected message with performative '" + msg.getPerformative() + "' for the protocol '" + msg.getProtocol() + "' ";
                errorMsg += " current state: '" + mStateMachine.getCurrentStateId() + "',";
                errorMsg += " role mapping -- " + mStateMachine.getRoleMapping().toString();
                errorMsg += " -- " + std::string(e.what()) + "\n";
                throw conversation::ProtocolException(errorMsg);
            }
            
            notifyAll(msg, false);
            return;
        } else if( msg.getProtocol().empty())
        {
            LOG_WARN("Conversation: received message has no protocol being set. Current conversation using '%s'", mProtocol.c_str());
        }

        if( msg.getLanguage().empty())
        {
            LOG_INFO("Conversation: received message has not language being set. Current conversation using '%s'", mContentLanguage.c_str());
        } else if(mContentLanguage != msg.getLanguage())
        {
            LOG_INFO("Conversation: message with different content language being inserted: current '%s' - to be inserted '%s'", mContentLanguage.c_str(), msg.getLanguage().c_str());
        }

        // update the message state machine
        try {
            mStateMachine.consumeMessage(msg);
        } catch(const std::runtime_error& e)
        {
            std::string errorMsg = "Conversation: unexpected message with performative '" + msg.getPerformative() + "' for the protocol '" + msg.getProtocol() + "' ";
            errorMsg += " current state: '" + mStateMachine.getCurrentStateId() + "',";
            errorMsg += " role mapping -- " + mStateMachine.getRoleMapping().toString();
            errorMsg += " -- " + std::string(e.what()) + "\n";
            throw conversation::ProtocolException(errorMsg);
        }

        notifyAll(msg, newConversation);

    } catch(...)
    {
        // Notify only to handle internally
        throw;
    }
}

---

The documentation for this class was generated from the following files:

• /build/rock-master-18.09-multiagent-fipa-acl-0.20180914/src/conversation_monitor/conversation.h
• /build/rock-master-18.09-multiagent-fipa-acl-0.20180914/src/conversation_monitor/conversation.cpp