bdi4jade.core

## Class Capability

- java.lang.Object
- - bdi4jade.core.Capability

- All Implemented Interfaces:
    java.io.Serializable
  Direct Known Subclasses:
    UtilityBasedCabability

      public class Capability
      extends java.lang.Object
      implements java.io.Serializable

  This capability represents a component that aggregates the mental attitudes defined by the BDI architecture. It has a belief base with the associated beliefs (knowledge) and a plan library.
  Author:
    Ingrid Nunes
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected BeliefBase` | `beliefBase`
    `protected java.lang.String` | `id`
    `protected PlanLibrary` | `planLibrary`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `Capability()` Creates a new capability with a generated id.
    `` | `Capability(java.util.Set<Belief<?,?>> initialBeliefs, java.util.Set<Plan> initialPlans)` Creates a new capability with a generated id.
    `` | `Capability(java.lang.String id)` Creates a new capability with the given id.
    `protected` | `Capability(java.lang.String id, BeliefBase beliefBase, java.util.Set<Belief<?,?>> initialBeliefs, PlanLibrary planLibrary, java.util.Set<Plan> initialPlans)` Creates a new capability with the given id, or a generated one if it is null.
    `` | `Capability(java.lang.String id, java.util.Set<Belief<?,?>> initialBeliefs, java.util.Set<Plan> initialPlans)` Creates a new capability with the given id.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `addAnnotatedFields(java.lang.Class<? extends Capability> capabilityClass)` Adds by reflection capability components, such as beliefs and plans, according to annotated fields.
    `void` | `addAssociatedCapability(Capability capability)` Associates a capability to this capability.
    `void` | `addCandidatePlans(Goal goal, java.util.Map<Capability,java.util.Set<Plan>> candidatePlansMap)` Adds the set of plans of this capability that can achieve the given goal to a map of candidate plans.
    `void` | `addPartCapability(Capability partCapability)` Adds a capability as part of this capability, which is a whole-capability.
    `boolean` | `canAchieve(Goal goal)` Checks if this capability has a plan that can achieve the given goal.
    `boolean` | `canHandle(jade.lang.acl.ACLMessage msg)` Checks if this capability has a plan that can process the given message.
    `boolean` | `equals(java.lang.Object obj)` Returns true if the object given as parameter is a capability and has the same full id of this capability.
    `java.util.Set<Capability>` | `getAssociatedCapabilities()` Returns all capabilities with which this capability is associated.
    `BeliefBase` | `getBeliefBase()` Returns this capability belief base.
    `BeliefRevisionStrategy` | `getBeliefRevisionStrategy()` Returns the belief revision strategy of this capability.
    `DeliberationFunction` | `getDeliberationFunction()` Returns the deliberation function of this capability.
    `java.lang.String` | `getFullId()` Returns the full id of this capability, which is its id prefixed by all whole-capabilities' ids.
    `java.util.Set<Capability>` | `getGoalOwner(java.lang.Class<? extends Capability> owner, boolean internal)` Returns the capability instances that owns a dispatched goal, considering the superclasses of this capability, its associations and compositions.
    `java.lang.String` | `getId()` Returns this capability id.
    `BDIAgent` | `getMyAgent()` Returns the agent that this capability is associated with.
    `OptionGenerationFunction` | `getOptionGenerationFunction()` Returns the option generation function of this capability.
    `java.util.List<java.lang.Class<? extends Capability>>` | `getParentCapabilities()` Returns the classes of all parent capabilities of this capability.
    `java.util.Set<Capability>` | `getPartCapabilities()` Returns the parts of this capability.
    `PlanLibrary` | `getPlanLibrary()` Returns the plan library of this capability.
    `PlanSelectionStrategy` | `getPlanSelectionStrategy()` Returns the plan selection strategy of this capability.
    `Capability` | `getWholeCapability()` Returns the whole-capability, if this is a part capability.
    `int` | `hashCode()`
    `void` | `removeAssociatedCapability(Capability capability)` Dissociates a capability of this capability.
    `boolean` | `removePartCapability(Capability partCapability)` Removes a capability as part of this capability, which is a whole-capability.
    `void` | `setBeliefRevisionStrategy(BeliefRevisionStrategy beliefRevisionStrategy)` Sets the belief revision strategy of this capability.
    `void` | `setDeliberationFunction(DeliberationFunction deliberationFunction)` Sets the deliberation function of this capability.
    `void` | `setOptionGenerationFunction(OptionGenerationFunction optionGenerationFunction)` Sets the option generation function of this capability.
    `void` | `setPlanSelectionStrategy(PlanSelectionStrategy planSelectionStrategy)` Sets the plan selection strategy of this capability.
    `protected void` | `setup()` This is an empty holder for being overridden by subclasses.
    `protected void` | `takeDown()` This is an empty holder for being overridden by subclasses.
    `java.lang.String` | `toString()`

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### beliefBase

          protected final BeliefBase beliefBase

    - #### id

          protected final java.lang.String id

    - #### planLibrary

          protected final PlanLibrary planLibrary

  - ### Constructor Detail

    - #### Capability

          public Capability()

      Creates a new capability with a generated id. It uses `BeliefBase` and `PlanLibrary` as belief base and plan library respectively.

    - #### Capability

          public Capability(java.util.Set<Belief<?,?>> initialBeliefs,
                            java.util.Set<Plan> initialPlans)

      Creates a new capability with a generated id. It uses `BeliefBase` and `PlanLibrary` as belief base and plan library respectively, and adds initial beliefs and plans.
      Parameters:
        `initialBeliefs` - the initial set of beliefs to be added to the belief base of this capability.
        `initialPlans` - the initial set of plans to be added to the plan library of this capability.

    - #### Capability

          public Capability(java.lang.String id)

      Creates a new capability with the given id. It uses `BeliefBase` and `PlanLibrary` as belief base and plan library respectively.
      Parameters:
        `id` - the capability id. If it is null, the class name is going to be used.

    - #### Capability

          protected Capability(java.lang.String id,
                               BeliefBase beliefBase,
                               java.util.Set<Belief<?,?>> initialBeliefs,
                               PlanLibrary planLibrary,
                               java.util.Set<Plan> initialPlans)

      Creates a new capability with the given id, or a generated one if it is null. It also sets the belief base and plan library, and adds initial beliefs and plans.
      Parameters:
        `id` - the capability id. If it is null, the class name is going to be used.
        `beliefBase` - the belief base.
        `initialBeliefs` - the initial set of beliefs to be added to the belief base of this capability.
        `planLibrary` - the plan library.
        `initialPlans` - the initial set of plans to be added to the plan library of this capability.

    - #### Capability

          public Capability(java.lang.String id,
                            java.util.Set<Belief<?,?>> initialBeliefs,
                            java.util.Set<Plan> initialPlans)

      Creates a new capability with the given id. It uses `BeliefBase` and `PlanLibrary` as belief base and plan library respectively, and adds initial beliefs and plans.
      Parameters:
        `id` - the capability id. If it is null, the class name is going to be used.
        `initialBeliefs` - the initial set of beliefs to be added to the belief base of this capability.
        `initialPlans` - the initial set of plans to be added to the plan library of this capability.

  - ### Method Detail

    - #### addAnnotatedFields

          protected void addAnnotatedFields(java.lang.Class<? extends Capability> capabilityClass)

      Adds by reflection capability components, such as beliefs and plans, according to annotated fields. This method is invoked by for capability class, and all parent classes.
      Parameters:
        `capabilityClass` - the capability class of which fields should me added to this capability.

    - #### addAssociatedCapability

          public final void addAssociatedCapability(Capability capability)

      Associates a capability to this capability.
      Parameters:
        `capability` - the capability to be associated.

    - #### addCandidatePlans

          public void addCandidatePlans(Goal goal,
                                        java.util.Map<Capability,java.util.Set<Plan>> candidatePlansMap)

      Adds the set of plans of this capability that can achieve the given goal to a map of candidate plans. It checks its plan library and the part capabilities, recursively.
      Parameters:
        `goal` - the goal to be achieved.
        `candidatePlansMap` - the map to which the set of plans that can achieve the goal should be added.

    - #### addPartCapability

          public final void addPartCapability(Capability partCapability)

      Adds a capability as part of this capability, which is a whole-capability.
      Parameters:
        `partCapability` - the part capability to be added.

    - #### canAchieve

          public boolean canAchieve(Goal goal)

      Checks if this capability has a plan that can achieve the given goal. It checks the plan library of this capabilities and, if cannot achieve it, it checks part capabilities, recursively.
      Parameters:
        `goal` - the goal to be checked.
      Returns:
        true if this capability has at least a plan that can achieve the goal.

    - #### canHandle

          public boolean canHandle(jade.lang.acl.ACLMessage msg)

      Checks if this capability has a plan that can process the given message. It checks the plan library of this capabilities and, if cannot handle it, it checks part capabilities, recursively.
      Parameters:
        `msg` - the message to be checked.
      Returns:
        true if this capability has at least a plan that can process the message.

    - #### equals

          public final boolean equals(java.lang.Object obj)

      Returns true if the object given as parameter is a capability and has the same full id of this capability.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `obj` - the object to be tested as equals to this plan.
      See Also:
        `Object.equals(java.lang.Object)`

    - #### getAssociatedCapabilities

          public final java.util.Set<Capability> getAssociatedCapabilities()

      Returns all capabilities with which this capability is associated.
      Returns:
        the associated capabilities.

    - #### getBeliefBase

          public final BeliefBase getBeliefBase()

      Returns this capability belief base.
      Returns:
        the beliefBase.

    - #### getBeliefRevisionStrategy

          public final BeliefRevisionStrategy getBeliefRevisionStrategy()

      Returns the belief revision strategy of this capability.
      Returns:
        the beliefRevisionStrategy.

    - #### getDeliberationFunction

          public final DeliberationFunction getDeliberationFunction()

      Returns the deliberation function of this capability.
      Returns:
        the deliberationFunction.

    - #### getFullId

          public final java.lang.String getFullId()

      Returns the full id of this capability, which is its id prefixed by all whole-capabilities' ids.
      Returns:
        the full id of this capability.

    - #### getGoalOwner

          public final java.util.Set<Capability> getGoalOwner(java.lang.Class<? extends Capability> owner,
                                                              boolean internal)

      Returns the capability instances that owns a dispatched goal, considering the superclasses of this capability, its associations and compositions. A capability may dispatch its own goals and goals of its parents. It may also dispatch external goals of associated or part capabilities (and their parents), and all goals of whole capabilities. This method thus searches all capabilities that have a relationship with this capability (either inheritance, composition or association) and finds the concrete capability instances whose definition owns a goal (specified with the `Owner` annotation in goals). If this method returns an empty set, it means that this capability has no access to the goal owned by capabilities of the given class.
      Parameters:
        `owner` - the capability class that is the goal owner.
        `internal` - the boolean that indicates whether the goal is internal or external.
      Returns:
        the capability instances related to this capability (or the capability itself) that owns the goal, or an empty set if the capability has no access to goals owned by capability of the given class.

    - #### getId

          public java.lang.String getId()

      Returns this capability id.
      Returns:
        the id.

    - #### getMyAgent

          public final BDIAgent getMyAgent()

      Returns the agent that this capability is associated with.
      Returns:
        the agent.

    - #### getOptionGenerationFunction

          public final OptionGenerationFunction getOptionGenerationFunction()

      Returns the option generation function of this capability.
      Returns:
        the optionGenerationFunction.

    - #### getParentCapabilities

          public final java.util.List<java.lang.Class<? extends Capability>> getParentCapabilities()

      Returns the classes of all parent capabilities of this capability.
      Returns:
        the parentCapabilities.

    - #### getPartCapabilities

          public final java.util.Set<Capability> getPartCapabilities()

      Returns the parts of this capability.
      Returns:
        the partCapabilities.

    - #### getPlanLibrary

          public final PlanLibrary getPlanLibrary()

      Returns the plan library of this capability.
      Returns:
        the planLibrary.

    - #### getPlanSelectionStrategy

          public final PlanSelectionStrategy getPlanSelectionStrategy()

      Returns the plan selection strategy of this capability.
      Returns:
        the planSelectionStrategy.

    - #### getWholeCapability

          public final Capability getWholeCapability()

      Returns the whole-capability, if this is a part capability.
      Returns:
        the wholeCapability.

    - #### hashCode

          public final int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`
      See Also:
        `Object.hashCode()`

    - #### removeAssociatedCapability

          public final void removeAssociatedCapability(Capability capability)

      Dissociates a capability of this capability.
      Parameters:
        `capability` - the capability to be dissociated.

    - #### removePartCapability

          public final boolean removePartCapability(Capability partCapability)

      Removes a capability as part of this capability, which is a whole-capability.
      Parameters:
        `partCapability` - the part capability to be removed.
      Returns:
        true if the capability was removed, false otherwise.

    - #### setBeliefRevisionStrategy

          public final void setBeliefRevisionStrategy(BeliefRevisionStrategy beliefRevisionStrategy)

      Sets the belief revision strategy of this capability.
      Parameters:
        `beliefRevisionStrategy` - the beliefRevisionStrategy to set.

    - #### setDeliberationFunction

          public final void setDeliberationFunction(DeliberationFunction deliberationFunction)

      Sets the deliberation function of this capability.
      Parameters:
        `deliberationFunction` - the deliberationFunction to set.

    - #### setOptionGenerationFunction

          public final void setOptionGenerationFunction(OptionGenerationFunction optionGenerationFunction)

      Sets the option generation function of this capability.
      Parameters:
        `optionGenerationFunction` - the optionGenerationFunction to set.

    - #### setPlanSelectionStrategy

          public final void setPlanSelectionStrategy(PlanSelectionStrategy planSelectionStrategy)

      Sets the plan selection strategy of this capability.
      Parameters:
        `planSelectionStrategy` - the planSelectionStrategy to set.

    - #### setup

          protected void setup()

      This is an empty holder for being overridden by subclasses. It is used to initialize the capability. This method is invoked when this capability is attached to an agent for the first time. It may be used to add initial plans and beliefs. The reasoning strategies of this capability are initialized in the constructor with default strategies. This method may also customize them.

    - #### takeDown

          protected void takeDown()

      This is an empty holder for being overridden by subclasses. It is used to clean up a capability when it is removed from an agent.

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`
      See Also:
        `Object.toString()`