gov.nasa.arc.brahms.vm.api.jagt
Interface IExternalAgent

All Known Implementing Classes:
AbstractExternalAgent

public interface IExternalAgent

The IExternalAgent 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. It generally does not make much sense to implement this interface to build a Java agent implementation as this interface does not provide access to the world state or other agents. To build external agents it is recommended to extend the abstract class AbstractExternalAgent.


Method Summary
 void doWork()
          The virtual machine takes care of having the agent run in its own thread of execution.
 void initialize()
          Initialize is used to initialize the external agent after it has been loaded into the virtual machine.
 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.
 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.
 void onRetract(IFact fact)
          onRetract is called by the virtual machine whenever a fact is retracted from the world state.
 void pause()
          Pauses the external agent.
 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.
 void resume()
          Resumes the external agent from a pause.
 void start()
          Starts the external agent.
 void stop()
          Stops the external agent.
 

Method Detail

initialize

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.

Throws:
ExternalException - if an internal error occurs.

start

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

Throws:
ExternalException - if an internal error occurs.

pause

void pause()
           throws ExternalException
Pauses the external agent.

Throws:
ExternalException - if an internal error occurs.

resume

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

Throws:
ExternalException - if an internal error occurs.

stop

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

Throws:
ExternalException - if an internal error occurs.

reset

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.

Throws:
ExternalException - if an internal error occurs.

doWork

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).

Throws:
ExternalException - if an unrecoverable error occurs.

onProcess

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.

Parameters:
time - the time for which agents can process their events.
Throws:
ExternalException - if an internal error occurs.

onReceive

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.

Parameters:
belief - the IBelief communicated to this external agent
Throws:
ExternalException - if an error occurs handling this belief

onAssert

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.

Parameters:
fact - the IFact asserted in the world state
Throws:
ExternalException - if an error occurs handling this fact

onRetract

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.

Parameters:
fact - the IFact retracted from the world state
Throws:
ExternalException - if an error occurs handling this fact