AgentRunner (pogamut-base 3.8.1-SNAPSHOT API)

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

All Implemented Interfaces:

IAgentRunner<AGENT,PARAMS>
```
public abstract class AgentRunner<AGENT extends IAgent,PARAMS extends IAgentParameters>
extends 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'.
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 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 boolean`	`killingAgents` Whether we're currently killing all agents...
`protected Object`	`killingAgentsMutex` Guards `killingAgents` access.
`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 `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 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

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

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

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`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.
`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(List<AGENT> agents)` This method is called whenever start/pause/resume of the single agent fails to clean up.
`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 `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(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(Logger log)`
`AgentRunner<AGENT,PARAMS>`	`setLogLevel(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.
`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... agentParameters)` Start an agent instance configured with 'agentsParameters'.
`protected List<AGENT>`	`startAgentWithParams(boolean fillDefaults, PARAMS... params)` This method should be internally used to create and start the batch of agent instances.
`protected 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 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 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.
  - killingAgents
```
protected boolean killingAgents
```
    Whether we're currently killing all agents...
  - killingAgentsMutex
```
protected Object killingAgentsMutex
```
    Guards killingAgents access.
  - listener
```
protected cz.cuni.amis.utils.flag.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 Logger getLog()
```
  - setLog
```
public AgentRunner<AGENT,PARAMS> setLog(Logger log)
```
  - startAgent
```
public AGENT startAgent()
                 throws cz.cuni.amis.utils.exception.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:
    
    cz.cuni.amis.utils.exception.PogamutException
  - startAgents
```
public List<AGENT> startAgents(int count)
                        throws cz.cuni.amis.utils.exception.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:
    
    cz.cuni.amis.utils.exception.PogamutException
  - startAgents
```
public List<AGENT> startAgents(PARAMS... agentParameters)
                        throws cz.cuni.amis.utils.exception.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.
    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!
    
    Specified by:
    
    startAgents in interface IAgentRunner<AGENT extends IAgent,PARAMS extends IAgentParameters>
    
    Returns:
    
    list of started agents
    
    Throws:
    
    cz.cuni.amis.utils.exception.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(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 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 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(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(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 by the factory.
    May be utilized by the GaviaLib user to inject additional code into the runner.
    
    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 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:
    
    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 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:
    
    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 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(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 -

Class AgentRunner<AGENT extends IAgent,PARAMS extends IAgentParameters>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

mutex

factory

log

defaultLogLevel

consoleLogging

latch

agents

killed

main

killingAgents

killingAgentsMutex

listener

Constructor Detail

AgentRunner

Method Detail

getLog

setLog

startAgent

startAgents

startAgents

isPausing

setPausing

isMain

setMain

setLogLevel

setConsoleLogging

startAgentWithParams

startAgentWithParamsMain

newDefaultAgentParameters

newAgentId

fillInDefaults

fillInDefaults

createAgentWithParams

startAgent

killAgents

killAgent

preInitHook

preStartHook

postStartHook

preResumeHook

postStartedHook