jade.semantics.kbase

Class ArrayListKBaseImpl

java.lang.Object

jade.semantics.kbase.ArrayListKBaseImpl

All Implemented Interfaces:

KBase

public class ArrayListKBaseImpl
extends Object
implements KBase

Class that implements the belief base api. The data are stored in an ArrayList. The observers of the base are also stored in ArrayLists.

Version:

0.9, 0.9

Author:

Vincent Pautret - France Telecom

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	ArrayListKBaseImpl.DataStorage

Field Summary

Fields

Modifier and Type	Field and Description
(package private) Term	agentName All the beliefs of this KBase have the form (B agentName ...)
private Formula	belNotOPattern
private Formula	belOPattern
private Formula	bPattern
private ArrayList	closedPredicateList List of patterns which are closed
private ArrayListKBaseImpl.DataStorage	dataStorage Storage of beliefs
private Formula	iPattern
private Formula	ireFormula
private Logger	logger Logger
private Formula	notBelOPattern
private Formula	notBPattern
private Formula	notIPattern
private Formula	notUPattern
private Formula	notURefPattern
private ArrayList	observers List of observers
(package private) HashSet	observersToApplied HashSet of Observations which contains the observers to trigger when a formula is asserted
private Formula	uPattern Patterns for assertion and query methods
private Formula	URefPattern
private KBase	wrappingKBase The wrapping KBase

Constructor Summary

Constructors

Constructor and Description
ArrayListKBaseImpl(Term agentName) Creates a new belief base.
ArrayListKBaseImpl(Term agentName, KBase wrappingKBase) Creates a new belief base.

Method Summary

Modifier and Type	Method and Description
void	addClosedPredicate(Formula pattern) Define a new pattern of closed formula.
void	addObserver(Observer obs) Adds a new Observer in the observer table
void	assertFormula(Formula formula) Tries to assert the formula.
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.
Logger	getLogger()
KBase	getWrappingKBase() The KBase mechanism follows the decoration design pattern.
boolean	isClosed(Formula pattern, QueryResult b) 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) Queries directly the belief base.
ListOfTerm	queryRef(IdentifyingExpression expression) Deprecated. Use queryRefSingleTerm(IdentifyingExpression) or queryRef(IdentifyingExpression, ArrayList) instead.
Term	queryRef(IdentifyingExpression expression, ArrayList falsityReasons)
Term	queryRefSingleTerm(IdentifyingExpression expression) Allways returns a single term depending on the IRE and the result list returned by queryRef.
void	removeClosedPredicate(Finder finder) Remove the definition of a pattern of closed formula.
void	removeFormula(Finder finder) Deprecated. use retractFormula(Formula) instead
boolean	removeFormula(Formula formula) Removes the specified formula from the base.
void	removeObserver(Finder finder) Removes from the KBase the observers detected by the finder.
void	removeObserver(Observer obs) Removes the given observer
void	retractFormula(Formula formula) It retracts the formula given in parameter from the belief base by asserting (not (B ??myself ??formula)).
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() For debugging purpose only
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

wrappingKBase

private KBase wrappingKBase

The wrapping KBase

agentName

Term agentName

All the beliefs of this KBase have the form (B agentName ...)

dataStorage

private ArrayListKBaseImpl.DataStorage dataStorage

Storage of beliefs

closedPredicateList

private ArrayList closedPredicateList

List of patterns which are closed

observers

private ArrayList observers

List of observers

uPattern

private final Formula uPattern

Patterns for assertion and query methods

notUPattern

private final Formula notUPattern

iPattern

private final Formula iPattern

notIPattern

private final Formula notIPattern

bPattern

private final Formula bPattern

notBPattern

private final Formula notBPattern

belOPattern

private final Formula belOPattern

belNotOPattern

private final Formula belNotOPattern

notBelOPattern

private final Formula notBelOPattern

notURefPattern

private final Formula notURefPattern

URefPattern

private final Formula URefPattern

ireFormula

private final Formula ireFormula

logger

private Logger logger

Logger

observersToApplied

HashSet observersToApplied

HashSet of Observations which contains the observers to trigger when a formula is asserted

Constructor Detail

ArrayListKBaseImpl

public ArrayListKBaseImpl(Term agentName)

Creates a new belief base.

Parameters:

remoteAgent - the owner of the base

ArrayListKBaseImpl

public ArrayListKBaseImpl(Term agentName,
                          KBase wrappingKBase)

Creates a new belief base.

Parameters:

remoteAgent - the owner of the base

wrappingKBase - the kbase that wrap this one

Method Detail

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.

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

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.

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.

assertFormula

public void assertFormula(Formula formula)

Tries to assert the formula. The assertion depends on the formula. If the formula matches the pattern:

• "(I ??myself ??phi)", the formula is asserted.
• "(not (I ??myself ??phi))", the formula "(I ??myself ??phi)" is removed if it is in the base
• "(B ??myself (O ??phi))", the formula is asserted.
• "(B ??myself (not (O ??phi)))", the formula "(O ??phi)" is removed if it is in the base
• "(B ??myself ??phi)", the formula phi is asserted if it is an AtomicFormula
• "(B ??myself (not ??phi)), if the formula phi is in the base, it is removed

??myself represents the current semantic agent.
If the formula matches another pattern nothing is done. At the end of the assert, each boolean that corresponds to the applicability of the observers is set to false.

Specified by:

assertFormula in interface KBase

Parameters:

formula - the formula to assert in the 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

queryRef

@Deprecated
public ListOfTerm queryRef(IdentifyingExpression expression)

Deprecated. Use queryRefSingleTerm(IdentifyingExpression) or queryRef(IdentifyingExpression, ArrayList) instead.

Queries the belief base on the formula (B ??agent (= ??ire ??Result)), where ??ire is instantiated with the identifying expression given in parameter. The ListOfTerm corresponding to the solutions is the value of the meta variable ??Result, which could be null.

Specified by:

queryRef in interface KBase

Parameters:

expression - the identifying expression on which the query relates.

Returns:

a list of terms that corresponds to the question or null (meaning the answer : "I do not know")

queryRef

public Term queryRef(IdentifyingExpression expression,
                     ArrayList falsityReasons)

Specified by:

queryRef in interface KBase

queryRefSingleTerm

public Term queryRefSingleTerm(IdentifyingExpression expression)

Allways returns a single term depending on the IRE and the result list returned by queryRef. - if the IRE is iota and the result owns 1 single term : returns this term - if the IRE is any and the result owns 1 term at least : returns the first term - if the IRE is all or some : returns a set containing all results - else return null

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

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)

Queries directly the belief base.

Specified by:

query in interface KBase

Parameters:

formula - a formula

reasons - the list of formulas, which are believed by the agent and explain the result of the query is unknown

Returns:

a list of solutions to the query

removeFormula

public boolean removeFormula(Formula formula)

Removes the specified formula from the base.

Parameters:

formula - a formula

Returns:

true if the formula to remove was actually in the KBase

removeFormula

@Deprecated
public void removeFormula(Finder finder)

Deprecated. use retractFormula(Formula) instead

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.

retractFormula

public void retractFormula(Formula formula)

It retracts the formula given in parameter from the belief base by asserting (not (B ??myself ??formula)). The formula to retract may include meta-variables.

Specified by:

retractFormula in interface KBase

Parameters:

formula - the formula to retract from the belief base

toStrings

public ArrayList toStrings()

For debugging purpose only

Specified by:

toStrings in interface KBase

Returns:

an array that contains a string representation of each data in the base

addObserver

public void addObserver(Observer obs)

Adds a new Observer in the observer table

Specified by:

addObserver in interface KBase

Parameters:

o - the observer to add

removeObserver

public void removeObserver(Finder finder)

Removes from the KBase the observers detected by the finder.

Specified by:

removeObserver in interface KBase

Parameters:

finder - the finder

removeObserver

public void removeObserver(Observer obs)

Removes the given observer

Specified by:

removeObserver in interface KBase

Parameters:

obs - the observer to be removed

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)

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)

isClosed

public boolean isClosed(Formula pattern,
                        QueryResult b)

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.

b - 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.

getLogger

public Logger getLogger()