jade.core
Class Agent

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

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: 2003/12/03 17:07:27 $ $Revision: 2.125 $
Author:
Giovanni Rimassa - Universita' di Parma
See Also:
Serialized Form

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()
          Actions to perform before cloning.
protected  void beforeMove()
          Actions to perform before moving.
 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 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 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.
 void doMove(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 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.
 AID getAID()
          Method to query the private Agent ID.
 AID getAMS()
          Get the Agent ID for the platform AMS.
protected  java.lang.Object[] getArguments()
          Get the array of arguments passed to this agent.
 AgentContainer getContainerController()
          Return a controller for this agents container.
 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 agent home address.
 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.
static void read(java.io.InputStream s)
          Read a previously saved agent from an input stream and restarts it under its former name.
static void read(java.io.InputStream s, java.lang.String agentName)
          Read a previously saved agent from an input stream and restarts it under a different name.
 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 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 this agents container.
NOT available in MIDP

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

getArguments

protected 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).

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.

getHap

public final java.lang.String getHap()
Method to query the agent home address. This is the address of the platform where the agent was created, and will never change during the whole lifetime of the agent.

Returns:
A String containing the agent home address (e.g. iiop://fipa.org:50/acc).

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()

doMove

public void doMove(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(Location destination,
                    java.lang.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.

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.


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:
read(InputStream s)

read

public static void read(java.io.InputStream s)
                 throws java.io.IOException
Read a previously saved agent from an input stream and restarts it under its former name. This method can realize some sort of mobility through time, where an agent is saved, then destroyed and then restarted from the saved copy.
NOT available in MIDP

Parameters:
s - The stream the agent will be read from. The stream is not closed on exit.
Throws:
java.io.IOException - Thrown if some I/O error occurs during stream reading.
See Also:
write(OutputStream s)

read

public static void read(java.io.InputStream s,
                        java.lang.String agentName)
                 throws java.io.IOException
Read a previously saved agent from an input stream and restarts it under a different name. This method can realize agent cloning through streams, where an agent is saved, then an exact copy of it is restarted as a completely separated agent, with the same state but with different identity and address.
NOT available in MIDP

Parameters:
s - The stream the agent will be read from. The stream is not closed on exit.
agentName - The name of the new agent, copy of the saved original one.
Throws:
java.io.IOException - Thrown if some I/O error occurs during stream reading.
See Also:
write(OutputStream 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:
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:
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:
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()
Actions to perform before moving. This empty placeholder method can be overridden by user defined agents to execute some actions just before leaving an agent container for a migration.
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()
Actions to perform before cloning. This empty placeholder method can be overridden by user defined agents to execute some actions just before copying an agent to another agent container.
NOT available in MIDP


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.

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