bdi4jade.belief

## Class BeliefBase

- java.lang.Object
- - bdi4jade.belief.BeliefBase

- All Implemented Interfaces:
    java.io.Serializable

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

  This class represents a belief base of a capability. It aggregates its knowledge.
  Author:
    Ingrid Nunes
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `BeliefBase()` The default constructor.
    `` | `BeliefBase(Capability capability)` Creates a belief base associated with a capability.
    `` | `BeliefBase(Capability capability, java.util.Set<Belief<?,?>> beliefs)` Creates a belief base associated with a capability and adds the beliefs in the provided belief set as the initial beliefs of this belief base.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addBelief(Belief<?,?> belief)` Adds a belief to the belief base.
    `void` | `addBeliefListener(BeliefListener beliefListener)` Adds a belief listener to be notified about changes in the belief base.
    `void` | `addOrUpdateBelief(Belief<?,?> belief)` Adds a belief to the belief base.
    `Belief<?,?>` | `getBelief(java.lang.Object name)` Retrieves a belief from the belief base.
    `java.util.Set<BeliefListener>` | `getBeliefListeners()` Returns all the current belief listeners of this belief base.
    `java.util.Collection<Belief<?,?>>` | `getBeliefs()` Gets all beliefs of this belief base and the belief bases of the whole-capabilities of the capability that this belief base belongs to.
    `java.util.Set<Belief<?,?>>` | `getBeliefsAssignableFrom(java.lang.Class<?> beliefNameType)` Returns all beliefs whose name is of the given class or any other class that is assignable to this class.
    `java.util.Set<Belief<?,?>>` | `getBeliefsByType(java.lang.Class<?> beliefNameType)` Returns all beliefs whose name is of the given class.
    `Capability` | `getCapability()` Returns the capability with which this belief base is associated.
    `java.util.Set<Belief<?,?>>` | `getLocalBeliefs()` Gets all beliefs of this specific belief base.
    `java.util.Set<Belief<?,?>>` | `getLocalBeliefsAssignableFrom(java.lang.Class<?> beliefNameType)` Returns all beliefs whose name is of the given class or any other class that is assignable to this class.
    `java.util.Set<Belief<?,?>>` | `getLocalBeliefsByType(java.lang.Class<?> beliefNameType)` Returns beliefs whose name is of the given class.
    `java.util.List<java.lang.Object>` | `getLocalBeliefValues()` Returns a list of belief values from this belief base.
    `boolean` | `hasBelief(java.lang.Object name)` Checks whether a belief is part of the belief base.
    `boolean` | `hasBelief(java.lang.Object name, java.lang.Object value)` Checks whether a belief is part of the belief base with an specific value.
    `protected void` | `notifyBeliefChanged(BeliefEvent beliefChanged)` Notifies the capability associated with this belief base that a belief was modified.
    `Belief<?,?>` | `removeBelief(java.lang.Object name)` Removes a belief from the belief base.
    `void` | `removeBeliefListener(BeliefListener beliefListener)` Removes a belief listener.
    `protected void` | `setCapability(Capability capability)` Associates a capability with this belief base.
    `int` | `size()` Gets the size of this specific belief base (the number of beliefs).
    `java.lang.String` | `toString()` Returns this belief base as a string in the form: "Belief base of Capability ID = [ BELIEFS ]".
    `boolean` | `updateBelief(java.lang.Object name, java.lang.Object value)` Updates the value of a belief in the belief base.

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

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

- - ### Constructor Detail

    - #### BeliefBase

          protected BeliefBase()

      The default constructor. It should be only used if persistence frameworks are used.

    - #### BeliefBase

          public BeliefBase(Capability capability)

      Creates a belief base associated with a capability.
      Parameters:
        `capability` - the capability to which this belief base belongs.

    - #### BeliefBase

          public BeliefBase(Capability capability,
                            java.util.Set<Belief<?,?>> beliefs)

      Creates a belief base associated with a capability and adds the beliefs in the provided belief set as the initial beliefs of this belief base.
      Parameters:
        `capability` - the capability to which this belief base belongs.
        `beliefs` - the initial beliefs.

  - ### Method Detail

    - #### addBelief

          public void addBelief(Belief<?,?> belief)

      Adds a belief to the belief base.
      Parameters:
        `belief` - the belief to be added.

    - #### addBeliefListener

          public void addBeliefListener(BeliefListener beliefListener)

      Adds a belief listener to be notified about changes in the belief base.
      Parameters:
        `beliefListener` - the listener to be added.

    - #### addOrUpdateBelief

          public void addOrUpdateBelief(Belief<?,?> belief)

      Adds a belief to the belief base. It updates the belief value, if it already exists.
      Parameters:
        `belief` - the belief to be added or updated.

    - #### getBelief

          public Belief<?,?> getBelief(java.lang.Object name)

      Retrieves a belief from the belief base. If this belief base does not contain it, the method checks whole-capabilities' belief base recursively.
      Parameters:
        `name` - the name of the belief to be retrieved.
      Returns:
        the belief, or null if no belief is found.

    - #### getBeliefListeners

          public java.util.Set<BeliefListener> getBeliefListeners()

      Returns all the current belief listeners of this belief base.
      Returns:
        the belief listeners.

    - #### getBeliefs

          public java.util.Collection<Belief<?,?>> getBeliefs()

      Gets all beliefs of this belief base and the belief bases of the whole-capabilities of the capability that this belief base belongs to.
      Returns:
        the beliefs of this capability and all of its whole-capabilities.

    - #### getBeliefsAssignableFrom

          public java.util.Set<Belief<?,?>> getBeliefsAssignableFrom(java.lang.Class<?> beliefNameType)

      Returns all beliefs whose name is of the given class or any other class that is assignable to this class. It also searches beliefs in belief bases of whole capabilities.
      Parameters:
        `beliefNameType` - the class of the name of beliefs.
      Returns:
        the set of beliefs assignable from the given class.

    - #### getBeliefsByType

          public java.util.Set<Belief<?,?>> getBeliefsByType(java.lang.Class<?> beliefNameType)

      Returns all beliefs whose name is of the given class. It also searches beliefs in belief bases of whole capabilities.
      Parameters:
        `beliefNameType` - the class of the name of beliefs.
      Returns:
        the set of beliefs of the given class.

    - #### getCapability

          public Capability getCapability()

      Returns the capability with which this belief base is associated.
      Returns:
        the capability.

    - #### getLocalBeliefs

          public java.util.Set<Belief<?,?>> getLocalBeliefs()

      Gets all beliefs of this specific belief base.
      Returns:
        the beliefs

    - #### getLocalBeliefsAssignableFrom

          public java.util.Set<Belief<?,?>> getLocalBeliefsAssignableFrom(java.lang.Class<?> beliefNameType)

      Returns all beliefs whose name is of the given class or any other class that is assignable to this class.
      Parameters:
        `beliefNameType` - the class of the name of beliefs.
      Returns:
        the set of beliefs assignable from the given class.

    - #### getLocalBeliefsByType

          public java.util.Set<Belief<?,?>> getLocalBeliefsByType(java.lang.Class<?> beliefNameType)

      Returns beliefs whose name is of the given class.
      Parameters:
        `beliefNameType` - the class of the name of beliefs.
      Returns:
        the set of beliefs of the given class.

    - #### getLocalBeliefValues

          public java.util.List<java.lang.Object> getLocalBeliefValues()

      Returns a list of belief values from this belief base.
      Returns:
        the beliefValues

    - #### hasBelief

          public boolean hasBelief(java.lang.Object name)

      Checks whether a belief is part of the belief base. If this belief base does not contain it, the method checks whole-capabilities' belief base recursively.
      Parameters:
        `name` - the belief to be checked
      Returns:
        true if the belief base contains the belief.

    - #### hasBelief

          public boolean hasBelief(java.lang.Object name,
                                   java.lang.Object value)

      Checks whether a belief is part of the belief base with an specific value. If this belief base does not contain it, the method checks whole-capabilities' belief base recursively.
      Parameters:
        `name` - the belief to be checked
        `value` - the value to be checked
      Returns:
        true if the belief base contains the belief.

    - #### notifyBeliefChanged

          protected void notifyBeliefChanged(BeliefEvent beliefChanged)

      Notifies the capability associated with this belief base that a belief was modified. It also recursively notifies belief listeners of part capabilities.
      Parameters:
        `beliefChanged` - the belief that was changed

    - #### removeBelief

          public Belief<?,?> removeBelief(java.lang.Object name)

      Removes a belief from the belief base. If this belief base does not contain it, the method checks whole-capabilities' belief base recursively to remove this belief..
      Parameters:
        `name` - the name of the belief to be removed.
      Returns:
        the belief was removed, null if it is not part of the belief base.

    - #### removeBeliefListener

          public void removeBeliefListener(BeliefListener beliefListener)

      Removes a belief listener.
      Parameters:
        `beliefListener` - the listener to be removed.

    - #### setCapability

          protected void setCapability(Capability capability)

      Associates a capability with this belief base. Ideally, the capability should be final and initialized in the constructor. This method should be only used if persistence frameworks are used.
      Parameters:
        `capability` - the capability to set.

    - #### size

          public int size()

      Gets the size of this specific belief base (the number of beliefs).
      Returns:
        the size of this belief base.

    - #### toString

          public java.lang.String toString()

      Returns this belief base as a string in the form: "Belief base of Capability ID = [ BELIEFS ]".
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        the string representation of this belief base.
      See Also:
        `Object.toString()`

    - #### updateBelief

          public boolean updateBelief(java.lang.Object name,
                                      java.lang.Object value)

      Updates the value of a belief in the belief base. In case the belief is not present in the belief base (of in its whole-capabilities' belief bases), nothing is performed and the method returns false. If the type of the new value being provided does not match the current type, the method still subscribes the previous value.
      Parameters:
        `name` - the belief to be updated.
        `value` - the new value to the belief.
      Returns:
        true if the belief was updated.