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

All Known Implementing Classes:

AgentRunner

public interface IAgentRunner<AGENT extends IAgent,PARAMS extends IAgentParameters>

Utility interface for classes that can instantiate & start (possibly multiple) agents at once. All agents must be of the same class though. Note that this usually is not a problem as the agent class is a shell that may contain arbitrary agent's logic implementations. (If it proves to be a problem, check whether there is a suitable implementation of the IMultipleAgentRunner implementation that you can use.)

Every implementor is instantiated with default values that should be passed into the agent when no other parameters are provided. Therefore you may use startAgent() to start agent with default params, or startAgents(int) and startAgents(IAgentParameters...) where you may specify your own params.

Note that the IAgentRunner 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 IAgentRunner (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 they start and resume them at once when all agents have been instantiated.

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

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 setMain(boolean) with 'true' and the runner will behave differently. (Note that all startAgent methods will block!)

Author:

jimmy

Method Summary

boolean	isMain() Whether the runner is set to provide 'main' functionality (see the Javadoc for the whole class).
boolean	isPausing() Tells, whether the pausing behavior is enabled.
IAgentRunner<AGENT,PARAMS>	setMain(boolean state) Sets 'main' functionality (see the Javadoc for the whole class).
IAgentRunner<AGENT,PARAMS>	setPausing(boolean state) Sets the pausing behavior.
AGENT	startAgent() Starts the agent by providing default parameters (defined during the construction of the implementor).
List<AGENT>	startAgents(int count) Starts agents by providing every one of them with default parameters (defined during the construction of the implementor).
List<AGENT>	startAgents(PARAMS... agentsParameters) Start an agent instance configured with 'agentsParameters'.

Method Detail

startAgent

AGENT startAgent()
                                throws cz.cuni.amis.utils.exception.PogamutException

Starts the agent by providing default parameters (defined during the construction of the implementor).

Returns:

agent instance configured with default parameters that has been started

Throws:

cz.cuni.amis.utils.exception.PogamutException

startAgents

List<AGENT> startAgents(int count)
                                       throws cz.cuni.amis.utils.exception.PogamutException

Starts agents by providing every one of them with default parameters (defined during the construction of the implementor).

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

Parameters:

count - how many agents should be started

Returns:

list of started agents

Throws:

cz.cuni.amis.utils.exception.PogamutException

startAgents

List<AGENT> startAgents(PARAMS... agentsParameters)
                                       throws cz.cuni.amis.utils.exception.PogamutException

Start an agent instance configured with 'agentsParameters'. The length of the 'agentsParameters' array determines how many agents are going to be started.

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

WARNING: if you want to use this method, you have to carefully type your runner instance, i.e., provide java-generic <AGENT_CLASS> information, otherwise Java won't compile your code correctly!

Parameters:

agentsParameters -

Returns:

list of started agents

Throws:

cz.cuni.amis.utils.exception.PogamutException

setPausing

IAgentRunner<AGENT,PARAMS> 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

IAgentRunner<AGENT,PARAMS> setMain(boolean state)

Sets 'main' functionality (see the Javadoc for the whole class).

Parameters:

state -

Returns:

isMain

boolean isMain()

Whether the runner is set to provide 'main' functionality (see the Javadoc for the whole class).

Returns: