sema
Class Agent.Action

java.lang.Object
  sema.Agent.Action

Direct Known Subclasses:

ActToSatisfaction, CommunicatingAgent.Discussion, EatingAgent.Consuming, EatingAgent.EatElement, GrowingAgent.Growing, MovingAgent.Errer, MovingAgent.MoveTo, NewAgent.NewAction

Enclosing class:

Agent

public class Agent.Action

extends java.lang.Object

Basic action of an agent. It provides a simple way to spread the execution of an action during simulated time. In fact, the execution of a method is instantanious in the virtual world (necessary to disconnect virtual and real time, and to allow agents to evolve simultanely). However, to be coherent from the point of view of the simulation, an action must so be divided into shorter steps. The event is the smallest possible action to be executed by the engine.
An Action is a super event repeting itself, but before every call to an action method (that is: step(), resumedStep() or firstStep()), it checks whether it can execute. If not, the whenRefused() method will be called, and the action will end (no more event will be executed from this action).
When an action is executing, the corresponding method will be called: firstStep() if it is the first event of the action, step() if we are in the normal loop, and resumedStep() if it wakes up from a paused state.
You can pause (means: not executing any events or methods for this action) an action at anytime with pause(), but before pausing, the action will call whenPaused() to prepare the pause. You can resume an action with resume(). It will return false if failed to resume, that is if the action is ended after the resume attempt. If a resume is done when the action was paused, resumedStep() is executed. This encapsulation of actions provides an easy way to define behaviours. The advantages of the action are the possibility to easily undertake several actions at the same time for each agent and the automatic management of the parrallelism and steps.

See Also:

Agent.registerAction(sema.Agent.Action), Agent.unregisterAction(sema.Agent.Action)

Constructor Summary

Agent.Action()

Agent.Action(double t)
Creates a new action that will begin in t simulated units.

Method Summary

protected void	close() Closing method, always executed as the last code of an action that has begun.
protected float	firstStep() Called at the begin of the action.
boolean	hasBegun() Returns true if the action has begun.
boolean	isDisabled() Returns true if the action has been definitively disabled, by the stop() method, because the action ended normally, or because it was refused by @link accepAction(Agent.Action).
boolean	isPaused() Returns true if the action is currently paused.
void	pause() Pauses the action, which can be resumed with resume().
void	pause(double maxWaiting) Pauses the action for at most the given delay.
boolean	resume() Resumes an action previously paused.
protected float	resumedStep() Called when the action is resumed.
boolean	start() Starts the action 'immediatly' (from the agent point of view).
boolean	start(double t) Starts the action in t simulated unit.
protected float	step() Body of the action.
void	stop() Stops the action and disables it.
protected void	whenEnd() Called when a negative value has been returned by one of the step methods.
protected void	whenPaused() Called when the action is paused.
protected void	whenRefused() Called before stopping the action because it has been refused by Agent.acceptAction(Agent.Action).
protected void	whenStartInPause() Called when the action is started with the start method, but was previously paused.
protected void	whenStopped() Called when the action is going to be stopped, because of a call to the stop() method.

Methods inherited from class java.lang.Object

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

Constructor Detail

Agent.Action

public Agent.Action()

Agent.Action

public Agent.Action(double t)

Creates a new action that will begin in t simulated units.

Method Detail

start

public final boolean start()

Starts the action 'immediatly' (from the agent point of view). To be coherent with the simulation of the agent, it waits for 'delay' simulated units. Does nothing and returns false if already started, paused or stopped.

start

public final boolean start(double t)

Starts the action in t simulated unit. Does nothing and returns false if already started or stopped. In the special case where start is called as the action where previously paused, the whenStartInPause method is called.

isDisabled

public final boolean isDisabled()

Returns true if the action has been definitively disabled, by the stop() method, because the action ended normally, or because it was refused by @link accepAction(Agent.Action).

isPaused

public final boolean isPaused()

Returns true if the action is currently paused.

hasBegun

public final boolean hasBegun()

Returns true if the action has begun.

pause

public final void pause()

Pauses the action, which can be resumed with resume(). The whenPaused() method is called before it is effectively paused.

pause

public final void pause(double maxWaiting)

Pauses the action for at most the given delay.

See Also:

pause().

stop

public final void stop()

Stops the action and disables it. Before disabling, the whenStopped() method is called.

resume

public final boolean resume()

Resumes an action previously paused. Returns true if the action is active after the call (even if it was already active before).

firstStep

protected float firstStep()

Called at the begin of the action. By default, calls step().

resumedStep

protected float resumedStep()

Called when the action is resumed. By default, calls step().

whenStartInPause

protected void whenStartInPause()

Called when the action is started with the start method, but was previously paused. By default, it performs the normal action of start. This is a technical method that should be ignored, excepted for special actions.

whenPaused

protected void whenPaused()

Called when the action is paused. By default, it does nothing.

whenStopped

protected void whenStopped()

Called when the action is going to be stopped, because of a call to the stop() method. The close() method will be called after this one.

whenRefused

protected void whenRefused()

Called before stopping the action because it has been refused by Agent.acceptAction(Agent.Action).

whenEnd

protected void whenEnd()

Called when a negative value has been returned by one of the step methods. This is the normal end of the action, that will generally mean that the goal has been reeached.

close

protected void close()

Closing method, always executed as the last code of an action that has begun.

step

protected float step()

Body of the action. This is the main code to execute. The value returned is the time (in simulated units) to wait before the next call to the body. A negative value means that the action must end. The main idea of this function is that its execution is intended to be spread on a time that should be coherent with the simulation.

Typically, a moving agent that is walking would make a step towards a direction then another, and theses steps would be differents calls to step(). Internal variables should be stocked in the action to allow a good step by step execution.