gov.nasa.arc.brahms.vm.api.jagt
Class AbstractExternalAgent

java.lang.Object
  extended by gov.nasa.arc.brahms.vm.api.jagt.AbstractExternalAgent
All Implemented Interfaces:
IExternalAgent

public abstract class AbstractExternalAgent
extends java.lang.Object
implements IExternalAgent

The AbstractExternalAgent is an interface for external agents implemented in Java loaded into the virtual machine to participate in a simulation or real-time agent environment. The external agent can perform any Java actions. This abstract implementation provides access to the concepts loaded in the virtual machine and the world state to allow for communications with these concepts and to allow for world state changes to be triggered by this agent.


Constructor Summary
AbstractExternalAgent()
          Constructor, creates a new AbstractExternalAgent
 
Method Summary
protected  void assertFact(IFact fact)
          Schedules the assertion of the specified fact into the world state including the distribution of the fact to all agents and objects.
 IFact conclude(IConcept concept, IAttribute attribute, int relop, boolean value, int factcertainty)
          Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is a boolean.
 IFact conclude(IConcept concept, IAttribute attribute, int relop, double value, int factcertainty)
          Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is a double.
 IFact conclude(IConcept concept, IAttribute attribute, int relop, IConcept value, int factcertainty)
          Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is an IConcept.
 IFact conclude(IConcept concept, IAttribute attribute, int relop, int value, int factcertainty)
          Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is an integer.
 IFact conclude(IConcept concept, IAttribute attribute, int relop, IUnknown value, int factcertainty)
          Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is the value 'unknown'.
 IFact conclude(IConcept concept, IAttribute attribute, int relop, java.lang.String value, boolean symbol, int factcertainty)
          Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is a String.
 IFact conclude(IConcept lhsConcept, IRelation relation, IConcept rhsConcept, int factcertainty)
          Concludes a new IFact of the form concept relation concept.
 IFact conclude(IConcept lhsConcept, IRelation relation, IConcept rhsConcept, int truthValue, int factcertainty)
          Concludes a new IFact of the form concept relation concept with the specified truth value.
 IFact conclude(IConcept lhsConcept, IRelation relation, IUnknown rhsConcept, int factcertainty)
          Concludes a new IFact of the form concept relation concept.
 IFact conclude(IConcept lhsConcept, IRelation relation, IUnknown rhsConcept, int truthValue, int factcertainty)
          Concludes a new IFact of the form concept relation concept with the specified truth value.
abstract  void doWork()
          The virtual machine takes care of having the agent run in its own thread of execution.
 IContext getContext()
          Returns this activity's context
protected  IModel getModel()
          Returns a reference to the model loaded in the virtual machine.
protected  IVMController getVMController()
          Returns the virtual machine's controller usable by this agent.
protected  IWorldState getWorldState()
          Returns a reference to the world state managing the fact set.
abstract  void initialize()
          Initialize is used to initialize the external agent after it has been loaded into the virtual machine.
 boolean isValidTruthValue(int truth)
          Checks whether the specified value is a valid truth value.
abstract  void onAssert(IFact fact)
          onAssert is called by the virtual machine whenever a new fact is asserted in the world state.
 void onProcess(long time)
          onProcess is called by the virtual machine when the virtual machine is in simulation mode and the agent is notified by the scheduler that it is allowed to process any events for the specified time.
abstract  void onReceive(IBelief belief)
          onReceive is called by the virtual machine whenever a new belief is communicated to the external agent by another agent or object.
abstract  void onRetract(IFact fact)
          onRetract is called by the virtual machine whenever a fact is retracted from the world state.
abstract  void pause()
          Pauses the external agent.
abstract  void reset()
          Resets the external agent to the initialized state as it was placed in using the initialize method, performing any additional clean-up if necessary.
abstract  void resume()
          Resumes the external agent from a pause.
protected  void retractFact(IFact fact)
          Schedules the retraction of the specified fact from the world state including the notification of the retraction to all agents and objects.
protected  void send(IBelief[] beliefs, IActiveInstance agent)
          Sends the specified set of beliefs to the specified agent, causing the assertion of the beliefs in the specified agent's belief set.
protected  void send(IBelief[] beliefs, IActiveInstance[] agents)
          Sends the specified beliefs to the specified agents, causing the assertion of the beliefs in the belief set of every agent in the list of agents.
protected  void send(IBelief belief, IActiveInstance agent)
          Sends the specified belief to the specified agent, causing the assertion of the belief in the specified agent's belief set.
protected  void send(IBelief belief, IActiveInstance[] agents)
          Sends the specified belief to the specified agents, causing the assertion of the belief in the belief set of every agent in the list of agents.
 void setAgentCtx(gov.nasa.arc.brahms.common.rt.IActiveInstanceCtx agt)
          Sets the agent to be wrapped by this external agent.
 void setProperties(java.util.Properties p)
          Sets the properties for the activity.
 void setVMController(gov.nasa.arc.brahms.vm.controller.VMController vmc)
          Sets the virtual machine's controller.
abstract  void start()
          Starts the external agent.
abstract  void stop()
          Stops the external agent.
 java.lang.String toString()
          Returns a string representation of this object
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

AbstractExternalAgent

public AbstractExternalAgent()
Constructor, creates a new AbstractExternalAgent

Method Detail

setProperties

public final void setProperties(java.util.Properties p)
                         throws ExternalException
Sets the properties for the activity. The properties specify the allowed capabilities of the external activity. This method is called by the virtual machine and can not be called in the doActivity method.

Parameters:
p - the Properties set by the virtual machine.
Throws:
ExternalException - if the properties were already set.

setVMController

public final void setVMController(gov.nasa.arc.brahms.vm.controller.VMController vmc)
                           throws ExternalException
Sets the virtual machine's controller. This controller is set by the virtual machine and cannot be replaced.

Parameters:
vmc - the VMController
Throws:
ExternalException

setAgentCtx

public final void setAgentCtx(gov.nasa.arc.brahms.common.rt.IActiveInstanceCtx agt)
                       throws ExternalException
Sets the agent to be wrapped by this external agent. This method is called by the virtual machine and can not be called by the external agent.

Parameters:
agt - the IActiveInstanceCtx for the agent
Throws:
ExternalException - if a null agent is specified or if the external agent already wraps another agent

getContext

public final IContext getContext()
Returns this activity's context

Returns:
IContext the context for this activity

getVMController

protected final IVMController getVMController()
                                       throws ExternalException
Returns the virtual machine's controller usable by this agent.

Parameters:
controller - the virtual machine's controller
Throws:
ExternalException

getModel

protected final IModel getModel()
                         throws ExternalException
Returns a reference to the model loaded in the virtual machine.

Returns:
IModel the model loaded in the virtual machine.
Throws:
ExternalException - is an internal error occurs.

getWorldState

protected final IWorldState getWorldState()
                                   throws ExternalException
Returns a reference to the world state managing the fact set.

Returns:
IWorldState the virtual machine's world state
Throws:
ExternalException - if an internal error occurs.

isValidTruthValue

public final boolean isValidTruthValue(int truth)
Checks whether the specified value is a valid truth value.

Parameters:
truth - the truth value to be tested
Returns:
true if the truth value is valid, false otherwise

conclude

public final IFact conclude(IConcept concept,
                            IAttribute attribute,
                            int relop,
                            IUnknown value,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is the value 'unknown'.

Parameters:
concept - the IConcept for which an attribute value is specified
attribute - the IAttribute defined for the concept to which to assign a value
relop - the relational operator, one of IRelationalOperator.EQUALS or IRelationalOperator.NOT_EQUALS.
value - the value 'unknown' to be assigned to the attribute
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the value does not match with the attribute's type, the attribute is not specified for the given concept. if an invalid relational operator is specified or if the fact certainty is less than 0 or more than 100.
See Also:
IUnknown.UNKNOWN

conclude

public final IFact conclude(IConcept concept,
                            IAttribute attribute,
                            int relop,
                            int value,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is an integer. The attribute's type must be int or double.

Parameters:
concept - the IConcept for which an attribute value is specified
attribute - the IAttribute defined for the concept to which to assign a value
relop - the relational operator, one of IRelationalOperator.EQUALS or IRelationalOperator.NOT_EQUALS.
value - the integer value to be assigned to the attribute
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the value does not match with the attribute's type, the attribute is not specified for the given concept. if an invalid relational operator is specified or if the fact certainty is less than 0 or more than 100.

conclude

public final IFact conclude(IConcept concept,
                            IAttribute attribute,
                            int relop,
                            double value,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is a double. The attribute's type must be double.

Parameters:
concept - the IConcept for which an attribute value is specified
attribute - the IAttribute defined for the concept to which to assign a value
relop - the relational operator, one of IRelationalOperator.EQUALS or IRelationalOperator.NOT_EQUALS.
value - the double value to be assigned to the attribute
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the value does not match with the attribute's type, the attribute is not specified for the given concept. if an invalid relational operator is specified or if the fact certainty is less than 0 or more than 100.

conclude

public final IFact conclude(IConcept concept,
                            IAttribute attribute,
                            int relop,
                            boolean value,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is a boolean. The attribute's type must be boolean.

Parameters:
concept - the IConcept for which an attribute value is specified
attribute - the IAttribute defined for the concept to which to assign a value
relop - the relational operator, one of IRelationalOperator.EQUALS or IRelationalOperator.NOT_EQUALS.
value - the boolean value to be assigned to the attribute
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the value does not match with the attribute's type, the attribute is not specified for the given concept. if an invalid relational operator is specified or if the fact certainty is less than 0 or more than 100.

conclude

public final IFact conclude(IConcept concept,
                            IAttribute attribute,
                            int relop,
                            java.lang.String value,
                            boolean symbol,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is a String. The attribute's type must be symbol or string.

Parameters:
concept - the IConcept for which an attribute value is specified
attribute - the IAttribute defined for the concept to which to assign a value
relop - the relational operator, one of IRelationalOperator.EQUALS or IRelationalOperator.NOT_EQUALS.
value - the String value to be assigned to the attribute
symbol - indicates if the value is a symbol or string
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the value does not match with the attribute's type, the attribute is not specified for the given concept. if an invalid relational operator is specified or if the fact certainty is less than 0 or more than 100.

conclude

public final IFact conclude(IConcept concept,
                            IAttribute attribute,
                            int relop,
                            IConcept value,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is an IConcept. The attribute's type must be an IMetaType or IConcept. The attribute name must not be 'location'. The 'location' attribute's value is managed by the virtual machine.

Parameters:
concept - the IConcept for which an attribute value is specified
attribute - the IAttribute defined for the concept to which to assign a value
relop - the relational operator, one of IRelationalOperator.EQUALS or IRelationalOperator.NOT_EQUALS.
value - the IConcept value to be assigned to the attribute
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the value does not match with the attribute's type, the attribute is not specified for the given concept. if an invalid relational operator is specified or if the fact certainty is less than 0 or more than 100.

conclude

public final IFact conclude(IConcept lhsConcept,
                            IRelation relation,
                            IConcept rhsConcept,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept relation concept. The truth-value is set to true.

Parameters:
lhsConcept - the IConcept for which the relation is specified
relation - the IRelation defined for the concept
rhsConcept - the IUnknown value to be related to the lhsConcept
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the rhsConcept does not match with the relation's type, the relation is not specified for the given lhsConcept or if the fact certainty is less than 0 or more than 100.
See Also:
IUnknown.UNKNOWN

conclude

public final IFact conclude(IConcept lhsConcept,
                            IRelation relation,
                            IUnknown rhsConcept,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept relation concept. The truth-value is set to true.

Parameters:
lhsConcept - the IConcept for which the relation is specified
relation - the IRelation defined for the concept
rhsConcept - the 'unknown' value to be related to the lhsConcept
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the rhsConcept does not match with the relation's type, the relation is not specified for the given lhsConcept or if the fact certainty is less than 0 or more than 100.

conclude

public final IFact conclude(IConcept lhsConcept,
                            IRelation relation,
                            IUnknown rhsConcept,
                            int truthValue,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept relation concept with the specified truth value.

Parameters:
lhsConcept - the IConcept for which the relation is specified
relation - the IRelation defined for the concept
rhsConcept - the IUnknown value to be related to the lhsConcept
truthValue - the truth value of the relationship (TRUE, FALSE, UNKNOWN)
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the rhsConcept does not match with the relation's type, the relation is not specified for the given lhsConcept or if the fact certainty is less than 0 or more than 100.
See Also:
IUnknown.UNKNOWN, ITruthValue.TRUE, ITruthValue.FALSE, ITruthValue.UNKNOWN

conclude

public final IFact conclude(IConcept lhsConcept,
                            IRelation relation,
                            IConcept rhsConcept,
                            int truthValue,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept relation concept with the specified truth value.

Parameters:
lhsConcept - the IConcept for which the relation is specified
relation - the IRelation defined for the concept
rhsConcept - the IConcept to be related to the lhsConcept
truthValue - the truth value of the relationship (TRUE, FALSE, UNKNOWN)
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the rhsConcept does not match with the relation's type, the relation is not specified for the given lhsConcept or if the fact certainty is less than 0 or more than 100.
See Also:
ITruthValue.TRUE, ITruthValue.FALSE, ITruthValue.UNKNOWN

assertFact

protected final void assertFact(IFact fact)
                         throws ExternalException
Schedules the assertion of the specified fact into the world state including the distribution of the fact to all agents and objects. The fact is not guaranteed to immediately be asserted in the world state.

Parameters:
fact - the IFact to be asserted
Throws:
ExternalException - if an internal error occurs

retractFact

protected final void retractFact(IFact fact)
                          throws ExternalException
Schedules the retraction of the specified fact from the world state including the notification of the retraction to all agents and objects. The fact is not guaranteed to immediately be retracted from the world state.

Parameters:
fact - the IFact to be retracted
Throws:
ExternalException - if an internal error occurs

send

protected final void send(IBelief belief,
                          IActiveInstance agent)
                   throws ExternalException
Sends the specified belief to the specified agent, causing the assertion of the belief in the specified agent's belief set. The transmission of the belief is scheduled and is therefor not guaranteed to immeditiately be available in the agent's belief set.

Note: If multiple beliefs are to be transmitted to a remote agent use the send method to which multiple beliefs can be passed to reduce communication overhead. The beliefs will be bundled in one communication package in that case, while with this method for each belief a communication package is created.

Parameters:
belief - the IBelief to be send to the specified agent
agent - the IActiveInstance to which to send the belief
Throws:
ExternalException - if an internal error occurs

send

protected final void send(IBelief belief,
                          IActiveInstance[] agents)
                   throws ExternalException
Sends the specified belief to the specified agents, causing the assertion of the belief in the belief set of every agent in the list of agents. The transmission of the belief is scheduled and is therefor not guaranteed to immeditiately be available in the belief sets of the agents.

Note: If multiple beliefs are to be transmitted to remote agents use the send method to which multiple beliefs can be passed to reduce communication overhead. The beliefs will be bundled in one communication package in that case, while with this method for each belief a communication package is created.

Parameters:
belief - the IBelief to be send to the specified agent
agents - the list of IActiveInstance to which to send the belief
Throws:
ExternalException - if an internal error occurs

send

protected final void send(IBelief[] beliefs,
                          IActiveInstance agent)
                   throws ExternalException
Sends the specified set of beliefs to the specified agent, causing the assertion of the beliefs in the specified agent's belief set. The transmission of the beliefs is scheduled and is therefor not guaranteed to immeditiately be available in the agent's belief set.

Note: If multiple beliefs are to be transmitted to a remote agent this method should be used to reduce communication overhead. The beliefs will be bundled in one communication package.

Parameters:
beliefs - the list of IBelief to be send to the specified agent
agent - the IActiveInstance to which to send the belief
Throws:
ExternalException - if an internal error occurs

send

protected final void send(IBelief[] beliefs,
                          IActiveInstance[] agents)
                   throws ExternalException
Sends the specified beliefs to the specified agents, causing the assertion of the beliefs in the belief set of every agent in the list of agents. The transmission of the beliefs is scheduled and is therefor not guaranteed to immeditiately be available in the belief sets of the agents.

Note: If multiple beliefs are to be transmitted to a remote agent this method should be used to reduce communication overhead. The beliefs will be bundled in one communication package.

Parameters:
beliefs - the list of IBelief to be send to the specified agents
agents - the list of IActiveInstance to which to send the beliefs
Throws:
ExternalException - if an internal error occurs

initialize

public abstract void initialize()
                         throws ExternalException
Initialize is used to initialize the external agent after it has been loaded into the virtual machine. All agents are initialized before they are started.

Specified by:
initialize in interface IExternalAgent
Throws:
ExternalException - if an internal error occurs.

start

public abstract void start()
                    throws ExternalException
Starts the external agent. Any initializations required for running the agent are to be performed here.

Specified by:
start in interface IExternalAgent
Throws:
ExternalException - if an internal error occurs.

pause

public abstract void pause()
                    throws ExternalException
Pauses the external agent.

Specified by:
pause in interface IExternalAgent
Throws:
ExternalException - if an internal error occurs.

resume

public abstract void resume()
                     throws ExternalException
Resumes the external agent from a pause.

Specified by:
resume in interface IExternalAgent
Throws:
ExternalException - if an internal error occurs.

stop

public abstract void stop()
                   throws ExternalException
Stops the external agent. Here clean-up is to be performed for the run-time state of the external agent.

Specified by:
stop in interface IExternalAgent
Throws:
ExternalException - if an internal error occurs.

reset

public abstract void reset()
                    throws ExternalException
Resets the external agent to the initialized state as it was placed in using the initialize method, performing any additional clean-up if necessary.

Specified by:
reset in interface IExternalAgent
Throws:
ExternalException - if an internal error occurs.

doWork

public abstract void doWork()
                     throws ExternalException
The virtual machine takes care of having the agent run in its own thread of execution. In the doWork method the core functionality of the agent is to be implemented. Note that it is up to the developer to make sure that doWork remains active while the agent is active,. error recovery is the responsibility of the developer. If the doWork method ends the external agent will be stopped and reset. It is also the developer's responsibility to handle pauses and resumes if they are relevant for the external agent. It is recommended that the developer implements a clean implementation to stop the work when the agent is stopped (stop method called).

Specified by:
doWork in interface IExternalAgent
Throws:
ExternalException - if an unrecoverable error occurs.

onProcess

public void onProcess(long time)
               throws ExternalException
onProcess is called by the virtual machine when the virtual machine is in simulation mode and the agent is notified by the scheduler that it is allowed to process any events for the specified time. This method is never called in real-time mode. Note that the developer should not block this call. If this method is implemented it should return almost immediately. If the implementation of the external agent is dependant on the time the implementation should probably set the time value internally and have a notification mechanism built-in to notify doWork that the time has changed.

This method has an empty implementation and should be overridden if the notification is essential for the external agent.

Specified by:
onProcess in interface IExternalAgent
Parameters:
time - the time for which agents can process their events.
Throws:
ExternalException - if an internal error occurs.

onReceive

public abstract void onReceive(IBelief belief)
                        throws ExternalException
onReceive is called by the virtual machine whenever a new belief is communicated to the external agent by another agent or object. Processing the actual incoming belief is optional.

Specified by:
onReceive in interface IExternalAgent
Parameters:
belief - the IBelief communicated to this external agent
Throws:
ExternalException - if an error occurs handling this belief

onAssert

public abstract void onAssert(IFact fact)
                       throws ExternalException
onAssert is called by the virtual machine whenever a new fact is asserted in the world state. If the external agent concludes a new fact this external agent is also guaranteed to be notified that the fact is actually asserted through a call to this method. Processing the assertion is optional.

Specified by:
onAssert in interface IExternalAgent
Parameters:
fact - the IFact asserted in the world state
Throws:
ExternalException - if an error occurs handling this fact

onRetract

public abstract void onRetract(IFact fact)
                        throws ExternalException
onRetract is called by the virtual machine whenever a fact is retracted from the world state. If the external agent retracts a fact from the world state this external agent is also guaranteed to be notified that the fact is actually retracted through a call to this method. Processing the retraction is optional.

Specified by:
onRetract in interface IExternalAgent
Parameters:
fact - the IFact retracted from the world state
Throws:
ExternalException - if an error occurs handling this fact

toString

public java.lang.String toString()
Returns a string representation of this object

Overrides:
toString in class java.lang.Object
Returns:
String the string representation