bdi4jade.plan

## Class PlanInstance

- java.lang.Object
- - bdi4jade.plan.PlanInstance

- All Implemented Interfaces:
    GoalListener, java.util.EventListener

      public class PlanInstance
      extends java.lang.Object
      implements GoalListener

  This class represents a plan that has been instantiated to be executed, with an associated plan body (a behavior).
  Author:
    ingrid

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `PlanInstance.EndState` This enumuration represents the possible end states of a plan execution.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PlanInstance(Plan plan, Intention intention)` Creates a new plan instance.

  - ### 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.
    `PlanInstance.EndState` | `getEndState()` Returns the end state of plan.
    `Goal` | `getGoal()` Returns the goal to be achieved by this plan instance.
    `GoalFinishedEvent` | `getGoalEvent()` Returns a goal event from the queue.
    `GoalFinishedEvent` | `getGoalEvent(boolean block)` Returns a goal event from the queue.
    `GoalFinishedEvent` | `getGoalEvent(long ms)` Returns a goal event from the queue.
    `Plan` | `getPlan()` Returns the `Plan` that is associated with this plan instance.
    `void` | `goalPerformed(GoalEvent event)` Notifies the listener that the goal was performed.
    `void` | `startPlan()` Starts the plan body, a `Behaviour`, associated with this plan.
    `void` | `stopPlan()` Stops the plan body, a `Behaviour`, associated with this plan.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### PlanInstance

          public PlanInstance(Plan plan,
                      Intention intention)
                       throws PlanInstantiationException

      Creates a new plan instance. It is associated with a plan definition ( `Plan`) and an `Intention`. It creates an instance of the plan body defined in the plan and throws an exception if an error occurs in this process.
      Parameters:
        `plan` - the plan associated this this plan instance.
        `intention` - the intention that this plan instance have to achieve.
      Throws:
        `PlanBodyInstantiationException` - in an error occurred during the instantiation.
        `PlanInstantiationException`

  - ### Method Detail

    - #### dispatchProtectedGoal

          public 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

          public 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

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

    - #### dispatchGoal

          public void dispatchGoal(Goal goal)

      Dispatches a goal to be achieved.
      Parameters:
        `goal` - the goal to be dispatched.

    - #### dispatchSubgoal

          public void dispatchSubgoal(Goal subgoal)

      Dispatches a subgoal to be achieved.
      Parameters:
        `subgoal` - the subgoal to be dispatched.

    - #### dispatchSubgoalAndListen

          public 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

          public BeliefBase getBeliefBase()

      Returns the belief base of the capability.
      Returns:
        the belief base containing the beliefs.

    - #### getEndState

          public PlanInstance.EndState getEndState()

      Returns the end state of plan. A null value means that the plan is still in execution. If the plan body has come to an end state, it invokes the method to set the output parameters of the goal, in case the plan body implements the `OutputPlanBody` interface (this is invoked only once). If the plan body has come to a failed state, it sets all of its subgoals as no longer desired.
      Returns:
        the end state of the plan.

    - #### getGoal

          public Goal getGoal()

      Returns the goal to be achieved by this plan instance.
      Returns:
        the goal.

    - #### getGoalEvent

          public GoalFinishedEvent 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

          public GoalFinishedEvent 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

          public GoalFinishedEvent 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

          public Plan getPlan()

      Returns the `Plan` that is associated with this plan instance.
      Returns:
        the plan.

    - #### goalPerformed

          public void goalPerformed(GoalEvent event)

      Description copied from interface: `GoalListener`
      Notifies the listener that the goal was performed.
      Specified by:
        `goalPerformed` in interface `GoalListener`
      Parameters:
        `event` - the performed goal event.
      See Also:
        `GoalListener.goalPerformed(bdi4jade.event.GoalEvent)`

    - #### startPlan

          public void startPlan()

      Starts the plan body, a `Behaviour`, associated with this plan.

    - #### stopPlan

          public void stopPlan()

      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.