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

    All Methods Instance Methods Abstract Methods
    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.