bdi4jade.plan.planbody

## Class AbstractPlanBody

- java.lang.Object
- - jade.core.behaviours.Behaviour
  - - bdi4jade.plan.planbody.AbstractPlanBody

- All Implemented Interfaces:
    GoalListener, PlanBody, java.io.Serializable, java.util.EventListener
  Direct Known Subclasses:
    BeliefGoalPlanBody, ParallelGoalPlanBody, SequentialGoalPlanBody

      public abstract class AbstractPlanBody
      extends jade.core.behaviours.Behaviour
      implements PlanBody

  This class provides an almost complete implementation of the `PlanBody` interface. It represents a plan that has been instantiated to be executed.
  Author:
    Ingrid Nunes
  See Also:
    Serialized Form

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class jade.core.behaviours.Behaviour

      `jade.core.behaviours.Behaviour.RunnableChangedEvent`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected org.apache.commons.logging.Log` | `log`

    - ### Fields inherited from class jade.core.behaviours.Behaviour

      `myAgent, myEvent, NOTIFY_DOWN, NOTIFY_UP, parent, STATE_BLOCKED, STATE_READY, STATE_RUNNING`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractPlanBody()` Creates a new plan body.

  - ### 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.
    `boolean` | `done()` Indicates to the JADE platform that this behavior/plan body finished its execution.
    `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 plan.
    `Goal` | `getGoal()` Returns the goal to be achieved by this plan instance.
    `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 body.
    `void` | `goalPerformed(GoalEvent event)` Receives the notification that a goal event has occurred.
    `void` | `init(Plan plan, Intention intention)` Initializes this plan body.
    `protected void` | `setEndState(Plan.EndState endState)` Sets the end state of plan.
    `void` | `start()` Starts the plan body, by adding it as to the agent as a `Behaviour` .
    `void` | `stop()` Stops the plan body execution.

    - ### Methods inherited from class jade.core.behaviours.Behaviour

      `action, actionWrapper, block, block, getAgent, getBehaviourName, getDataStore, getExecutionState, getParent, getRestartCounter, handle, handleBlockEvent, handleRestartEvent, isRunnable, onEnd, onStart, reset, restart, root, setAgent, setBehaviourName, setDataStore, setExecutionState`

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

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

    - ### Methods inherited from interface bdi4jade.plan.planbody.PlanBody

      `onEnd, onStart, reset`

- - ### Field Detail

    - #### log

          protected final org.apache.commons.logging.Log log

  - ### Constructor Detail

    - #### AbstractPlanBody

          public AbstractPlanBody()

      Creates a new plan body.

  - ### Method Detail

    - #### dispatchGoal

          public void dispatchGoal(Goal goal)

      Description copied from interface: `PlanBody`
      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.
      Specified by:
        `dispatchGoal` in interface `PlanBody`
      Parameters:
        `goal` - the goal to be dispatched.
      See Also:
        `PlanBody.dispatchGoal(Goal)`

    - #### dispatchProtectedGoal

          public void dispatchProtectedGoal(Goal goal)

      Description copied from interface: `PlanBody`
      Dispatches a goal to be achieved, using the capability (or its children capabilities) associated with the plan.
      Specified by:
        `dispatchProtectedGoal` in interface `PlanBody`
      Parameters:
        `goal` - the goal to be dispatched.
      See Also:
        `PlanBody.dispatchProtectedGoal(Goal)`

    - #### dispatchProtectedSubgoal

          public void dispatchProtectedSubgoal(Goal subgoal)

      Description copied from interface: `PlanBody`
      Dispatches a subgoal to be achieved, using the capability (or its children capabilities) associated with the plan.
      Specified by:
        `dispatchProtectedSubgoal` in interface `PlanBody`
      Parameters:
        `subgoal` - the subgoal to be dispatched.
      See Also:
        `PlanBody.dispatchProtectedSubgoal(Goal)`

    - #### dispatchProtectedSubgoalAndListen

          public void dispatchProtectedSubgoalAndListen(Goal subgoal)

      Description copied from interface: `PlanBody`
      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.
      Specified by:
        `dispatchProtectedSubgoalAndListen` in interface `PlanBody`
      Parameters:
        `subgoal` - the subgoal to be dispatched.
      See Also:
        `PlanBody.dispatchProtectedSubgoalAndListen(Goal)`

    - #### dispatchSubgoal

          public void dispatchSubgoal(Goal subgoal)

      Description copied from interface: `PlanBody`
      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.
      Specified by:
        `dispatchSubgoal` in interface `PlanBody`
      Parameters:
        `subgoal` - the subgoal to be dispatched.
      See Also:
        `PlanBody.dispatchSubgoal(Goal)`

    - #### dispatchSubgoalAndListen

          public void dispatchSubgoalAndListen(Goal subgoal)

      Description copied from interface: `PlanBody`
      Dispatches a subgoal to be achieved and registers itself as a listener to receive a notification of the end of execution of the goal.
      Specified by:
        `dispatchSubgoalAndListen` in interface `PlanBody`
      Parameters:
        `subgoal` - the subgoal to be dispatched.
      See Also:
        `PlanBody.dispatchSubgoalAndListen(Goal)`

    - #### done

          public final boolean done()

      Indicates to the JADE platform that this behavior/plan body finished its execution. If `getEndState()` returns null, it returns false, as the plan body has not reached a final state. It returns true otherwise.
      Specified by:
        `done` in class `jade.core.behaviours.Behaviour`
      Returns:
        false if `getEndState()` returns null, true otherwise.
      See Also:
        `Behaviour.done()`

    - #### getBeliefBase

          public BeliefBase getBeliefBase()

      Description copied from interface: `PlanBody`
      Returns the belief base of the capability associated with the plan of this plan body.
      Specified by:
        `getBeliefBase` in interface `PlanBody`
      Returns:
        the belief base containing the capability beliefs.
      See Also:
        `PlanBody.getBeliefBase()`

    - #### getEndState

          public Plan.EndState getEndState()

      Returns the end state of plan. A null value means that the plan is still executing.
      Specified by:
        `getEndState` in interface `PlanBody`
      Returns:
        the end state of the plan.

    - #### getGoal

          public final Goal getGoal()

      Returns the goal to be achieved by this plan instance.
      Specified by:
        `getGoal` in interface `PlanBody`
      Returns:
        the goal.

    - #### getGoalEvent

          public GoalEvent getGoalEvent()

      Returns a goal event from the queue. If the queue is empty, the plan body execution is blocked.
      Specified by:
        `getGoalEvent` in interface `PlanBody`
      Returns:
        the goal event or null if the queue is empty.

    - #### getGoalEvent

          public GoalEvent getGoalEvent(boolean block)

      Returns a goal event from the queue. If the queue is empty, the plan body execution is blocked if the parameter passed to this method is true.
      Specified by:
        `getGoalEvent` in interface `PlanBody`
      Parameters:
        `block` - true if the plan body must be blocked if the queue is empty.
      Returns:
        the goal event or null if the queue is empty.

    - #### getGoalEvent

          public GoalEvent getGoalEvent(long ms)

      Returns a goal event from the queue. If the queue is empty, the plan body execution is blocked for the specified milliseconds.
      Specified by:
        `getGoalEvent` in interface `PlanBody`
      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 final Plan getPlan()

      Returns the `Plan` that is associated with this plan body.
      Specified by:
        `getPlan` in interface `PlanBody`
      Returns:
        the plan.

    - #### goalPerformed

          public void goalPerformed(GoalEvent event)

      Receives the notification that a goal event has occurred. If the event has a finished status, it is added to the event queue, which can be retrieved by invoking the `getGoalEvent()` method, and restarts the plan body execution.
      Specified by:
        `goalPerformed` in interface `GoalListener`
      Parameters:
        `event` - the goal event that occurred.
      See Also:
        `GoalListener.goalPerformed(bdi4jade.event.GoalEvent)`

    - #### init

          public final 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`. It also sets up the plan input parameters based on the goal input parameters.
      Specified by:
        `init` in interface `PlanBody`
      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.

    - #### setEndState

          protected final void setEndState(Plan.EndState endState)

      Sets the end state of plan. A null value means that the plan is still executing. 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), or sets up the goal inputs parameters based on the plan body output parameters. If an error occurs during this setting process, a warn is shown, but no exception is thrown. If the plan body has come to an end state, it drops all subgoals, in case they are still trying to be achieved.
      Parameters:
        `endState` - the endState to set.

    - #### start

          public final void start()

      Starts the plan body, by adding it as to the agent as a `Behaviour` .
      Specified by:
        `start` in interface `PlanBody`

    - #### stop

          public final void stop()

      Stops the plan body execution. It drops all plan body subgoals. If the body implements the `DisposablePlanBody`, it invokes the method to about the plan body, so it can perform finalizations.
      Specified by:
        `stop` in interface `PlanBody`