cz.cuni.amis.pogamut.base.agent.utils.runner.impl
Class AgentRunner<AGENT extends IAgent,PARAMS extends IAgentParameters>

java.lang.Object
  cz.cuni.amis.pogamut.base.agent.utils.runner.impl.AgentRunner<AGENT,PARAMS>

All Implemented Interfaces:

IAgentRunner<AGENT,PARAMS>

Direct Known Subclasses:

UT2004AnalyzerRunner, UT2004BotRunner, UT2004ObserverRunner, UT2004ServerRunner

public abstract class AgentRunner<AGENT extends IAgent,PARAMS extends IAgentParameters>
extends java.lang.Object
implements IAgentRunner<AGENT,PARAMS>

BASIC USAGE

Class used for starting the agent with certain default parameters. This class can't be used alone as it is abstract. That's because the GaviaLib does not provide any concrete agent implementation you may instance. Instead, the GaviaLib must be used together with some environment-Pogamut bridge that defines a concrete IAgent with concrete IAgentParameters.

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), AgentRunner#preResumeHook(IAgent[]), postStartHook(IAgent) and AgentRunner#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).

Additional features:

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

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.

USING AgentRunner FROM THE MAIN METHOD

There is one problem using Pogamut agents that comes from the decision to use JMX for the agents management. If you start the agent in the main method and terminates it at some point in time - the JVM will not exit. That's because of the rmi registry daemon thread that will hang up in the air preventing JVM from termination. This can be handled by calling PogamutPlatform.close() in the end, that shuts down the rmi registry.

If you happen to need to use AgentRunner from the main method, do not forget to call setMain(boolean) with param 'true'.

Field Summary

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

Constructor Summary

AgentRunner(IAgentFactory<AGENT,PARAMS> factory)
The runner needs the 'factory' so it know how to construct (instantiate) new agents.

Method Summary

protected AGENT	createAgentWithParams(PARAMS params) Method that is used by AgentRunner#startAgentWithParams(IAgentParameters[]) to instantiate new agents.
protected void	fillInDefaults(PARAMS params) Fills defaults parameters into the 'params' by using newDefaultAgentParameters().
protected void	fillInDefaults(PARAMS[] paramsArray) Fills defaults parameters into every 'params' of the array by using newDefaultAgentParameters(), i.e., we're creating a new default parameters for every 'params' from the array.
java.util.logging.Logger	getLog()
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.
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(java.util.List<AGENT> agents) This method is called whenever start/pause/resume of the single agent fails to clean up.
protected IAgentId	newAgentId(java.lang.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(java.util.List<AGENT> agents) Custom hook called after all the agents have been instantiated by the factory and started with IAgent.start().
protected void	postStartHook(AGENT agent) Custom hook called after the agent is instantiated by the factory and started with IAgent.start().
protected void	preInitHook() Custom hook called before all the agents are going to be instantiated by the factory.
protected void	preResumeHook(java.util.List<AGENT> agents) Custom hook called only iff isPausing().
protected void	preStartHook(AGENT agent) Custom hook called after the agent is instantiated by the factory and before the IAgent.start() is called.
AgentRunner<AGENT,PARAMS>	setConsoleLogging(boolean enabled) Allows you to disable/enable default console logging for the agent.
AgentRunner<AGENT,PARAMS>	setLog(java.util.logging.Logger log)
AgentRunner<AGENT,PARAMS>	setLogLevel(java.util.logging.Level logLevel) Sets default logging level for newly created agents (default is Level.WARNING).
AgentRunner<AGENT,PARAMS>	setMain(boolean state) Sets 'main' functionality (see the Javadoc for the whole class).
AgentRunner<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).
protected void	startAgent(AGENT agent) Method that is used by AgentRunner#startAgentWithParams(IAgentParameters[]) to start newly created agent.
java.util.List<AGENT>	startAgents(int count) Starts agents by providing every one of them with default parameters (defined during the construction of the implementor).
java.util.List<AGENT>	startAgents(PARAMS... agentParameters) Start an agent instance configured with 'agentsParameters'.
protected java.util.List<AGENT>	startAgentWithParams(boolean fillDefaults, PARAMS... params) This method should be internally used to create and start the batch of agent instances.
protected java.util.List<AGENT>	startAgentWithParamsMain(boolean fillDefaults, PARAMS... params) E.g.

Methods inherited from class java.lang.Object

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

Field Detail

mutex

protected java.lang.Object mutex

Mutex that synchronize killing of agents due to a failure.

factory

protected IAgentFactory<AGENT extends IAgent,PARAMS extends IAgentParameters> factory

Used to instantiate new agents.

log

protected java.util.logging.Logger log

Use to log stuff.

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

defaultLogLevel

protected java.util.logging.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 java.util.concurrent.CountDownLatch latch

Latch where we're awaiting till all agents finishes.

agents

protected java.util.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 FlagListener<IAgentState> listener

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

Constructor Detail

AgentRunner

public AgentRunner(IAgentFactory<AGENT,PARAMS> factory)

The runner needs the 'factory' so it know how to construct (instantiate) new agents.

Parameters:

factory - preconfigured factory that is going to be used to produce new instances of agents

Method Detail

getLog

public java.util.logging.Logger getLog()

setLog

public AgentRunner<AGENT,PARAMS> setLog(java.util.logging.Logger log)

startAgent

public AGENT startAgent()
                                throws PogamutException

Description copied from interface: IAgentRunner

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

Specified by:

startAgent in interface IAgentRunner<AGENT extends IAgent,PARAMS extends IAgentParameters>

Returns:

agent instance configured with default parameters that has been started

Throws:

PogamutException

startAgents

public java.util.List<AGENT> startAgents(int count)
                                                 throws PogamutException

Description copied from interface: IAgentRunner

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.

Specified by:

startAgents in interface IAgentRunner<AGENT extends IAgent,PARAMS extends IAgentParameters>

Parameters:

count - how many agents should be started

Returns:

list of started agents

Throws:

PogamutException

startAgents

public java.util.List<AGENT> startAgents(PARAMS... agentParameters)
                                                 throws PogamutException

Description copied from interface: IAgentRunner

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.

Specified by:

startAgents in interface IAgentRunner<AGENT extends IAgent,PARAMS extends IAgentParameters>

Returns:

list of started agents

Throws:

PogamutException

isPausing

public boolean isPausing()

Description copied from interface: IAgentRunner

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

Returns:

state of the pausing behavior

setPausing

public AgentRunner<AGENT,PARAMS> setPausing(boolean state)

Description copied from interface: IAgentRunner

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

Returns:

this instance

isMain

public boolean isMain()

Description copied from interface: IAgentRunner

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

Specified by:

isMain in interface IAgentRunner<AGENT extends IAgent,PARAMS extends IAgentParameters>

Returns:

setMain

public AgentRunner<AGENT,PARAMS> setMain(boolean state)

Description copied from interface: IAgentRunner

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

Specified by:

setMain in interface IAgentRunner<AGENT extends IAgent,PARAMS extends IAgentParameters>

Returns:

setLogLevel

public AgentRunner<AGENT,PARAMS> setLogLevel(java.util.logging.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 AgentRunner<AGENT,PARAMS> 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:

startAgentWithParams

protected java.util.List<AGENT> startAgentWithParams(boolean fillDefaults,
                                                     PARAMS... params)

This method should be internally used to create and start the batch of agent instances.

Parameters:

fillDefaults - whether the method should fill default values into the 'params'

params -

Returns:

startAgentWithParamsMain

protected java.util.List<AGENT> startAgentWithParamsMain(boolean fillDefaults,
                                                         PARAMS... params)

E.g. startAgentWithParams(boolean, IAgentParameters[]) but provides the blocking mechanism.

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

newAgentId

protected IAgentId newAgentId(java.lang.String name)

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

Parameters:

name -

fillInDefaults

protected void fillInDefaults(PARAMS params)

Fills defaults parameters into the 'params' by using newDefaultAgentParameters().

Parameters:

params -

fillInDefaults

protected void fillInDefaults(PARAMS[] paramsArray)

Fills defaults parameters into every 'params' of the array by using newDefaultAgentParameters(), i.e., we're creating a new default parameters for every 'params' from the array.

Parameters:

params -

createAgentWithParams

protected AGENT createAgentWithParams(PARAMS params)

Method that is used by AgentRunner#startAgentWithParams(IAgentParameters[]) to instantiate new agents. Uses 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 AgentRunner#startAgentWithParams(IAgentParameters[]) to start newly created agent.

Parameters:

agent -

killAgents

protected void killAgents(java.util.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 PogamutException

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

May be utilized by the GaviaLib user to inject additional code into the runner.

Throws:

PogamutException

preStartHook

protected void preStartHook(AGENT agent)
                     throws PogamutException

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

May be utilized by the GaviaLib user to inject additional code into the runner.

Parameters:

agent -

Throws:

PogamutException

postStartHook

protected void postStartHook(AGENT agent)
                      throws PogamutException

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

May be utilized by the GaviaLib user to inject additional code into the runner.

Parameters:

agent -

Throws:

PogamutException

preResumeHook

protected void preResumeHook(java.util.List<AGENT> agents)

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

May be utilized by the GaviaLib user to inject additional code into the runner.

Parameters:

agents -

postStartedHook

protected void postStartedHook(java.util.List<AGENT> agents)

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

May be utilized by the GaviaLib user to inject additional code into the runner.

Parameters:

agents -