cz.cuni.amis.pogamut.base.agent.utils.runner.impl

Class MultipleAgentRunner<AGENT extends IAgent,PARAMS extends IAgentParameters,MODULE extends GuiceAgentModule>

java.lang.Object

cz.cuni.amis.pogamut.base.agent.utils.runner.impl.MultipleAgentRunner<AGENT,PARAMS,MODULE>

All Implemented Interfaces:

IMultipleAgentRunner<AGENT,PARAMS,MODULE>

public abstract class MultipleAgentRunner<AGENT extends IAgent,PARAMS extends IAgentParameters,MODULE extends GuiceAgentModule>
extends Object
implements IMultipleAgentRunner<AGENT,PARAMS,MODULE>

Class used for starting the agent with certain default parameters.

The class is similar to the MultipleAgentRunner but implements different interface (IMultipleAgentRunner), that is, it allows to start different classes of agents at once. In fact it uses MultipleAgentRunner to do the job.

TODO!!! Additional features:

• AgentRunner.setLogLevel(Level) - allows you to set default logging level for the newly created agent (default Level.WARNING)
• AgentRunner.setConsoleLogging(boolean) - allows you to attach default console logger (via IAgentLogger.addDefaultConsoleHandler())

The class provides start-synchronization behavior of respective agents via setPausing(boolean). For more information see IAgentRunner.setPausing(boolean).

Note that the class also provides you with hook-methods that can be utilized to additionally configure agent instances as they are created and started. These are preInitHook(), preStartHook(IAgent), MultipleAgentRunner#preResumeHook(IAgent[]), postStartHook(IAgent) and MultipleAgentRunner#postStartedHook(IAgent[]).

This class is (almost complete) implementation that can instantiate and start one or multiple agents (of the same class). The only thing that is left to be implemented is newDefaultAgentParameters() that are used to IAgentParameters.assignDefaults(IAgentParameters) into user provided parameters (if any of are provided).

This runner is based on the IAgentFactory interface that is utilized to create new instances. It is advised that concrete agent runners hides this fact from the user instantiating the factory themselves so the user must not dive deep into GaviaLib architecture.

Author:

Jimmy

Field Summary

Fields

Modifier and Type	Field and Description
protected List<AGENT>	agents List of started agents.
protected boolean	consoleLogging Whether the console logging is enabled as default.
protected Level	defaultLogLevel Default log level that is set to the agent after its instantiation.
protected boolean	killed Whether we had to kill all agents (i.e., some exception/failure has happened).
protected CountDownLatch	latch Latch where we're awaiting till all agents finishes.
protected cz.cuni.amis.utils.flag.FlagListener<IAgentState>	listener Listener that lowers the count on the latch (if reaches zero, start method resumes and closes the Pogamut platform), and watches for the agent's failure (MultipleAgentRunner#killAgents(IAgent[]) in this case).
protected Logger	log Use to log stuff.
protected boolean	main Whether we should provide 'main' feature.
protected Object	mutex Mutex that synchronize killing of agents due to a failure.

Constructor Summary

Constructors

Constructor and Description
MultipleAgentRunner()

Method Summary

Methods

Modifier and Type	Method and Description
protected AGENT	createAgentWithParams(IAgentFactory<AGENT,PARAMS> factory, PARAMS params) Method that is used by MultipleAgentRunner#startAgentWithParams(IAgentParameters[]) to instantiate new agents.
int	getAgentCount(IAgentDescriptor<PARAMS,MODULE>... agentDescriptors) Sums all IAgentDescriptor.getCount().
Logger	getLog()
boolean	isMain() Whether the runner is set to provide 'main' functionality.
boolean	isPausing() Tells, whether the pausing behavior is enabled.
protected void	killAgent(AGENT agent) Kills a single agent instance, called during clean up when start/pause/resume of the agent fails.
protected void	killAgents(List<AGENT> agents) This method is called whenever start/pause/resume of the single agent fails to clean up.
protected abstract IAgentFactory	newAgentFactory(MODULE agentModule) Creates a new factory for the given 'agentModule'.
protected IAgentId	newAgentId(String name) Creates new AgentId from the 'name' and unique number that is automatically generated from the ID.
protected abstract IAgentParameters	newDefaultAgentParameters() Method that is called to provide another default parameters for newly created agents.
protected void	postStartedHook(List<AGENT> agents) Custom hook called after all the agents have been instantiated by the MultipleAgentRunner#factory and started with IAgent.start().
protected void	postStartHook(AGENT agent) Custom hook called after the agent is instantiated and started with IAgent.start().
protected void	preInitHook() Custom hook called before all the agents are going to be instantiated.
protected void	preResumeHook(List<AGENT> agents) Custom hook called only iff isPausing().
protected void	preStartHook(AGENT agent) Custom hook called after the agent is instantiated and before the IAgent.start() is called.
MultipleAgentRunner<AGENT,PARAMS,MODULE>	setConsoleLogging(boolean enabled) Allows you to disable/enable default console logging for the agent.
MultipleAgentRunner<AGENT,PARAMS,MODULE>	setLog(Logger log)
MultipleAgentRunner<AGENT,PARAMS,MODULE>	setLogLevel(Level logLevel) Sets default logging level for newly created agents (default is Level.WARNING).
MultipleAgentRunner<AGENT,PARAMS,MODULE>	setMain(boolean state) Sets 'main' functionality.
MultipleAgentRunner<AGENT,PARAMS,MODULE>	setPausing(boolean state) Sets the pausing behavior.
protected void	startAgent(AGENT agent) Method that is used by MultipleAgentRunner#startAgentWithParams(IAgentParameters[]) to start newly created agent.
List<AGENT>	startAgents(IAgentDescriptor<PARAMS,MODULE>... agentDescriptors) Start an agent instances described by 'agentDescriptors'.
protected List<AGENT>	startAgentsMain(IAgentDescriptor<PARAMS,MODULE>... agentDescriptors)
protected void	startAgentsMain(IAgentDescriptor<PARAMS,MODULE> agentDescriptor, boolean pausingBehavior, List<AGENT> result) Overridden to provide the blocking mechanism.
protected List<AGENT>	startAgentsStandard(IAgentDescriptor<PARAMS,MODULE>... agentDescriptors)
protected void	startAgentsStandard(IAgentDescriptor<PARAMS,MODULE> agentDescriptor, List<AGENT> result) Starts all agents described by 'agentDescriptor', puts new agent instances into 'result'.

Methods inherited from class java.lang.Object

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

Field Detail

mutex

protected Object mutex

Mutex that synchronize killing of agents due to a failure.

log

protected Logger log

Use to log stuff.

WARNING: may be null! Always check it before logging!

defaultLogLevel

protected Level defaultLogLevel

Default log level that is set to the agent after its instantiation.

consoleLogging

protected boolean consoleLogging

Whether the console logging is enabled as default. (Default is TRUE.)

latch

protected CountDownLatch latch

Latch where we're awaiting till all agents finishes.

agents

protected List<AGENT extends IAgent> agents

List of started agents.

killed

protected boolean killed

Whether we had to kill all agents (i.e., some exception/failure has happened).

main

protected boolean main

Whether we should provide 'main' feature.

listener

protected cz.cuni.amis.utils.flag.FlagListener<IAgentState> listener

Listener that lowers the count on the latch (if reaches zero, start method resumes and closes the Pogamut platform), and watches for the agent's failure (MultipleAgentRunner#killAgents(IAgent[]) in this case).

Constructor Detail

MultipleAgentRunner

public MultipleAgentRunner()

Method Detail

setLog

public MultipleAgentRunner<AGENT,PARAMS,MODULE> setLog(Logger log)

getLog

public Logger getLog()

getAgentCount

public int getAgentCount(IAgentDescriptor<PARAMS,MODULE>... agentDescriptors)

Sums all IAgentDescriptor.getCount().

Parameters:

agentDescriptors -

Returns:

number of agents described by 'agentDescriptors'

newDefaultAgentParameters

protected abstract IAgentParameters newDefaultAgentParameters()

Method that is called to provide another default parameters for newly created agents.

Note that it might be the case, that some parameters can't be shared between agent instances, thus you might always need to provide a new parameters. This decision is up to you as an implementor (that means you must understand how these parameters are used by the particular agent, fail-safe behaviour is to always provide a new one).

Notice that the method does not require you to provide parameters of the type 'PARAMS' allowing you to provide any params as defaults.

Returns:

new default parameters

newAgentFactory

protected abstract IAgentFactory newAgentFactory(MODULE agentModule)

Creates a new factory for the given 'agentModule'. Called from within MultipleAgentRunner#startAgents(IAgentDescriptor, List) to obtain a factory for the IAgentDescriptor.getAgentModule().

Parameters:

module -

Returns:

new factory configured with 'agentModule'

startAgents

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

Description copied from interface: IMultipleAgentRunner

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.

Specified by:

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

Returns:

array of started agents

isPausing

public boolean isPausing()

Description copied from interface: IMultipleAgentRunner

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.

Specified by:

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

Returns:

state of the pausing behavior

setPausing

public MultipleAgentRunner<AGENT,PARAMS,MODULE> setPausing(boolean state)

Description copied from interface: IMultipleAgentRunner

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.

Specified by:

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

Returns:

this instance

isMain

public boolean isMain()

Description copied from interface: IMultipleAgentRunner

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

Specified by:

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

Returns:

setMain

public MultipleAgentRunner<AGENT,PARAMS,MODULE> setMain(boolean state)

Description copied from interface: IMultipleAgentRunner

Sets 'main' functionality.

Specified by:

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

Returns:

setLogLevel

public MultipleAgentRunner<AGENT,PARAMS,MODULE> setLogLevel(Level logLevel)

Sets default logging level for newly created agents (default is Level.WARNING).

If set to null, no level is set as default to the agent logger.

This probably violates the way how logging should be set up, but is more transparent for beginners.

Returns:

this instance

setConsoleLogging

public MultipleAgentRunner<AGENT,PARAMS,MODULE> setConsoleLogging(boolean enabled)

Allows you to disable/enable default console logging for the agent. (Default is TRUE.)

This probably violates the way how logging should be set up, but is more transparent for beginners.

Parameters:

enabled -

Returns:

startAgentsStandard

protected List<AGENT> startAgentsStandard(IAgentDescriptor<PARAMS,MODULE>... agentDescriptors)

startAgentsMain

protected List<AGENT> startAgentsMain(IAgentDescriptor<PARAMS,MODULE>... agentDescriptors)

startAgentsStandard

protected void startAgentsStandard(IAgentDescriptor<PARAMS,MODULE> agentDescriptor,
                       List<AGENT> result)

Starts all agents described by 'agentDescriptor', puts new agent instances into 'result'.

Does not catch exceptions (they are propagated by JVM as usual).

Parameters:

agentDescriptor -

result -

startAgentsMain

protected void startAgentsMain(IAgentDescriptor<PARAMS,MODULE> agentDescriptor,
                   boolean pausingBehavior,
                   List<AGENT> result)

Overridden to provide the blocking mechanism. (For more info see AgentRunner.startAgentWithParams(boolean, IAgentParameters...).

newAgentId

protected IAgentId newAgentId(String name)

Creates new AgentId from the 'name' and unique number that is automatically generated from the ID.

Parameters:

name -

createAgentWithParams

protected AGENT createAgentWithParams(IAgentFactory<AGENT,PARAMS> factory,
                          PARAMS params)

Method that is used by MultipleAgentRunner#startAgentWithParams(IAgentParameters[]) to instantiate new agents. Uses MultipleAgentRunner#factory to do the job. It assumes the params were already configured with defaults.

Parameters:

params -

Returns:

startAgent

protected void startAgent(AGENT agent)

Method that is used by MultipleAgentRunner#startAgentWithParams(IAgentParameters[]) to start newly created agent.

Parameters:

agent -

killAgents

protected void killAgents(List<AGENT> agents)

This method is called whenever start/pause/resume of the single agent fails to clean up.

Recalls killAgent(IAgent) for every non-null agent instance.

Parameters:

agents - some array elements may be null!

killAgent

protected void killAgent(AGENT agent)

Kills a single agent instance, called during clean up when start/pause/resume of the agent fails.

Parameters:

agent -

preInitHook

protected void preInitHook()
                    throws cz.cuni.amis.utils.exception.PogamutException

Custom hook called before all the agents are going to be instantiated.

Throws:

cz.cuni.amis.utils.exception.PogamutException

preStartHook

protected void preStartHook(AGENT agent)
                     throws cz.cuni.amis.utils.exception.PogamutException

Custom hook called after the agent is instantiated and before the IAgent.start() is called.

Parameters:

agent -

Throws:

cz.cuni.amis.utils.exception.PogamutException

postStartHook

protected void postStartHook(AGENT agent)
                      throws cz.cuni.amis.utils.exception.PogamutException

Custom hook called after the agent is instantiated and started with IAgent.start().

Parameters:

agent -

Throws:

cz.cuni.amis.utils.exception.PogamutException

preResumeHook

protected void preResumeHook(List<AGENT> agents)

Custom hook called only iff isPausing(). This method is called after all the agents have been instantiated by the MultipleAgentRunner#factory and resumed with IAgent.resume().

Parameters:

agents -

postStartedHook

protected void postStartedHook(List<AGENT> agents)

Custom hook called after all the agents have been instantiated by the MultipleAgentRunner#factory and started with IAgent.start().

Parameters:

agents -