aos.jack.jak.agent
Class Agent

java.lang.Object
  aos.jack.jak.scheduler.Executee
      aos.jack.jak.agent.Agent

public class Agent

extends Executee

The Agent class is the primary base class for JACK agents. It provides the core implementation for dealing with events, messages, and tasks.

Field Summary

ThreadPool	thread_pool The default thread pool for this agent.
Timer	timer The default timer for this agent.

Constructor Summary

Agent(java.lang.String n)
Constructs an agent with a given name.

Method Summary

protected void	__init1() Support for agent constructor methods.
protected void	__init2() Support for agent constructor methods.
protected void	addToDo(aos.jack.jak.agent.ToDo tdo)
aos.jack.jak.agent.WaitFor	addWaitFor(aos.jack.jak.agent.WaitForClient inform, aos.jack.jak.core.Generator g, Cursor c, boolean b)
aos.jack.jak.agent.WaitFor	addWaitFor(aos.jack.jak.agent.WaitForClient inform, aos.jack.jak.core.Generator g, int ind, boolean b)
void	bug(java.lang.String n) Prints a string with agent identification.
void	changeFocus() Forces a thread context switch away from this agent.
java.lang.String	describeState() Dumps a text description of the current state of the agent.
void	discardReplies(MessageEvent e) Discards any pending replies for a message.
void	dump() Dumps a verbose text description of the agent's state to System.err.
void	dump(java.io.PrintWriter w) Dumps a verbose text description of the agent's state to a PrintWriter.
void	dumpPlans(java.io.PrintWriter pw) Dumps a text description of all plans available in the agent and the events they handle.
java.lang.String	dumpToString() Returns a verbose text description of the agent's state.
static Agent	findLocalAgent(java.lang.String name) Looks up a named agent at the local portal.
void	finish() Upon calling this method, the agent's plan processing will stop after the next plan step and the agent will no longer receive messages.
Agent	getAgent() Returns this agent instance.
java.lang.String	getBasename() Returns the basename of the agent.
static Agent	getCurrentAgent() Get the agent that is currently executing in the current thread.
aos.jack.jak.task.Task	getCurrentTask() Return the Task currently being executed by the agent.
Event[]	getKnownEvents() Returns an array of known Events loaded in the agent.
Plan[]	getKnownPlans() Returns an array of known plans loaded in the agent.
java.lang.String	getName() Returns the name of the agent.
java.util.Observable	getObservable() Returns an Observable which will be notified when any change occurs in the agent.
MessageEvent	getReply(MessageEvent e) Gets the first pending reply for the specified message.
TaskManager	getTaskManager() Return the current TaskManager (tasks).
AgentInfo	getTraceableInfo(TraceableBase b)
static boolean	inAgent() A method to determine if some Java code is executing within the context of an agent.
void	initialize(InitialData data) A convenience hook for agent initialisation.
boolean	isBlocked(aos.jack.jak.task.Task in) Determines if the given task is blocked (in this agent).
boolean	isIdle() Determine is the agent has nothing to do -- no messages or events to process and no runnable tasks.
java.lang.String	name() Returns the name of the agent.
int	nEvents()
int	nMessages()
int	nTasks()
int	nTodo()
void	postEvent(Event e) This method is used to tell the agent to handle a new event.
boolean	postEventAndWait(Event e) This method is used to tell the agent to handle a new event.
void	process()
protected void	processEvent(Event ev)
protected void	processMessage(Message cur)
protected void	processTask(aos.jack.jak.task.Task tsk)
protected void	processToDo(aos.jack.jak.agent.ToDo cur)
Cursor	replied(MessageEvent e) Returns a cursor which will be triggered and return true when a reply to the message is available.
void	reply(MessageEvent r, MessageEvent e) Sends a reply message (e) to a received message (r).
void	restartIfIdle()
protected void	rmToDo(aos.jack.jak.agent.ToDo tdo)
void	rmWaitFor(aos.jack.jak.agent.WaitFor o)
void	send(java.lang.String to, Message e) Sends a Message to the named agent.
void	send(java.lang.String to, MessageEvent e) Sends a MessageEvent to the named agent.
protected void	startAgent() Starts the agent's event processing.
java.lang.String	toString() Returns the name of the agent class together with the agent name.
void	trigger(java.lang.Object o, int n)
void	warning(java.lang.String n) Prints a string with agent identification.

Methods inherited from class aos.jack.jak.scheduler.Executee

isPaused, remove, run, stop

Methods inherited from class java.lang.Object

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

Field Detail

timer

public Timer timer

The default timer for this agent. By default, this is RTClock.timer

thread_pool

public ThreadPool thread_pool

The default thread pool for this agent.

Constructor Detail

Agent

public Agent(java.lang.String n)

Constructs an agent with a given name. The constructor is given the local name of the agent, and this is extended with the portal name, separated by an "@" character, to form the agent's full name. The constructor also invokes the chain of data structure building methods, loading all capabilities, databases, events and plans for the agent.

Method Detail

nEvents

public int nEvents()

nMessages

public int nMessages()

nTasks

public int nTasks()

nTodo

public int nTodo()

getTaskManager

public TaskManager getTaskManager()

Return the current TaskManager (tasks).

getName

public java.lang.String getName()

Returns the name of the agent. The name returned is the agent's full name, which consists of both the declared name and the portal name, separated by an "@" character.

Overrides:

getName in class Executee

name

public java.lang.String name()

Returns the name of the agent. The name returned is the agent's full name, which consists of both the declared name and the portal name, separated by an "@" character. It is identical to getName() but is here for backwards compatability

Overrides:

name in class Executee

getBasename

public java.lang.String getBasename()

Returns the basename of the agent. I.e simply the agents name without portal address

findLocalAgent

public static Agent findLocalAgent(java.lang.String name)

Looks up a named agent at the local portal. This method looks up the given name as an addressable at the default portal. If the named Addressable is an Agent, that it is returned, otherwise the method returns null. Note that the given name should not include a portal name suffix.

startAgent

protected void startAgent()

Starts the agent's event processing. The JACK compiler lays out a call to the startAgent() method as part of the generated agent's constructor. Derived agent code may override this method to add additional initialisation behaviour, but must then make sure to also invoke super.startAgent().

warning

public void warning(java.lang.String n)

Prints a string with agent identification. This is a convenience method that prints the given warning string together with the agent's full name.

bug

public void bug(java.lang.String n)

Prints a string with agent identification. This is a convenience method that prints the given bug string together with the agent's full name and a stack trace

finish

public void finish()

Upon calling this method, the agent's plan processing will stop after the next plan step and the agent will no longer receive messages.

__init1

protected void __init1()

Support for agent constructor methods. Can be called by a derived type during their construction to do first phase initialization (events, data, etc.).

__init2

protected void __init2()

Support for agent constructor methods. Can be called by a derived type during their construction to do second phase initialization (plans).

changeFocus

public void changeFocus()

Forces a thread context switch away from this agent. Upon completion of the current plan step, the agent will release the processing thread for dealing with other agents.

restartIfIdle

public void restartIfIdle()

isBlocked

public boolean isBlocked(aos.jack.jak.task.Task in)

Determines if the given task is blocked (in this agent).

addToDo

protected void addToDo(aos.jack.jak.agent.ToDo tdo)

rmToDo

protected void rmToDo(aos.jack.jak.agent.ToDo tdo)

replied

public Cursor replied(MessageEvent e)

Returns a cursor which will be triggered and return true when a reply to the message is available. It will return null if the message has not been sent.

getReply

public MessageEvent getReply(MessageEvent e)

Gets the first pending reply for the specified message. This will return null if the message has not been sent or if there are no pending replies.

discardReplies

public void discardReplies(MessageEvent e)

Discards any pending replies for a message.

processToDo

protected void processToDo(aos.jack.jak.agent.ToDo cur)

processMessage

protected void processMessage(Message cur)

processEvent

protected void processEvent(Event ev)

processTask

protected void processTask(aos.jack.jak.task.Task tsk)

isIdle

public boolean isIdle()

Determine is the agent has nothing to do -- no messages or events to process and no runnable tasks. It may have blocked tasks and

process

public void process()

inAgent

public static boolean inAgent()

A method to determine if some Java code is executing within the context of an agent. This uses getCurrentAgent().

getCurrentTask

public aos.jack.jak.task.Task getCurrentTask()

Return the Task currently being executed by the agent.

getCurrentAgent

public static Agent getCurrentAgent()

Get the agent that is currently executing in the current thread. This will return null if there isn't one executing in the current thread when the call is made.

postEventAndWait

public boolean postEventAndWait(Event e)

This method is used to tell the agent to handle a new event. The event is handled synchronously by the agent. This method returns true if the task that the agent performs to handle the event succeeds or false if it fails. Note: Unlike most other agent methods, this method must not be called from any of an agent's tasks. It can only be used from methods used by normal Java programs that are integrated with the JACK application.

postEvent

public void postEvent(Event e)

This method is used to tell the agent to handle a new event. The event is handled asynchronously by the agent. This method does not return a result as a separate task is executed to handle posted events.

addWaitFor

public aos.jack.jak.agent.WaitFor addWaitFor(aos.jack.jak.agent.WaitForClient inform,
                                             aos.jack.jak.core.Generator g,
                                             int ind,
                                             boolean b)

addWaitFor

public aos.jack.jak.agent.WaitFor addWaitFor(aos.jack.jak.agent.WaitForClient inform,
                                             aos.jack.jak.core.Generator g,
                                             Cursor c,
                                             boolean b)

rmWaitFor

public void rmWaitFor(aos.jack.jak.agent.WaitFor o)

reply

public void reply(MessageEvent r,
                  MessageEvent e)

Sends a reply message (e) to a received message (r).

send

public void send(java.lang.String to,
                 MessageEvent e)

Sends a MessageEvent to the named agent. If the agent is in a different process, the full name is required, otherwise the short name is sufficient.

send

public void send(java.lang.String to,
                 Message e)

Sends a Message to the named agent.

getAgent

public Agent getAgent()

Returns this agent instance.

initialize

public void initialize(InitialData data)

A convenience hook for agent initialisation. Apart from the call made by aos.jack.Kernel.createAgent, this method is not used by JACK, but provided as generic support for agent initialisation.

toString

public java.lang.String toString()

Returns the name of the agent class together with the agent name.

dumpToString

public java.lang.String dumpToString()

Returns a verbose text description of the agent's state.

dump

public void dump()

Dumps a verbose text description of the agent's state to System.err.

dump

public void dump(java.io.PrintWriter w)

Dumps a verbose text description of the agent's state to a PrintWriter.

getKnownPlans

public Plan[] getKnownPlans()

Returns an array of known plans loaded in the agent.

getKnownEvents

public Event[] getKnownEvents()

Returns an array of known Events loaded in the agent.

getObservable

public java.util.Observable getObservable()

Returns an Observable which will be notified when any change occurs in the agent.

trigger

public void trigger(java.lang.Object o,
                    int n)

getTraceableInfo

public AgentInfo getTraceableInfo(TraceableBase b)

dumpPlans

public void dumpPlans(java.io.PrintWriter pw)

Dumps a text description of all plans available in the agent and the events they handle. It also lists the reasoning methods in the plans.

describeState

public java.lang.String describeState()

Dumps a text description of the current state of the agent.

Overrides:

describeState in class Executee