jade.core
Class Agent

java.lang.Object
  jade.core.Agent

All Implemented Interfaces:

Runnable, Serializable, jade.util.leap.Serializable, jade.core.TimerListener

public class Agent

extends Object

implements Runnable, jade.util.leap.Serializable, jade.core.TimerListener

The Agent class is the common superclass for user defined software agents. It provides methods to perform basic agent tasks, such as:

• Message passing using ACLMessage objects, both unicast and multicast with optional pattern matching.
• Complete Agent Platform life cycle support, including starting, suspending and killing an agent.
• Scheduling and execution of multiple concurrent activities.
• Simplified interaction with FIPA system agents for automating common agent tasks (DF registration, etc.).

Application programmers must write their own agents as Agent subclasses, adding specific behaviours as needed and exploiting Agent class capabilities.

Version:

$Date: 2006-04-13 16:57:28 +0200 (Thu, 13 Apr 2006) $ $Revision: 1.1 $

Author:

Giovanni Rimassa - Universita' di Parma

See Also:

Serialized Form

Nested Class Summary

private class	Agent.AgentDeathError
private static class	Agent.AgentInMotionError
private class	Agent.AssociationTB
private static class	Agent.CondVar
private static class	Agent.TBPair

Field Summary

static int	AP_ACTIVE Represents the active agent state.
static int	AP_COPY Represents the copy agent state.
static int	AP_DELETED Represents the deleted agent state.
(package private) static int	AP_FROZEN Represents the frozen agent state.
(package private) static int	AP_GONE Represents the gone agent state.
static int	AP_IDLE Represents the idle agent state.
static int	AP_INITIATED Represents the initiated agent state.
static int	AP_MAX Out of band value for Agent Platform Life Cycle states.
static int	AP_MIN Out of band value for Agent Platform Life Cycle states.
(package private) static int	AP_RELOADING Represents the loading agent state.
(package private) static int	AP_SAVING Represents the saving agent state.
static int	AP_SUSPENDED Represents the suspended agent state.
static int	AP_TRANSIT Represents the transit agent state.
static int	AP_WAITING Represents the waiting agent state.
private Object[]	arguments
protected jade.core.behaviours.Behaviour	currentBehaviour The Behaviour that is currently executing.
protected jade.lang.acl.ACLMessage	currentMessage Last message received.
static int	D_ACTIVE Represents the active agent state.
static int	D_MAX Out of band value for Domain Life Cycle states.
static int	D_MIN Out of band value for Domain Life Cycle states.
static int	D_RETIRED Represents the retired agent state.
static int	D_SUSPENDED Represents the suspended agent state.
static int	D_UNKNOWN Represents the unknown agent state.
private boolean	generateBehaviourEvents When set to false (default) all behaviour-related events (such as ADDED_BEHAVIOUR or CHANGED_BEHAVIOUR_STATE) are not generated in order to improve performances.
private Hashtable	helpersTable
private int	messageCounter
private jade.core.MessageQueue	msgQueue
private int	msgQueueMaxSize
private jade.core.AID	myAID
private int	myAPState
private jade.core.ContainerID	myBufferContainer
private int	myBufferedState
private jade.wrapper.AgentContainer	myContainer Declared transient because the container changes in case of agent migration.
private jade.core.Location	myDestination
private String	myHap
private String	myName
private String	myNewName
private String	myRepository
private jade.core.Scheduler	myScheduler
private Thread	myThread
private AgentToolkit	myToolkit
private jade.util.leap.Map	o2aLocks
private jade.util.leap.List	o2aQueue
private int	o2aQueueSize
private Agent.AssociationTB	pendingTimers
private Long	persistentID
private Set	persistentPendingTimers
private static long	serialVersionUID
private Object	stateLock
private Object	suspendLock
private boolean	terminating This flag is used to distinguish the normal AP_ACTIVE state from the particular case in which the agent state is set to AP_ACTIVE during agent termination to allow it to deregister with the AMS.
private jade.content.ContentManager	theContentManager
private TimerDispatcher	theDispatcher

Constructor Summary

	Agent() Default constructor.
(package private)	Agent(jade.core.AID id) Constructor to be used by special "agents" that will never powerUp.

Method Summary

private void	activateAllBehaviours()
void	addBehaviour(jade.core.behaviours.Behaviour b) This method adds a new behaviour to the agent.
(package private) void	addPlatformAddress(String address) This method adds a new platform address to the AID of this Agent.
protected void	afterClone() Actions to perform after cloning.
protected void	afterLoad() Actions to perform after loading an agent.
protected void	afterMove() Actions to perform after moving.
protected void	afterReload() Actions to perform after reloading.
protected void	afterThaw() Actions to perform after thawing.
protected void	beforeClone() This empty placeholder method shall be overridden by user defined agents to execute some actions before copying an agent to another agent container.
protected void	beforeFreeze() Actions to perform before freezing.
protected void	beforeMove() This empty placeholder shall be overridden by user defined agents to execute some actions before the original agent instance on the source container is stopped (e.g.
protected void	beforeReload() Actions to perform before reloading.
protected void	beforeSave() Actions to perform before saving an agent.
jade.lang.acl.ACLMessage	blockingReceive() Receives an ACL message from the agent message queue.
jade.lang.acl.ACLMessage	blockingReceive(long millis) Receives an ACL message from the agent message queue, waiting at most a specified amount of time.
jade.lang.acl.ACLMessage	blockingReceive(jade.lang.acl.MessageTemplate pattern) Receives an ACL message matching a given message template.
jade.lang.acl.ACLMessage	blockingReceive(jade.lang.acl.MessageTemplate pattern, long millis) Receives an ACL message matching a given message template, waiting at most a specified time.
private void	changeStateTo(int state)
private void	destroy()
void	doActivate() Make a state transition from suspended to active or waiting (whichever state the agent was in when doSuspend() was called) within Agent Platform Life Cycle.
void	doClone(jade.core.Location destination, String newName) Make a state transition from active to copy within Agent Platform Life Cycle.
void	doDelete() Make a state transition from active, suspended or waiting to deleted state within Agent Platform Life Cycle, thereby destroying the agent.
(package private) void	doExecute() Make a state transition from transit or copy to active within Agent Platform Life Cycle.
(package private) void	doGone() Make a state transition from transit to gone state.
void	doMove(jade.core.Location destination) Make a state transition from active to transit within Agent Platform Life Cycle.
void	doSuspend() Make a state transition from active or waiting to suspended within Agent Platform Life Cycle; the original agent state is saved and will be restored by a doActivate() call.
void	doTimeOut(jade.core.Timer t) Restarts the behaviour associated with t.
void	doWait() Make a state transition from active to waiting within Agent Platform Life Cycle.
void	doWait(long millis) Make a state transition from active to waiting within Agent Platform Life Cycle.
void	doWake() Make a state transition from waiting to active within Agent Platform Life Cycle.
jade.core.AgentState	getAgentState()
jade.core.AID	getAID() Method to query the private Agent ID.
jade.core.AID	getAMS() Get the Agent ID for the platform AMS.
protected Object[]	getArguments() Get the array of arguments passed to this agent.
private Set	getBehaviours()
private int	getBufferedState()
jade.wrapper.AgentContainer	getContainerController() Return a controller for this agents container.
jade.content.ContentManager	getContentManager() Retrieves the agent's content manager
int	getCurQueueSize() This method retrieves the current lenght of the message queue of this agent.
jade.core.AID	getDefaultDF() Get the Agent ID for the platform default DF.
private boolean	getGenerateBehaviourEvents()
String	getHap() Method to query the Home Agent Platform.
jade.core.ServiceHelper	getHelper(String serviceName) Retrieves the agent's service helper
String	getLocalName() Method to query the agent local name.
(package private) jade.core.MessageQueue	getMessageQueue() This is only called by the RealNotificationManager to provide the Introspector agent with a snapshot of the messages currently pending in the queue and by the RealMobilityManager to transfer messages in the queue
String	getName() Method to query the agent complete name (GUID).
Object	getO2AObject() This method picks an object (if present) from the internal object-to-agent communication queue.
private Set	getPendingTimers()
private Long	getPersistentID()
String	getProperty(String key, String aDefault) Retrieve a configuration property set in the Profile of the local container (first) or as a System property.
int	getQueueSize() Reads message queue size.
(package private) jade.core.Scheduler	getScheduler() This is only called by the RealNotificationManager to provide the Introspector agent with a snapshot of the behaviours currently loaded in the agent
int	getState() Read current agent state.
private boolean	getTerminating()
jade.core.Location	here() Method to retrieve the location this agent is currently at.
(package private) void	idle()
private void	interruptThread() This method is used to interrupt the agent's thread.
(package private) void	join() This is used by the agent container to wait for agent termination.
private void	mainLoop()
(package private) void	notifyAddBehaviour(jade.core.behaviours.Behaviour b)
void	notifyChangeBehaviourState(jade.core.behaviours.Behaviour b, String from, String to)
private void	notifyChangedAgentState(int oldState, int newState)
private void	notifyCopy()
private void	notifyDestruction()
private void	notifyFreeze()
private void	notifyMove()
private void	notifyPosted(jade.lang.acl.ACLMessage msg)
private void	notifyReceived(jade.lang.acl.ACLMessage msg)
private void	notifyReload()
(package private) void	notifyRemoveBehaviour(jade.core.behaviours.Behaviour b)
void	notifyRestarted(jade.core.behaviours.Behaviour b) Notifies this agent that one of its behaviours has been restarted for some reason.
private void	notifySave()
private void	notifySend(jade.lang.acl.ACLMessage msg)
private void	notifyStarted()
void	postMessage(jade.lang.acl.ACLMessage msg) Put a received message into the agent message queue.
void	powerUp(jade.core.AID id, Thread t)
void	putBack(jade.lang.acl.ACLMessage msg) Puts a received ACL message back into the message queue.
void	putO2AObject(Object o, boolean blocking) This method should not be used by application code.
private void	readObject(ObjectInputStream in)
jade.lang.acl.ACLMessage	receive() Receives an ACL message from the agent message queue.
jade.lang.acl.ACLMessage	receive(jade.lang.acl.MessageTemplate pattern) Receives an ACL message matching a given template.
void	removeBehaviour(jade.core.behaviours.Behaviour b) This method removes a given behaviour from the agent.
(package private) void	removePlatformAddress(String address) This method removes an old platform address from the AID of this Agent.
void	requestFreeze(String repository, jade.core.ContainerID bufferContainer)
void	requestReload(String repository)
void	requestSave(String repository)
(package private) void	resetToolkit()
void	restartLater(jade.core.behaviours.Behaviour b, long millis) Schedules a restart for a behaviour, after a certain amount of time has passed.
void	restore(InputStream s) This method reads a previously saved agent, replacing the current state of this agent with the one previously saved.
void	run() This method is the main body of every agent.
void	send(jade.lang.acl.ACLMessage msg) Send an ACL message to another agent.
(package private) void	setAID(jade.core.AID id)
void	setArguments(Object[] args) Called by AgentContainerImpl in order to pass arguments to a just created Agent.
private void	setBehaviours(Set behaviours)
private void	setBufferedState(int bs)
void	setEnabledO2ACommunication(boolean enabled, int queueSize) This method declares this agent attitude towards object-to-agent communication, that is, whether the agent accepts to communicate with other non-JADE components living within the same JVM.
void	setGenerateBehaviourEvents(boolean b)
private void	setMessageQueue(jade.core.MessageQueue mq)
private void	setPendingTimers(Set timers)
private void	setPersistentID(Long l)
void	setQueueSize(int newSize) Set message queue size.
private void	setState(int state)
private void	setTerminating(boolean b)
void	setToolkit(AgentToolkit at)
protected void	setup() This protected method is an empty placeholder for application specific startup code.
protected void	takeDown() This protected method is an empty placeholder for application specific cleanup code.
(package private) void	waitOn(Object lock, long millis) Since in MIDP Thread.interrupt() does not exist and a simulated interruption is used to "interrupt" the agent's thread, we must check whether the simulated interruption happened just before and after going to sleep.
private void	waitUntilActivate()
void	waitUntilStarted() This method blocks until the agent has finished its start-up phase (i.e.
private void	waitUntilWake(long millis)
void	write(OutputStream s) Write this agent to an output stream; this method can be used to record a snapshot of the agent state on a file or to send it through a network connection.
private void	writeObject(ObjectOutputStream out)

Methods inherited from class java.lang.Object

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

Field Detail

serialVersionUID

private static final long serialVersionUID

See Also:

Constant Field Values

AP_MIN

public static final int AP_MIN

Out of band value for Agent Platform Life Cycle states.

See Also:

Constant Field Values

AP_INITIATED

public static final int AP_INITIATED

Represents the initiated agent state.

See Also:

Constant Field Values

AP_ACTIVE

public static final int AP_ACTIVE

Represents the active agent state.

See Also:

Constant Field Values

AP_IDLE

public static final int AP_IDLE

Represents the idle agent state.

See Also:

Constant Field Values

AP_SUSPENDED

public static final int AP_SUSPENDED

Represents the suspended agent state.

See Also:

Constant Field Values

AP_WAITING

public static final int AP_WAITING

Represents the waiting agent state.

See Also:

Constant Field Values

AP_DELETED

public static final int AP_DELETED

Represents the deleted agent state.

See Also:

Constant Field Values

AP_TRANSIT

public static final int AP_TRANSIT

Represents the transit agent state.

See Also:

Constant Field Values

AP_COPY

public static final int AP_COPY

Represents the copy agent state.

See Also:

Constant Field Values

AP_GONE

static final int AP_GONE

Represents the gone agent state. This is the state the original instance of an agent goes into when a migration transaction successfully commits.

See Also:

Constant Field Values

AP_SAVING

static final int AP_SAVING

Represents the saving agent state. This is the state an agent goes into when its actual storage within a persistent data repository takes place.

See Also:

Constant Field Values

AP_RELOADING

static final int AP_RELOADING

Represents the loading agent state. This is the state an agent goes into when its current state is about to be replaced with a new one retrieved from a persistent data repository.

See Also:

Constant Field Values

AP_FROZEN

static final int AP_FROZEN

Represents the frozen agent state. This is similar to the suspended state, but the agent is actually removed from its container and kept on a persistent store.

See Also:

Constant Field Values

AP_MAX

public static final int AP_MAX

Out of band value for Agent Platform Life Cycle states.

See Also:

Constant Field Values

D_MIN

public static final int D_MIN

Out of band value for Domain Life Cycle states.

See Also:

Constant Field Values

D_ACTIVE

public static final int D_ACTIVE

Represents the active agent state.

See Also:

Constant Field Values

D_SUSPENDED

public static final int D_SUSPENDED

Represents the suspended agent state.

See Also:

Constant Field Values

D_RETIRED

public static final int D_RETIRED

Represents the retired agent state.

See Also:

Constant Field Values

D_UNKNOWN

public static final int D_UNKNOWN

Represents the unknown agent state.

See Also:

Constant Field Values

D_MAX

public static final int D_MAX

Out of band value for Domain Life Cycle states.

See Also:

Constant Field Values

msgQueueMaxSize

private int msgQueueMaxSize

msgQueue

private transient jade.core.MessageQueue msgQueue

o2aQueue

private transient jade.util.leap.List o2aQueue

o2aQueueSize

private int o2aQueueSize

o2aLocks

private transient jade.util.leap.Map o2aLocks

myToolkit

private transient AgentToolkit myToolkit

myName

private String myName

myAID

private jade.core.AID myAID

myHap

private String myHap

stateLock

private transient Object stateLock

suspendLock

private transient Object suspendLock

myThread

private transient Thread myThread

theDispatcher

private transient TimerDispatcher theDispatcher

myScheduler

private jade.core.Scheduler myScheduler

pendingTimers

private transient Agent.AssociationTB pendingTimers

messageCounter

private int messageCounter

currentBehaviour

protected jade.core.behaviours.Behaviour currentBehaviour

The Behaviour that is currently executing.

See Also:

Behaviour

currentMessage

protected jade.lang.acl.ACLMessage currentMessage

Last message received.

See Also:

ACLMessage

myAPState

private volatile int myAPState

terminating

private boolean terminating

This flag is used to distinguish the normal AP_ACTIVE state from the particular case in which the agent state is set to AP_ACTIVE during agent termination to allow it to deregister with the AMS. In this case in fact a call to doDelete(), doMove(), doClone() and doSuspend() should have no effect.

generateBehaviourEvents

private boolean generateBehaviourEvents

When set to false (default) all behaviour-related events (such as ADDED_BEHAVIOUR or CHANGED_BEHAVIOUR_STATE) are not generated in order to improve performances. These events in facts are very frequent.

myDestination

private transient jade.core.Location myDestination

myNewName

private transient String myNewName

myRepository

private transient String myRepository

myBufferContainer

private transient jade.core.ContainerID myBufferContainer

myBufferedState

private int myBufferedState

persistentID

private Long persistentID

myContainer

private transient jade.wrapper.AgentContainer myContainer

Declared transient because the container changes in case of agent migration.

arguments

private transient Object[] arguments

theContentManager

private jade.content.ContentManager theContentManager

helpersTable

private transient Hashtable helpersTable

persistentPendingTimers

private transient Set persistentPendingTimers

Constructor Detail

Agent

public Agent()

Default constructor.

Agent

Agent(jade.core.AID id)

Constructor to be used by special "agents" that will never powerUp.

Method Detail

restartLater

public void restartLater(jade.core.behaviours.Behaviour b,
                         long millis)

Schedules a restart for a behaviour, after a certain amount of time has passed.

Parameters:

b - The behaviour to restart later.

millis - The amount of time to wait before restarting b.

See Also:

Behaviour.block(long millis)

doTimeOut

public void doTimeOut(jade.core.Timer t)

Restarts the behaviour associated with t. This method runs within the time-critical Timer Dispatcher thread and is not intended to be called by users. It is defined public only because is part of the TimerListener interface.

Specified by:

doTimeOut in interface jade.core.TimerListener

notifyRestarted

public void notifyRestarted(jade.core.behaviours.Behaviour b)

Notifies this agent that one of its behaviours has been restarted for some reason. This method clears any timer associated with behaviour object b, and it is unneeded by application level code. To explicitly schedule behaviours, use block() and restart() methods.

Parameters:

b - The behaviour object which was restarted.

See Also:

Behaviour.restart()

getAMS

public final jade.core.AID getAMS()

Get the Agent ID for the platform AMS.

Returns:

An AID object, that can be used to contact the AMS of this platform.

getDefaultDF

public final jade.core.AID getDefaultDF()

Get the Agent ID for the platform default DF.

Returns:

An AID object, that can be used to contact the default DF of this platform.

setTerminating

private void setTerminating(boolean b)

getTerminating

private boolean getTerminating()

getPersistentID

private Long getPersistentID()

setPersistentID

private void setPersistentID(Long l)

getContainerController

public final jade.wrapper.AgentContainer getContainerController()

Return a controller for this agents container.
NOT available in MIDP

Returns:

jade.wrapper.AgentContainer The proxy container for this agent.

setArguments

public final void setArguments(Object[] args)

Called by AgentContainerImpl in order to pass arguments to a just created Agent.

Usually, programmers do not need to call this method in their code.

See Also:

how to get the arguments passed to an agent

getArguments

protected Object[] getArguments()

Get the array of arguments passed to this agent.

Take care that the arguments are transient and they do not migrate with the agent neither are cloned with the agent!

Returns:

the array of arguments passed to this agent.

See Also:

How to use arguments or properties to configure your agent.

getLocalName

public final String getLocalName()

Method to query the agent local name.

Returns:

A String containing the local agent name (e.g. peter).

getName

public final String getName()

Method to query the agent complete name (GUID).

Returns:

A String containing the complete agent name (e.g. peter@fipa.org:50).

getAID

public final jade.core.AID getAID()

Method to query the private Agent ID. Note that this Agent ID is different from the one that is registered with the platform AMS.

Returns:

An Agent ID object, containing the complete agent GUID, addresses and resolvers.

setAID

void setAID(jade.core.AID id)

addPlatformAddress

void addPlatformAddress(String address)

This method adds a new platform address to the AID of this Agent. It is called by the container when a new MTP is activated in the platform (in the local container - installMTP() - or in a remote container - updateRoutingTable()) to keep the Agent AID updated.

removePlatformAddress

void removePlatformAddress(String address)

This method removes an old platform address from the AID of this Agent. It is called by the container when a new MTP is deactivated in the platform (in the local container - uninstallMTP() - or in a remote container - updateRoutingTable()) to keep the Agent AID updated.

getHap

public final String getHap()

Method to query the Home Agent Platform. This is the name of the platform where the agent has been created, therefore it will never change during the entire lifetime of the agent. In JADE the name of an agent by default is composed by the concatenation (using '@') of the agent local name and the Home Agent Platform name

Returns:

A String containing the name of the home agent platform (e.g. myComputerName:1099/JADE).

here

public jade.core.Location here()

Method to retrieve the location this agent is currently at.

Returns:

A Location object, describing the location where this agent is currently running.

join

void join()

This is used by the agent container to wait for agent termination. We have alreader called doDelete on the thread which would have issued an interrupt on it. However, it still may decide not to exit. So we will wait no longer than 5 seconds for it to exit and we do not care of this zombie agent. FIXME: we must further isolate container and agents, for instance by using custom class loader and dynamic proxies and JDK 1.3. FIXME: the timeout value should be got by Profile

setQueueSize

public void setQueueSize(int newSize)
                  throws IllegalArgumentException

Set message queue size. This method allows to change the number of ACL messages that can be buffered before being actually read by the agent or discarded.

Parameters:

newSize - A non negative integer value to set message queue size to. Passing 0 means unlimited message queue. When the number of buffered messages exceeds this value, older messages are discarded according to a FIFO replacement policy.

Throws:

IllegalArgumentException - If newSize is negative.

See Also:

getQueueSize()

getCurQueueSize

public int getCurQueueSize()

This method retrieves the current lenght of the message queue of this agent.

Returns:

The number of messages that are currently stored into the message queue.

getQueueSize

public int getQueueSize()

Reads message queue size. A zero value means that the message queue is unbounded (its size is limited only by amount of available memory).

Returns:

The actual size of the message queue (i.e. the max number of messages that can be stored into the queue)

See Also:

setQueueSize(int newSize), getCurQueueSize()

changeStateTo

private void changeStateTo(int state)

getState

public int getState()

Read current agent state. This method can be used to query an agent for its state from the outside.

Returns:

the Agent Platform Life Cycle state this agent is currently in.

setState

private void setState(int state)

getAgentState

public jade.core.AgentState getAgentState()

getScheduler

jade.core.Scheduler getScheduler()

This is only called by the RealNotificationManager to provide the Introspector agent with a snapshot of the behaviours currently loaded in the agent

getMessageQueue

jade.core.MessageQueue getMessageQueue()

This is only called by the RealNotificationManager to provide the Introspector agent with a snapshot of the messages currently pending in the queue and by the RealMobilityManager to transfer messages in the queue

setMessageQueue

private void setMessageQueue(jade.core.MessageQueue mq)

doMove

public void doMove(jade.core.Location destination)

Make a state transition from active to transit within Agent Platform Life Cycle. This method is intended to support agent mobility and is called either by the Agent Platform or by the agent itself to start a migration process.
NOT available in MIDP

Parameters:

destination - The Location to migrate to.

doClone

public void doClone(jade.core.Location destination,
                    String newName)

Make a state transition from active to copy within Agent Platform Life Cycle. This method is intended to support agent mobility and is called either by the Agent Platform or by the agent itself to start a clonation process.
NOT available in MIDP

Parameters:

destination - The Location where the copy agent will start.

newName - The name that will be given to the copy agent.

requestSave

public void requestSave(String repository)

requestReload

public void requestReload(String repository)

requestFreeze

public void requestFreeze(String repository,
                          jade.core.ContainerID bufferContainer)

doExecute

void doExecute()

Make a state transition from transit or copy to active within Agent Platform Life Cycle. This method is intended to support agent mobility and is called by the destination Agent Platform when a migration process completes and the mobile agent is about to be restarted on its new location.

doGone

void doGone()

Make a state transition from transit to gone state. This state is only used to label the original copy of a mobile agent which migrated somewhere.

doSuspend

public void doSuspend()

Make a state transition from active or waiting to suspended within Agent Platform Life Cycle; the original agent state is saved and will be restored by a doActivate() call. This method can be called from the Agent Platform or from the agent iself and stops all agent activities. Incoming messages for a suspended agent are buffered by the Agent Platform and are delivered as soon as the agent resumes. Calling doSuspend() on a suspended agent has no effect.

See Also:

doActivate()

doActivate

public void doActivate()

Make a state transition from suspended to active or waiting (whichever state the agent was in when doSuspend() was called) within Agent Platform Life Cycle. This method is called from the Agent Platform and resumes agent execution. Calling doActivate() when the agent is not suspended has no effect.

See Also:

doSuspend()

doWait

public void doWait()

Make a state transition from active to waiting within Agent Platform Life Cycle. This method can be called by the Agent Platform or by the agent itself and causes the agent to block, stopping all its activities until some event happens. A waiting agent wakes up as soon as a message arrives or when doWake() is called. Calling doWait() on a suspended or waiting agent has no effect.

See Also:

doWake()

doWait

public void doWait(long millis)

Make a state transition from active to waiting within Agent Platform Life Cycle. This method adds a timeout to the other doWait() version.

Parameters:

millis - The timeout value, in milliseconds.

See Also:

doWait()

doWake

public void doWake()

Make a state transition from waiting to active within Agent Platform Life Cycle. This method is called from Agent Platform and resumes agent execution. Calling doWake() when an agent is not waiting has no effect.

See Also:

doWait()

doDelete

public void doDelete()

Make a state transition from active, suspended or waiting to deleted state within Agent Platform Life Cycle, thereby destroying the agent. This method can be called either from the Agent Platform or from the agent itself. Calling doDelete() on an already deleted agent has no effect.

idle

void idle()
    throws InterruptedException

Throws:

InterruptedException

write

public void write(OutputStream s)
           throws IOException

Write this agent to an output stream; this method can be used to record a snapshot of the agent state on a file or to send it through a network connection. Of course, the whole agent must be serializable in order to be written successfully.
NOT available in MIDP

Parameters:

s - The stream this agent will be sent to. The stream is not closed on exit.

Throws:

IOException - Thrown if some I/O error occurs during writing.

See Also:

jade.core.Agent#read(InputStream s)

restore

public void restore(InputStream s)
             throws IOException

This method reads a previously saved agent, replacing the current state of this agent with the one previously saved. The stream must contain the saved state of the same agent that it is trying to restore itself; that is, both the Java object and the agent name must be the same.
NOT available in MIDP

Parameters:

s - The input stream the agent state will be read from.

Throws:

IOException - Thrown if some I/O error occurs during stream reading. Note: This method is currently not implemented

putO2AObject

public void putO2AObject(Object o,
                         boolean blocking)
                  throws InterruptedException

This method should not be used by application code. Use the same-named method of jade.wrapper.Agent instead.
NOT available in MIDP

Throws:

InterruptedException

See Also:

jade.wrapper.Agent#putO2AObject(Object o, boolean blocking)

getO2AObject

public Object getO2AObject()

This method picks an object (if present) from the internal object-to-agent communication queue. In order for this method to work, the agent must have declared its will to accept objects from other software components running within its JVM. This can be achieved by calling the jade.core.Agent.setEnabledO2ACommunication() method. If the retrieved object was originally inserted by an external component using a blocking call, that call will return during the execution of this method.
NOT available in MIDP

Returns:

the first object in the queue, or null if the queue is empty.

See Also:

jade.wrapper.Agent#putO2AObject(Object o, boolean blocking), setEnabledO2ACommunication(boolean enabled, int queueSize)

setEnabledO2ACommunication

public void setEnabledO2ACommunication(boolean enabled,
                                       int queueSize)

This method declares this agent attitude towards object-to-agent communication, that is, whether the agent accepts to communicate with other non-JADE components living within the same JVM.
NOT available in MIDP

Parameters:

enabled - Tells whether Java objects inserted with putO2AObject() will be accepted.

queueSize - If the object-to-agent communication is enabled, this parameter specifiies the maximum number of Java objects that will be queued. If the passed value is 0, no maximum limit is set up for the queue.

See Also:

jade.wrapper.Agent#putO2AObject(Object o, boolean blocking), getO2AObject()

run

public final void run()

This method is the main body of every agent. It can handle automatically AMS registration and deregistration and provides startup and cleanup hooks for application programmers to put their specific code into.

Specified by:

run in interface Runnable

See Also:

setup(), takeDown()

setup

protected void setup()

This protected method is an empty placeholder for application specific startup code. Agent developers can override it to provide necessary behaviour. When this method is called the agent has been already registered with the Agent Platform AMS and is able to send and receive messages. However, the agent execution model is still sequential and no behaviour scheduling is active yet. This method can be used for ordinary startup tasks such as DF registration, but is essential to add at least a Behaviour object to the agent, in order for it to be able to do anything.

See Also:

addBehaviour(Behaviour b), Behaviour

takeDown

protected void takeDown()

This protected method is an empty placeholder for application specific cleanup code. Agent developers can override it to provide necessary behaviour. When this method is called the agent has not deregistered itself with the Agent Platform AMS and is still able to exchange messages with other agents. However, no behaviour scheduling is active anymore and the Agent Platform Life Cycle state is already set to deleted. This method can be used for ordinary cleanup tasks such as DF deregistration, but explicit removal of all agent behaviours is not needed.

beforeMove

protected void beforeMove()

This empty placeholder shall be overridden by user defined agents to execute some actions before the original agent instance on the source container is stopped (e.g. releasing local resources such as a GUI).
IMPORTANT: At this point, it is ensured that the move process is successful and that a moved agent instance has been created on the destination container Therefore setting the value of a class field in this method will have no impact on the moved agent instance. Such parameters must indeed be set before the doMove() method is called.
NOT available in MIDP

afterMove

protected void afterMove()

Actions to perform after moving. This empty placeholder method can be overridden by user defined agents to execute some actions just after arriving to the destination agent container for a migration.
NOT available in MIDP

beforeClone

protected void beforeClone()

This empty placeholder method shall be overridden by user defined agents to execute some actions before copying an agent to another agent container.
NOT available in MIDP

See Also:

beforeMove(), afterClone()

afterClone

protected void afterClone()

Actions to perform after cloning. This empty placeholder method can be overridden by user defined agents to execute some actions just after creating an agent copy to the destination agent container.
NOT available in MIDP

beforeSave

protected void beforeSave()

Actions to perform before saving an agent. This empty placeholder method can be overridden by user defined agents to execute some actions just before the current agent is saved to a persistent store.
Not available in J2ME. Requires the Persistence JADE add-on

afterLoad

protected void afterLoad()

Actions to perform after loading an agent. This empty placeholder method can be overridden by user defined agents to execute some actions just after the current agent is loaded from a persistent store.
Not available in J2ME. Requires the Persistence JADE add-on

beforeReload

protected void beforeReload()

Actions to perform before reloading. This empty placeholder method can be overridden by user defined agents to execute some actions just before the agent thread terminates (and before a new thread is started that will execute the newly reloaded agent).

afterReload

protected void afterReload()

Actions to perform after reloading. This empty placeholder method can be overridden by user defined agents to execute some actions just after a new thread has started executing the newly reloaded agent (and before the thread enters the main agent execution loop.

beforeFreeze

protected void beforeFreeze()

Actions to perform before freezing. This empty placeholder method can be overridden by user defined agents to execute some actions just before an agent is frozen on a persistent store and its thread terminates.
NOT available in MIDP

afterThaw

protected void afterThaw()

Actions to perform after thawing. This empty placeholder method can be overridden by user defined agents to execute some actions just after a previously frozen agent is thawed and its thread is started on the proper agent container.
NOT available in MIDP

powerUp

public void powerUp(jade.core.AID id,
                    Thread t)

writeObject

private void writeObject(ObjectOutputStream out)
                  throws IOException

Throws:

IOException

readObject

private void readObject(ObjectInputStream in)
                 throws IOException,
                        ClassNotFoundException

Throws:

IOException

ClassNotFoundException

mainLoop

private void mainLoop()
               throws InterruptedException,
                      InterruptedIOException

Throws:

InterruptedException

InterruptedIOException

waitUntilWake

private void waitUntilWake(long millis)

waitUntilActivate

private void waitUntilActivate()

destroy

private void destroy()

addBehaviour

public void addBehaviour(jade.core.behaviours.Behaviour b)

This method adds a new behaviour to the agent. This behaviour will be executed concurrently with all the others, using a cooperative round robin scheduling. This method is typically called from an agent setup() to fire off some initial behaviour, but can also be used to spawn new behaviours dynamically.

Parameters:

b - The new behaviour to add to the agent.

See Also:

setup(), Behaviour

removeBehaviour

public void removeBehaviour(jade.core.behaviours.Behaviour b)

This method removes a given behaviour from the agent. This method is called automatically when a top level behaviour terminates, but can also be called from a behaviour to terminate itself or some other behaviour.

Parameters:

b - The behaviour to remove.

See Also:

Behaviour

send

public final void send(jade.lang.acl.ACLMessage msg)

Send an ACL message to another agent. This methods sends a message to the agent specified in :receiver message field (more than one agent can be specified as message receiver).

Parameters:

msg - An ACL message object containing the actual message to send.

See Also:

ACLMessage

receive

public final jade.lang.acl.ACLMessage receive()

Receives an ACL message from the agent message queue. This method is non-blocking and returns the first message in the queue, if any. Therefore, polling and busy waiting is required to wait for the next message sent using this method.

Returns:

A new ACL message, or null if no message is present.

See Also:

ACLMessage

receive

public final jade.lang.acl.ACLMessage receive(jade.lang.acl.MessageTemplate pattern)

Receives an ACL message matching a given template. This method is non-blocking and returns the first matching message in the queue, if any. Therefore, polling and busy waiting is required to wait for a specific kind of message using this method.

Parameters:

pattern - A message template to match received messages against.

Returns:

A new ACL message matching the given template, or null if no such message is present.

See Also:

ACLMessage, MessageTemplate

blockingReceive

public final jade.lang.acl.ACLMessage blockingReceive()

Receives an ACL message from the agent message queue. This method is blocking and suspends the whole agent until a message is available in the queue.

Returns:

A new ACL message, blocking the agent until one is available.

See Also:

receive(), ACLMessage

blockingReceive

public final jade.lang.acl.ACLMessage blockingReceive(long millis)

Receives an ACL message from the agent message queue, waiting at most a specified amount of time.

Parameters:

millis - The maximum amount of time to wait for the message.

Returns:

A new ACL message, or null if the specified amount of time passes without any message reception.

blockingReceive

public final jade.lang.acl.ACLMessage blockingReceive(jade.lang.acl.MessageTemplate pattern)

Receives an ACL message matching a given message template. This method is blocking and suspends the whole agent until a message is available in the queue.

Parameters:

pattern - A message template to match received messages against.

Returns:

A new ACL message matching the given template, blocking until such a message is available.

See Also:

receive(MessageTemplate), ACLMessage, MessageTemplate

blockingReceive

public final jade.lang.acl.ACLMessage blockingReceive(jade.lang.acl.MessageTemplate pattern,
                                                      long millis)

Receives an ACL message matching a given message template, waiting at most a specified time.

Parameters:

pattern - A message template to match received messages against.

millis - The amount of time to wait for the message, in milliseconds.

Returns:

A new ACL message matching the given template, or null if no suitable message was received within millis milliseconds.

See Also:

blockingReceive()

putBack

public final void putBack(jade.lang.acl.ACLMessage msg)

Puts a received ACL message back into the message queue. This method can be used from an agent behaviour when it realizes it read a message of interest for some other behaviour. The message is put in front of the message queue, so it will be the first returned by a receive() call.

See Also:

receive()

setToolkit

public final void setToolkit(AgentToolkit at)

resetToolkit

final void resetToolkit()

waitUntilStarted

public void waitUntilStarted()

This method blocks until the agent has finished its start-up phase (i.e. until just before its setup() method is called. When this method returns, the target agent is registered with the AMS and the JADE platform is aware of it.

notifyStarted

private void notifyStarted()

notifyDestruction

private void notifyDestruction()

notifyPosted

private void notifyPosted(jade.lang.acl.ACLMessage msg)

notifyReceived

private void notifyReceived(jade.lang.acl.ACLMessage msg)

notifySend

private void notifySend(jade.lang.acl.ACLMessage msg)

notifyMove

private void notifyMove()
                 throws jade.security.JADESecurityException,
                        jade.core.IMTPException,
                        jade.core.NotFoundException

Throws:

jade.security.JADESecurityException

jade.core.IMTPException

jade.core.NotFoundException

notifyCopy

private void notifyCopy()
                 throws jade.security.JADESecurityException,
                        jade.core.IMTPException,
                        jade.core.NotFoundException,
                        jade.core.NameClashException

Throws:

jade.security.JADESecurityException

jade.core.IMTPException

jade.core.NotFoundException

jade.core.NameClashException

notifySave

private void notifySave()
                 throws jade.core.ServiceException,
                        jade.core.NotFoundException,
                        jade.core.IMTPException

Throws:

jade.core.ServiceException

jade.core.NotFoundException

jade.core.IMTPException

notifyReload

private void notifyReload()
                   throws jade.core.ServiceException,
                          jade.core.NotFoundException,
                          jade.core.IMTPException

Throws:

jade.core.ServiceException

jade.core.NotFoundException

jade.core.IMTPException

notifyFreeze

private void notifyFreeze()
                   throws jade.core.ServiceException,
                          jade.core.NotFoundException,
                          jade.core.IMTPException

Throws:

jade.core.ServiceException

jade.core.NotFoundException

jade.core.IMTPException

notifyAddBehaviour

void notifyAddBehaviour(jade.core.behaviours.Behaviour b)

notifyRemoveBehaviour

void notifyRemoveBehaviour(jade.core.behaviours.Behaviour b)

notifyChangeBehaviourState

public void notifyChangeBehaviourState(jade.core.behaviours.Behaviour b,
                                       String from,
                                       String to)

setGenerateBehaviourEvents

public void setGenerateBehaviourEvents(boolean b)

getGenerateBehaviourEvents

private boolean getGenerateBehaviourEvents()

notifyChangedAgentState

private void notifyChangedAgentState(int oldState,
                                     int newState)

activateAllBehaviours

private void activateAllBehaviours()

postMessage

public final void postMessage(jade.lang.acl.ACLMessage msg)

Put a received message into the agent message queue. The message is put at the back end of the queue. This method is called by JADE runtime system when a message arrives, but can also be used by an agent, and is just the same as sending a message to oneself (though slightly faster).

Parameters:

msg - The ACL message to put in the queue.

See Also:

send(ACLMessage msg)

getContentManager

public jade.content.ContentManager getContentManager()

Retrieves the agent's content manager

Returns:

The content manager.

getHelper

public jade.core.ServiceHelper getHelper(String serviceName)
                                  throws jade.core.ServiceException

Retrieves the agent's service helper

Returns:

The service helper.

Throws:

jade.core.ServiceException

getProperty

public String getProperty(String key,
                          String aDefault)

Retrieve a configuration property set in the Profile of the local container (first) or as a System property.

Parameters:

key - the key that maps to the property that has to be retrieved.

aDefault - a default value to be returned if there is no mapping for key

interruptThread

private void interruptThread()

This method is used to interrupt the agent's thread. In J2SE/PJAVA it just calls myThread.interrupt(). In MIDP, where interrupt() is not supported the thread interruption is simulated as described below. The agent thread can be in one of the following four states: 1) Running a behaviour. 2) Sleeping on msgQueue due to a doWait() 3) Sleeping on suspendLock due to a doSuspend() 4) Sleeping on myScheduler due to a schedule() with no active behaviours The idea is: set the 'isInterrupted' flag, then wake up the thread wherever it may be

waitOn

void waitOn(Object lock,
            long millis)
      throws InterruptedException

Since in MIDP Thread.interrupt() does not exist and a simulated interruption is used to "interrupt" the agent's thread, we must check whether the simulated interruption happened just before and after going to sleep.

Throws:

InterruptedException

setBufferedState

private void setBufferedState(int bs)

getBufferedState

private int getBufferedState()

getBehaviours

private Set getBehaviours()

setBehaviours

private void setBehaviours(Set behaviours)

getPendingTimers

private Set getPendingTimers()

setPendingTimers

private void setPendingTimers(Set timers)