jade.core
Class Agent

java.lang.Object
  |
  +--jade.core.Agent
All Implemented Interfaces:
java.lang.Runnable, java.io.Serializable, Serializable
Direct Known Subclasses:
GatewayAgent

public class Agent
extends java.lang.Object
implements java.lang.Runnable, Serializable

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

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

Version:
$Date: 2006-03-01 15:56:08 +0100 (Wed, 01 Mar 2006) $ $Revision: 5864 $
Author:
Giovanni Rimassa - Universita' di Parma, Giovanni Caire - TILAB
See Also:
Serialized Form

Nested Class Summary
static class Agent.Interrupted
          Inner class Interrupted.
 
Constructor Summary
Agent()
          Default constructor.
 
Method Summary
 void addBehaviour(Behaviour b)
          This method adds a new behaviour to the agent.
protected  void afterClone()
          Actions to perform after cloning.
protected  void afterMove()
          Actions to perform after moving.
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 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).
 ACLMessage blockingReceive()
          Receives an ACL message from the agent message queue.
 ACLMessage blockingReceive(long millis)
          Receives an ACL message from the agent message queue, waiting at most a specified amount of time.
 ACLMessage blockingReceive(MessageTemplate pattern)
          Receives an ACL message matching a given message template.
 ACLMessage blockingReceive(MessageTemplate pattern, long millis)
          Receives an ACL message matching a given message template, waiting at most a specified time.
 void changeStateTo(LifeCycle newLifeCycle)
           
 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(Location destination, java.lang.String newName)
          Make this agent be cloned on another location.
 void doDelete()
          Make a state transition from active, suspended or waiting to deleted state within Agent Platform Life Cycle, thereby destroying the agent.
 void doMove(Location destination)
          Make this agent move to a remote location.
 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 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.
 AgentState getAgentState()
           
 AID getAID()
          Method to query the private Agent ID.
 AID getAMS()
          Get the Agent ID for the platform AMS.
 java.lang.Object[] getArguments()
          Get the array of arguments passed to this agent.
 AgentContainer getContainerController()
          Return a controller for the container this agent lives in.
 ContentManager getContentManager()
          Retrieves the agent's content manager
 int getCurQueueSize()
          This method retrieves the current lenght of the message queue of this agent.
 AID getDefaultDF()
          Get the Agent ID for the platform default DF.
 java.lang.String getHap()
          Method to query the Home Agent Platform.
 ServiceHelper getHelper(java.lang.String serviceName)
          Retrieves the agent's service helper
 java.lang.String getLocalName()
          Method to query the agent local name.
 java.lang.String getName()
          Method to query the agent complete name (GUID).
 java.lang.Object getO2AObject()
          This method picks an object (if present) from the internal object-to-agent communication queue.
 java.lang.String getProperty(java.lang.String key, java.lang.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.
 Location here()
          Method to retrieve the location this agent is currently at.
 void postMessage(ACLMessage msg)
          Put a received message into the agent message queue.
 void putBack(ACLMessage msg)
          Puts a received ACL message back into the message queue.
 void putO2AObject(java.lang.Object o, boolean blocking)
          This method should not be used by application code.
 ACLMessage receive()
          Receives an ACL message from the agent message queue.
 ACLMessage receive(MessageTemplate pattern)
          Receives an ACL message matching a given template.
 void removeBehaviour(Behaviour b)
          This method removes a given behaviour from the agent.
 void restore(java.io.InputStream s)
          This method reads a previously saved agent, replacing the current state of this agent with the one previously saved.
 void restoreBufferedState()
           
 void send(ACLMessage msg)
          Send an ACL message to another agent.
 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 setQueueSize(int newSize)
          Set message queue size.
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.
 void write(java.io.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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.lang.Runnable
run
 

Constructor Detail

Agent

public Agent()
Default constructor.

Method Detail

getAMS

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

getContainerController

public final AgentContainer getContainerController()
Return a controller for the container this agent lives in.
NOT available in MIDP

Returns:
jade.wrapper.AgentContainer a controller for the container this agent lives in.

getArguments

public java.lang.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 java.lang.String getLocalName()
Method to query the agent local name.

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

getName

public final java.lang.String getName()
Method to query the agent complete name (GUID).

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

getHap

public final java.lang.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).

getAID

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

here

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

setQueueSize

public void setQueueSize(int newSize)
                  throws java.lang.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:
java.lang.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

public void changeStateTo(LifeCycle newLifeCycle)

restoreBufferedState

public void restoreBufferedState()

getAgentState

public AgentState getAgentState()

doMove

public void doMove(Location destination)
Make this agent move to a remote location. 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. It should be noted that this method just changes the agent state to AP_TRANSIT. The actual migration takes place asynchronously.
NOT available in MIDP

Parameters:
destination - The Location to migrate to.

doClone

public void doClone(Location destination,
                    java.lang.String newName)
Make this agent be cloned on another location. 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. It should be noted that this method just changes the agent state to AP_COPY. The actual clonation takes place asynchronously.
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.

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.
NOT available in MIDP

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.
NOT available in MIDP

See Also:
doSuspend()

doWait

public void doWait()
Make a state transition from active to waiting within Agent Platform Life Cycle. This method has only effect when called by the agent thread and causes the agent to block, stopping all its activities until a message arrives or the doWake() method is called.

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.


write

public void write(java.io.OutputStream s)
           throws java.io.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:
java.io.IOException - Thrown if some I/O error occurs during writing.
See Also:
jade.core.Agent#read(InputStream s)

restore

public void restore(java.io.InputStream s)
             throws java.io.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:
java.io.IOException - Thrown if some I/O error occurs during stream reading. Note: This method is currently not implemented

putO2AObject

public void putO2AObject(java.lang.Object o,
                         boolean blocking)
                  throws java.lang.InterruptedException
This method should not be used by application code. Use the same-named method of jade.wrapper.Agent instead.
NOT available in MIDP

java.lang.InterruptedException
See Also:
jade.wrapper.Agent#putO2AObject(Object o, boolean blocking)

getO2AObject

public java.lang.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()

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


addBehaviour

public void addBehaviour(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(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(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 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 ACLMessage receive(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 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 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 ACLMessage blockingReceive(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 ACLMessage blockingReceive(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(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()

postMessage

public final void postMessage(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 ContentManager getContentManager()
Retrieves the agent's content manager

Returns:
The content manager.

getHelper

public ServiceHelper getHelper(java.lang.String serviceName)
                        throws ServiceException
Retrieves the agent's service helper

Returns:
The service helper.
ServiceException

getProperty

public java.lang.String getProperty(java.lang.String key,
                                    java.lang.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


JADE