cz.cuni.amis.pogamut.base.agent.utils.runner
Interface IMultipleAgentRunner<AGENT extends IAgent,PARAMS extends IAgentParameters,MODULE extends GuiceAgentModule>

Type Parameters:

AGENT - common ancestor of all agents that are going to be started

PARAMS -

MODULE -

All Known Implementing Classes:

MultipleAgentRunner, MultipleUT2004BotRunner

public interface IMultipleAgentRunner<AGENT extends IAgent,PARAMS extends IAgentParameters,MODULE extends GuiceAgentModule>

Utility interface for classes that can instantiate & start (possibly multiple) agents at once. Agents may be also of different classes.

Every implementor is instantiated with default values that should be passed into the agent when no other parameters are provided.

Note that the IMultipleAgentRunner utilize IAgentParameters.assignDefaults(IAgentParameters) to fill missing fields into IAgentParameters which allows you to instantiate the IAgentParameters implementor with custom data leaving the rest to the IMultipleAgentRunner (eases the pain of starting agents greatly).

The interface also provides a "synchronizing" feature via setPausing(boolean). If set true, the runner will pause all agents after their construction and resume them at once when all agents has been instantiated.

Pausing behavior is disabled (== set to false) as default.

NOTE: it might seem strange why there exists IAgentRunner and IMultipleAgentRunner interfaces when IAgentRunner can be implemented using IMultipleAgentRunner. Even though that is true, it would be infeasible as IMultipleAgentRunner always needs to instantiate new factories for every IAgentDescriptor passed (unlike the IAgentRunner that may utilize the same factory instance repeatedly).

USING FROM THE main(String[] args) METHOD

Starting agents from the main method requires special care:

1. if one of your agents fails, all agents should be closed (simulation has been broken)
2. when all your agent dies, Pogamut platform should be closed (so the JVM could terminate)

Previous two points are not-so-easy to implement (and we won't bother you with them). Instead, you could just call IAgentRunner.setMain(boolean) with 'true' and the runner will behave differently. (Note that all startAgent methods will block!)

Method Summary

boolean	isMain() Whether the runner is set to provide 'main' functionality.
boolean	isPausing() Tells, whether the pausing behavior is enabled.
IMultipleAgentRunner<AGENT,PARAMS,MODULE>	setMain(boolean state) Sets 'main' functionality.
IMultipleAgentRunner<AGENT,PARAMS,MODULE>	setPausing(boolean state) Sets the pausing behavior.
java.util.List<AGENT>	startAgents(IAgentDescriptor<PARAMS,MODULE>... agentDescriptors) Start an agent instances described by 'agentDescriptors'.

Method Detail

startAgents

java.util.List<AGENT> startAgents(IAgentDescriptor<PARAMS,MODULE>... agentDescriptors)

Start an agent instances described by 'agentDescriptors'. The method creates a new factory for every descriptor (as it must use different agent modules). The length of the 'agentDescriptors' array together with IAgentDescriptor.getCount() determines how many agents are going to be instantiated and started.

Note that if any instantiation/start of the agent fails, all agents are killed before the method throws the exception.

Parameters:

agentsParameters -

Returns:

array of started agents

setPausing

IMultipleAgentRunner<AGENT,PARAMS,MODULE> setPausing(boolean state)

Sets the pausing behavior.

If set true, the runner will pause all agents after their construction and resume them at once whenever all agents has been successfully started.

Parameters:

state -

Returns:

this instance

isPausing

boolean isPausing()

Tells, whether the pausing behavior is enabled.

If enabled, the runner will pause all agents after their construction and resume them at once whenever all agents has been instantiated.

Returns:

state of the pausing behavior

setMain

IMultipleAgentRunner<AGENT,PARAMS,MODULE> setMain(boolean state)

Sets 'main' functionality.

Parameters:

state -

Returns:

isMain

boolean isMain()

Whether the runner is set to provide 'main' functionality.

Returns: