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

All Known Implementing Classes:

AbstractCommunicationAgent, 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.

Version:

$Revision: 1.1 $ $Date: 2009/11/23 18:40:38 $ $Author: rnado $

Author:

Ron van Hoof

Method Summary

void	doWork() The virtual machine takes care of having the agent run in its own thread of execution.
IAgent	getBrahmsAgent() Returns the Brahms agent reference for this agent.
void	initialize() Initialize is used to initialize the external agent after it has been loaded into the virtual machine.
boolean	isAcceptingFacts() Indicates whether the agent wants to be notified of any fact related events (assertion/retraction).
boolean	isAutoReady() Indicates whether the agent should automatically notify the scheduler it is ready for more events after it was notified of the current set of events and after onProcess was called.
void	notifyNewEvents() Notifies the scheduler (only in simulation mode) that the external agent has new events ready for distribution.
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	onThreadEnd() onThreadEnd is the last method called just before the agent's thread is gracefully ending.
void	pause() Pauses the external agent.
void	ready() Notifies the scheduler that the agent completed its processing and is ready to receive more events.
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	setBrahmsAgent(IAgent agent) Sets the Brahms agent reference for this agent.
void	start() Starts the external agent.
void	stop() Stops the external agent.

Method Detail

setBrahmsAgent

void setBrahmsAgent(IAgent agent)

Sets the Brahms agent reference for this agent. This method is called by the Brahms virtual machine. The Brahms agent reference is required to notify other agents of this agent.

Parameters:

agent - the Brahms agent reference for this external agent

getBrahmsAgent

IAgent getBrahmsAgent()

Returns the Brahms agent reference for this agent. This method is called by the Brahms virtual machine. The Brahms agent reference is required to notify other agents of this agent. return IAgent the Brahms agent reference for this external agent

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.

isAutoReady

boolean isAutoReady()

Indicates whether the agent should automatically notify the scheduler it is ready for more events after it was notified of the current set of events and after onProcess was called. If the method returns false the agent is responsible for notifying the scheduler it is ready by invoking the ready method. The simulation will not proceed until all agents notified the scheduler that they are ready for the next set of events.

Note: Only relevant when the agent is used in simulation mode.

Returns:

boolean true to automatically send a ready notice, false to have the agent control whent o send a ready notice.

ready

void ready()

Notifies the scheduler that the agent completed its processing and is ready to receive more events. If isAutoReady this method is a no-op, if not isAutoReady the agent must notify the scheduler when it is ready to receive new events after onProcess has been called. Only when ready is called will the simulation proceed. The simulation waits after onProcess is called for all agents until all agents are ready to receive more events before the simulation distributes the new events and advances time.

Note: Only relevant when the agent is used in simulation mode a no-op in real-time mode.

notifyNewEvents

void notifyNewEvents()

Notifies the scheduler (only in simulation mode) that the external agent has new events ready for distribution. This is used in cases where none of the agents are doing anything and the scheduler is dormant since there are not events to be distributed. This tells the scheduler that this external agent has events waiting and has the scheduler wake up all agents to allow them to process any events they have waiting.

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

isAcceptingFacts

boolean isAcceptingFacts()

Indicates whether the agent wants to be notified of any fact related events (assertion/retraction). (Default: true)

Returns:

boolean true to accept fact assertions/retractions, false if not

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

onThreadEnd

void onThreadEnd()
                 throws ExternalException

onThreadEnd is the last method called just before the agent's thread is gracefully ending. It is the last method called in the agent's run method allowing the agent developer to provide final thread cleanup if any is necessary.

Throws:

ExternalException - if an error occurs during the cleanup