JACK 5.4 Application Interface

aos.jack.jak.agent
Class Agent

java.lang.Object
  extended byaos.jack.jak.scheduler.Executee
      extended byaos.jack.jak.agent.Agent
Direct Known Subclasses:
SimAgent, SimEngine, TimeFlowManager, Updater

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 context switch away from this agent.
static void describeAllAgents(java.io.PrintStream out)
          Dump the current state of each agent to the given PrintStream.
 java.lang.String describeState()
          Dumps a text description of the current state of the agent.
 void discardAllTasks()
          This will discard the all the agent's tasks.
 void discardOtherTasks()
          This will discard all the agent's tasks except the one currently running.
 void discardReplies(MessageEvent e)
          Discards any pending replies for the given message event.
 void dump()
          Dumps a verbose text description of the agent's state to System.err.
 void dump(java.io.PrintStream out)
          Dumps a verbose text description of the agent's state to the given java.io.PrintStream.
 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, which is the local name given on construction.
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 full name of the agent, which consists of both the local name supplied on construction and the name of the portal on which it was created, separated by an "@" character.
 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()
          Determines if the agent has nothing to do -- no messages or events to process and no runnable tasks.
 java.lang.String name()
          Deprecated.
 int nEvents()
          Returns the number of pending events.
 int nMessages()
          Returns the number of pending messages.
 int nTasks()
          Returns the number of active tasks.
 int nTodo()
          Returns the number of things in the agent's "todo" list.
 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()
          Forces the agent to unblock from an IDLE state.
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 ful 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()
Returns the number of pending events.


nMessages

public int nMessages()
Returns the number of pending messages.


nTasks

public int nTasks()
Returns the number of active tasks.


nTodo

public int nTodo()
Returns the number of things in the agent's "todo" list. These take priority over events and messages.


getTaskManager

public TaskManager getTaskManager()
Return the current TaskManager (tasks).


getName

public java.lang.String getName()
Returns the full name of the agent, which consists of both the local name supplied on construction and the name of the portal on which it was created, separated by an "@" character. E.g. "agent@portal".

Overrides:
getName in class Executee

name

public java.lang.String name()
Deprecated. Returns the name of the agent as defined by getName(). It is retained for backwards compatability.

Overrides:
name in class Executee

getBasename

public java.lang.String getBasename()
Returns the basename of the agent, which is the local name given on construction. This does not include any information about the portal on which the agent was created.


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 must 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 context switch away from this agent. Upon completion of the current plan step, the agent will release the processing thread which will enable other agents to progress or allow the current agent to reconsider what it should be doing when it starts executing again.


restartIfIdle

public void restartIfIdle()
Forces the agent to unblock from an IDLE state. This is intended for extended task manager handling of opaque queues (e.g. for CoJack).


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 a FalseCursor() 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 the given message event.


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()
Determines if the agent has nothing to do -- no messages or events to process and no runnable tasks. Note: it may have blocked tasks and @wait_for's that have not triggered yet. This will also return true if finish() has been called on the agent.


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 should only be used from methods that are not run within the context of an Agent.


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. A new task is spawned to handle the posted event.


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


discardAllTasks

public void discardAllTasks()
This will discard the all the agent's tasks. After calling this, the agent will be idle. This should be called with care!


discardOtherTasks

public void discardOtherTasks()
This will discard all the agent's tasks except the one currently running. This should be called with care!


describeAllAgents

public static void describeAllAgents(java.io.PrintStream out)
Dump the current state of each agent to the given PrintStream.


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 ful 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.PrintStream out)
Dumps a verbose text description of the agent's state to the given java.io.PrintStream.


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

JACK 5.4 Application Interface

Copyright (C) 1999-2008, Agent Oriented Software Pty. Ltd.

US Government Restricted Rights
The JACK Modules and relevant Software Material have been developed entirely at private expense and are accordingly provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of DFARS 252.227-7013 or subparagraph (c)(1) and (2) of the Commercial Computer Software Restricted Rights and 48 CFR 52.2270-19, as applicable.


Agent Oriented Software Pty. Ltd.     http://www.aosgrp.com
PO Box 639, Carlton South, Victoria 3053, Australia
Phone: +61 3 9349 5055, Fax: +61 3 9349 5088