jade.wrapper
Class AgentContainer

java.lang.Object
  |
  +--jade.wrapper.AgentContainer
Direct Known Subclasses:
MainContainer

public class AgentContainer
extends java.lang.Object
implements PlatformController

This class is a Proxy class, allowing access to a JADE agent container. Invoking methods on instances of this class, it is possible to request services from in-process agent containers. This class must not be instantiated by applications. Instead, use the createContainer() method in class Runtime.

Author:
Giovanni Rimassa - Universita` di Parma
See Also:
Runtime.createAgentContainer(Profile)

Inner classes inherited from class jade.wrapper.PlatformController
PlatformController.Listener
 
Constructor Summary
AgentContainer(AgentContainerImpl impl, java.lang.String platformName)
          Public constructor.
 
Method Summary
 Agent acceptNewAgent(java.lang.String nickname, Agent anAgent)
          Add an Agent to this container.
 void addPlatformListener(PlatformController.Listener aListener)
          Add a platform listener.
 AgentController createNewAgent(java.lang.String nickname, java.lang.String className, java.lang.Object[] args)
          Creates a new JADE agent, running within this container,
 AgentController getAgent(java.lang.String localAgentName)
          Get agent proxy to local agent given its name.
 java.lang.String getName()
          return the name (i.e. the HAP) of this platform
 State getState()
          Returns an instance of PlatformState.
 void installMTP(java.lang.String address, java.lang.String className)
          Installs a new message transport protocol, that will run within this container.
 void kill()
          Shuts down this container, terminating all the agents running within it.
 void removePlatformListener(PlatformController.Listener aListener)
          Remove a platform listener.
 void resume()
          Activate the agent platform.
 void start()
          Start the platform after its been initialized.
 void suspend()
          Suspend the agent platform.
 void uninstallMTP(java.lang.String address)
          Removes a message transport protocol, previously running within this container.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AgentContainer

public AgentContainer(AgentContainerImpl impl,
                      java.lang.String platformName)
Public constructor. This constructor requires a concrete implementation of a JADE agent container, which cannot be instantiated by applications, so it cannot be meaningfully called from application code. The proper way to create an agent container from an application is to call the Runtime.createContainer() method.
Parameters:
impl - A concrete implementation of a JADE agent container.
platformName - the name of the platform
See Also:
Runtime.createAgentContainer(Profile)
Method Detail

getAgent

public AgentController getAgent(java.lang.String localAgentName)
                         throws ControllerException
Get agent proxy to local agent given its name.
Specified by:
getAgent in interface PlatformController
Parameters:
localAgentName - The short local name of the desired agent.
Throws:
ControllerException - If any probelms occur obtaining this proxy.

createNewAgent

public AgentController createNewAgent(java.lang.String nickname,
                                      java.lang.String className,
                                      java.lang.Object[] args)
                               throws StaleProxyException
Creates a new JADE agent, running within this container,
Specified by:
createNewAgent in interface PlatformController
Parameters:
nickname - A platform-unique nickname for the newly created agent. The agent will be given a FIPA compliant agent identifier using the nickname and the ID of the platform it is running on.
className - The fully qualified name of the class that implements the agent.
args - An object array, containing initialization parameters to pass to the new agent.
Returns:
A proxy object, allowing to call state-transition forcing methods on the real agent instance.

acceptNewAgent

public Agent acceptNewAgent(java.lang.String nickname,
                            Agent anAgent)
                     throws StaleProxyException
Add an Agent to this container. Typically Agent would be some class extending Agent which was instantiated and configured.
Parameters:
nickname - A platform-unique nickname for the newly created agent. The agent will be given a FIPA compliant agent identifier using the nickname and the ID of the platform it is running on.
anAgent - The agent to be added to this agent container.
Returns:
An AgentController, allowing to call state-transition forcing methods on the real agent instance.

kill

public void kill()
          throws StaleProxyException
Shuts down this container, terminating all the agents running within it.
Specified by:
kill in interface PlatformController
Tags copied from interface: PlatformController
Throws:
ControllerException - If any probelms other than illegal state occur.
java.lang.IllegalStateException - If state is illegal for this activity.

installMTP

public void installMTP(java.lang.String address,
                       java.lang.String className)
                throws jade.mtp.MTPException,
                       StaleProxyException
Installs a new message transport protocol, that will run within this container.
Parameters:
address - The transport address exported by the new MTP, in string format.
className - The fully qualified name of the Java class that implements the transport protocol.
Throws:
jade.mtp.MTPException - If something goes wrong during transport protocol activation.

uninstallMTP

public void uninstallMTP(java.lang.String address)
                  throws jade.mtp.MTPException,
                         NotFoundException,
                         StaleProxyException
Removes a message transport protocol, previously running within this container.
Parameters:
address - The transport address exported by the new MTP, in string format.
Throws:
jade.mtp.MTPException - If something goes wrong during transport protocol activation.
NotFoundException - If no protocol with the given address is currently installed on this container.

getName

public java.lang.String getName()
return the name (i.e. the HAP) of this platform
Specified by:
getName in interface PlatformController
Tags copied from interface: PlatformController
Returns:
String The platform name.

start

public void start()
           throws ControllerException
Description copied from interface: PlatformController
Start the platform after its been initialized.
Specified by:
start in interface PlatformController
Tags copied from interface: PlatformController
Throws:
ControllerException - If any probelms other than illegal state occur.
java.lang.IllegalStateException - If state is illegal for this activity.

suspend

public void suspend()
             throws ControllerException
Description copied from interface: PlatformController
Suspend the agent platform. Next action may be resume or kill.
Specified by:
suspend in interface PlatformController
Tags copied from interface: PlatformController
Throws:
ControllerException - If any probelms other than illegal state occur.
java.lang.IllegalStateException - If state is illegal for this activity.

resume

public void resume()
            throws ControllerException
Description copied from interface: PlatformController
Activate the agent platform. Next action may be suspend or kill.
Specified by:
resume in interface PlatformController
Tags copied from interface: PlatformController
Throws:
ControllerException - If any probelms other than illegal state occur.
java.lang.IllegalStateException - If state is illegal for this activity.

getState

public State getState()
Description copied from interface: PlatformController
Returns an instance of PlatformState.
Specified by:
getState in interface PlatformController

addPlatformListener

public void addPlatformListener(PlatformController.Listener aListener)
                         throws ControllerException
Description copied from interface: PlatformController
Add a platform listener.
Specified by:
addPlatformListener in interface PlatformController
Tags copied from interface: PlatformController
Parameters:
aListener - The listener to be notified.

removePlatformListener

public void removePlatformListener(PlatformController.Listener aListener)
                            throws ControllerException
Description copied from interface: PlatformController
Remove a platform listener.
Specified by:
removePlatformListener in interface PlatformController
Tags copied from interface: PlatformController
Parameters:
aListener - The listener to be notified.