org.iids.aos.hostmanager
Class LifeCycleModule

java.lang.Object
  org.iids.aos.systemservices.module.AbstractModule
      org.iids.aos.hostmanager.LifeCycleModule

All Implemented Interfaces:

Module

public class LifeCycleModule
extends AbstractModule

Agent lifecycle management module.

All lifecycle related management can be found here, like migrating, suspending and running agents.

NOTE: synchronization to be investigated

Author:

mobach@cs.vu.nl, rjtimmer@cs.vu.nl

Constructor Summary

LifeCycleModule(Communicator _communicator, AgentScapeConfig _asc, SystemServiceModule ssm, RegistrationModule rm, AgentRegistrationModule arm, AgentScapeHMNegotiationModule nm, AgentContainerManager acm, MessageCenter mc)

Method Summary

boolean	containsAgent(AgentID id) Query to see if this host contains a certain agent.
void	createAgent(AgentID agentID, java.lang.String token)
AgentHandle	createAgentHandle(AgentID id) Creates a new unique AgentHandle for an existing agent, which can be used to refer to this agent.
AgentArchive	exportAgent(AgentID id)
int	getAgentCPUtime(AgentID agentId) Report CPU time consumed by an agent.
java.util.List<AgentHandle>	getAgentHandles(AgentID id) Obtain a list of agent handles belonging to an agent.
MigrationEndpoint	handleMigration(AgentID agentId, java.lang.String migrationToken, Address requestingAddress) Called by local location manager to instruct host manager to prepare for an incoming agent.
boolean	isStarted()
void	killAgent(AgentID agentId)
void	migrationRequest(AgentID requestingAgentId, java.lang.String migrationToken, AgentScapeID locationId) Handles migration requests from local agents.
void	migrationStatus(MigrationID mid, boolean success) Called by remote hostmanager to indicate success or failure of agent migration on the remote side.
void	notifyCompletion(ContainerWaitThread cwt) Used by a ContainerWaitThread to indicate that it completed the transfer, and the agent can be loaded (if successful).
java.util.List<Envelope>	removeAgentHandle(AgentID id, AgentHandle ah, boolean pickup)
void	start()
void	startAgent(AgentID agentId, boolean collect, java.lang.String[] args) Instruct host/agentserver to start running an agent.
void	stop()
void	suspendAgent(AgentID agentId) Suspend a running agent.
AgentArchive	waitForAgent(AgentID id, boolean pickup) Collect finished agent container (if it was killed on this host).

Methods inherited from class org.iids.aos.systemservices.module.AbstractModule

getCommunicator, getModuleName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LifeCycleModule

public LifeCycleModule(Communicator _communicator,
                       AgentScapeConfig _asc,
                       SystemServiceModule ssm,
                       RegistrationModule rm,
                       AgentRegistrationModule arm,
                       AgentScapeHMNegotiationModule nm,
                       AgentContainerManager acm,
                       MessageCenter mc)
                throws java.lang.NoSuchMethodException,
                       CommunicatorException

Throws:

java.lang.NoSuchMethodException

CommunicatorException

Method Detail

createAgent

public void createAgent(AgentID agentID,
                        java.lang.String token)
                 throws AgentCreationException

Throws:

AgentCreationException

startAgent

public void startAgent(AgentID agentId,
                       boolean collect,
                       java.lang.String[] args)
                throws AgentIDUnknownException,
                       AgentStartupException

Instruct host/agentserver to start running an agent.

Implementation of HostManager.start_agent(org.iids.aos.systemservices.communicator.structs.AgentID, boolean, java.lang.String[]).

Throws:

AgentIDUnknownException

AgentStartupException

suspendAgent

public void suspendAgent(AgentID agentId)
                  throws AgentIDUnknownException,
                         AgentSuspendException

Suspend a running agent.

Implementation of HostManager.suspend_agent(org.iids.aos.systemservices.communicator.structs.AgentID).

Throws:

AgentIDUnknownException

AgentSuspendException

killAgent

public void killAgent(AgentID agentId)
               throws AgentIDUnknownException

Throws:

AgentIDUnknownException

getAgentCPUtime

public int getAgentCPUtime(AgentID agentId)
                    throws AgentIDUnknownException

Report CPU time consumed by an agent. Should really not throw AgentIDUnknownException to prevent from leaking the AgentID outside of AgentScape.

Parameters:

agentId - AgentID to get CPU time from.

Returns:

Consumed CPU time (in milliseconds?) for this agent.

Throws:

AgentIDUnknownException

migrationRequest

public void migrationRequest(AgentID requestingAgentId,
                             java.lang.String migrationToken,
                             AgentScapeID locationId)
                      throws MigrationFailedException

Handles migration requests from local agents.

The remote host manager is contacted, and the AC is sent to the remote host. Once this is done, this function returns. The remote host then tries to start the agent.

Note that if the migration succeeds, but agent startup cannot be completed, the initiating host does not notice this. This is now the responsibility of the host manager that accepted the agent.

Parameters:

requestingAgentId - AgentID of the requesting agent.

migrationToken - String token for this agent. This can be either a lease identifier indicating where the agent will be placed, or a string containing the language requirement for the agent.

locationId - Target location of the agent

Throws:

MigrationFailedException - If the migration failed for some reason.

handleMigration

public MigrationEndpoint handleMigration(AgentID agentId,
                                         java.lang.String migrationToken,
                                         Address requestingAddress)
                                  throws MigrationFailedException

Called by local location manager to instruct host manager to prepare for an incoming agent.

This creates a migration endpoint to which the initiating host manager can send the Agent Container.

Parameters:

agentId - AgentID of the incoming agent to expect.

migrationToken - Token that identifier this migration action. Could be either a pre-negotiated lease information, or a String containing the language requirements used to select agent server.

requestingAddress - Address of the HostManager that initiated the transfer.

Returns:

A MigrationEndpoint is created which the AC can be sent to.

Throws:

MigrationFailedException - If the migration request could not be fulfilled.

migrationStatus

public void migrationStatus(MigrationID mid,
                            boolean success)
                     throws MigrationFailedException

Called by remote hostmanager to indicate success or failure of agent migration on the remote side.

If there is a (sending) thread blocked waiting for the AC to arrive (there probably is), then it is unblocked and notified of the migration status.

Parameters:

mid - Migration ID identifying the agent transfer.

success - Boolean identifying successful migration (true) or failure (false).

Throws:

MigrationFailedException

containsAgent

public boolean containsAgent(AgentID id)

Query to see if this host contains a certain agent.

createAgentHandle

public AgentHandle createAgentHandle(AgentID id)
                              throws AgentIDUnknownException

Creates a new unique AgentHandle for an existing agent, which can be used to refer to this agent.

Implementation of HostManager.create_agent_handle(org.iids.aos.systemservices.communicator.structs.AgentID).

Throws:

AgentIDUnknownException

removeAgentHandle

public java.util.List<Envelope> removeAgentHandle(AgentID id,
                                                  AgentHandle ah,
                                                  boolean pickup)
                                           throws AgentIDUnknownException

Throws:

AgentIDUnknownException

getAgentHandles

public java.util.List<AgentHandle> getAgentHandles(AgentID id)
                                            throws AgentIDUnknownException

Obtain a list of agent handles belonging to an agent.

Implementation of HostManager.get_agent_handles(org.iids.aos.systemservices.communicator.structs.AgentID).

Throws:

AgentIDUnknownException

notifyCompletion

public void notifyCompletion(ContainerWaitThread cwt)

Used by a ContainerWaitThread to indicate that it completed the transfer, and the agent can be loaded (if successful).

If all is well, the remote host (that shipped the AC) is notified that the AC has arrived. After that we try to load the agent implementation from the AC.

The agent is loaded after notifying the sending host because this notification can get lost (i.e. if the connection breaks). In this case this would mean that the agent will not be started here, and the sending host manager can find out itself (e.g. after a timeout) that something went wrong, so it can possibly restart the agent locally. If the notification was to be sent after loading the agent, then we could have two copies of the same agent.

In short, migration is an at-most-once process.

Parameters:

cwt - The ContainerWaitThread that noticed completion of the transfer

isStarted

public boolean isStarted()

start

public void start()

stop

public void stop()

waitForAgent

public AgentArchive waitForAgent(AgentID id,
                                 boolean pickup)
                          throws AgentIDUnknownException,
                                 AgentContainerException

Collect finished agent container (if it was killed on this host).

Implementation of HostManager.wait_for_agent(org.iids.aos.systemservices.communicator.structs.AgentID, boolean).

Throws:

AgentIDUnknownException

AgentContainerException

exportAgent

public AgentArchive exportAgent(AgentID id)
                         throws AgentIDUnknownException,
                                AgentContainerException

Throws:

AgentIDUnknownException

AgentContainerException