jade.wrapper
Class Agent

java.lang.Object
  |
  +--jade.wrapper.Agent
All Implemented Interfaces:
AgentController

public class Agent
extends java.lang.Object
implements AgentController

This class is a Proxy class, allowing access to a JADE agent. Invoking methods on instances of this class, it is possible to trigger state transition of the agent life cycle. This class must not be instantiated by applications. Instead, use the createAgent() method in class AgentContainer.
NOT available in MIDP

Author:
Giovanni Rimassa - Universita' di Parma
See Also:
AgentContainer.createNewAgent(String, String, Object[])

Field Summary
static boolean ASYNC
          Constant representing an asynchronous rendez-vous policy.
static boolean SYNC
          Constant representing a synchronous rendez-vous policy.
 
Constructor Summary
Agent(AID id, Agent a)
          Default constructor.
 
Method Summary
 void activate()
          Triggers a state transition from SUSPENDED to ACTIVE.
 void clone(Location where, java.lang.String newName)
          Clones the current agent.
 java.lang.String getName()
          Get the platforms name of the agent.
 State getState()
          Read current agent state.
 void kill()
          Triggers a state transition from ACTIVE to DELETED.
 void move(Location where)
          Triggers a state transition from ACTIVE to TRANSIT.
 void putO2AObject(java.lang.Object o, boolean blocking)
          Passes an application-specific object to a local agent, created using JADE In-Process Interface.
 void start()
          Triggers a state transition from INITIATED to ACTIVE.
 void suspend()
          Triggers a state transition from ACTIVE to SUSPENDED.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ASYNC

public static final boolean ASYNC
Constant representing an asynchronous rendez-vous policy.

See Also:
putO2AObject(Object, boolean), Constant Field Values

SYNC

public static final boolean SYNC
Constant representing a synchronous rendez-vous policy.

See Also:
putO2AObject(Object o, boolean blocking), Constant Field Values
Constructor Detail

Agent

public Agent(AID id,
             Agent a)
Default constructor. This should not be called by applications, but the method AgentContainer.createAgent() should be used instead.

Parameters:
id - The AID of the agent to be wrapped by this proxy.
a - The real JADE agent, that will be wrapped by this proxy.
See Also:
AgentContainer.createNewAgent(String, String, Object[])
Method Detail

getName

public java.lang.String getName()
                         throws StaleProxyException
Get the platforms name of the agent. This name would be what the platform would use to uniquely reference this agent.

Specified by:
getName in interface AgentController
Returns:
The agents name.
StaleProxyException

start

public void start()
           throws StaleProxyException
Triggers a state transition from INITIATED to ACTIVE. This call also starts the internal agent thread. If this call is performed on an already started agent, nothing happens.

Specified by:
start in interface AgentController
Throws:
StaleProxyException - If the underlying agent is dead or gone.

suspend

public void suspend()
             throws StaleProxyException
Triggers a state transition from ACTIVE to SUSPENDED.

Specified by:
suspend in interface AgentController
Throws:
StaleProxyException - If the underlying agent is dead or gone.

activate

public void activate()
              throws StaleProxyException
Triggers a state transition from SUSPENDED to ACTIVE.

Specified by:
activate in interface AgentController
Throws:
StaleProxyException - If the underlying agent is dead or gone.

kill

public void kill()
          throws StaleProxyException
Triggers a state transition from ACTIVE to DELETED. This call also stops the internal agent thread and fully terminates the agent. If this call is performed on an already terminated agent, nothing happens.

Specified by:
kill in interface AgentController
Throws:
StaleProxyException - If the underlying agent is dead or gone.

move

public void move(Location where)
          throws StaleProxyException
Triggers a state transition from ACTIVE to TRANSIT. This call also moves the agent code and data to another container. This calls terminates the locally running agent, so that this proxy object becomes detached from the moved agent that keeps on executing elsewhere (i.e., no proxy remotization is performed).

Parameters:
where - A Location object, representing the container the agent should move to.
Throws:
StaleProxyException - If the underlying agent is dead or gone.

clone

public void clone(Location where,
                  java.lang.String newName)
           throws StaleProxyException
Clones the current agent. Calling this method does not really trigger a state transition in the current agent lifecycle. Rather, it creates another agent on the given location, that is just a copy of this agent.

Parameters:
where - The Location object, representing the container where the new agent copy will start.
newName - The new nickname to give to the copy.
Throws:
StaleProxyException - If the underlying agent is dead or gone.

putO2AObject

public void putO2AObject(java.lang.Object o,
                         boolean blocking)
                  throws StaleProxyException
Passes an application-specific object to a local agent, created using JADE In-Process Interface. The object will be put into an internal agent queue, from where it can be picked using the jade.core.Agent.getO2AObject() method. The agent must first declare its will to accept passed objects, using the jade.core.Agent.setEnabledO2ACommunication() method.

Parameters:
o - The object to put in the private agent queue.
blocking - A flag, stating the desired rendez-vous policy; it can be ASYNC, for a non-blocking call, returning right after putting the object in the quque, or SYNC, for a blocking call that does not return until the agent picks the object from the private queue.
StaleProxyException
See Also:
Agent.getO2AObject(), Agent.setEnabledO2ACommunication(boolean enabled, int queueSize)

getState

public State getState()
               throws StaleProxyException
Read current agent state. This method can be used to query an agent for its state from the outside.

Specified by:
getState in interface AgentController
Returns:
the Agent Platform Life Cycle state this agent is currently in.
StaleProxyException


JADE