brahms.communication
Class AbstractCommunicationAgent

java.lang.Object
  gov.nasa.arc.brahms.vm.api.jagt.AbstractExternalAgent
      brahms.communication.AbstractCommunicationAgent

All Implemented Interfaces:

IExternalAgent

public abstract class AbstractCommunicationAgent
extends AbstractExternalAgent

The AbstractCommunicationAgent is a base class for external agents that communicate with other agents solely using CommunicativeActs. This agent supports simulation mode, realtime mode and distributed realtime mode.

The minimum set of methods to be implemented by an implementation are:

• getConfigurationFile
• onInitialize
• onStart
• onStop
• onMessage

The methods for which a default implementation is provided but that can be overridden by an implementation to provide custom behavior without affecting the behavior of the agent are:

• getName
• getQualifiedName
• getConfigurationFile
• onPause
• onResume

The methods that must be used to communicate with other agents to ensure proper operation in all modes of operation:

• sendMessage(CommunicativeAct message, IActiveInstance recipient)
• sendMessage(IObject message, IActiveInstance recipient)

The agent automatically loads the configuration properties for the agent if a configuration file is specified getConfigurationFile. These properties are available through getProperties.

The agent automatically enqueues any incoming CommunicativeActs in the agent's onReceive method. The messages are processed in onMessage. The agent calls onMessage for incoming message at the appropriate time depending on the mode of operation (either in doWork in the agent's thread when in a realtime mode or in simulation mode when isAutoReady() returns false, or in onProcess when in simulation mode and isAutoReady() returns true). Methods are available to manipulate the incoming message queue (enqueue/dequeueIncomingMessage).

The agent should send out messages using any of the sendMessage methods. This ensures that outgoing communications are sent out using the appropriate methods and that the scheduler is made aware of the communication when in simulation mode. The agent can register an IReplyHandler for a message that is sent out if responses are expected for that message. In that case the agent will forward responses to the appropriate IReplyHandler and will not call onMessage for those responses. Only one IReplyHandler can be registered for a CommunicativeAct, if a new IReplyHandler is registered it replaces the previously registered IReplyHandler. Use removeReplyHandler(CommunicativeAct) to remove the reply handler when it is no longer needed. NOTE: Be very careful with the reply handlers when the agent is run in simulation mode and isAutoReady returns true. The reply handler must not block or it will prevent the transmission of any outgoing messages and prevent any responses for the message from being delivered.

If time synchronization is of importance in simulation mode, i.e. the agent must ensure that that simulation does not advance until it completes its incoming message processing, then the agent must set the auto-ready flag to false setAutoReady(false) in its initialization method onInitialize. By default auto-ready is true. Having auto-ready set to false makes message processing more efficient in that all incoming messages are processed on the agent's thread of execution instead of on the scheduler's thread of execution. However the agent must itself call ready() when it finishes doing all of its needed processing and wants the simulation to resume. This notifies the scheduler to distribute any outgoing messages and to notify this agent of any messages that were queued for delivery. If no events are delivered to the agent during simulation cycles or any delivered events do not result in messages to be processed then automatically a ready() is invoked by this agent when onProcess is called. So only when there are incoming CommunicativeActs the agent must call ready() to resume the simulation. Note that setAutoReady, isAutoReady and ready have no influence when the agent is run in real-time mode.

The agent automatically acquires a memory reference for every CommunicativeAct it creates and receives. By default the agent will automatically release the reference to the CommunicativeAct:

• After a CommunicativeAct is sent provided no reply handler is registered for it
• After a received CommunicativeAct is processed (after a call to onMessage for the message).
• After a notification to the IReplyHandler after which only the reply CommunicativeAct is released.
• On deregistration of an IReplyHandler at which time the CommunicativeAct for which the reply handler was registered is released.

If the agent wants to manually release a memory reference for the CommunicativeActs it needs to disable the automatic memory reference release by calling setAutoMemoryReferenceRelease(false). In this case only when the agent is stopped will this implementation release all references to CommunicativeActs that are queued in the incoming and outgoing message queues for CommunicativeActs that have not yet been processed and release the references for any CommunicativeActs for which reply handlers are registered.

Version:

$Revision: 1.3 $ $Date: 2008/02/28 19:46:50 $ $Author: rvhoof $

Author:

Ron van Hoof

Constructor Summary

AbstractCommunicationAgent()

Method Summary

CommunicativeAct	dequeueIncomingMessage() Removes the first CommunicativeAct from the incoming queue and blocks the calling thread if no messages are queued.
CommunicativeAct	dequeueIncomingMessage(boolean block) Removes the first CommunicativeAct from the incoming queue and blocks the calling thread if no data is queued and block = true or returns null if block = false.
void	doWork() The virtual machine takes care of having the agent run in its own thread of execution.
void	enqueueIncomingMessage(CommunicativeAct message) Adds the specified CommunicativeAct to the incoming message queue.
java.lang.String	getConfigurationFile() Returns the name of the file used to load the agent's configuration properties.
java.lang.String	getName() Returns this communication agent's simple name.
java.util.Properties	getProperties() Returns the configuration properties for this agent.
java.lang.String	getQualifiedName() Returns this communication agent's fully qualified name.
RunState	getRunState() Returns the RunState for the agent.
int[]	getStateLock() Returns the lock used to make access to the RunState thread safe.
boolean	hasIncomingMessage() Indicates whether one or more messages are still in the queue.
void	initialize() Initialize is used to initialize the external agent after it has been loaded into the virtual machine.
boolean	isAutoMemoryReferenceRelease() Indicates whether the agent should automatically release the memory references obtained to the CommunicativeActs it creates and/or receives.
protected java.util.Properties	loadConfigurationProperties() Loads the configuration properties for the agent.
void	onAssert(IFact fact) onAssert is called by the virtual machine whenever a new fact is asserted in the world state.
abstract void	onInitialize() Called when the agent is being initialized after it has been loaded into virtual machine.
abstract void	onMessage(CommunicativeAct message) Processes the specified message received by this agent.
void	onPause() Called when the agent is being paused.
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	onReset() Called when the agent is being reset.
void	onResume() Called when the agent is being resumed from a pause.
void	onRetract(IFact fact) onRetract is called by the virtual machine whenever a fact is retracted from the world state.
abstract void	onStart() Called when the agent is being started.
abstract void	onStop() Called when the agent is being stopped.
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	removeReplyHandler(CommunicativeAct message) Removes the IReplyHandler that was registered for the specified CommunicativeAct.
void	removeReplyHandler(IObject message) Removes the IReplyHandler that was registered for the specified CommunicativeAct.
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	sendMessage(CommunicativeAct message, IActiveInstance recipient) Sends the specified message to the specified recipient.
void	sendMessage(CommunicativeAct message, IActiveInstance recipient, IReplyHandler replyHandler) Sends the specified message to the specified recipient and has responses for the specified message sent to the specified reply handler.
void	setAutoMemoryReferenceRelease(boolean autoRelease) Sets whether the agent should automatically release the memory references obtained to the CommunicativeActs it creates and/or receives.
void	setRunState(RunState state) Sets the RunState for the agent.
void	start() Starts the external agent.
void	stop() Stops the external agent.

Methods inherited from class gov.nasa.arc.brahms.vm.api.jagt.AbstractExternalAgent

assertFact, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, conclude, deregisterForMonitoring, getBrahmsAgent, getContext, getModel, getModeOfOperation, getVMController, getWorldState, isAcceptingFacts, isAutoReady, isValidTruthValue, notifyNewEvents, onThreadEnd, registerForMonitoring, retractFact, send, send, send, send, setAcceptingFacts, setAgentCtx, setAutoReady, setBrahmsAgent, setProperties, setVMController, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractCommunicationAgent

public AbstractCommunicationAgent()

Method Detail

getName

public final java.lang.String getName()

Returns this communication agent's simple name.

Returns:

String this agent's simple name

getQualifiedName

public final java.lang.String getQualifiedName()

Returns this communication agent's fully qualified name.

Returns:

String this agent's fully qualified name

getConfigurationFile

public java.lang.String getConfigurationFile()

Returns the name of the file used to load the agent's configuration properties. This must be the simple name of the file. The configuration file is loaded by looking for it on the classpath, user's home directory, java directory, and current directory. By default the configuration file's name is getName()+".cfg"

Returns:

String the configuration file to configure this agent, null if no file is used to configure the agent

getProperties

public java.util.Properties getProperties()

Returns the configuration properties for this agent.

Returns:

Properties the agent's configuration properties

getStateLock

public final int[] getStateLock()

Returns the lock used to make access to the RunState thread safe.

Returns:

int[] the RunState's lock

getRunState

public final RunState getRunState()

Returns the RunState for the agent.

Note: This method is not threadsafe, use the state lock to enforce a thread safe retrieval of the RunState.

Returns:

RunState the agent's RunState

See Also:

getStateLock()

setRunState

public final void setRunState(RunState state)

Sets the RunState for the agent.

Note: This method is not threadsafe, use the state lock to enforce a thread safe modification of the RunState.

Parameters:

state - RunState

See Also:

getStateLock()

isAutoMemoryReferenceRelease

public final boolean isAutoMemoryReferenceRelease()

Indicates whether the agent should automatically release the memory references obtained to the CommunicativeActs it creates and/or receives.

Returns:

boolean true if the agent automatically releases the memory references, false to have the agent implementation take care of it.

setAutoMemoryReferenceRelease

public final void setAutoMemoryReferenceRelease(boolean autoRelease)

Sets whether the agent should automatically release the memory references obtained to the CommunicativeActs it creates and/or receives.

Parameters:

autoRelease - true if the agent is to automatically release the memory references, false to have the agent implementation take care of it.

initialize

public final 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

Specified by:

initialize in class AbstractExternalAgent

Throws:

ExternalException - if an internal error occurs.

loadConfigurationProperties

protected java.util.Properties loadConfigurationProperties()

Loads the configuration properties for the agent.

Returns:

Properties returns the loaded configuration properties

onInitialize

public abstract void onInitialize()
                           throws ExternalException

Called when the agent is being initialized after it has been loaded into virtual machine. All agents are initialized before they are started. At the time of this call any configuration properties will have been loaded.

Throws:

ExternalException - if an internal error occurs.

start

public final 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

Specified by:

start in class AbstractExternalAgent

Throws:

ExternalException - if an internal error occurs.

onStart

public abstract void onStart()
                      throws ExternalException

Called when the agent is being started. Any initializations required for running the agent are to be performed here.

Throws:

ExternalException - if an internal error occurs

pause

public final void pause()
                 throws ExternalException

Pauses the external agent.

Specified by:

pause in interface IExternalAgent

Specified by:

pause in class AbstractExternalAgent

Throws:

ExternalException - if an internal error occurs.

onPause

public void onPause()
             throws ExternalException

Called when the agent is being paused.

Throws:

ExternalException - if an internal error occurs

resume

public final void resume()
                  throws ExternalException

Resumes the external agent from a pause.

Specified by:

resume in interface IExternalAgent

Specified by:

resume in class AbstractExternalAgent

Throws:

ExternalException - if an internal error occurs.

onResume

public void onResume()
              throws ExternalException

Called when the agent is being resumed from a pause.

Throws:

ExternalException - if an internal error occurs

stop

public final 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

Specified by:

stop in class AbstractExternalAgent

Throws:

ExternalException - if an internal error occurs.

onStop

public abstract void onStop()
                     throws ExternalException

Called when the agent is being stopped. Add code to properly shut down the agent and release any resources obtained by this agent.

Throws:

ExternalException - if an internal error occurs

reset

public final 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

Specified by:

reset in class AbstractExternalAgent

Throws:

ExternalException - if an internal error occurs.

onReset

public void onReset()
             throws ExternalException

Called when the agent is being 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.

Throws:

ExternalException - if an internal error occurs

doWork

public final void doWork()
                  throws ExternalException

The virtual machine takes care of having the agent run in its own thread of execution.

Specified by:

doWork in interface IExternalAgent

Specified by:

doWork in class AbstractExternalAgent

Throws:

ExternalException - if an unrecoverable error occurs.

onProcess

public final 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. Blocking this method will effectively pause the simulation until the method returns. The scheduler will not advance time until this agent completed this method.

This method first send out any scheduled outgoing messages, scheduled by calls to sendMessage, then processes any messages that were received by this agent calling onMessage for each incoming message, lastly it sends out any new scheduled outgoing messages, scheduled as a result of processing the incoming messages.

Specified by:

onProcess in interface IExternalAgent

Overrides:

onProcess in class AbstractExternalAgent

Parameters:

time - the time for which agents can process their events.

Throws:

ExternalException - if an internal error occurs

See Also:

AbstractExternalAgent.onProcess(long)

enqueueIncomingMessage

public void enqueueIncomingMessage(CommunicativeAct message)
                            throws QueueException

Adds the specified CommunicativeAct to the incoming message queue.

Parameters:

message - the CommunicativeAct to be enqueued

Throws:

QueueException - if the queue was closed.

dequeueIncomingMessage

public CommunicativeAct dequeueIncomingMessage()
                                        throws QueueException

Removes the first CommunicativeAct from the incoming queue and blocks the calling thread if no messages are queued.

Returns:

CommunicativeAct the first message in the queue

Throws:

QueueException - if the queue was closed while waiting for new messages.

dequeueIncomingMessage

public CommunicativeAct dequeueIncomingMessage(boolean block)
                                        throws QueueException

Removes the first CommunicativeAct from the incoming queue and blocks the calling thread if no data is queued and block = true or returns null if block = false.

Parameters:

block - true to have the method block until a message is enqueued, false to not block and return null if no messages are present

Returns:

CommunicativeAct the first message in the queue, or null if there are no messages and block=false

Throws:

QueueException - if the queue was closed while waiting for new messages.

hasIncomingMessage

public boolean hasIncomingMessage()

Indicates whether one or more messages are still in the queue.

Returns:

boolean true if one or more message are in the queue, false otherwise

onMessage

public abstract void onMessage(CommunicativeAct message)

Processes the specified message received by this agent.

Parameters:

message - the CommunicativeAct with the message details

sendMessage

public void sendMessage(CommunicativeAct message,
                        IActiveInstance recipient)
                 throws ExternalException

Sends the specified message to the specified recipient.

Parameters:

message - the CommunicativeAct to be sent

recipient - the IActiveInstance to deliver the message to

Throws:

ExternalException - if message is not a CommunicativeAct or because of an internal error or in case of a communication failure the linked exception will be one of ServiceException, NoSuchActorException, ActorNotActiveException, NotLocatableException, TransportFailure, or SecurityFailure

See Also:

ServiceException, SecurityFailure, NoSuchActorException, ActorNotActiveException, NotLocatableException, TransportFailure

sendMessage

public void sendMessage(CommunicativeAct message,
                        IActiveInstance recipient,
                        IReplyHandler replyHandler)
                 throws ExternalException

Sends the specified message to the specified recipient and has responses for the specified message sent to the specified reply handler.

Parameters:

message - the CommunicativeAct to be sent

recipient - the IActiveInstance to deliver the message to

replyHandler - the IReplyHandler to notify of any responses to the specified message

Throws:

ExternalException - if message is not a CommunicativeAct or because of an internal error or in case of a communication failure the linked exception will be one of ServiceException, NoSuchActorException, ActorNotActiveException, NotLocatableException, TransportFailure, or SecurityFailure

See Also:

ServiceException, SecurityFailure, NoSuchActorException, ActorNotActiveException, NotLocatableException, TransportFailure

ready

public final 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.

Specified by:

ready in interface IExternalAgent

Overrides:

ready in class AbstractExternalAgent

removeReplyHandler

public void removeReplyHandler(CommunicativeAct message)

Removes the IReplyHandler that was registered for the specified CommunicativeAct.

Parameters:

message - the CommunicativeAct for which to remove the IReplyHandler

removeReplyHandler

public void removeReplyHandler(IObject message)

Removes the IReplyHandler that was registered for the specified CommunicativeAct.

Parameters:

message - the Brahms CommunicativeAct for which to remove the IReplyHandler

onReceive

public 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

Specified by:

onReceive in class AbstractExternalAgent

Parameters:

belief - the IBelief communicated to this external agent

Throws:

ExternalException - if an error occurs handling this belief

onAssert

public 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

Specified by:

onAssert in class AbstractExternalAgent

Parameters:

fact - the IFact asserted in the world state

Throws:

ExternalException - if an error occurs handling this fact

onRetract

public 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

Specified by:

onRetract in class AbstractExternalAgent

Parameters:

fact - the IFact retracted from the world state

Throws:

ExternalException - if an error occurs handling this fact