cz.cuni.amis.pogamut.base.agent
Interface IAgent

All Superinterfaces:

IComponent, IComponentAware, IControllable

All Known Subinterfaces:

IAgent3D, IEmbodiedAgent, IGhostAgent, IObservingAgent, IUnrealBot, IUnrealServer<BOT>, IUT2004Analyzer, IUT2004AnalyzerObserver, IUT2004Bot, IUT2004Observer, IUT2004Server, IWorldServer<A>

All Known Implementing Classes:

AbstractAgent, AbstractAgent3D, AbstractEmbodiedAgent, AbstractGhostAgent, AbstractObservingAgent, AbstractUT2004Observer, AbstractUT2004Server, AbstractWorldServer, Agent3DJMXProxy, AgentJMXProxy, BotJMXProxy, GhostAgentJMXProxy, NativeUnrealBotAdapter, NativeUT2004BotAdapter, TestAgents.NetworkLoggingAgent, UT2004Analyzer, UT2004AnalyzerObserver, UT2004AnalyzerObsStats, UT2004Bot, UT2004Observer, UT2004Server

@MXBean
public interface IAgent
extends IControllable, IComponent, IComponentAware

MXBean interface - serves the purpose only to JMX, you should always derive your agent from at least AbstractAgent, even though it's not enforced right now it may be in the future!

The key component of the agent is EventBus. The agent is propagating system events like "state of the agent has changed", "agent is starting", "agent is running", "agent name has changed", etc. See ComponentBus for information how the system is working - notice that the best way how to see what events are propagated - attach a listener to "ISystemClass.class" into the event bus and log all events that are being broadcasted.

Method Summary

IAgentId	getComponentId() Returns agent id - contains also a human-readable name that can be changed
Folder	getIntrospection() Returns folder with introspection information.
IAgentLogger	getLogger() Returns AgentLogger for the instance allowing creating new log categories or adding new handlers to them.
java.lang.String	getName() Returns human-readable agent's name.
ImmutableFlag<IAgentState>	getState() Returns the state of the agent (whether it's running / dead / etc.).
void	kill() Stops the agent (unconditionally), closing whatever connection it may have, this method must be non-blocking + interrupting all the communication, logic or whatever threads the agent may have.
void	pause() This should pause the the agent.
void	resume() This should resume the logic of the agent.
void	start() Attempt to launch the agent.
void	startPaused() Attempt to launch the agent.
void	stop() Attempt to stop the agent, usually meaning dropping all running flags and see whether it will stop automatically.

Methods inherited from interface cz.cuni.amis.pogamut.base.component.IComponentAware

getEventBus

Method Detail

getName

java.lang.String getName()

Returns human-readable agent's name.

Do not use as unique id of the agent:

1) the name might change during the life of agent

2) we do not ensure it's unique

Use getComponentId().getToken() instead!

Use getComponentId().getName().setFlag() to change the name of the agent.

Returns:

getComponentId

IAgentId getComponentId()

Returns agent id - contains also a human-readable name that can be changed

Specified by:

getComponentId in interface IComponent

Returns:

getLogger

IAgentLogger getLogger()

Returns AgentLogger for the instance allowing creating new log categories or adding new handlers to them.

Returns:

getState

ImmutableFlag<IAgentState> getState()

Returns the state of the agent (whether it's running / dead / etc.).

Note that the type AgentState wraps two things:

• AgentStateType that describes the type of the state (init, running, paused, etc.)
• String description of the state

Returns:

getIntrospection

Folder getIntrospection()

Returns folder with introspection information. Useful for showing agent model variables and parameters.

Returns:

Folder with introspection info

start

void start()
           throws ComponentCantStartException

Attempt to launch the agent. If it does not throw an exception, agent has been successfully started, also the state of the agent state is changed into Running state.

This method is not suitable for simultaneous start of multiple agents that should start working together in the environment. (I.e., during tournaments of agents when you need to synchronize their start in the environment.) In such cases use startPaused() and then multiple threads+barrier to execute resume() of all agents at once.

Specified by:

start in interface IControllable

Throws:

ComponentCantStartException

startPaused

void startPaused()
                 throws ComponentCantStartException

Attempt to launch the agent. If it does not throw an exception, agent has been successfully started (paused).

In contrast with start() this method will initialize the agent inside the environment but pauses it after the start (i.e., its reasoning should not run, the action should not do any decisions).

To fully start the agent, you need to resume() it.

It is designed to provide safe synchronization of multiple agent simulations when you need to start the reasoning of agents synchronously.

Throws:

ComponentCantStartException

pause

void pause()
           throws ComponentCantPauseException

This should pause the the agent. If it does not throw an exception, agent has been successfully started, also the state of the agent state is changed into Paused state.

If your agent can't be paused, throw OperationNotSupportedException.

Throws:

ComponentCantPauseException

resume

void resume()
            throws ComponentCantResumeException

This should resume the logic of the agent. If it does not throw an exception, agent has been successfully resumed, also the state of the agent state is changed into Running state.

If your agent can't be paused therefore can't be resumed, throw OperationNotSupportedException.

Throws:

ComponentCantResumeException

stop

void stop()
          throws ComponentCantStopException

Attempt to stop the agent, usually meaning dropping all running flags and see whether it will stop automatically. This method may be blocking. If it does not throw the exception, the agent has been successfully stopped, also the state of the agent is changed into End state.

If the stop can not complete - it must automatically call kill() method.

Specified by:

stop in interface IControllable

Throws:

ComponentCantStopException

kill

void kill()

Stops the agent (unconditionally), closing whatever connection it may have, this method must be non-blocking + interrupting all the communication, logic or whatever threads the agent may have.

After calling kill() method, the only method that may be called is getState() to examine state of the agent.

This also equals to "exception happened outside the agent" and "IFatalErrorEvent should be propagated inside the agent"

Specified by:

kill in interface IControllable