jade.semantics.kbase

Class KBaseDecorator

java.lang.Object

jade.semantics.kbase.KBaseDecorator

All Implemented Interfaces:

KBase

Direct Known Subclasses:

FilterKBaseImpl

public class KBaseDecorator
extends Object
implements KBase

Field Summary

Fields

Modifier and Type	Field and Description
protected KBase	decorated The decorated KBase

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	KBaseDecorator(KBase decorated) Build a KBase decorator

Method Summary

Modifier and Type	Method and Description
void	addClosedPredicate(Formula pattern) Define a new pattern of closed formula.
void	addObserver(Observer o) Add an observer to this KBase instance (at the end of the list of observers).
void	assertFormula(Formula formula) Assert a fact (given as a FIPA-SL formula) believed by the owning agent into this belief base.
Term	eval(Term expression)
Term	getAgentName() Get the name of the agent (given as a FIPA-SL term representing his AID) owning this KBase instance.
KBase	getDecorated() Return the decorated kbase
KBase	getWrappingKBase() The KBase mechanism follows the decoration design pattern.
boolean	isClosed(Formula pattern, QueryResult values) Return true if a given pattern of formula is closed on a given domain of values, and false otherwise.
QueryResult	query(Formula formula) Check wether a given fact is believed by the agent owning this KBase instance.
QueryResult	query(Formula formula, ArrayList reasons)
ListOfTerm	queryRef(IdentifyingExpression expression) Return a list of objects satisfying a given logical description (expressed as an Identifying Referential Expression), which is believed by the agent owning this KBase instance.
Term	queryRef(IdentifyingExpression expression, ArrayList falsityReasons)
Term	queryRefSingleTerm(IdentifyingExpression expression) Return a term satisfying a given logical description (expressed as an Identifying Referential Expression), which is believed by the agent owning this KBase instance.
void	removeClosedPredicate(Finder finder) Remove the definition of a pattern of closed formula.
void	removeFormula(Finder finder) Removes from the belief base all formulas recognized by a given finder.
void	removeObserver(Finder finder) Remove from this KBase instance all the observers that are identified by a given finder.
void	removeObserver(Observer obs) Remove from this KBase instance a given observer.
void	retractFormula(Formula formula) Retract a fact from the belief base.
void	setAgentName(Term agent) Modify the agent (given as a FIPA-SL term representing his AID) the beliefs stored in this KBase instance belong to.
void	setWrappingKBase(KBase kbase) Set the most enclosing KBase.
ArrayList	toStrings() Return the list of believed facts contained in this KBase instance as an array of String.
void	updateObservers(Formula formula) Update the status of all observers concerned by a given formula.

Methods inherited from class java.lang.Object

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

Field Detail

decorated

protected KBase decorated

The decorated KBase

Constructor Detail

KBaseDecorator

protected KBaseDecorator(KBase decorated)

Build a KBase decorator

Parameters:

decorated - the decorated KBase

Method Detail

getDecorated

public KBase getDecorated()

Return the decorated kbase

Returns:

the decorated kbase

addClosedPredicate

public void addClosedPredicate(Formula pattern)

Description copied from interface: KBase

Define a new pattern of closed formula.

If there is no instance of this pattern, which is already believed by the agent owning the belief base, this is equivalent to assert (= (all ??VARS ??pattern) (set)), where ??VAR is a sequence of all meta-references occurring in the pattern.

Specified by:

addClosedPredicate in interface KBase

Parameters:

pattern - the pattern of formula to declare as closed.

See Also:

KBase.isClosed(Formula, QueryResult)

addObserver

public void addObserver(Observer o)

Description copied from interface: KBase

Add an observer to this KBase instance (at the end of the list of observers). Observers make it possible to monitor the truth value of a given fact and trigger some action each time this fact becomes believed by the agent owning the belief base. For example, this mechanism is used by the SIPs that manage the interpretation of the SUBSCRIBE or REQUEST-WHEN* messages.

Specified by:

addObserver in interface KBase

Parameters:

o - the observer to add

assertFormula

public void assertFormula(Formula formula)

Description copied from interface: KBase

Assert a fact (given as a FIPA-SL formula) believed by the owning agent into this belief base. It is very important to understand that asserted facts are necessarily facts believed by the agent, independently from their truth value in the real world.

Asserting p actually means that (B ??myself p) is true (where ??myself represents the agent owning the belief base), while asserting (not p) actually means that (B ??myself (not p)) is true.
Consequently, asserting p is equivalent to asserting (B ??myself p) (because in the underlying formal model - see the FIPA SL specifications, (B i (B i p)) is logically equivalent to (B i p)).

The KBase implementations are expected to maintain a logically consistent set of beliefs. When a fact, which is inconsistent with an already stored belief, is asserted, the implementation must explicitly choose an option that ensures the global consistency (for example, keeping the most recently asserted fact in the base).

Depending on their sophistication, the KBase implementations may not be able to actually store all asserted facts. In this case, the reasoning (or "intellectual") capabilities of the owning agent will simply be considered as limited, which is a very common case. In any case, the asserted facts that cannot be dealt with should not create any inconsistency in the belief base. For example, the implementation provided with the JSA framework does not deal with uncertainty modal operators, so that asserting (U ??myself p) has no effect.

Specified by:

assertFormula in interface KBase

Parameters:

formula - the formula to assert.

getAgentName

public Term getAgentName()

Description copied from interface: KBase

Get the name of the agent (given as a FIPA-SL term representing his AID) owning this KBase instance. Note that a KBase instance stores the beliefs of only one agent, even if these beliefs may concern beliefs on other agents.

Specified by:

getAgentName in interface KBase

Returns:

the name of the agent believing the facts stored in this KBase object.

getWrappingKBase

public KBase getWrappingKBase()

Description copied from interface: KBase

The KBase mechanism follows the decoration design pattern. A KBase instance can be enclosed within another KBase instance, wich can in turn be enclosed in another KBase instance and so on.

Specified by:

getWrappingKBase in interface KBase

Returns:

the most enclosing KBase instance, on which to proceed assertion and query operations. This also corresonds to the KBase instance attached to the semantic capabilities of an agent. It can be this KBase object.

isClosed

public boolean isClosed(Formula pattern,
                        QueryResult values)

Description copied from interface: KBase

Return true if a given pattern of formula is closed on a given domain of values, and false otherwise.

A pattern of formula is considered as closed on a set of values if and only if:

• its instantiation with each value is believed by the agent owning the belief base,
• the agent believes that its instantiation with any other value is necessarily false.

Closed formulas are particularly useful to deal with the iota and the all IRE quantifiers. For example, the belief (B ??myself (= (all ?x (age ?x 25)) (set john mary))) is actually stored in the belief base as the formula (age ??x 25) closed on the domain (john, mary). This makes it possible to retrieve implicit entailments such as (B ??myself (not (age peter 25))) (without the closed formula mechanism, one could only entail (not (B ??myself (age peter 25)))).

Consequent to the formal definition of the underlying logical model for agents' beliefs, all patterns of mental attitudes of the agent owning the belief base (that is all patterns logically equivalent to a formula of the form (B ??myself ??PHI)) are necessarily closed. In other words, agents know exactly what are all their mental attitudes, they cannot not be aware of them.

Closed formulas can be defined and undefined using the KBase.addClosedPredicate(Formula) and KBase.removeClosedPredicate(Finder) methods.

Specified by:

isClosed in interface KBase

Parameters:

pattern - the pattern of closed formula to check.

values - the domain of values to used to check the closure. null value does not check the values, only the registration of the pattern as a closed formula.

Returns:

true if the pattern is closed on the given domain, false otherwise.

query

public QueryResult query(Formula formula)

Description copied from interface: KBase

Check wether a given fact is believed by the agent owning this KBase instance.

If the fact is not believed by the agent, the method returns null.

The queried fact may include meta-references. In this case, the method returns all bindings of these meta-references, for which the corresponding instantiated fact is believed by the agent. These bindings are returned using a QueryResult instance. If the queried fact include no meta-reference and is actually believed, the returned QueryResult object is an empty list equal to QueryResult.KNOWN.

For example, if (age john 25), (age mary 25) and (age peter 20) are believed by the agent, querying for (age ??who 25) will return a list of two MatchResult objects containing respectively the bindings (??who=john) and (??who=mary).

Specified by:

query in interface KBase

Parameters:

formula - a fact to retrieve in the belief base (may include meta- references)

Returns:

null (QueryResult.UNKNOWN) if the agent doesn't know about this fact,
an empty QueryResult (QueryResult.KNOWN) if the queried fact is believed by the agent and includes no meta-reference,

a not empty QueryResult, if the queried fact is believed by the agent and includes meta-reference.

query

public QueryResult query(Formula formula,
                         ArrayList reasons)

Specified by:

query in interface KBase

queryRef

public ListOfTerm queryRef(IdentifyingExpression expression)

Description copied from interface: KBase

Return a list of objects satisfying a given logical description (expressed as an Identifying Referential Expression), which is believed by the agent owning this KBase instance.

Formally, given an IRE ??IRE quantified by either iota or any, the method returns a list of one single term ??o such that: (B ??myself (= ??IRE ??o)) is true.
Given an IRE ??IRE quantified by either all or some, the method returns a set ??set of zero or more terms (given as a ListOfTerm object) such that: (B ??myself (= ??IRE ??set)) is true.

If no term satisfy the previous formulas, then the method returns null (which actually means that either the agent does not know the specified objects or there is no such objects).

Specified by:

queryRef in interface KBase

Parameters:

expression - an Identifying Referential Expression describing one or more objects to find within the agent's beliefs.

Returns:

a list of terms containing all the objects satisfying the input IRE according the the agent's beliefs, or null if there is no such object in the agent's beliefs.

queryRef

public Term queryRef(IdentifyingExpression expression,
                     ArrayList falsityReasons)

Specified by:

queryRef in interface KBase

queryRefSingleTerm

public Term queryRefSingleTerm(IdentifyingExpression expression)

Description copied from interface: KBase

Return a term satisfying a given logical description (expressed as an Identifying Referential Expression), which is believed by the agent owning this KBase instance.

Formally, given an IRE ??IRE quantified by either iota or any, the method returns either a term ??o such that (B ??myself (= ??IRE ??o)) is true or null if (not (exists ?o (B ??myself (= ??IRE ?o)))).
Given an IRE ??IRE quantified by either all or some, the method returns a set ??set of zero or more terms such that: (B ??myself (= ??IRE ??set)) is true.

Specified by:

queryRefSingleTerm in interface KBase

Parameters:

expression - an Identifying Referential Expression describing one or more objects to find within the agent's beliefs.

Returns:

a term satisfying the input IRE according the the agent's beliefs, or null if there is no such object according to the agent's beliefs.

See Also:

KBase.queryRef(IdentifyingExpression)

eval

public Term eval(Term expression)

Specified by:

eval in interface KBase

Parameters:

expression - a term to evaluate

Returns:

a term, which is logically equal to the given expression

removeClosedPredicate

public void removeClosedPredicate(Finder finder)

Description copied from interface: KBase

Remove the definition of a pattern of closed formula. This pattern is identified by a Finder object.

Specified by:

removeClosedPredicate in interface KBase

Parameters:

finder - a finder identifying the pattern of closed formula to remove.

See Also:

KBase.isClosed(Formula, QueryResult)

removeFormula

public void removeFormula(Finder finder)

Description copied from interface: KBase

Removes from the belief base all formulas recognized by a given finder.

Specified by:

removeFormula in interface KBase

Parameters:

finder - a finder to identify formulas to remove from the belief base.

removeObserver

public void removeObserver(Finder finder)

Description copied from interface: KBase

Remove from this KBase instance all the observers that are identified by a given finder.

Specified by:

removeObserver in interface KBase

Parameters:

finder - a finder that identifies the observers to remove.

removeObserver

public void removeObserver(Observer obs)

Description copied from interface: KBase

Remove from this KBase instance a given observer.

Specified by:

removeObserver in interface KBase

Parameters:

obs - the observer to remove.

retractFormula

public void retractFormula(Formula formula)

Description copied from interface: KBase

Retract a fact from the belief base. Actually, this method should be a shortcut for the assertion of (not (B ??myself formula)). In other words, retracting p actually means that (not (B ??myself p)) is true.

The retracted formula may include meta-references, in this case, all stored facts that match the input formula are retracted. For example, if (age john 25), (age mary 25) and (age peter 20) are believed by the agent, retracting (age ??person 25) will result in dropping the first two facts from the belief base.

Specified by:

retractFormula in interface KBase

Parameters:

formula - the formula to retract.

setAgentName

public void setAgentName(Term agent)

Description copied from interface: KBase

Modify the agent (given as a FIPA-SL term representing his AID) the beliefs stored in this KBase instance belong to.

Specified by:

setAgentName in interface KBase

Parameters:

agent - the agent the beliefs of this KBase object belong to.

setWrappingKBase

public void setWrappingKBase(KBase kbase)

Description copied from interface: KBase

Set the most enclosing KBase. This method is for internal use only, and should never be called by the JSA programmer.

Specified by:

setWrappingKBase in interface KBase

toStrings

public ArrayList toStrings()

Description copied from interface: KBase

Return the list of believed facts contained in this KBase instance as an array of String. It is useful for debugging purposes.

Specified by:

toStrings in interface KBase

Returns:

the list of believed facts in this belief base.

updateObservers

public void updateObservers(Formula formula)

Description copied from interface: KBase

Update the status of all observers concerned by a given formula. Updating an observer means requesting it to check whether its monitored formula has become believed by the agent owning the belief base (and trigger the associated action if needed). An observer is concerned by a formula if asserting this formula may change the truth value of its monitored formula.

A null formula forces all observers to be updated.

This operation is needed to trigger the observers even when an assertion does not lead to an actual assertion in the belief base.

Specified by:

updateObservers in interface KBase

Parameters:

formula - a formula that has just been asserted.

See Also:

Observer