fipa::acl::State Class Reference

implements a state of the StateMachine class More...

#include <state.h>

Inherited by fipa::acl::default_state::ConversationCancelling, fipa::acl::FinalState, and fipa::acl::UndefinedState.

Public Member Functions
	State ()
	empty constructor initializes default fields More...
	State (const StateId &id)
	constructor taking the unique name(id) of the state as arguement More...
Transition	addTransition (const Transition &t)
const Transition &	getTransition (const ACLMessage &msg, const MessageArchive &archive, const RoleMapping &roleMapping) const
	Check whether the received message triggers a transition. More...
void	consumeSubStateMachineMessage (const ACLMessage &msg, const fipa::acl::StateMachine &stateMachine, const fipa::acl::RoleMapping &roleMapping, int numberOfSubConversations)
const Transition &	getSubstateMachineProxiedTransition (const ACLMessage &msg, const MessageArchive &archive, const RoleMapping &roleMapping)
	Check whether the received message triggers a substatemachine proxied transition. This method is not const, as the generated transitions will be added when they trigger successfully. More...
void	generateDefaultTransitions ()
	method that generates implicit generic transitions applicable to all states, that may or may not be speciffied in the configuration file such as not-understood transition (if it is specified it is not doubled); this method is to be called after all states specified in the configuration have been added to the state machine, preferably after all generic transition have been added as well More...
bool	isFinal () const
bool	isFinished () const
	method that returns whether the state is a finished state or not. In the case of a state with embedded state machines, this is a bit more coplex, see the implementation More...
bool	isDefaultState () const
	Test if state belongs to the default state or not. More...
void	setId (const StateId &id)
	setter method for the uid field of the state NOTE: maybe should be taken out and name only be allowed to be set on More...
std::string	getId () const
	getter method for the uid field of the class More...
const std::vector< Transition > &	getTransitions () const
const std::vector< EmbeddedStateMachine > &	getEmbeddedStatemachines () const
void	addEmbeddedStateMachine (fipa::acl::EmbeddedStateMachine embeddedStateMachine)
std::string	toString () const
std::string	toXML () const

Static Public Attributes
static const StateId	UNDEFINED_ID = "__undefined__"
static const StateId	NOT_UNDERSTOOD = "__internal_state:not_understood__"
static const StateId	CONVERSATION_CANCELLING = "__internal_state:conversation_cancelling__"
static const StateId	CONVERSATION_CANCEL_SUCCESS = "__internal_state:conversation_cancel_success__"
static const StateId	CONVERSATION_CANCEL_FAILURE = "__internal_state:conversation_cancel_failure__"
static const StateId	GENERAL_FAILURE_STATE = "__internal_state:general_failure__"

Protected Member Functions
void	setFinal (bool final)
	setter method for the final field of the class When changing the final state flag make sure you either remove existing transitions or create the default transition if needed More...

Friends
class	Transition
class	default_transition::NotUnderstood
class	default_transition::ConversationCancelling
class	default_transition::ConversationCancelSuccess
class	default_transition::ConversationCancelFailure
class	default_transition::GeneralFailure
class	StateMachineReader
class	StateMachine

Detailed Description

implements a state of the StateMachine class

Definition at line 41 of file state.h.

Constructor & Destructor Documentation

State() [1/2]

fipa::acl::State::State

(

)

empty constructor initializes default fields

Definition at line 33 of file state.cpp.

    : mId(State::UNDEFINED_ID)
    , mIsFinal(false)
{
}

State() [2/2]

fipa::acl::State::State

(

const StateId &

id

)

constructor taking the unique name(id) of the state as arguement

Parameters

id	intended id for the state

Definition at line 39 of file state.cpp.

    : mId(uid)
    , mIsFinal(false)
{
}

Member Function Documentation

addEmbeddedStateMachine()

void fipa::acl::State::addEmbeddedStateMachine

(

fipa::acl::EmbeddedStateMachine

embeddedStateMachine

)

Add an embedded state machine.

Definition at line 357 of file state.cpp.

{
    mEmbeddedStateMachines.push_back(embeddedStateMachine);
}

addTransition()

Transition fipa::acl::State::addTransition

(

const Transition &

t

)

Add a state transition

Returns

Transition with update source state field

Definition at line 45 of file state.cpp.

{
    std::vector<Transition>::const_iterator it;
    it = std::find(mTransitions.begin(), mTransitions.end(), t);
    if( it == mTransitions.end())
    {
        Transition transition = t;
        transition.setSourceState(mId);
        mTransitions.push_back(transition);
        return transition;
    } else {
        return *it;
    }
}

consumeSubStateMachineMessage()

void fipa::acl::State::consumeSubStateMachineMessage	(	const ACLMessage &	msg,
		const fipa::acl::StateMachine &	stateMachine,
		const fipa::acl::RoleMapping &	roleMapping,
		int	numberOfSubConversations
	)

Tries to consume a message meant for a sub state machine.

Exceptions

runtime_error

if this does not work

Definition at line 147 of file state.cpp.

{
    LOG_INFO("State consumeSubStateMachineMessage");
    
    // Loop through all not-ended sub state machines
    for(std::vector<StateMachine>::iterator it0 = mSubStateMachines.begin(); it0 != mSubStateMachines.end(); it0++)
    {
        if(it0->inFinalState() || it0->inFailureState())
        {
            // StateMachine ended already
            continue;
        }
        // Test if this StateMachine is correct by maintaining a copy of it
        StateMachine copy = *it0;
        
        // Test the update
        try {
            LOG_DEBUG("Trying an existing sub state machine");
            it0->consumeMessage(msg);
            // It worked
            return;
        } catch(const std::runtime_error& e)
        {
            LOG_DEBUG("Sub state machine incorrect: ", e.what());
            // The state machine was obviously not correct, we play back the copy
            *it0 = copy;
        }
    }
    
    LOG_DEBUG("Trying to search for a fitting a embedded state machine");
    
    EmbeddedStateMachine* embeddedStateMachinePtr = NULL;
    // We must be in a state that allows subProtocols
    std::string protocol = msg.getProtocol();
    
    // Search for an embedded state machine with the same protocol
    std::vector<EmbeddedStateMachine>::iterator it;
    for(it = mEmbeddedStateMachines.begin(); it != mEmbeddedStateMachines.end(); it++)
    {
        // Protocol must match Regex
        boost::regex peformativeRegex(it->name);
        if(regex_match(protocol, peformativeRegex))
        {           
            // Check that the sender role is correct
            // This throws if the mapping does not exist
            const AgentIDList l = roleMapping.getMapping().at(it->fromRole);
            AgentIDList::const_iterator lit = std::find(l.begin(), l.end(), msg.getSender());
            if(lit == l.end())
            {
                // Sender does not match
                continue;
            }
            
            // Check that the number of subconversations allows another one
            if(mSubStateMachines.size() >= numberOfSubConversations)
            {
                continue;
            }
            
            // This is the right ESM
            embeddedStateMachinePtr = &(*it);
            break;
        }
    }
    
    if(!embeddedStateMachinePtr)
    {
        // No fitting running or new embedded state machine found
        LOG_ERROR("State consumeSubStateMachineMessage: No fitting sub state machine found");
        throw std::runtime_error("State consumeSubStateMachineMessage: No fitting sub state machine found");
    }
    
    LOG_DEBUG("Found a fitting embedded state machine and will try to create a sub state machine now");
    
    // Construct a new state machine with mapped sender role
    if(!protocol.empty())
    {
        // Copy the given state machine
        StateMachine subStateMachine = stateMachine;
        subStateMachine.setSelf(msg.getSender());
        
        // update the message state machine
        try {
            LOG_DEBUG("Substate machine initialized, trying to consume message");
            subStateMachine.consumeMessage(msg);
        } catch(const std::runtime_error& e)
        {
            // Also constructing and using a new one did not work for that message.
            std::string errorMsg = "Substatemachine creation failed: ";
            errorMsg += " -- " + std::string(e.what());
            throw std::runtime_error(errorMsg);
        }
        
        // If that was successful, save the actual protocol and number of subconversations in the embedded state machine
        LOG_DEBUG("New sub state machine consumed message");
        mSubStateMachines.push_back(subStateMachine);
        embeddedStateMachinePtr->actualProtocol = protocol;
        embeddedStateMachinePtr->numberOfSubConversations = numberOfSubConversations;
    } else {
        LOG_ERROR("Protocol not set");
        throw std::runtime_error("Protocol not set");
    }
    
    LOG_DEBUG("State consumeSubStateMachineMessage successfully created new sub state machine");
}

generateDefaultTransitions()

void fipa::acl::State::generateDefaultTransitions

(

)

method that generates implicit generic transitions applicable to all states, that may or may not be speciffied in the configuration file such as not-understood transition (if it is specified it is not doubled); this method is to be called after all states specified in the configuration have been added to the state machine, preferably after all generic transition have been added as well

Definition at line 60 of file state.cpp.

{
    // Not adding any transition for final states without substatemachines
    if(isFinal())
    {
        if(mEmbeddedStateMachines.empty())
        {
            return;
        }
    }
    else if(mTransitions.empty())
    {
        throw std::runtime_error("Invalid state: non final state without transition defined");
    }

    std::vector<Transition> transitions(mTransitions);

    std::vector<Transition>::const_iterator it = transitions.begin();
    for (; it != transitions.end();++it)
    {
        // we don't generate a not-understood transition for not-understood message...
        boost::regex peformativeRegex(it->getPerformativeRegExp());
        if(regex_match(PerformativeTxt[ACLMessage::NOT_UNDERSTOOD], peformativeRegex))
        {
            continue;
        } else {
            // Add the not understood transition for every matching transition
            default_transition::NotUnderstood transitionSender = default_transition::NotUnderstood(it->getSenderRole(), it->getReceiverRole(), mId);
            addTransition(*dynamic_cast<Transition*>(&transitionSender));

            default_transition::NotUnderstood transitionReceiver = default_transition::NotUnderstood(it->getReceiverRole(), it->getSenderRole(), mId);
            addTransition(*dynamic_cast<Transition*>(&transitionReceiver));
        }

        if(regex_match(PerformativeTxt[ACLMessage::CANCEL], peformativeRegex))
        {
            continue;
        } else {
            // Add the cancel transition -- bidirectional regarding receiver/sender role
            default_transition::ConversationCancelling transitionSender = default_transition::ConversationCancelling(it->getSenderRole(), it->getReceiverRole(), mId);
            addTransition(*dynamic_cast<Transition*>(&transitionSender));

            default_transition::ConversationCancelling transitionReceiver = default_transition::ConversationCancelling(it->getReceiverRole(), it->getSenderRole(), mId);
            addTransition(*dynamic_cast<Transition*>(&transitionReceiver));
        }

        if(regex_match(PerformativeTxt[ACLMessage::FAILURE], peformativeRegex))
        {
            continue;
        } else {
            // Add default failure transition -- which only applies for self as receiver
            default_transition::GeneralFailure transitionReceiver = default_transition::GeneralFailure(mId);
            addTransition(*dynamic_cast<Transition*>(&transitionReceiver));
        }
    }
    
    // Also add default states for each substatemachine that proxies
    std::vector<EmbeddedStateMachine>::const_iterator it0 = mEmbeddedStateMachines.begin();
    for (; it0 != mEmbeddedStateMachines.end();++it0)
    {
        if(!it0->proxiedTo.empty())
        {
            // Add the not understood transition for every matching transition
            default_transition::NotUnderstood transitionSender0 = default_transition::NotUnderstood(it0->fromRole, it0->proxiedToRole, mId);
            addTransition(*dynamic_cast<Transition*>(&transitionSender0));
            default_transition::NotUnderstood transitionReceiver0 = default_transition::NotUnderstood(it0->proxiedToRole, it0->fromRole, mId);
            addTransition(*dynamic_cast<Transition*>(&transitionReceiver0));
            
            // Add the cancel transition -- bidirectional regarding receiver/sender role
            default_transition::ConversationCancelling transitionSender1 = default_transition::ConversationCancelling(it0->fromRole, it0->proxiedToRole, mId);
            addTransition(*dynamic_cast<Transition*>(&transitionSender1));
            default_transition::ConversationCancelling transitionReceiver1 = default_transition::ConversationCancelling(it0->proxiedToRole, it0->fromRole, mId);
            addTransition(*dynamic_cast<Transition*>(&transitionReceiver1));
            
            // Add default failure transition -- which only applies for self as receiver
            default_transition::GeneralFailure transitionReceiver2 = default_transition::GeneralFailure(mId);
            addTransition(*dynamic_cast<Transition*>(&transitionReceiver2));
        }
    }
}

getEmbeddedStatemachines()

const std::vector<EmbeddedStateMachine>& fipa::acl::State::getEmbeddedStatemachines ( ) const

inline

Retrieve embedded statemachine.

Returns

list of embedded statemachines

Definition at line 193 of file state.h.

{ return mEmbeddedStateMachines; }

getId()

std::string fipa::acl::State::getId ( ) const

inline

getter method for the uid field of the class

Definition at line 181 of file state.h.

{ return mId; }

getSubstateMachineProxiedTransition()

const Transition & fipa::acl::State::getSubstateMachineProxiedTransition	(	const ACLMessage &	msg,
		const MessageArchive &	archive,
		const RoleMapping &	roleMapping
	)

Check whether the received message triggers a substatemachine proxied transition. This method is not const, as the generated transitions will be added when they trigger successfully.

Returns

the transition

Exceptions

runtime_error

if the msg is invalid in the current state

Definition at line 280 of file state.cpp.

{
    if(archive.hasMessages())
    {
        const ACLMessage& initiatingMsg = archive.getInitiatingMessage();
        // If state has substatemachine(s) && substatemachine(s) proxied_to not empty && actual_protocol != inform && response not already received:
        // Genereate Transition on-the-fly, if posssible
        std::vector<EmbeddedStateMachine>::iterator it0 = mEmbeddedStateMachines.begin();
        for (; it0 != mEmbeddedStateMachines.end(); ++it0)
        {
            LOG_DEBUG("Checking if a transition needs to be generated");
            // FIXME there can be other protocols that do not expect any responses
            if(!it0->proxiedTo.empty() && it0->actualProtocol != "inform" && !it0->receivedProxiedReply )
            {
                LOG_DEBUG("Generating a transition");
                // Generate a transition (any performative, not leaving the state)
                Transition transition (it0->fromRole, it0->proxiedToRole, ".*", getId(), getId());
                // And see if it triggers
                if (transition.triggers(msg, initiatingMsg, roleMapping)) 
                {
                    // Save that a proxied reply was received
                    it0->receivedProxiedReply = true;
                    mSubstateMachineProxiedTransitions.push_back(transition);
                    LOG_DEBUG("Transition triggered");
                    // We cannot use the local var to return as a reference
                    return mSubstateMachineProxiedTransitions.back();
                }
            }
        }
    }

    throw std::runtime_error("Message does not trigger any (incl. proxied) transitions in this state");
}

getTransition()

const Transition & fipa::acl::State::getTransition	(	const ACLMessage &	msg,
		const MessageArchive &	archive,
		const RoleMapping &	roleMapping
	)		const

Check whether the received message triggers a transition.

Returns

the transition

Exceptions

runtime_error

if the msg is invalid in the current state

Definition at line 253 of file state.cpp.

{
    std::vector<Transition>::const_iterator it = mTransitions.begin();
    for (; it != mTransitions.end(); ++it)
    {
        // TODO: better use the directly corresponding one
        // but this should be ok for now
        if(!archive.hasMessages())
        {
            // Initiating message, i.e. validation should only apply to performative
            boost::regex peformativeRegex(it->getPerformativeRegExp());
            if(regex_match(msg.getPerformative(), peformativeRegex))
            {
                return *it;
            }
        } else {
            const ACLMessage& initiatingMsg = archive.getInitiatingMessage();
            if (it->triggers(msg, initiatingMsg, roleMapping)) 
            {
                return *it;
            }
        }
    }

    throw std::runtime_error("Message does not trigger any transition in this state");
}

getTransitions()

const std::vector<Transition>& fipa::acl::State::getTransitions ( ) const

inline

Retrieve transitions associated with this state

Returns

list of transitions

Definition at line 187 of file state.h.

{ return mTransitions; }

isDefaultState()

bool fipa::acl::State::isDefaultState

(

)

const

Test if state belongs to the default state or not.

Returns

true if state is default, false otherwise

Definition at line 141 of file state.cpp.

{
    std::vector<StateId>::const_iterator cit = std::find(msDefaultStates.begin(), msDefaultStates.end(), mId);
    return cit != msDefaultStates.end();
}

isFinal()

bool fipa::acl::State::isFinal ( ) const

inline

Definition at line 156 of file state.h.

{ return mIsFinal; }

isFinished()

bool fipa::acl::State::isFinished

(

)

const

method that returns whether the state is a finished state or not. In the case of a state with embedded state machines, this is a bit more coplex, see the implementation

Returns

true if state is finished, false otherwise

Definition at line 314 of file state.cpp.

{
    if(!isFinal())
    {
        return false;
    }
    
    // Check all subprotocols
    std::vector<StateMachine>::const_iterator it;
    for(it = mSubStateMachines.begin(); it != mSubStateMachines.end(); it++)
    {
        if(!it->inFinalState() && !it->inFailureState())
        {
            LOG_DEBUG("State not finished (subconversation still running)");
            return false;
        }
    } 
    
    // When there are embedded state machines, they all must have forwarded a proxied reply, if this was
    // necessary in the first place
    std::vector<EmbeddedStateMachine>::const_iterator it0 = mEmbeddedStateMachines.begin();
    for (; it0 != mEmbeddedStateMachines.end(); ++it0)
    {
        // They must also all have started enough sub state machines
        // Check that enough subprotocols have been started
        if(it0->numberOfSubConversations != mSubStateMachines.size())
        {
            LOG_DEBUG("State not finished (subconversation still running)");
            return false;
        }
        
        // FIXME there can be other protocols that do not expect any responses
        if(!it0->proxiedTo.empty() && it0->actualProtocol != "inform" && !it0->receivedProxiedReply )
        {
            LOG_DEBUG("State not finished (proxied response missing)");
            return false;
        }
    }
    
    return true;
}

setFinal()

void fipa::acl::State::setFinal ( bool  final )

inlineprotected

setter method for the final field of the class When changing the final state flag make sure you either remove existing transitions or create the default transition if needed

Parameters

final

Change status of state

Definition at line 97 of file state.h.

{ mIsFinal = final; }

setId()

void fipa::acl::State::setId ( const StateId &  id )

inline

setter method for the uid field of the state NOTE: maybe should be taken out and name only be allowed to be set on

construction, as if we rename the state later on the state machine might crash(surely will actually)

Parameters

id	to set as id for the state

Definition at line 176 of file state.h.

{ mId = id; }

toString()

std::string fipa::acl::State::toString

(

)

const

Convert state to string representation

Definition at line 362 of file state.cpp.

{
    std::stringstream state;
    state << "state id: '" << mId << "', final: '" << mIsFinal << "'\n";
    for(std::vector<Transition>::const_iterator it = mTransitions.begin(); it != mTransitions.end(); ++it)
    {
        state << "\t" << it->toString() << "\n";
    }
    
    for(std::vector<EmbeddedStateMachine>::const_iterator it = mEmbeddedStateMachines.begin(); it != mEmbeddedStateMachines.end(); ++it)
    {
        state << "\t" << it->toString() << "\n";
    }
    
    return state.str();
}

toXML()

std::string fipa::acl::State::toXML

(

)

const

Convert state to XML representation

Definition at line 379 of file state.cpp.

{
    std::stringstream ss;;
    ss << "<state id=\"" << mId << "\"";
    if(mIsFinal)
    {
        ss << " final=\"yes\" /";
    }
    ss << ">" << std::endl;

    for(std::vector<Transition>::const_iterator it = mTransitions.begin(); it != mTransitions.end(); ++it)
    {
        ss << "\t" << it->toXML() << "\n";
    }

    for(std::vector<EmbeddedStateMachine>::const_iterator it = mEmbeddedStateMachines.begin(); it != mEmbeddedStateMachines.end(); ++it)
    {
        ss << "\t" << it->toXML() << "\n";
    }

    return ss.str();
}

Friends And Related Function Documentation

default_transition::ConversationCancelFailure

friend class default_transition::ConversationCancelFailure

friend

Definition at line 47 of file state.h.

default_transition::ConversationCancelling

friend class default_transition::ConversationCancelling

friend

Definition at line 45 of file state.h.

default_transition::ConversationCancelSuccess

friend class default_transition::ConversationCancelSuccess

friend

Definition at line 46 of file state.h.

default_transition::GeneralFailure

friend class default_transition::GeneralFailure

friend

Definition at line 48 of file state.h.

default_transition::NotUnderstood

friend class default_transition::NotUnderstood

friend

Definition at line 44 of file state.h.

StateMachine

friend class StateMachine

friend

Definition at line 50 of file state.h.

StateMachineReader

friend class StateMachineReader

friend

Definition at line 49 of file state.h.

Transition

friend class Transition

friend

Definition at line 43 of file state.h.

Member Data Documentation

CONVERSATION_CANCEL_FAILURE

const StateId fipa::acl::State::CONVERSATION_CANCEL_FAILURE = "__internal_state:conversation_cancel_failure__"

static

Definition at line 107 of file state.h.

CONVERSATION_CANCEL_SUCCESS

const StateId fipa::acl::State::CONVERSATION_CANCEL_SUCCESS = "__internal_state:conversation_cancel_success__"

static

Definition at line 106 of file state.h.

CONVERSATION_CANCELLING

const StateId fipa::acl::State::CONVERSATION_CANCELLING = "__internal_state:conversation_cancelling__"

static

Definition at line 105 of file state.h.

GENERAL_FAILURE_STATE

const StateId fipa::acl::State::GENERAL_FAILURE_STATE = "__internal_state:general_failure__"

static

Definition at line 108 of file state.h.

NOT_UNDERSTOOD

const StateId fipa::acl::State::NOT_UNDERSTOOD = "__internal_state:not_understood__"

static

Definition at line 104 of file state.h.

UNDEFINED_ID

const StateId fipa::acl::State::UNDEFINED_ID = "__undefined__"

static

Default states

Definition at line 103 of file state.h.

---

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

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