The AgentLoader

The AgentLoader is used by the System to control an Agent. It provides the same init / start / stop / concludeAgent methods as the AgentIFace.

Figure: Creating an Agent

20#20

When a new Agent is created (see Figure ), the AgentLoader loads the needed classes using the AgentClassLoader which is a subclass of the standard ClassLoader. The AgentClassLoader supports only the loading from the CLASSPATH but can easily be extended to load them from other AgentSystems and from web / ftp servers. The Agent runs in its own thread group which has some security advantages. The priority of each Agent and its own thread can be controlled through the thread group of the Agent and it also shows if the Agent is still executing. Since the Agent is untrusted code all the calls to methods of the Agent have to be done by a thread for itself to do not block the execution of the AgentLoader and the System. The first thread for the Agent is created for instantiating the Agent. When the Agent is instantiated its constructor is called, possible containing evil code. This thread is member of the thread group of the Agent and has the same priority, which is lower then the of the rest of the System. The AgentLoader waits now at a maximum of one second for the thread to make the Agent object available. The Agent can spend more time in the constructor but the AgentLoader continuous work after waiting the one second. The timeout for the Agent methods is still a static variable of the AgentLoader class, but could be put into the configuration file in future. If the Agent has not finished with its constructor after the timeout, the AgentLoader throws an Exception and exits from its constructor (where all this stuff is done). This lets only Agents execute in the machine which are compliant to the timeout rules of the System. This can be done strictly because the Agent should not have code in its constructor. Therefor an Agent is provided with the initUser() method, which is described in the Agent class section. After instantiating the AgentLoader scans the Agent class to store the list of available methods for receiving messages. These message have to start with the string ``handle'' to be recognized. The AgentLoader uses for this purpose the getMethods() of the Class object of the Agent class. This is done by the following line of code:
Method [] agentMethods = this.agent.getClass().getMethods();

After collecting the message methods the AgentLoader constructor exits, having created the new Agent.

When an Agent was received by the System and has to be started again here, it receives also an AgentLoader. The boolean parameter create tells the AgentLoader if it has to create a new Agent or just restart an old one. When an Agent is traveling its own thread is stopped and thus it cannot be restarted again. Once a thread has finished executing its run() method, it is no longer possible to start it again (like with calling the start() method of the thread again). Therefor the AgentLoader has to create a new Thread with the old Agent as parameter (as well as the Agent thread group). Then the AgentLoader scans the methods like mentioned before to find all message receivers and stores them.

When the AgentLoader has finished instantiating the Agent it is available for the System by calling the getAgent() method of the loader.

The following list will describe the other methods to be used to control an Agent.

getClassLoader

Returns the AgentClassLoader used for this Agent to load its classes.

getAgentID

Returns the ID of the Agent.

getState

Returns the status of the Agent. The Agent can be in one of the following states:

• [LOADED]The Agent has been instantiated or is currently instantiating.
• [INITIALIZING]The Agent is executing its initAgent method.
• [INITIALIZED]The Agent has been initialized, that means it has finished executing its initAgent method, but is not yet started.
• [STARTING]The Agent is starting, that means it is currently executing its startAgent method.
• [STARTED]The Agent is started and running.
• [STOPPING]The Agent is stopping, that means it is currently executing its stopAgent method.
• [STOPPED]The Agent is stopped. It is no longer executing any code.
• [CONCLUDING]The Agent is terminating, that means it is currently executing its terminateAgent method.
• [CONCLUDED]The Agent is terminated and will be removed from the Agent System. It is no longer accessible and executing.

getStatusString

The getState just returns the number representing the status of the Agent. This method returns a string describing the status, like for example ``STARTED''.

initAgent

Initializes the Agent. This method does not call the initAgent method of the Agent directly, instead it creates a thread that calls the initAgentReal of the AgentLoader. This method calls then the initAgent on the Agent. This has to be done to call all Agent method in its own thread group. After starting this thread the AgentLoader waits at maximum the time given in the timeout variable like when instantiating an Agent. When the Agent´s initAgent method needs more time, the AgentLoader prints an error message on the screen to inform the system administrator about it.

initAgentReal

This method calls the initAgent method of the Agent. It is called by the thread created in the initAgent method as mentioned before. Before calling the initAgent method of the Agent it sets the status to ``INITIALIZING'' and after finishing to ``INITIALIZED''.

startAgent

Starts the Agent. It uses the same mechanism as the initAgent method and creates a Thread that calls the method startAgentReal. It then waits until the Agent has started or a timeout occurred.

startAgentReal

This method calls the startAgent method of the Agent. It is called by the thread created in the startAgent method of the AgentLoader. Before calling the startAgent method of the Agent it sets the status to ``STARTING'' and after finishing to ``STARTED''.

stopAgent

The routine to stop the Agent is different as the init and start routines. In some special cases it is necessary that the stopAgent method of the AgentLoader (and the System) returns to enable the Agent to stop at all. When an Agent calls the move method of a communication service, it should be stopped and then transfered to another System. While being blocked at the call of the move method, the Agent is not able to stop itself. But the System waits in its prepareToMove method until it is stopped or the timeout is reached. This has to be done asynchronously. For this reason creates the stopAgent method a thread which will then stop the Agent, starts the thread and exits. The thread calls the stopAgentReal method as the others before, but then waits for the Agent to be stopped and sets the status accordingly. The last two steps are normally done by the stopAgent method, but have to be done in the thread to do not block the method. The Agent provides a method isExecuting which returns true if the Agent is currently executing a method. The thread loops as long as the Agent is executing its method. When the Agent has stopped executing, the status is set to ``STOPPED''.

stopAgentReal

This method calls the suspendAgent method of the Agent. It is called by the thread created by the stopAgent method of the AgentLoader. Before calling the suspendAgent method it sets the status of the Agent to ``STOPPING''.

concludeAgent

The concludeAgent method concludes an Agent using the same mechanism as the stopAgent method. It creates a thread which calls the concludeAgentReal method and then waits until the Agent has concluded. The Agent is terminated, when its thread does no longer execute, which can be watched with the method isAlive of the thread class. When the Agent has terminated its status is set to ``CONCLUDED''.

concludeAgentReal

This method calls the terminateAgent method of the Agent. It is called by the thread created by the concludeAgent method of the AgentLoader. Before calling the terminateAgent method it sets the status of the Agent to ``CONCLUDING''.

handleAgentMessage

When a message is sent to the Agent the communication service calls this method to let the message be processed. Messages are calls to methods encapsulated into the AgentMessage object. The AgentLoader already has a hash table of the available methods to call messages on. It retrieves the AgentMethod object fitting to the message name, which is the same as the method name (without the leading ``handle''). It invokes the method and puts the result into an AgentResponse object which is returned then. When an exception occurs the corresponding error code is set into the AgentResponse object.