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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `dispatchGoal(Goal goal)` Dispatches a goal to be achieved.
    `void` | `dispatchProtectedGoal(Goal goal)` Dispatches a goal to be achieved, using the capability (or its children capabilities) associated with the plan.
    `void` | `dispatchProtectedSubgoal(Goal subgoal)` Dispatches a subgoal to be achieved, using the capability (or its children capabilities) associated with the plan.
    `void` | `dispatchProtectedSubgoalAndListen(Goal subgoal)` Dispatches a subgoal to be achieved, using the capability (or its children capabilities) associated with the plan, and registers itself as a listener to receive a notification of the end of execution of the goal.
    `void` | `dispatchSubgoal(Goal subgoal)` Dispatches a subgoal to be achieved.
    `void` | `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.
    `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` | `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

    - #### dispatchGoal

          void 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.

    - #### dispatchProtectedGoal

          void dispatchProtectedGoal(Goal goal)

      Dispatches a goal to be achieved, using the capability (or its children capabilities) associated with the plan.
      Parameters:
        `goal` - the goal to be dispatched.

    - #### dispatchProtectedSubgoal

          void dispatchProtectedSubgoal(Goal subgoal)

      Dispatches a subgoal to be achieved, using the capability (or its children capabilities) associated with the plan.
      Parameters:
        `subgoal` - the subgoal to be dispatched.

    - #### dispatchProtectedSubgoalAndListen

          void dispatchProtectedSubgoalAndListen(Goal subgoal)

      Dispatches a subgoal to be achieved, using the capability (or its children capabilities) associated with the plan, 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.

    - #### dispatchSubgoal

          void 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.

    - #### dispatchSubgoalAndListen

          void 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.

    - #### 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.

    - #### 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()`, `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()`

    - #### 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.