gov.nasa.arc.brahms.vm.rt
Class VMExternalAgentCtx

java.lang.Object
  gov.nasa.arc.brahms.common.rt.BrahmsObjectCtx
      gov.nasa.arc.brahms.common.rt.ConceptCtx
          gov.nasa.arc.brahms.common.rt.ActiveInstanceCtx
              gov.nasa.arc.brahms.vm.rt.VMActiveInstanceCtx
                  gov.nasa.arc.brahms.vm.rt.VMAgentCtx
                      gov.nasa.arc.brahms.vm.rt.VMExternalAgentCtx

All Implemented Interfaces:

IActiveInstanceCtx, IAgentCtx, IBrahmsObjectCtx, IConceptCtx, IRuntimeConstants, gov.nasa.arc.brahms.vm.engine.IPriorityWorkManager, gov.nasa.arc.brahms.vm.engine.IWorkManager, gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement, gov.nasa.arc.brahms.vm.monitoring.IMonitoredAgent, IFrameStatusListener, IRuntimeConceptCtx, java.beans.PropertyChangeListener, java.io.Serializable, java.lang.Runnable, java.util.EventListener

public class VMExternalAgentCtx
extends VMAgentCtx
implements IAgentCtx, java.lang.Runnable

The VMExternalAgentCtx is the runtime class for the external agents with extensions for it to function in the Brahms virtual machine. The agent's behavior itself is defined in Java. This context therefor only manages the interfaces between the virtual machine and the external agent.

Version:

$Revision: 1.8 $ $Date: 2009/04/28 14:28:02 $ $Author: rvhoof $

Author:

Ron van Hoof

See Also:

IAgentCtx, Serialized Form

Field Summary

Fields inherited from class gov.nasa.arc.brahms.vm.rt.VMActiveInstanceCtx

m_bInitialized, m_llCIMessageQueue, m_llReceivedMessageConversationIds, m_oBeliefSet, m_oEngine, m_oIncomingMessageLock

Fields inherited from interface gov.nasa.arc.brahms.common.rt.IRuntimeConstants

ABORTED, ACTIVE, ACTIVITY, AVAILABLE, COMPLETED, CONSEQUENCE, DETECTABLE, ENDED, ENGINE, EXTERNAL_AGENT, FROM, IMPASSED, INITIAL, INTERRUPTED, JAVA_PROPERTY, sABORTED, sACTIVE, sAVAILABLE, sCOMPLETED, sENDED, sIMPASSED, sINTERRUPTED, sUNAVAILABLE, TO, TRANSFER, UNAVAILABLE

Constructor Summary

VMExternalAgentCtx(Agent agt)
Constructor, creates a new context for the specified agent.

Method Summary

void	deregisterThreadListener() Deregisters the thread listener to detect when this agent's thread of execution is terminated and under what circumstances.
IExternalAgent	getExternalImplementation() Returns the implementation for the external agent.
void	initialize(gov.nasa.arc.brahms.vm.controller.VMController vmc, long time) Initializes the concept for use in a virtual machine controller by the specified virtual machine controller.
boolean	isAcceptingFacts() Indicates whether this actor is interested in being notified of fact assertions/retractions.
void	pause() Pauses the external agent.
void	postEvent(gov.nasa.arc.brahms.vm.events.DiscreteEvent evt) The only events that can come in are events for beliefs communicated to this external agent or facts asserted in or retracted from the world state.
void	process(long time) In simulation mode the Scheduler determines when an agent can process events up to what time.
protected void	processEvent(gov.nasa.arc.brahms.vm.events.DiscreteEvent evt) Processes the specified event.
protected void	processInformMessage(gov.nasa.ci.api.communication.ICommunicativeAct msg) Processes the specified message as an inform message.
protected void	processNotUnderstoodMessage(gov.nasa.ci.api.communication.ICommunicativeAct msg) Processes the specified message as a Not-Understood message.
protected void	processRequestMessage(gov.nasa.ci.api.communication.ICommunicativeAct msg) Processes the specified message as a request message.
void	registerThreadListener() Registers a thread listener to detect when this agent's thread of execution is terminated and under what circumstances.
void	reset() Resets the concept removing its context and any references and additional components created to use this concept in a virtual machine.
void	resume() Resumes the external agent.
void	run() The run method implemented for the thread used to keep the external agent alive
protected void	sendNotUnderstoodMessage(gov.nasa.ci.api.communication.ICommunicativeAct msg, java.lang.String message) This method sends a Not Understood message to the sender to inform it of the fact that this agent does not understand the contents it was sent.
void	start() Starts the external agent.
void	stop() Stops the external agent.

Methods inherited from class gov.nasa.arc.brahms.vm.rt.VMAgentCtx

createEngine, getMatchingStrategy

Methods inherited from class gov.nasa.arc.brahms.vm.rt.VMActiveInstanceCtx

activateCompositeActivity, addActiveDetectable, addBelief, addDeletedListener, addEventReference, addFrameBindingReference, addHardReference, addKnowsLocationOf, addSoftReference, addStatementReference, addStatusListener, clearKnowsLocationOf, containsBelief, createWorkSelector, deactivateCompositeActivity, deregisterForMonitoring, detect, doWork, finalizeDelete, getActiveDetectables, getBelief, getBelief, getBelief, getBelief, getBelief, getBelief, getBeliefChangeSupport, getBeliefForIndex, getBeliefForIndex, getBeliefRSN, getBeliefs, getBeliefs, getBeliefs, getBeliefs, getBeliefs, getBeliefs, getBeliefs, getBeliefs, getBeliefs, getBeliefs, getBeliefs, getBeliefs, getBeliefs, getBeliefs, getBeliefs, getBeliefsForIndex, getBeliefsForIndex, getContainedInstances, getContainsRelation, getContext, getController, getElement, getFactChangeSupport, getFactRSN, getKnowsLocationOf, getLocationAttribute, getPriorityAvailableThoughtframe, getPriorityAvailableWorkframe, getPriorityInterruptedFrame, getRemoteBeliefs, getRemovedBeliefs, getSoftReferences, getStatusListeners, hasAddedBelief, hasEventReferences, hasFrames, hasRemovedBelief, hasSoftReferences, initializeMemoryManagement, initiateDelete, isDeleted, isDeleteInitiated, isMarkedForGC, isSynchronizationRequired, knowsLocationOf, processMessage, propertyChange, registerForMonitoring, registerJavaObject, removeActiveDetectable, removeAllBeliefs, removeBelief, removeEventReference, removeFrameBindingReference, removeHardReference, removeKnowsLocationOf, removeSoftReference, removeStatementReference, removeStatusListener, retractEvent, setBeliefChangeSupport, setController, setFactChangeSupport, setMarkedForGC, setSynchronizationRequired, statusChanged, trigger, triggerImpasseResolution, unregisterJavaObject

Methods inherited from class gov.nasa.arc.brahms.common.rt.ActiveInstanceCtx

addAvailableFrame, addBelief, addCompletedFrame, addContainedElement, addImpasseDetectable, addImpassedFrame, addInterruptedFrame, addPastLocation, getAvailableThoughtframes, getAvailableWorkframes, getBelievedTime, getCompletedThoughtframeNames, getCompletedThoughtframes, getCompletedWorkframeNames, getCompletedWorkframes, getContainedElements, getCurrentWork, getImpasseDetectables, getImpassedFrames, getInterruptedFrames, getLocation, getPastLocations, hasAvailableThoughtframes, hasAvailableWorkframes, hasCompletedThoughtframes, hasCompletedWorkframes, hasImpassedFrames, hasInterruptedFrames, removeAllAvailableFrames, removeAllCompletedFrames, removeAllContainedElements, removeAllImpasseDetectables, removeAllImpassedFrames, removeAllInterruptedFrames, removeAllPastLocations, removeAvailableFrame, removeBelief, removeCompletedFrame, removeContainedElement, removeImpasseDetectable, removeImpassedFrame, removeInterruptedFrame, removePastLocation, setBelievedTime, setCurrentWork, setLocation

Methods inherited from class gov.nasa.arc.brahms.common.rt.ConceptCtx

addAttribute, addRelation, getAttribute, getRelation, initAttributeRelationCache, removeAttribute, removeRelation, resetAttributeRelationCache, toString

Methods inherited from class gov.nasa.arc.brahms.common.rt.BrahmsObjectCtx

addNote, getContextFor, getEndTime, getID, getNote, getNotes, getStartTime, removeNote, setContextFor, setEndTime, setID, setStartTime

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface gov.nasa.arc.brahms.common.rt.IActiveInstanceCtx

addAvailableFrame, addBelief, addCompletedFrame, addContainedElement, addImpasseDetectable, addImpassedFrame, addInterruptedFrame, addPastLocation, getAvailableThoughtframes, getAvailableWorkframes, getBeliefs, getBelievedTime, getCompletedThoughtframeNames, getCompletedThoughtframes, getCompletedWorkframeNames, getCompletedWorkframes, getContainedElements, getCurrentWork, getImpasseDetectables, getImpassedFrames, getInterruptedFrames, getLocation, getPastLocations, hasAvailableThoughtframes, hasAvailableWorkframes, hasCompletedThoughtframes, hasCompletedWorkframes, hasImpassedFrames, hasInterruptedFrames, removeAllAvailableFrames, removeAllBeliefs, removeAllCompletedFrames, removeAllContainedElements, removeAllImpasseDetectables, removeAllImpassedFrames, removeAllInterruptedFrames, removeAllPastLocations, removeAvailableFrame, removeBelief, removeCompletedFrame, removeContainedElement, removeImpasseDetectable, removeImpassedFrame, removeInterruptedFrame, removePastLocation, setBelievedTime, setCurrentWork, setLocation

Methods inherited from interface gov.nasa.arc.brahms.common.rt.IBrahmsObjectCtx

addNote, getContextFor, getEndTime, getID, getNote, getNotes, getStartTime, removeNote, setEndTime, setID, setStartTime

Methods inherited from interface gov.nasa.arc.brahms.vm.engine.IPriorityWorkManager

getCurrentWork

Constructor Detail

VMExternalAgentCtx

public VMExternalAgentCtx(Agent agt)

Constructor, creates a new context for the specified agent.

Parameters:

agt - the Agent for which to create a context

Method Detail

initialize

public void initialize(gov.nasa.arc.brahms.vm.controller.VMController vmc,
                       long time)
                throws VMException

Initializes the concept for use in a virtual machine controller by the specified virtual machine controller. The initialization sets up any additional components required for the concept to be used in the virtual machine.

Specified by:

initialize in interface IRuntimeConceptCtx

Overrides:

initialize in class VMActiveInstanceCtx

Parameters:

vmc - the VMController controlling the virtual machine in which this concept is to be used.

time - the time at which the initialization is performed

Throws:

VMException - if an error occurs in initializing the concept

getExternalImplementation

public IExternalAgent getExternalImplementation()

Returns the implementation for the external agent.

Returns:

IExternalAgent the external agent implementation.

isAcceptingFacts

public boolean isAcceptingFacts()

Indicates whether this actor is interested in being notified of fact assertions/retractions.

Overrides:

isAcceptingFacts in class VMActiveInstanceCtx

Returns:

boolean true to accept facts, false if not

start

public void start()
           throws VMException

Starts the external agent.

Overrides:

start in class VMActiveInstanceCtx

Throws:

VMException - if an error occurs in starting the external agent.

pause

public void pause()
           throws VMException

Pauses the external agent.

Overrides:

pause in class VMActiveInstanceCtx

Throws:

VMException - if an error occurs in pausing the external agent.

resume

public void resume()
            throws VMException

Resumes the external agent.

Overrides:

resume in class VMActiveInstanceCtx

Throws:

VMException - if an error occurs in resuming the external agent.

stop

public void stop()
          throws VMException

Stops the external agent.

Overrides:

stop in class VMActiveInstanceCtx

Throws:

VMException - if an error occurs in stopping the external agent.

postEvent

public void postEvent(gov.nasa.arc.brahms.vm.events.DiscreteEvent evt)
               throws VMException

The only events that can come in are events for beliefs communicated to this external agent or facts asserted in or retracted from the world state. The incoming events will be placed on a queue for processing by the external agent.

Overrides:

postEvent in class VMActiveInstanceCtx

Parameters:

evt - the DiscreteEvent to be added to the event queue

Throws:

VMException - if an error occurs in adding the event to the queue

run

public void run()

The run method implemented for the thread used to keep the external agent alive

Specified by:

run in interface java.lang.Runnable

process

public void process(long time)
             throws VMException

In simulation mode the Scheduler determines when an agent can process events up to what time. When the Scheduler calls the process method it specifies the time up to where the active instance can process events. The active instance can process events marked for a time of up to and including the specified time.

Note: In real time mode the active instance processes any events as fast as possible without waiting for approval from the Scheduler. This method is considered irrelevant for the real time mode.

Overrides:

process in class VMActiveInstanceCtx

Parameters:

time - the time of the events that can be processed, up to and including the specified time

Throws:

VMException - if an error occurs in the continuation of the processing

reset

public void reset()
           throws VMException

Resets the concept removing its context and any references and additional components created to use this concept in a virtual machine.

Specified by:

reset in interface IRuntimeConceptCtx

Overrides:

reset in class VMActiveInstanceCtx

Throws:

VMException - if in error occurs in resetting the active instance

registerThreadListener

public void registerThreadListener()

Registers a thread listener to detect when this agent's thread of execution is terminated and under what circumstances.

Overrides:

registerThreadListener in class VMActiveInstanceCtx

deregisterThreadListener

public void deregisterThreadListener()

Deregisters the thread listener to detect when this agent's thread of execution is terminated and under what circumstances.

Overrides:

deregisterThreadListener in class VMActiveInstanceCtx

processEvent

protected void processEvent(gov.nasa.arc.brahms.vm.events.DiscreteEvent evt)

Processes the specified event.

Parameters:

evt - the DiscreteEvent to be processed

processInformMessage

protected void processInformMessage(gov.nasa.ci.api.communication.ICommunicativeAct msg)
                             throws MessageFormatException

Processes the specified message as an inform message. The contents will be a set of beliefs that need to be parsed and asserted to this agent's belief set.

Parameters:

msg - the inform ICommunicativeAct to be processed

Throws:

MessageFormatException - if the contents of the message was not formatted as expected.

processRequestMessage

protected void processRequestMessage(gov.nasa.ci.api.communication.ICommunicativeAct msg)
                              throws MessageFormatException

Processes the specified message as a request message. The contents will be a pattern that need to be parsed and matched to this agent's belief set. The matching beliefs need to be returned to the requestor.

Parameters:

msg - the request ICommunicativeAct to be processed

Throws:

MessageFormatException - if the contents of the message was not formatted as expected.

processNotUnderstoodMessage

protected void processNotUnderstoodMessage(gov.nasa.ci.api.communication.ICommunicativeAct msg)
                                    throws MessageFormatException

Processes the specified message as a Not-Understood message. The contents will be a string with the reason for why the message was not understood.

Parameters:

msg - the inform ICommunicativeAct to be processed

Throws:

MessageFormatException - if the contents of the message was not formatted as expected.

sendNotUnderstoodMessage

protected void sendNotUnderstoodMessage(gov.nasa.ci.api.communication.ICommunicativeAct msg,
                                        java.lang.String message)

This method sends a Not Understood message to the sender to inform it of the fact that this agent does not understand the contents it was sent.

Parameters:

msg - the ICommunicativeAct for which to send a not understood reply

message - the message explaining the reason for the not understood message