casa

Class AbstractProcess

java.lang.Object

java.lang.Thread

casa.AbstractProcess

All Implemented Interfaces:

CasaObservable, AgentPrintInterface, MessageSender, PolicyAgentInterface, ProcessInterface, TraceInterface, Comparable<AbstractProcess>, Runnable, Observer

Direct Known Subclasses:

TransientAgent

public abstract class AbstractProcess
extends Thread
implements ProcessInterface, PolicyAgentInterface, CasaObservable, Comparable<AbstractProcess>, TraceInterface

This class contains the basic methods for any process. It's primary responsibility is sending and receiving messages. Messages (MLMessage) are sent directly using either local calls (if the other agent happens to be in the same process) or TCP/IP. Messages (and other Events) are received by removing them an EventQueue, which is populated by the AbstractProcess's sister thread, a SocketServer. One of ABstractProcess's most important functions is to monitor the event queue in an event loop, removing items (such as messages) for processing (via processEvent(Event) or, if there is nothing in the event queue, calling processCommitments(). (If there's nothing left to do, it just sleeps.)

The class makes use of several important methods as part of the event loop (which listens for incoming messages and other events):

message loop status	method called	function
not started	initializeConstructor(ParamsMap, AgentUI, int)	pre-loop init, called once only, during the constructor, and in the thread of the caller, not the agent's thread.
	initializeThread(ParamsMap, AgentUI)	pre-loop init, called once only, before theevent loop starts, and in the agent's main thread, not the caller's thread. This is called before the agent is registered (see TransientAgent.initializeAfterRegistered(boolean) for the method called after the agent is registered with the LAC.
running	eventBufferLoopBody()	implements the body of the loop, called repeatedly. The default version will call doIdle() if there's no messages available
	pendingFinishRun()	called when an exit() has been called, called only once
	finished	finishRun()	called after the message loop has exited, called only once

When overriding these methods, be sure to call the super version to avoid crippling the functionality of the process.

In addition, there are several important virtual methods having to do with message handling. All of these methods should return a Status with a value of:

• negative: to indicate failed handling of the message (no more processing necessary)
• 0: to indicate successful handling of the message (no more processing necessary)
• 1: the message was not handled or not recognized (continue to attempt processing normally)
• greater than 1: the message processing failed or was somehow not completely successful but we should continue to attempt processing normally)

method	comment
handleEvent(Event)	Normal handling of incoming messages. See TransientAgent.handleEvent(Event).
#resolveConnectException(MLMessage)	This method is called when a send has failed due to a ConnectionException, which might have been caused by an unresolved URL. The subclass can resolve the URL (as TransientAgent#resolveConnectException(MLMessage) does) and return 0 to cause the send to be retried (once). AbstractProcess's default is to do nothing and return -1.
unhandledMessage(MLMessage)	This method is called as a last-ditch effort to handle the message, after all other normal processing has not handled it (as opposed to failing). AbstractProcess's default is to reply with a not-understood message. This method has a void return

When overriding these methods, be sure to call the super version so that superclasses may handle any relevant messages that your class does not.

Other important messages are:

• sendMessage(MLMessage)
• sendMessage(String, String, URLDescriptor, String...)
• sendRequestAndWait(MLMessage, long, MessageEventDescriptor...)
• sendRequestAndWait(String, String, URLDescriptor, String[])

Copyright: Copyright 2003-2014, Knowledge Science Group, University of Calgary. Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. The Knowledge Science Group makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

Version:

0.9

Author:

Rob Kremer, Chad La Fournie

See Also:

TransientAgent, ProcessInterface

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	AbstractProcess.Subthread

Nested classes/interfaces inherited from class java.lang.Thread

Thread.State, Thread.UncaughtExceptionHandler

Field Summary

Fields

Modifier and Type	Field and Description
private static CasaLispOperator	AGENT__SHOW_EVENT_QUEUE Lisp operator: (SHOW-EVENTQUEUE) Show the agent's events on the event queue.
(package private) EventQueue	eventQueue The agent's event queue.
private boolean	exit Set by exit() to signal the agent to exit.
private boolean	exited Set when the agent is fully existed and not longer accepting any messages
(package private) int	exitWaitCounter
private static CasaLispOperator	GET_HOST_NAMES Lisp operator: (GET-HOST-NAMES) Show the host names for this computer.
private static CasaLispOperator	GET_INETADDRESSES Lisp operator: (GET-INETADDRESSES) Show the host names for this computer.
(package private) long	heartbeat The interval (in milliseconds) that the agent should sleep if it has nothing else to do.
protected boolean	huntForPort True if this agent is to keep looking for a port if it fails to open the port suggested in the constructor.
private boolean	initializationComplete
protected ParamsMap	initParams
private AgentUI	initUI
private static int	maxPort The normal maximum range of agent lister port numbers
private static int	minPort The normal minimum range of agent lister port numbers
private CasaObservableObject	observerDelegate This class should actually multiply inherit from Thread and CasaObservable, but this is Java, so it can't: Instead we're forced to hold this reference to an ObservableState object.
protected Ontology	ontology The performative type hierarchy for this agent
protected static Ontology	ontologyShared
ProcessOptions	options The user-setable and potential persistent options for this object type.
private boolean	pause Set to true to pause the agent at the next message send or recieve
private static int	portCounter Agents use this static as a place to start when searching for ports.
private boolean	portOpen True whenever the message listener port is open
private int	reqID A number to be used to generate unique reply-with fields in messages.
protected SecurityFilterInterface	securityFilter The security filter used to encode/decode outgoing/incoming messages
private SocketServerInterface	socketServer The Listener thread that will queue incoming messages to the event queue (see eventQueue).
private Thread	starter used only to signal the starting thread that this agent is up and running
private long	subthreadID
protected Trace	trace the Trace object that handles debugging traces and messages
static int	TRACE_MONITOR Constant as a bit mask to signal tracing to a monitor window
static int	TRACE_OFF Constant as a bit mask to signal tracing is off
static int	TRACE_ON Constant as a bit mask to signal tracing is on
static int	TRACE_TO_FILE Constant as a bit mask to signal tracing to a log file
static int	TRACE_UNDEFINED Constant as a bit mask to signal the trace mode is undefined
(package private) ConcurrentSkipListSet<Transformation>	transformations
protected static int	uniqueThreadName
private URLDescriptor	url The URL of this object
boolean	waitingForAgentToStart Used only by #makeAgentInThisProc(ParamsMap, AgentUI) and run() to synchronize the start of the socket server.
(package private) boolean	waitingForEvent used by eventBufferLoopBody() and EventQueue.notifyNewItem(Event) to notify of events being placed in the queue
(package private) boolean	waitingForSocketServerToStart Used only by startSocketServer() and SocketServerTCPIP.run() to synchronize the start of the socket server.

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors

Constructor and Description
AbstractProcess(ParamsMap params, AgentUI ui, int port) Constructor.

Method Summary

Modifier and Type	Method and Description
abstract void	addConversation(String convID, Conversation conv)
void	addObserver(Observer observer) Part of the Observable interface from the observer pattern (Gamma et al.).
void	addObserver(Observer o, String... notifyTypes)
void	addObserver(URLDescriptor observer) Extension to the Observable interface from the observer pattern (Gamma et al.).
void	addObserver(URLDescriptor observer, String... notifyTypes)
int	addTraceTags(String tags) Adds a comma-delimited list of trace tags to a string.
void	addTransformation(Transformation trans)
boolean	authorizeMessage(MLMessage msg) Determines whether the given message should be handled by receiveMessage, or if it should be thrown out.
void	bump() wakes up the agent if it is sleeping waiting for an event to happen
void	clearAllTraceTags() Turns off ALL the trace tags.
void	closePort() Method to close the module's open port and return it to the system.
int	compareTo(AbstractProcess o)
int	countObservers()
void	defer(Runnable x) Can be used to defer a section of code on to the agent's event queue so that the code will execute in the agent's main thread.
void	defer(Runnable x, long milliseconds) Can be used to defer a section of code on to the agent's event queue so that the code will execute in the agent's main thread.
void	deleteObserver(Observer observer) Part of the Observable interface from the observer pattern (Gamma et al.).
void	deleteObserver(URLDescriptor observer) Extension to the Observable interface from the observer pattern (Gamma et al.).
void	deleteObservers()
void	dequeueEvent(Event event) Remove the event from the agent's event queue iff the event is already in the queue
boolean	equals(Object other)
private void	eventBufferLoop() The basic loop where this process checks for incoming messages on it's socket port.
protected void	eventBufferLoopBody() This method is called by eventBufferLoop() and may be overridden by a subclass as the actual code to dequeue messages off the queue.
protected void	eventBufferLoopPeriodic() Deprecated.
protected Event	eventQueuePeek()
boolean	existed()
void	exit() Tells the process to exit.
protected void	finalize()
protected void	finishRun() Subclasses may override this method to cleanup after the message loop exits and the agent is about to terminate.
void	fixupMessage(MLMessage message) corrects message fields like message timeout if bad
static AbstractProcess	getAgent()
String	getAgentName() Returns the name of the current process
protected abstract SocialCommitment	getChosenCommitment()
abstract LinkedList<Conversation>	getConversation(String convID)
protected String	getEventQueue()
ParamsMap	getInitParams()
MLMessage	getNewMessage(String performative, String act, URLDescriptor reciever) Creates a basic message with the given performative, act, and reciever.
MLMessage	getNewMessage(String performative, String act, URLDescriptor reciever, String... list) Creates a basic message with the given performative, act, and reciever.
ProcessOptions	getOptions() Returns a reference to this object's ProcessOptions object.
int	getPort() Returns the port that this agent is listening on.
SocketServerInterface	getSocketServer()
abstract String	getStrategy() Returns the strategy that this agent uses to interpret messages.
Trace	getTrace() get the associated Trace object.
String	getTraceTags()
Transformation	getTransformationFor(Describable d)
String	getUniqueRequestID() Returns a unique string that can be conveniently used in the reply-with and in-reply-to fields of a message.
URLDescriptor	getURL() Returns a copy of the URL of the current process
boolean	getUseAckProtocol() Retrieves whether this agent will use the the Ack (acknowledge) protocol.
boolean	getUsePriority() Get the state of using message queue priorities.
protected abstract void	handleEvent(Event event) This method is called from processEvent(Event).
protected abstract boolean	hasActiveCommitments()
boolean	hasChanged()
abstract boolean	hasConversation(String convID) Abstract classes for managing agent conversations.
boolean	hasOpenPort() Tests if this process has any open ports.
void	in(String methodName) Debugging method: should be the first line of every method in this class and in every subclass.
protected void	initializeConstructor(ParamsMap params, AgentUI ui, int port) Initializes all local variables and starts up the listener thread (to listen for and queue up any incoming messages).
protected void	initializeThread(ParamsMap params, AgentUI ui) Subclasses may override this method to initialize before the message loop is called, after the constructor is finished but before control is returned to the thread that called the constructor.
protected URLDescriptor	initializeURL(int port, String name) Initialize the URL for this object.
boolean	isA(Act child, Act ancestor) Determines if child is a subtype of (or the same type as the act named by the String ancestor.
boolean	isA(Act child, String ancestor) Determines if child is a subtype of (or the same type as the act named by the String ancestor.
boolean	isA(String child, Act ancestor) Determines if child is a subtype of (or the same type as the act named by the String ancestor.
boolean	isA(String child, String ancestor) Determines if child is a subtype of (or the same type as) ancestor.
boolean	isAAct(Act child, Act ancestor) Determines if child is a subtype of (or the same type as the act named by the String ancestor.
boolean	isAAct(String child, String ancestor)
boolean	isAgentThread()
boolean	isAPerformative(MLMessage m, String ancestor) Determines if performative field of message m is a subtype of (or the same type as the performative named by the String performative.
boolean	isAPerformative(String child, String ancestor) Determines if child is a subtype of (or the same type as the performative named by the String ancestor.
protected boolean	isEventQueueReady() Determines if the event queue has an event ready to process.
boolean	isExiting() determines if this process is in the process of exiting.
boolean	isInitialized()
boolean	isLoggingTag(String tag) Returns true if the process is logging tag, tag is "error," or tag is null
boolean	isObserveMessages()
boolean	isPaused() Determines if the agent is currently in the pause state.
boolean	isStoppable() determines if this process can be stopped.
boolean	isThisMyAddress(URLDescriptor theURL)
boolean	isTracing() Is tracing on?
static void	loadClass(String className)
protected ProcessOptions	makeOptions() Factory method to make a new options object.
Thread	makeSubthread(Runnable runnable) Creates a new thread in the same ThreadGroup as this agent, with the agent specified.
Thread	makeSubthread(Runnable runnable, String name) Creates a new thread in the same ThreadGroup as this agent, with the agent specified.
protected int	makeTraceParam() Used to make a trace parameter integer that matches the current options.
void	notifyObservers()
void	notifyObservers(String eventType, Object argument)
void	notifyObserversWithNoArg(String notifyType) Notify with no arguments
void	notifyObserversWithTop(Object arg) TOP is the notification type
protected void	notifySendingMessage(MLMessage message) This method is to be overridden by any subclasses that wish to be informed whenever a message is actually sent out.
void	out(String methodName) Debugging method: should be the last line of every method (and every exiting branch) in this class and in every subclass.
private void	pauseCheck() Checks for the pause state and wait()'s until interuped if paused.
protected void	pendingFinishRun() Subclasses may override this method to cleanup after an exit() has been called, but before the message loop exits and the agent is about to terminate.
String	println(String traceTag, String txt) Debugging or error method: Uses the Trace object to log the string if appropriate (ie: the traceTAg matches a tag that's turned on in the Trace object.
String	println(String traceTag, String txt, int flags) Equivalent to println(tag, string, null, flag)
String	println(String traceTag, String txt, Status tempStatus) Deprecated.
String	println(String traceTag, String txt, Throwable ex) Same as println(String, String) but appends ex.toString() and prints a stack trace after.
String	println(String traceTag, String txt, Throwable ex, int flags) This is the println method that defines all the other println methods.
protected abstract SocialCommitment	processCommitment(SocialCommitment sc)
protected SocialCommitment	processCommitments() Subclasses will normally override this.
private void	processEvent(Event event) This method is a pre-processing step before the event from the event queue is passed passed on to handleEvent(Event) for actual processing event.
void	queueEvent(Event event) Queues an event to the agent's event queue
void	queueEventIf(Event event) Put the Event on the agent's event queue iff the event is not already on the queue.
void	realizeAgentBehaviourFromOptions() Refresh agent behaviour from the options object.
abstract Conversation	removeConversation(Conversation conv)
int	removeTraceTags(String tags) Removes the tags in the comma-delimited streams specified in tags.
protected void	resetRuntimeOptionsFromCommandLine()
protected void	resetSecurityPackage(String pack)
protected void	resetTraceOptions() Synchronize the trace options with what's actually happening: if options says we're monitoring, start the monitor; if they say to log to a file, make sure the file is open for logging.
protected Status	resolveConnectException(MLMessage msg, Runnable1<String,Status> cmd) This method may be overridden by a subclass to handle a ConnectionException during a call to sendMessage(MLMessage).
Describable	revTransform(Describable d)
String	revTransform(String d)
void	run() This method starts the message handling loop by calling eventBufferLoop(), which actually does the loop.
(package private) Status	sendMessage_primitive(MLMessage message, boolean... shouldResolve) Sends the message to the the message.receiver or, if message.receiver is missing or empty, to message.to.
Status	sendMessage(MLMessage message) Sends the message to the the message.receiver or, if message.receiver is missing or empty, to message.to.
Status	sendMessage(String performative, String act, URLDescriptor reciever, String... list) Utility method to construct and send a message asynchronously using sendMessage(MLMessage).
protected StatusObject<MLMessage>	sendMessageAndWait(MLMessage message, long timeout, MessageEventDescriptor... messageDescriptors) Sends a message, message, waiting up to timeout milliseconds for the request transaction to complete, and returns as StatusObject which contains the final message, if it completed.
protected StatusObject<MLMessage>	sendQueryAndWait(MLMessage message, long timeout, MessageEventDescriptor... messageDescriptors) Sends a QUERY (QUERY-REF or QUERY-IF) message, message, waiting up to timeout milliseconds for the query transaction to complete, and returns as StatusObject which contains the final message, if it completed.
protected StatusObject<MLMessage>	sendRequestAndWait(MLMessage message, long timeout, MessageEventDescriptor... messageDescriptors) Sends a REQUEST message, message, waiting up to timeout milliseconds for the request transaction to complete, and returns as StatusObject which contains the final message, if it completed.
MLMessage	sendRequestAndWait(String performative, String act, URLDescriptor reciever, String... list) Utility method to construct and send a syncronous message using sendRequestAndWait(MLMessage, long, MessageEventDescriptor...).
void	setAllTraceTags() Turns all ALL the trace tags.
void	setObserveMessages(boolean newVal) Set whether the agent will ignore or process messages that are not addressed to it (broadcaste messages never ignored).
void	setOptions(ProcessOptions options) Sets this object's ProcessOptions object.
void	setPause(boolean val) Set or clear the agent pausing immediately after processing the next message send or recieve.
int	setTraceTags(String tags) Works the same as addTraceTags, but removes all previous tags beforehand.
void	setTracing(boolean doTrace) Turn tracing on / off.
void	setURL(URLDescriptor url) Sets the URL of for current process
boolean	setUseAckProtocol(boolean b) Sets whether this agent will use the the Ack (acknowledge) protocol.
void	setUsePriority(boolean newVal) Set the use of message priorities.
private boolean	someTriggered(MessageObserverEvent[] events)
protected void	startSocketServer() Start the SocketServer and initialize the eventQueue
void	startTraceMonitor() Display the trace monitor window.
void	step() If the agent is is the pause state, activates (resumes) the agent until processing the next sent or recieved message.
Describable	transform(Describable d)
String	transform(String d)
protected void	unhandledMessage(MLMessage message) Subclasses may override this method to override default processing of unhandled messages.
void	update(Observable o, Object arg)
void	updateOptions() Save the options to a persistent database.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface casa.interfaces.ProcessInterface

getName

Methods inherited from interface casa.interfaces.PolicyAgentInterface

abclEval, abclEval, abclEval, chooseSC, dispatchMsgHandlerMethod, evesdrop, executeCommand, getKnowledgeBase, getName, getOntology, getSCStore, getSubscribeEvents

Field Detail

observerDelegate

private CasaObservableObject observerDelegate

This class should actually multiply inherit from Thread and CasaObservable, but this is Java, so it can't: Instead we're forced to hold this reference to an ObservableState object. Initialized in the constructor.

url

private URLDescriptor url

The URL of this object

socketServer

private SocketServerInterface socketServer

The Listener thread that will queue incoming messages to the event queue (see eventQueue).

eventQueue

EventQueue eventQueue

The agent's event queue.

reqID

private int reqID

A number to be used to generate unique reply-with fields in messages. To be used ONLY by getUniqueRequestID().

exit

private boolean exit

Set by exit() to signal the agent to exit.

exited

private boolean exited

Set when the agent is fully existed and not longer accepting any messages

huntForPort

protected boolean huntForPort

True if this agent is to keep looking for a port if it fails to open the port suggested in the constructor. If huntForPort is false, this agent should fail if it can't open it's suggested port.

minPort

private static final int minPort

The normal minimum range of agent lister port numbers

See Also:

Constant Field Values

maxPort

private static final int maxPort

The normal maximum range of agent lister port numbers

See Also:

Constant Field Values

portCounter

private static int portCounter

Agents use this static as a place to start when searching for ports. The number is normally incremented (circularly) so agents can heuristically avoid tripping over one another in searching for ports.

portOpen

private boolean portOpen

True whenever the message listener port is open

trace

protected final Trace trace

the Trace object that handles debugging traces and messages

TRACE_UNDEFINED

public static final int TRACE_UNDEFINED

Constant as a bit mask to signal the trace mode is undefined

See Also:

Constant Field Values

TRACE_OFF

public static final int TRACE_OFF

Constant as a bit mask to signal tracing is off

See Also:

Constant Field Values

TRACE_ON

public static final int TRACE_ON

Constant as a bit mask to signal tracing is on

See Also:

Constant Field Values

TRACE_MONITOR

public static final int TRACE_MONITOR

Constant as a bit mask to signal tracing to a monitor window

See Also:

Constant Field Values

TRACE_TO_FILE

public static final int TRACE_TO_FILE

Constant as a bit mask to signal tracing to a log file

See Also:

Constant Field Values

options

public ProcessOptions options

The user-setable and potential persistent options for this object type. This field must have public access to allow OPTIONS processing to get at it.

ontology

protected Ontology ontology

The performative type hierarchy for this agent

ontologyShared

protected static Ontology ontologyShared

securityFilter

protected SecurityFilterInterface securityFilter

The security filter used to encode/decode outgoing/incoming messages

starter

private final Thread starter

used only to signal the starting thread that this agent is up and running

transformations

ConcurrentSkipListSet<Transformation> transformations

initializationComplete

private boolean initializationComplete

initParams

protected ParamsMap initParams

initUI

private AgentUI initUI

waitingForSocketServerToStart

volatile boolean waitingForSocketServerToStart

Used only by startSocketServer() and SocketServerTCPIP.run() to synchronize the start of the socket server.

waitingForAgentToStart

public volatile boolean waitingForAgentToStart

Used only by #makeAgentInThisProc(ParamsMap, AgentUI) and run() to synchronize the start of the socket server.

waitingForEvent

volatile boolean waitingForEvent

used by eventBufferLoopBody() and EventQueue.notifyNewItem(Event) to notify of events being placed in the queue

exitWaitCounter

int exitWaitCounter

heartbeat

long heartbeat

The interval (in milliseconds) that the agent should sleep if it has nothing else to do. The agent will "wake up" every interval to check to see if there is something in the event queue or any social commitments to process.
Set this value to 0 to have the agent only wake up when it is interrupted (which is is whenever something is queued to the event queue, etc.).

uniqueThreadName

protected static int uniqueThreadName

pause

private boolean pause

Set to true to pause the agent at the next message send or recieve

subthreadID

private long subthreadID

AGENT__SHOW_EVENT_QUEUE

private static final CasaLispOperator AGENT__SHOW_EVENT_QUEUE

Lisp operator: (SHOW-EVENTQUEUE)
Show the agent's events on the event queue.

GET_HOST_NAMES

private static final CasaLispOperator GET_HOST_NAMES

Lisp operator: (GET-HOST-NAMES)
Show the host names for this computer.

GET_INETADDRESSES

private static final CasaLispOperator GET_INETADDRESSES

Lisp operator: (GET-INETADDRESSES)
Show the host names for this computer.

Constructor Detail

AbstractProcess

public AbstractProcess(ParamsMap params,
                       AgentUI ui,
                       int port)
                throws IPSocketException

Constructor. Most of the work of the constructor is done by the initialize() method.

Parameters:

params - The parameters for creating this agent

ui - The UI to use to report any problems

port - The port number this process will use for communication with other objects. A -ve value indicates the agent should search starting with this port; +ve means it should fail if it can't open this port; 0 means it should choose it's own port.

Throws:

IPSocketException - when trying to bind to an IPSocket (port) that is either in use or invalid. See the port param above.

Method Detail

loadClass

public static final void loadClass(String className)

getSocketServer

public SocketServerInterface getSocketServer()

Returns:

the agent's socket server.

existed

public boolean existed()

Returns:

true iff the agent is fully existed and not longer accepting any messages

makeTraceParam

protected final int makeTraceParam()

Used to make a trace parameter integer that matches the current options. Normally used for an agent spawning sub-agents that have the same trace attributes as the agent.

Returns:

A trace parameter int that match the current options.

addTransformation

public void addTransformation(Transformation trans)

Specified by:

addTransformation in interface PolicyAgentInterface

getTransformationFor

public Transformation getTransformationFor(Describable d)

Specified by:

getTransformationFor in interface PolicyAgentInterface

transform

public Describable transform(Describable d)

Specified by:

transform in interface PolicyAgentInterface

revTransform

public Describable revTransform(Describable d)

Specified by:

revTransform in interface PolicyAgentInterface

transform

public String transform(String d)

Specified by:

transform in interface PolicyAgentInterface

revTransform

public String revTransform(String d)

Specified by:

revTransform in interface PolicyAgentInterface

isInitialized

public final boolean isInitialized()

Returns:

true iff the agent has completed initializeThread(ParamsMap, AgentUI) and in running its main thread.

getInitParams

public ParamsMap getInitParams()

Returns:

The parameters used that were passed to the constructor as a map from key to java/lisp object pairs

initializeConstructor

protected void initializeConstructor(ParamsMap params,
                                     AgentUI ui,
                                     int port)
                              throws Exception

Initializes all local variables and starts up the listener thread (to listen for and queue up any incoming messages). This method is called from the constructor and executes in the constructor caller's thread, not the agent's thread.

Parameters:

params - The parameters for initializing this agent

ui -

port - int this process will use for communication with other objects. A -ve value indicates the agent should search starting with this port; +ve means it should fail if it can't open this port; 0 means it should choose it's own port.

Throws:

IPSocketException

Exception

isAgentThread

public boolean isAgentThread()

Returns:

true iff this is the agent's thread, that is, the thread that reads events off the event queue.

resetRuntimeOptionsFromCommandLine

protected void resetRuntimeOptionsFromCommandLine()

resetTraceOptions

protected void resetTraceOptions()

Synchronize the trace options with what's actually happening: if options says we're monitoring, start the monitor; if they say to log to a file, make sure the file is open for logging.

makeOptions

protected ProcessOptions makeOptions()

Factory method to make a new options object. Subclasses should override this method if they need a specialized options object.

Returns:

a new ProcessOptions object

hasConversation

public abstract boolean hasConversation(String convID)

Abstract classes for managing agent conversations. Implemented in TransientAgent.

getConversation

public abstract LinkedList<Conversation> getConversation(String convID)

removeConversation

public abstract Conversation removeConversation(Conversation conv)

addConversation

public abstract void addConversation(String convID,
                                     Conversation conv)

isAPerformative

public boolean isAPerformative(MLMessage m,
                               String ancestor)

Determines if performative field of message m is a subtype of (or the same type as the performative named by the String performative.

Specified by:

isAPerformative in interface PolicyAgentInterface

Parameters:

m - the message under question

ancestor - the String name of the performative that's expected to be a super type

Returns:

true if m.performative is a subtype of ancestor, false otherwise

isAPerformative

public boolean isAPerformative(String child,
                               String ancestor)

Determines if child is a subtype of (or the same type as the performative named by the String ancestor.

Specified by:

isAPerformative in interface PolicyAgentInterface

Specified by:

isAPerformative in interface ProcessInterface

Parameters:

child - the name of the proposed child type

ancestor - the name of the proposed ancestor of the child

Returns:

if child is a subtype of ancestor, false otherwise

isA

public boolean isA(String child,
                   String ancestor)

Determines if child is a subtype of (or the same type as) ancestor. If either

Specified by:

isA in interface PolicyAgentInterface

Specified by:

isA in interface ProcessInterface

Parameters:

child - the name of the proposed child type; null is taken as "top"

ancestor - the name of the proposed ancestor of the child; null is taken as "top"

Returns:

if child is a subtype of ancestor, or if the at least one of them is not in the ontology, then return equal(child,ancestor).

isA

public boolean isA(Act child,
                   Act ancestor)

Determines if child is a subtype of (or the same type as the act named by the String ancestor. A subtype of a composite Act is: forall x,y:Act . x isa y = (forall i:int | i<|y| . x[i] isa y[i]).

Specified by:

isA in interface PolicyAgentInterface

Parameters:

child - the name of the proposed child type

ancestor - the name of the proposed ancestor of the child

Returns:

if child is a subtype of ancestor, false otherwise

isA

public boolean isA(String child,
                   Act ancestor)

Determines if child is a subtype of (or the same type as the act named by the String ancestor. A subtype of a composite Act is: forall x,y:Act . x isa y = (forall i:int | i<|y| . x[i] isa y[i]).

Specified by:

isA in interface PolicyAgentInterface

Parameters:

child - the name of the proposed child type

ancestor - the name of the proposed ancestor of the child

Returns:

if child is a subtype of ancestor, false otherwise

isA

public boolean isA(Act child,
                   String ancestor)

Determines if child is a subtype of (or the same type as the act named by the String ancestor. A subtype of a composite Act is: forall x,y:Act . x isa y = (forall i:int | i<|y| . x[i] isa y[i]).

Specified by:

isA in interface PolicyAgentInterface

Parameters:

child - the name of the proposed child type

ancestor - the name of the proposed ancestor of the child

Returns:

if child is a subtype of ancestor, false otherwise

isAAct

public boolean isAAct(Act child,
                      Act ancestor)

Determines if child is a subtype of (or the same type as the act named by the String ancestor. A subtype of a composite Act is: forall x,y:Act . x isa y = (forall i:int | i<|y| . x[i] isa y[i]).

Specified by:

isAAct in interface PolicyAgentInterface

Parameters:

child - the name of the proposed child type

ancestor - the name of the proposed ancestor of the child

Returns:

if child is a subtype of ancestor, false otherwise

isAAct

public boolean isAAct(String child,
                      String ancestor)

initializeURL

protected URLDescriptor initializeURL(int port,
                                      String name)

Initialize the URL for this object. If name contains '.'s or '/'s, then it's assumed to contain the complete path (and any '.'s are replaced with '/'s). If name doesn't contain any '.'s or '/'s, then the path part of the object string is inferred from it's class name. The username part is taken from the user.name system property.

Parameters:

port - The port that this object will open on (if -ve it's changed to its absolute value)

name - The name of the agent. Can be either with a path or not (in which case, the class name us used to infer a path)

Returns:

the URLDescriptor.make

in

public void in(String methodName)

Debugging method: should be the first line of every method in this class and in every subclass. It uses trace.in() to log the invocation of the method.

Parameters:

methodName - The string name of the method in the form "[className].[methodName]"

out

public void out(String methodName)

Debugging method: should be the last line of every method (and every exiting branch) in this class and in every subclass. It uses trace.out() to log the exiting of the method.

Parameters:

methodName - The string name of the method in the form "[className].[methodName]"

getURL

public URLDescriptor getURL()

Returns a copy of the URL of the current process

Specified by:

getURL in interface PolicyAgentInterface

Specified by:

getURL in interface ProcessInterface

Returns:

the URLDescriptor of the process

getAgentName

public String getAgentName()

Returns the name of the current process

Specified by:

getAgentName in interface ProcessInterface

Returns:

the name of this agent

getStrategy

public abstract String getStrategy()

Returns the strategy that this agent uses to interpret messages.

Specified by:

getStrategy in interface ProcessInterface

Returns:

an int port number

setURL

public void setURL(URLDescriptor url)

Sets the URL of for current process

Parameters:

url - a reference to URLDescriptor that will become this agent's URL

getUseAckProtocol

public boolean getUseAckProtocol()

Retrieves whether this agent will use the the Ack (acknowledge) protocol. That is, that this process will add ML.REQUEST_ACK to outgoing messages and resend if the message does not get acknowledged within the timeout period. This changes to always return false when the agent is exitting, because at that point, acks will probably fail.

Specified by:

getUseAckProtocol in interface PolicyAgentInterface

Specified by:

getUseAckProtocol in interface ProcessInterface

Returns:

true iff the agent uses the Ack protocol and isn't exitting

setUseAckProtocol

public boolean setUseAckProtocol(boolean b)

Sets whether this agent will use the the Ack (acknowledge) protocol. That is, that this process will add ML.REQUEST_ACK to outgoing messages and resend if the message does not get acknowledged within the reply-by period.

Specified by:

setUseAckProtocol in interface ProcessInterface

Parameters:

b - true to set the protocol, false to not use the protocol.

Returns:

true iff the agent used the Ack protocol (before the current setting);

getOptions

public ProcessOptions getOptions()

Returns a reference to this object's ProcessOptions object.

Specified by:

getOptions in interface PolicyAgentInterface

Specified by:

getOptions in interface ProcessInterface

Returns:

an reference to this object's ProcessOptions object.

setOptions

public void setOptions(ProcessOptions options)

Sets this object's ProcessOptions object.

Specified by:

setOptions in interface ProcessInterface

Parameters:

options - a reference to a ProcessOptions object will become this agent's options object

updateOptions

public void updateOptions()

Save the options to a persistent database. Since this is non-persistent class, there's nothing to do. Subclasses should override as appropriate.

Specified by:

updateOptions in interface ProcessInterface

realizeAgentBehaviourFromOptions

public void realizeAgentBehaviourFromOptions()

Refresh agent behaviour from the options object. Subclasses should override as appropriate.

Specified by:

realizeAgentBehaviourFromOptions in interface ProcessInterface

authorizeMessage

public boolean authorizeMessage(MLMessage msg)

Determines whether the given message should be handled by receiveMessage, or if it should be thrown out. This method is called from receiveMessage(). It should be overridden in subclasses to add actual behaviour. The overriding method should normally call and return super.authorizeMessage() if it doesn't want to filter incoming messages.

Parameters:

msg - contains the message to authorize

Returns:

true if the message is authorized to be processed; false otherwise

fixupMessage

public void fixupMessage(MLMessage message)
                  throws URLDescriptorException

corrects message fields like message timeout if bad

Parameters:

message - the message to correct

Throws:

URLDescriptorException - thrown if the receiver URL in the message is bad

sendMessage

public Status sendMessage(MLMessage message)

Sends the message to the the message.receiver or, if message.receiver is missing or empty, to message.to. Will adjust the following message fields:

• sets message.requestAck if the Ack protocol is on (getUseAckProtocol() returns true).
• adjust the value of message.reply-by to be the current time plus options.minTimeout if it is missing or or malformed or less than current time plus options.minTimeout (the exception is it is a subscribe message and message.timeout==0, which means "no timeout on the standing request").
• message.sender is always reset to be the URL of this agent

If send fails on a ConnectionException the first time, the subclass will be given a chance to resolve the problem by calling the "abstract" method #resolveConnectException(MLMessage). Normally, this will be because of an unresolved recipient URL. If resolveConnectException() is able to resolve the URL and returns 0, the send will be tried one more time.

Specified by:

sendMessage in interface MessageSender

Specified by:

sendMessage in interface PolicyAgentInterface

Specified by:

sendMessage in interface ProcessInterface

Parameters:

message - MLMessage of the message being sent, which contains the info about the recipient in the receiver or to fields.

Returns:

The Status describing the status of the operation:

0 if the message was sent without errors, or

-3 if there was an exception thrown during the message sending process (in this case, the returned object will be a StatusObject containing an Exception object).

See Also:

IPMessage

sendMessage_primitive

final Status sendMessage_primitive(MLMessage message,
                                   boolean... shouldResolve)
                            throws URLDescriptorException,
                                   IOException

Sends the message to the the message.receiver or, if message.receiver is missing or empty, to message.to. Will adjust the following message fields:

• sender is always reset to be the URL of this agent

If send fails on a ConnectionException the first time, the subclass will be given a chance to resolve the problem by calling the "abstract" method #resolveConnectException(MLMessage). Normally, this will be because of an unresolved recipient URL. If resolveConnectException() is able to resolve the URL and returns 0, the send will be tried one more time.

Parameters:

message - MLMessage of the message being sent, which contains the info about the recipient in the receiver or to fields.

shouldResolve - Uses only by recursive calls: Do not use.

Returns:

a Status object describing the success (0) or failure (-ve) of the operation

Throws:

URLDescriptorException

IOException

sendMessage

public Status sendMessage(String performative,
                          String act,
                          URLDescriptor reciever,
                          String... list)

Utility method to construct and send a message asynchronously using sendMessage(MLMessage).

Parameters:

performative - the performative field of the message

act - the act field

reciever - the URL of the message reciever

list - an array of key/value pairs (keys are even, values are odd). Key may not be null, but values may be.

Returns:

the Status returned from sendMessage(MLMessage)

sendRequestAndWait

public MLMessage sendRequestAndWait(String performative,
                                    String act,
                                    URLDescriptor reciever,
                                    String... list)

Utility method to construct and send a syncronous message using sendRequestAndWait(MLMessage, long, MessageEventDescriptor...).

Parameters:

performative - the performative field of the message

act - the act field

reciever - the reciever field

list - an array of key/value pairs (keys are even, values are odd). Key may not be null, but values may be.

Returns:

the reply message

Throws:

RuntimeException - if the list parameter is malformed

notifySendingMessage

protected void notifySendingMessage(MLMessage message)

This method is to be overridden by any subclasses that wish to be informed whenever a message is actually sent out. This version does nothing.

Parameters:

message -

Throws:

Exception

resolveConnectException

protected Status resolveConnectException(MLMessage msg,
                                         Runnable1<String,Status> cmd)

This method may be overridden by a subclass to handle a ConnectionException during a call to sendMessage(MLMessage). This method is guaranteed to be called at most only once per sent message. If this method returns a status of value 0, the send will be attempted exactly once more.
This implementation does nothing, and returns -1.

Parameters:

msg - the MLMessage the generated a ConnectionException on send.

Returns:

Status(-1)

sendRequestAndWait

protected StatusObject<MLMessage> sendRequestAndWait(MLMessage message,
                                                     long timeout,
                                                     MessageEventDescriptor... messageDescriptors)
                                              throws UnsupportedOperationException

Sends a REQUEST message, message, waiting up to timeout milliseconds for the request transaction to complete, and returns as StatusObject which contains the final message, if it completed. If the transaction times out either by a timeout event, or the timeout expiring the message will be null. Otherwise the message could be a PROPOSE, FAILURE, REFUSE, or NOT_UNDERSOOD.

If the messageDescriptor's are left out, this method will generate descriptors for PROPOSE/DISCHARGE|PERFORM|x, FAILURE/DISCHARGE|PERFORM|x, REFUSE/REQUEST|x, and NOT_UNDERSOOD/REQUEST|x.

Parameters:

message - The message to send, which should be a properly-addressed REQUEST message.

timeout - the time in milliseconds to wait if no event occurs

messageDescriptors - describing all the possible events to watch for the message, defaults to typical request protocol.

Returns:

a status of 0 is if a non-"negative-reply" message is returned, +ve if a "negative-reply" message is return, or -ve if no message was returned (a timeout).

Throws:

UnsupportedOperationException - if the message is somehow mangled

sendQueryAndWait

protected StatusObject<MLMessage> sendQueryAndWait(MLMessage message,
                                                   long timeout,
                                                   MessageEventDescriptor... messageDescriptors)
                                            throws UnsupportedOperationException

Sends a QUERY (QUERY-REF or QUERY-IF) message, message, waiting up to timeout milliseconds for the query transaction to complete, and returns as StatusObject which contains the final message, if it completed. If the transaction times out either by a timeout event, or the timeout expiring the message will be null. Otherwise the message could be a INFORM-IF/INFORM-REF, FAILURE, REFUSE, or NOT_UNDERSOOD (QUERY-IF-REPLYs or QUERY-REF-REPLYs).

If the messageDescriptor's are left out, this method will generate descriptors for QUERY-IF-REPLYs or QUERY-REF-REPLYs respectively (depending on the message performative).

Parameters:

message - The message to send, which should be a properly-addressed REQUEST message.

timeout - the time in milliseconds to wait if no event occurs

messageDescriptors - describing all the possible events to watch for the message, defaults to typical query protocol.

Returns:

a status of 0 is if a non-"negative-reply" message is returned, +ve if a "negative-reply" message is return, or -ve if no message was returned (a timeout).

Throws:

UnsupportedOperationException - if the message is somehow mangled

sendMessageAndWait

protected StatusObject<MLMessage> sendMessageAndWait(MLMessage message,
                                                     long timeout,
                                                     MessageEventDescriptor... messageDescriptors)
                                              throws UnsupportedOperationException

Sends a message, message, waiting up to timeout milliseconds for the request transaction to complete, and returns as StatusObject which contains the final message, if it completed. If the transaction times out either by a timeout event, or the timeout expiring the message will be null.

Parameters:

message - The message to send, which should be a properly-addressed REQUEST message.

timeout - the time in milliseconds to wait if no event occurs

messageDescriptors - describing all the possible events to watch for the message.

Returns:

a status of 0 is if a non-"negative-reply" message is returned, +ve if a "negative-reply" message is return, or -ve if no message was returned (a timeout).

Throws:

UnsupportedOperationException - if the message is somehow mangled or you don't supply the messageDescriptors

someTriggered

private boolean someTriggered(MessageObserverEvent[] events)

handleEvent

protected abstract void handleEvent(Event event)

This method is called from processEvent(Event). It should be overridden in subclasses to add actual behaviour. The overriding method should normally call and return super.handleMessage() if it doesn't handle the message. An overriding method should return:

0 if the message is handled +ve if the message was not handled, but should continue to attempt to process -ve if the message failed and any further processing should be aborted

Parameters:

event - The recieved message

startSocketServer

protected void startSocketServer()
                          throws IPSocketException

Start the SocketServer and initialize the eventQueue

Throws:

IPSocketException

queueEvent

public void queueEvent(Event event)

Queues an event to the agent's event queue

Specified by:

queueEvent in interface PolicyAgentInterface

Parameters:

event - the event to queue

queueEventIf

public void queueEventIf(Event event)

Put the Event on the agent's event queue iff the event is not already on the queue.

Specified by:

queueEventIf in interface PolicyAgentInterface

Parameters:

event - The event to queue.

dequeueEvent

public void dequeueEvent(Event event)

Remove the event from the agent's event queue iff the event is already in the queue

Specified by:

dequeueEvent in interface PolicyAgentInterface

Parameters:

event - The event to dequeue.

run

public final void run()

This method starts the message handling loop by calling eventBufferLoop(), which actually does the loop. If messageBufferLoop() returns, run() signals socketServer to exit and sends a inform/exit message to self so that socketServer will wake up to exit.

Specified by:

run in interface Runnable

Overrides:

run in class Thread

isStoppable

public boolean isStoppable()

determines if this process can be stopped. A subclass may override if there are more constraints on stopping. This implementation checks to see that that eventQueue is empty and there are no (non-standing-request) requests with replies pending.

Specified by:

isStoppable in interface ProcessInterface

Returns:

true if the process is stoppable, false otherwise.

exit

public void exit()

Tells the process to exit. Note that the process may not exit right away; generally, it must check to see that isStoppable() is true before it can actually exit (terminate eventBufferLoop()). In the event this method is called more than once, it will only call pendingFinishRun() the first time.

Specified by:

exit in interface ProcessInterface

isExiting

public boolean isExiting()

determines if this process is in the process of exiting. This returns the value of the exit field.

Specified by:

isExiting in interface ProcessInterface

Returns:

true if the process is exiting, false otherwise.

initializeThread

protected void initializeThread(ParamsMap params,
                                AgentUI ui)

Subclasses may override this method to initialize before the message loop is called, after the constructor is finished but before control is returned to the thread that called the constructor. Called once, just before messageBufferLoop(). This implementation initializes tracing. This method is safe as it is called from the thread of the agent (not the constructor)

Parameters:

quals -

pendingFinishRun

protected void pendingFinishRun()

Subclasses may override this method to cleanup after an exit() has been called, but before the message loop exits and the agent is about to terminate. Called once, just before the message loop terminates. This implementation does a notifyObservers(state.STATE_EXITING).

finishRun

protected void finishRun()

Subclasses may override this method to cleanup after the message loop exits and the agent is about to terminate. Called once, just before the agent terminates. This implementation does nothing but call notifyObservers(state.STATE_EXITED).

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

eventBufferLoop

private final void eventBufferLoop()

The basic loop where this process checks for incoming messages on it's socket port. This may be overridden by a subclass (but be careful about it!). This implementation mearly loops, calling eventBufferLoopBody() until after exit() has been called and isStoppable() becomes true.

defer

public void defer(Runnable x,
                  long milliseconds)

Can be used to defer a section of code on to the agent's event queue so that the code will execute in the agent's main thread. After it is done execution, it will interrupt the calling thread.

Parameters:

x - some Runnable to execute

milliseconds - the number of milliseconds (minimum) to wait before executing.

defer

public void defer(Runnable x)

Can be used to defer a section of code on to the agent's event queue so that the code will execute in the agent's main thread. After it is done execution, it will interrupt the calling thread.

Specified by:

defer in interface PolicyAgentInterface

Parameters:

x - some Runnable to execute

processCommitments

protected SocialCommitment processCommitments()

Subclasses will normally override this. It will be called whenever the agent is waiting around for an an event from an empty event queue. This method mearly returns false.

Returns:

true if it did something; false if it didn't.

isEventQueueReady

protected boolean isEventQueueReady()

Determines if the event queue has an event ready to process. Subclasses should override this method if they would like to pre-empt event dequeing in favour of processing a social commitment.

Returns:

eventQueuePeek

protected Event eventQueuePeek()

eventBufferLoopBody

protected void eventBufferLoopBody()

This method is called by eventBufferLoop() and may be overridden by a subclass as the actual code to dequeue messages off the queue. However, the subclass method is best off by calling super.eventBufferLoopBody() as part of it's implementation.
This implementation will

1. If there is an event in the event queue, process it (processCommitments()) and exit.
2. Otherwise if there are ready commitments, process one (processCommitments()) and exit.
3. Otherwise if there is still nothing in the event queue, wait to be interrupted (unless we are in exit state, then wait 500ms}).

isThisMyAddress

public boolean isThisMyAddress(URLDescriptor theURL)

processEvent

private void processEvent(Event event)

This method is a pre-processing step before the event from the event queue is passed passed on to handleEvent(Event) for actual processing event. In particular, message events require special processing:

1. the message is decoded if has been encoded for security
2. message events are dropped if isObserveMessages() is not true and the message is not addressed to this agent.
3. message events are dropped if they are not authorized according to authorizeMessage(MLMessage)
4. if this message is an exit message it's just dropped (part of how a casa agent ends)
5. notifyObservers() is called with parameters ML.EVENT_MESSAGE_RECEIVED and the message itself

So this method then calls handleEvent(Event) and if that returns

Parameters:

event - the event on the queue being processed

pauseCheck

private void pauseCheck()

Checks for the pause state and wait()'s until interuped if paused. The interupt will normally be called by a setPause(false) or a step().

isPaused

public boolean isPaused()

Determines if the agent is currently in the pause state.

Returns:

true iff the agent is currently in pause state (but could be active pending a processing the next message).

See Also:

setPause(boolean)

setPause

public void setPause(boolean val)

Set or clear the agent pausing immediately after processing the next message send or recieve. The agent can be resumed by passing false as the argument or by calling step().

Parameters:

val -

step

public void step()

If the agent is is the pause state, activates (resumes) the agent until processing the next sent or recieved message.

eventBufferLoopPeriodic

@Deprecated
protected void eventBufferLoopPeriodic()

Deprecated.

Called periodically from eventBufferLoopBody(). Subclasses may override to add fucntionality. This method does nothing.

unhandledMessage

protected void unhandledMessage(MLMessage message)

Subclasses may override this method to override default processing of unhandled messages. The default behaviour is just to log the unhandled message.

Parameters:

message - the unhandled message.

getUniqueRequestID

public String getUniqueRequestID()

Returns a unique string that can be conveniently used in the reply-with and in-reply-to fields of a message.

Specified by:

getUniqueRequestID in interface PolicyAgentInterface

Specified by:

getUniqueRequestID in interface ProcessInterface

Returns:

a unique String

getPort

public int getPort()

Returns the port that this agent is listening on.

Specified by:

getPort in interface ProcessInterface

Returns:

an int port number

closePort

public void closePort()

Method to close the module's open port and return it to the system.

Specified by:

closePort in interface ProcessInterface

hasOpenPort

public boolean hasOpenPort()

Tests if this process has any open ports.

Specified by:

hasOpenPort in interface ProcessInterface

Returns:

true if and only if the process has an open port; false otherwise.

addObserver

public void addObserver(Observer observer)

Part of the Observable interface from the observer pattern (Gamma et al.). Call to add an observer to this Observable's list of Observers. Observers will be notified by calling their update() method when this object. changes.

Specified by:

addObserver in interface ProcessInterface

Parameters:

observer - the Observer object to add.

addObserver

public void addObserver(URLDescriptor observer)

Extension to the Observable interface from the observer pattern (Gamma et al.). Call to add a remote agent observer to this Observable's list of remote Observers. Observers will be notified by send them an update() message when this object changes.

Specified by:

addObserver in interface ProcessInterface

Parameters:

observer - the Observer object to add.

deleteObserver

public void deleteObserver(Observer observer)

Part of the Observable interface from the observer pattern (Gamma et al.). Call to remove an observer from this object's list of observers.

Specified by:

deleteObserver in interface CasaObservable

Specified by:

deleteObserver in interface ProcessInterface

Parameters:

observer - the Observer object to delete from the list of observers

deleteObserver

public void deleteObserver(URLDescriptor observer)

Extension to the Observable interface from the observer pattern (Gamma et al.). Call to remove a remote observer from this object's list of remote observers.

Specified by:

deleteObserver in interface CasaObservable

Specified by:

deleteObserver in interface ProcessInterface

Parameters:

observer - the URL of the observer to delete from the list of observers

notifyObservers

public void notifyObservers(String eventType,
                            Object argument)

Specified by:

notifyObservers in interface CasaObservable

Specified by:

notifyObservers in interface PolicyAgentInterface

equals

public boolean equals(Object other)

Overrides:

equals in class Object

getNewMessage

public MLMessage getNewMessage(String performative,
                               String act,
                               URLDescriptor reciever)

Creates a basic message with the given performative, act, and reciever. Then it automatically adds sender, reply-with, and reply-by parameters to the message.

Specified by:

getNewMessage in interface ProcessInterface

Parameters:

performative - The performative of the new message.

act - The act of the new message.

reciever - The reciever of the new message.

Returns:

The new message with the given performative, act, and reciever and correct sender, reply-with, and reply-by fields.

getNewMessage

public MLMessage getNewMessage(String performative,
                               String act,
                               URLDescriptor reciever,
                               String... list)

Creates a basic message with the given performative, act, and reciever. Then it automatically adds sender, reply-with, and reply-by parameters to the message.

Parameters:

performative - The performative of the new message.

act - The act of the new message.

reciever - The reciever of the new message.

list - an array of strings: odd indicis are taken as keys and even as values

Returns:

The new message with the given performative, act, and reciever and correct sender, reply-with, and reply-by fields.

setTracing

public void setTracing(boolean doTrace)

Turn tracing on / off.

Specified by:

setTracing in interface ProcessInterface

Parameters:

doTrace - true to turn tracing on, false to turn tracing off

isTracing

public boolean isTracing()

Is tracing on?

Specified by:

isTracing in interface ProcessInterface

Returns:

true iff tracing is on

getTrace

public Trace getTrace()

get the associated Trace object. If isTracing() == true, then this is guaranteed non-null, otherwise, this may return null.

Specified by:

getTrace in interface ProcessInterface

Returns:

a reference to this agent's Trace object

isLoggingTag

public boolean isLoggingTag(String tag)

Returns true if the process is logging tag, tag is "error," or tag is null

Specified by:

isLoggingTag in interface AgentPrintInterface

Specified by:

isLoggingTag in interface PolicyAgentInterface

Specified by:

isLoggingTag in interface ProcessInterface

Specified by:

isLoggingTag in interface TraceInterface

Parameters:

tag - The tag in question of being traced or not.

Returns:

true if traceTags contains tag, false otherwise.

setUsePriority

public void setUsePriority(boolean newVal)

Set the use of message priorities.

Parameters:

newVal - true to use message queue priorities; false to use FIFO.

getUsePriority

public boolean getUsePriority()

Get the state of using message queue priorities.

Returns:

true if using message queue priorities; false if using FIFO

setObserveMessages

public void setObserveMessages(boolean newVal)

Set whether the agent will ignore or process messages that are not addressed to it (broadcaste messages never ignored).

Parameters:

newVal - true to have the agent process messages not addressed to it.

isObserveMessages

public boolean isObserveMessages()

Returns:

true iff the agent is processing messages not addressed to it.

startTraceMonitor

public void startTraceMonitor()

Display the trace monitor window. It will load with any history if trace is already on. If trace is off, it will be turned on.

Specified by:

startTraceMonitor in interface ProcessInterface

resetSecurityPackage

protected void resetSecurityPackage(String pack)

getEventQueue

protected String getEventQueue()

countObservers

public int countObservers()

Specified by:

countObservers in interface CasaObservable

deleteObservers

public void deleteObservers()

Specified by:

deleteObservers in interface CasaObservable

hasChanged

public boolean hasChanged()

Specified by:

hasChanged in interface CasaObservable

notifyObservers

public void notifyObservers()

Specified by:

notifyObservers in interface CasaObservable

notifyObserversWithTop

public void notifyObserversWithTop(Object arg)

Description copied from interface: CasaObservable

TOP is the notification type

Specified by:

notifyObserversWithTop in interface CasaObservable

Parameters:

arg - the argument to use

addObserver

public void addObserver(Observer o,
                        String... notifyTypes)

Specified by:

addObserver in interface CasaObservable

addObserver

public void addObserver(URLDescriptor observer,
                        String... notifyTypes)

Specified by:

addObserver in interface CasaObservable

notifyObserversWithNoArg

public void notifyObserversWithNoArg(String notifyType)

Description copied from interface: CasaObservable

Notify with no arguments

Specified by:

notifyObserversWithNoArg in interface CasaObservable

Parameters:

notifyType - the notification type to use

bump

public void bump()

wakes up the agent if it is sleeping waiting for an event to happen

Specified by:

bump in interface PolicyAgentInterface

update

public void update(Observable o,
                   Object arg)

Specified by:

update in interface Observer

makeSubthread

public Thread makeSubthread(Runnable runnable,
                            String name)

Creates a new thread in the same ThreadGroup as this agent, with the agent specified. Don't forget to call start() on the thread.

Parameters:

runnable - The runnable to execute.

name - The name of he new Thread.

Returns:

the new thread

makeSubthread

public Thread makeSubthread(Runnable runnable)

Creates a new thread in the same ThreadGroup as this agent, with the agent specified. Don't forget to call start() on the thread.

Parameters:

runnable - The runnable to execute.

Returns:

the new thread

getAgent

public static AbstractProcess getAgent()

compareTo

public int compareTo(AbstractProcess o)

Specified by:

compareTo in interface Comparable<AbstractProcess>

getChosenCommitment

protected abstract SocialCommitment getChosenCommitment()

hasActiveCommitments

protected abstract boolean hasActiveCommitments()

processCommitment

protected abstract SocialCommitment processCommitment(SocialCommitment sc)

setTraceTags

public int setTraceTags(String tags)

Description copied from interface: TraceInterface

Works the same as addTraceTags, but removes all previous tags beforehand.

Specified by:

setTraceTags in interface TraceInterface

Parameters:

tags - A command-delimited list of tags. White space is ignored.

Returns:

The number of tags inserted

removeTraceTags

public int removeTraceTags(String tags)

Description copied from interface: TraceInterface

Removes the tags in the comma-delimited streams specified in tags. Note that removeTraceTags("x,y") is equivalent to addTraceTags("-x,-y"). Unlike addTraceTags(String), the tag identifiers must appear alone, without the prefix "-" or the digit suffix.

Specified by:

removeTraceTags in interface TraceInterface

Parameters:

tags - The tags to be removed.

See Also:

TraceInterface.setTraceTags(String)

getTraceTags

public String getTraceTags()

Specified by:

getTraceTags in interface TraceInterface

Returns:

The current set of active trace tags as a comma-delimited String. Note that the "-" prefix does not appear, but the digit suffix may.

addTraceTags

public int addTraceTags(String tags)

Description copied from interface: TraceInterface

Adds a comma-delimited list of trace tags to a string. If any of tags are immediately preceded with a '-', those tags are removed instead. Eg: "a,-b,c,-d" will add a and c, and remove b and d. Whitespace before and after each tag is ignored. A tag can be any identifier-like string. You can also append a single digit (0-9) to indicate a higher level of detail (default = 0).

Specified by:

addTraceTags in interface TraceInterface

Parameters:

tags - a comma-delimited list of trace tags

Returns:

the number of tags processed (would be 4 in the above example)

println

public String println(String traceTag,
                      String txt,
                      Throwable ex,
                      int flags)

Description copied from interface: TraceInterface

This is the println method that defines all the other println methods. The following is printed/logged:

1. if the tag is error the message will be "bracketed" by a long string of ">"'s, if warning a medium string of ">"'s, if the #OPT_INCLUDE_CODE_LINE_NUMBER is in flags then so short string of ">"'s. In any of these cases, the ">"'s is followed by the guess of the calling source file and line number.
2. the record header.
3. the prefix, if it is set.
4. a stack trace if ex is non-null and #OPT_SUPRESS_STACK_TRACE is not set, or #OPT_FORCE_STACK_TRACE is set.
5. a matching closing string of "<"'s if we are bracketing with ">"'s.

The header is in the following format with no spaces:

 [* timestamp : agentName : tag : thread-name *] 
 

Specified by:

println in interface TraceInterface

Parameters:

traceTag - This tag MUST be present in set of traceTags for anything to be printed/logged.

txt - The message to be printed/logged.

ex - If this is non-null, the stack trace will be appended to the message

flags - The options flags; use bitwise disjunct ("|") to combine options - #OPT_SUPPRESS_AGENT_LOG, #OPT_COPY_TO_SYSERR, #OPT_COPY_TO_SYSOUT, #OPT_FORCE_STACK_TRACE, #OPT_INCLUDE_CODE_LINE_NUMBER, #OPT_SUPPRESS_HEADER_ON_SYSOUT, #OPT_SUPRESS_STACK_TRACE.

Returns:

The parameter txt

println

public String println(String traceTag,
                      String txt)

Debugging or error method: Uses the Trace object to log the string if appropriate (ie: the traceTAg matches a tag that's turned on in the Trace object.

Specified by:

println in interface AgentPrintInterface

Specified by:

println in interface PolicyAgentInterface

Specified by:

println in interface ProcessInterface

Specified by:

println in interface TraceInterface

Parameters:

traceTag - The txt String will be logged if the traceTag matches a tag that's turned on in the Trace object.

txt - The String to be logged

Returns:

The string actually printed to the log (without the time stamp) or null if nothing is printed because of the tracetag

See Also:

TraceInterface.println(String, String, Throwable, int)

println

public String println(String traceTag,
                      String txt,
                      Throwable ex)

Same as println(String, String) but appends ex.toString() and prints a stack trace after.

Specified by:

println in interface AgentPrintInterface

Specified by:

println in interface PolicyAgentInterface

Specified by:

println in interface ProcessInterface

Specified by:

println in interface TraceInterface

Parameters:

traceTag - The txt String will be logged if the traceTag matches a tag that's turned on in the Trace object.

txt - The String to be logged

ex - An Exception object

Returns:

The string actually printed to the log (without the time stamp) or null if nothing is printed because of the tracetag

See Also:

TraceInterface.println(String, String, Throwable, int)

println

@Deprecated
public String println(String traceTag,
                                  String txt,
                                  Status tempStatus)

Deprecated.

Same as println(String, String) but appends tempStatus.getExplanation().

Specified by:

println in interface AgentPrintInterface

Specified by:

println in interface PolicyAgentInterface

Specified by:

println in interface ProcessInterface

Parameters:

traceTag - The txt String will be logged if the traceTag matches a tag that's turned on in the Trace object.

txt - The String to be logged

tempStatus - A Status object

Returns:

The string actually printed to the log (without the time stamp) or null if nothing is printed because of the tracetag

println

public String println(String traceTag,
                      String txt,
                      int flags)

Description copied from interface: TraceInterface

Equivalent to println(tag, string, null, flag)

Specified by:

println in interface TraceInterface

flags - The options flags; use bitwise disjunct ("|") to combine options - #OPT_SUPPRESS_AGENT_LOG, #OPT_COPY_TO_SYSERR, #OPT_COPY_TO_SYSOUT, #OPT_FORCE_STACK_TRACE, #OPT_INCLUDE_CODE_LINE_NUMBER, #OPT_SUPPRESS_HEADER_ON_SYSOUT, #OPT_SUPRESS_STACK_TRACE.

Returns:

The parameter tag

See Also:

TraceInterface.println(String, String, Throwable, int)

setAllTraceTags

public void setAllTraceTags()

Description copied from interface: TraceInterface

Turns all ALL the trace tags.

Specified by:

setAllTraceTags in interface TraceInterface

clearAllTraceTags

public void clearAllTraceTags()

Description copied from interface: TraceInterface

Turns off ALL the trace tags.

Specified by:

clearAllTraceTags in interface TraceInterface