bdi4jade.plan.planbody

Interface PlanBody

All Superinterfaces:

java.util.EventListener, GoalListener

All Known Implementing Classes:

AbstractPlanBody, BeliefGoalPlanBody, FSMPlanBody, ParallelActionPlanBody, ParallelGoalPlanBody, SequentialActionPlanBody, SequentialGoalPlanBody

public interface PlanBody
extends GoalListener

This interface defines a plan body, which specifies a set of steps to achieve a goal. It is part of a Plan, which in turn specifies different properties such as the goals that a plan can achieve or messages it can process. When a plan should be executed, a plan body is instantiated and run. A plan body is a GoalListener as it may dispatch goals during its execution and be notified when it is achieved (or learn it is not possible to achieve it).

Author:

Ingrid Nunes

Method Summary

Modifier and Type	Method and Description
void	block() Blocks this behaviour.
boolean	dispatchGoal(Goal goal) Dispatches a goal to be achieved.
boolean	dispatchSubgoal(Goal subgoal) Dispatches a subgoal to be achieved.
boolean	dispatchSubgoalAndListen(Goal subgoal) Dispatches a subgoal to be achieved and registers itself as a listener to receive a notification of the end of execution of the goal.
BeliefBase	getBeliefBase() Returns the belief base of the capability associated with the plan of this plan body.
Capability	getCapability() Returns the capability associated with the plan of this plan body.
Plan.EndState	getEndState() Returns the end state of the execution of this plan.
Goal	getGoal() Returns the goal to be achieved by this plan body.
GoalEvent	getGoalEvent() Returns a goal event from the queue.
GoalEvent	getGoalEvent(boolean block) Returns a goal event from the queue.
GoalEvent	getGoalEvent(long ms) Returns a goal event from the queue.
Plan	getPlan() Returns the Plan that is associated with this plan instance.
void	init(Plan plan, Intention intention) Initializes this plan body.
int	onEnd() This method is invoked just once after this behaviour has ended.
void	onStart() This method is executed just once before starting this plan body execution.
void	reset() Restores plan body initial state.
void	restart() Restarts a blocked behaviour.
void	start() Starts the execution of a plan body, a Behaviour, associated with this plan.
void	stop() Stops the plan body, a Behaviour, associated with this plan.

Methods inherited from interface bdi4jade.event.GoalListener

goalPerformed

Method Detail

block

void block()

Blocks this behaviour. It should be noticed that this method is NOT a blocking call: when it is invoked, the internal behaviour state is set to Blocked so that, as soon as the action() method returns, the behaviour is put into a blocked behaviours queue so that it will not be scheduled anymore. The behaviour is moved back in the pool of active behaviours when either a message is received or the behaviour is explicitly restarted by means of its restart() method. If this behaviour is a child of a CompositeBehaviour a suitable event is fired to notify its parent behaviour up to the behaviour composition hierarchy root.

See Also:

Behaviour.block()

dispatchGoal

boolean dispatchGoal(Goal goal)

Dispatches a goal to be achieved. It is added as a top level agent goal, that is, the dispatched goal is independent of the goal that this plan body is trying to achieve.

Parameters:

goal - the goal to be dispatched.

Returns:

true if the goal could be dispatched, false otherwise.

dispatchSubgoal

boolean dispatchSubgoal(Goal subgoal)

Dispatches a subgoal to be achieved. Dispatched subgoals are goals of an agent as long as the plan body that dispatched it is being executed.

Parameters:

subgoal - the subgoal to be dispatched.

Returns:

true if the goal could be dispatched, false otherwise.

dispatchSubgoalAndListen

boolean dispatchSubgoalAndListen(Goal subgoal)

Dispatches a subgoal to be achieved and registers itself as a listener to receive a notification of the end of execution of the goal.

Parameters:

subgoal - the subgoal to be dispatched.

Returns:

true if the goal could be dispatched, false otherwise.

getBeliefBase

BeliefBase getBeliefBase()

Returns the belief base of the capability associated with the plan of this plan body.

Returns:

the belief base containing the capability beliefs.

getCapability

Capability getCapability()

Returns the capability associated with the plan of this plan body.

Returns:

the capability.

getEndState

Plan.EndState getEndState()

Returns the end state of the execution of this plan.

Returns:

the end state of this plan, or null if it has not finished yet.

getGoal

Goal getGoal()

Returns the goal to be achieved by this plan body.

Returns:

the goal.

getGoalEvent

GoalEvent getGoalEvent()

Returns a goal event from the queue. If the queue is empty, the behavior associated with this plan instance is blocked.

Returns:

the goal event or null if the queue is empty.

getGoalEvent

GoalEvent getGoalEvent(boolean block)

Returns a goal event from the queue. If the queue is empty, the behavior associated with this plan instance is going to be blocked if the parameter passed to this method is true.

Parameters:

block - true if the behavior must be blocked if the queue is empty.

Returns:

the goal event or null if the queue is empty.

getGoalEvent

GoalEvent getGoalEvent(long ms)

Returns a goal event from the queue. If the queue is empty, the behavior associated with this plan instance is going to be blocked for the specified milliseconds.

Parameters:

ms - the maximum amount of time that the behavior must be blocked.

Returns:

the goal event or null if the queue is empty.

getPlan

Plan getPlan()

Returns the Plan that is associated with this plan instance.

Returns:

the plan.

init

void init(Plan plan,
          Intention intention)
   throws PlanInstantiationException

Initializes this plan body. It associates this plan body with a plan definition (Plan) and an Intention. If this plan body has already been initialized, this method throws a PlanInstantiationException.

Parameters:

plan - the plan associated this this plan body.

intention - the intention that this plan instance have to achieve.

Throws:

PlanInstantiationException - if this plan body has already been initialized.

onEnd

int onEnd()

This method is invoked just once after this behaviour has ended. Therefore, it acts as an epilog for the task represented by this plan body. Note that onEnd is called after the plan body has already stopped its execution.

Returns:

an integer code representing the termination value of the behaviour.

See Also:

Behaviour.onEnd()

onStart

void onStart()

This method is executed just once before starting this plan body execution. Therefore, it acts as a prolog to the task represented by this plan body.

See Also:

Behaviour.onStart()

reset

void reset()

Restores plan body initial state. This method must be implemented by concrete subclasses in such a way that calling reset() on a plan body object is equivalent to destroying it and recreating it back.

See Also:

Behaviour.reset()

restart

void restart()

Restarts a blocked behaviour. This method fires a suitable event to notify this behaviour's parent. When the agent scheduler inserts a blocked event back into the agent ready queue, it restarts it automatically. When this method is called, any timer associated with this behaviour object is cleared.

See Also:

Behaviour.restart()

start

void start()

Starts the execution of a plan body, a Behaviour, associated with this plan.

stop

void stop()

Stops the plan body, a Behaviour, associated with this plan. If the body implements the DisposablePlanBody, it invokes the method to about the plan body, so it can perform finalizations.