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

    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.
    `java.util.Collection<Belief<?>>` | `getAllBeliefs()` Gets all beliefs of this belief base and the belief bases of the whole-capabilities of the capability that this belief base belongs to.
    `Belief<?>` | `getBelief(java.lang.String 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.Set<Belief<?>>` | `getBeliefs()` Gets all beliefs of this specific belief base.
    `java.util.List<java.lang.Object>` | `getBeliefValues()` Returns a list of all belief values from this belief base.
    `Capability` | `getCapability()` Returns the capability with which this belief base is associated.
    `boolean` | `hasBelief(java.lang.String name)` Checks whether a belief is part of the belief base.
    `protected void` | `notifyBeliefChanged(BeliefEvent beliefChanged)` Notifies the capability associated with this belief base that a belief was modified.
    `Belief<?>` | `removeBelief(java.lang.String 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.String 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.

    - #### getAllBeliefs

          public java.util.Collection<Belief<?>> getAllBeliefs()

      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.

    - #### getBelief

          public Belief<?> getBelief(java.lang.String 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.Set<Belief<?>> getBeliefs()

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

    - #### getBeliefValues

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

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

    - #### getCapability

          public Capability getCapability()

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

    - #### hasBelief

          public boolean hasBelief(java.lang.String 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.

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