public class Agent extends java.lang.Object implements java.lang.Runnable, Serializable
Agent
class is the common superclass for user
defined software agents. It provides methods to perform basic agent
tasks, such as:
ACLMessage
objects,
both unicast and multicast with optional pattern matching. Agent
subclasses, adding specific behaviours as needed
and exploiting Agent
class capabilities.Modifier and Type | Class and Description |
---|---|
static class |
Agent.Interrupted
Inner class Interrupted.
|
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
MSG_QUEUE_CLASS |
Constructor and Description |
---|
Agent()
Default constructor.
|
Modifier and Type | Method and Description |
---|---|
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) |
protected MessageQueue |
createMessageQueue()
Developer can override this method to provide an alternative message queue creation mechanism
|
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 |
getAID(java.lang.String name)
Method to build a complete agent GUID belonging to the same platform of the current agent
|
AID |
getAMS()
Get the Agent ID for the platform AMS.
|
java.lang.Object[] |
getArguments()
Get the array of arguments passed to this agent.
|
Properties |
getBootProperties()
Return the configuration properties exactly as they were passed to the Profile before
starting the local JADE container.
|
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 length 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).
|
<T> T |
getO2AInterface(java.lang.Class<T> theInterface)
Used internally by the framework
|
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.
|
boolean |
isAlive()
Returns true if the agent implemented by this Agent object is alive (regardless of the
actual agent internal state).
|
boolean |
isRestarting()
This method returns
true when this agent is restarting after a crash. |
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.
|
<T> void |
registerO2AInterface(java.lang.Class<T> theInterface,
T implementation)
Registers an implementation for a given O2A interface.
|
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 |
setO2AManager(Behaviour b)
Sets the behaviour responsible for managing objects passed to the agent by
means of the Object-To-Agent (O2A) communication mechanism.
|
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.
|
public static final java.lang.String MSG_QUEUE_CLASS
protected MessageQueue createMessageQueue()
public AgentContainer getContainerController()
public java.lang.Object[] getArguments()
Take care that the arguments are transient and they do not migrate with the agent neither are cloned with the agent!
public final boolean isRestarting()
true
when this agent is restarting after a crash.
The restarting indication is automatically reset as soon as the setup()
method of
this agent terminates.true
when this agent is restarting after a crash. false
otherwise.public final AID getAMS()
AID
object, that can be used to contact
the AMS of this platform.public AID getDefaultDF()
AID
object, that can be used to contact
the default DF of this platform.public final java.lang.String getLocalName()
String
containing the local agent name
(e.g. peter).public final java.lang.String getName()
String
containing the complete agent name
(e.g. peter@fipa.org:50).public final java.lang.String getHap()
String
containing the name of the home agent platform
(e.g. myComputerName:1099/JADE).public final AID getAID()
Agent ID
object, containing the complete
agent GUID, addresses and resolvers.public final AID getAID(java.lang.String name)
name
- Agent local name.Agent ID
object, containing the complete
agent GUID, addresses and resolvers.public boolean isAlive()
public Location here()
Location
object, describing the location
where this agent is currently running.public void setQueueSize(int newSize) throws java.lang.IllegalArgumentException
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.java.lang.IllegalArgumentException
- If newSize
is negative.getQueueSize()
public int getCurQueueSize()
public int getQueueSize()
setQueueSize(int newSize)
,
getCurQueueSize()
public void changeStateTo(LifeCycle newLifeCycle)
public void restoreBufferedState()
public AgentState getAgentState()
public void doMove(Location destination)
AP_TRANSIT
. The actual migration takes
place asynchronously.
destination
- The Location
to migrate to.public void doClone(Location destination, java.lang.String newName)
AP_COPY
. The actual clonation takes
place asynchronously.
destination
- The Location
where the copy agent will start.newName
- The name that will be given to the copy agent.public void doSuspend()
doActivate()
call. This method can be called from
the Agent Platform or from the agent itself 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.
doActivate()
public void doActivate()
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.
doSuspend()
public void doWait()
doWake()
method is called.doWake()
public void doWait(long millis)
doWait()
version.millis
- The timeout value, in milliseconds.doWait()
public void doWake()
doWake()
when an agent is not waiting has no effect.doWait()
public void doDelete()
doDelete()
on an already deleted
agent has no effect.public void write(java.io.OutputStream s) throws java.io.IOException
s
- The stream this agent will be sent to. The stream is
not closed on exit.java.io.IOException
- Thrown if some I/O error occurs during
writing.jade.core.Agent#read(InputStream s)
public void restore(java.io.InputStream s) throws java.io.IOException
s
- The input stream the agent state will be read from.java.io.IOException
- Thrown if some I/O error occurs during
stream reading.
Note: This method is currently not implementedpublic void putO2AObject(java.lang.Object o, boolean blocking) throws java.lang.InterruptedException
jade.wrapper.Agent
instead.
java.lang.InterruptedException
AgentController.putO2AObject(Object o, boolean blocking)
public java.lang.Object getO2AObject()
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.
null
if
the queue is empty.AgentController.putO2AObject(Object o, boolean blocking)
,
setEnabledO2ACommunication(boolean enabled, int queueSize)
public void setEnabledO2ACommunication(boolean enabled, int queueSize)
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.AgentController.putO2AObject(Object o, boolean blocking)
,
getO2AObject()
public void setO2AManager(Behaviour b)
putO2AObject()
method, only the manager
is waken up. This improves the efficiency since all behaviours not interested in
O2A communication remain sleeping. addBehaviour() method as usual.
NOT available in MIDP
b
- The behaviour that will act as O2A manager.AgentController.putO2AObject(Object o, boolean blocking)
,
getO2AObject()
public <T> T getO2AInterface(java.lang.Class<T> theInterface)
public <T> void registerO2AInterface(java.lang.Class<T> theInterface, T implementation)
theInterface
- The O2A interface the implementation is registered for.implementation
- The object providing an implementation for the given O2A interface.protected void setup()
Behaviour
object to the agent, in order for it to be
able to do anything.addBehaviour(Behaviour b)
,
Behaviour
protected void takeDown()
protected void beforeMove()
doMove()
method is called.
protected void afterMove()
protected void beforeClone()
beforeMove()
,
afterClone()
protected void afterClone()
public void addBehaviour(Behaviour b)
setup()
to fire off some
initial behaviour, but can also be used to spawn new behaviours
dynamically.public void removeBehaviour(Behaviour b)
b
- The behaviour to remove.Behaviour
public final void send(ACLMessage msg)
:receiver
message field (more than one agent can be specified as message
receiver).msg
- An ACL message object containing the actual message to
send.ACLMessage
public final ACLMessage receive()
null
if no message is
present.ACLMessage
public final ACLMessage receive(MessageTemplate pattern)
pattern
- A message template to match received messages
against.null
if no such message is present.ACLMessage
,
MessageTemplate
public final ACLMessage blockingReceive()
receive()
,
ACLMessage
public final ACLMessage blockingReceive(long millis)
millis
- The maximum amount of time to wait for the message.null
if the specified
amount of time passes without any message reception.public final ACLMessage blockingReceive(MessageTemplate pattern)
pattern
- A message template to match received messages
against.receive(MessageTemplate)
,
ACLMessage
,
MessageTemplate
public final ACLMessage blockingReceive(MessageTemplate pattern, long millis)
pattern
- A message template to match received messages
against.millis
- The amount of time to wait for the message, in
milliseconds.null
if no suitable message was received within
millis
milliseconds.blockingReceive()
public final void putBack(ACLMessage msg)
receive()
call.receive()
public final void postMessage(ACLMessage msg)
msg
- The ACL message to put in the queue.send(ACLMessage msg)
public ContentManager getContentManager()
public ServiceHelper getHelper(java.lang.String serviceName) throws ServiceException
ServiceException
public java.lang.String getProperty(java.lang.String key, java.lang.String aDefault)
Profile
of the local container (first) or as a System property.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
public Properties getBootProperties()