jade.wrapper

Interface AgentController

public interface AgentController

This interface is a Proxy, 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:

ContainerController.createNewAgent(String, String, Object[])

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	ASYNC Constant representing an asynchronous rendez-vous policy.
static boolean	SYNC Constant representing a synchronous rendez-vous policy.

Method Summary

Modifier and Type	Method and Description
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.
<T> T	getO2AInterface(java.lang.Class<T> theInterface) Retrieve an O2A (Object-to-Agent) interface to interact with the controlled 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.

Field Detail

ASYNC

static final boolean ASYNC

Constant representing an asynchronous rendez-vous policy.

See Also:

jade.wrapper.Agent#putO2AObject(Object, boolean), Constant Field Values

SYNC

static final boolean SYNC

Constant representing a synchronous rendez-vous policy.

See Also:

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

Method Detail

getName

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.

Returns:

The agents name.

Throws:

StaleProxyException

start

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.

Throws:

StaleProxyException - If the underlying agent is dead or gone.

suspend

void suspend()
      throws StaleProxyException

Triggers a state transition from ACTIVE to SUSPENDED.

Throws:

StaleProxyException - If the underlying agent is dead or gone.

activate

void activate()
       throws StaleProxyException

Triggers a state transition from SUSPENDED to ACTIVE.

Throws:

StaleProxyException - If the underlying agent is dead or gone.

kill

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.

Throws:

StaleProxyException - If the underlying agent is dead or gone.

move

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

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

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.

Throws:

StaleProxyException

See Also:

Agent.getO2AObject(), Agent.setEnabledO2ACommunication(boolean enabled, int queueSize)

getO2AInterface

<T> T getO2AInterface(java.lang.Class<T> theInterface)
               throws StaleProxyException

Retrieve an O2A (Object-to-Agent) interface to interact with the controlled agent.

Parameters:

theInterface - The O2A interface that must be retrieved

Returns:

An implementation of the indicated O2A interface

Throws:

StaleProxyException - If the underlying agent is dead or gone.

See Also:

jade.core.Agent#registerO2AInterface(Class theClass, T theInterface)

getState

State getState()
        throws StaleProxyException

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.

Throws:

StaleProxyException