jade.semantics.kbase.observers

Class Observer

java.lang.Object

jade.semantics.kbase.observers.Observer

Direct Known Subclasses:

BeliefObserver, ObserverAdapter

public abstract class Observer
extends Object

Defines a KBase observer. Such an observer provides a means to observe several formulas, possibly asserted in the KBase, and to react if their values change. Do not forget to initialise new observers if they are added to the KBase after its initial setup

Version:

0.9, 0.9

Author:

Thierry Martinez - France Telecom

Field Summary

Fields

Modifier and Type	Field and Description
(package private) Thread	awakeningThread The waker behaviour triggered at the end of the timeout or when the wake up date is reached.
private static boolean	DEBUG
(package private) static int	DIRECTLY_OBSERVED
(package private) QueryResult	lastQueryResultOnDirectlyObserved Store the last queried value of the DIRECTLY_OBSERVED formula.
(package private) KBase	myKBase The KBase the observer belongs to.
(package private) ArrayList	observedFormulas Stores the formulas to be observed.
(package private) long	timeout Timeout value to avoid to wait endlessly.
(package private) boolean	timeoutDisabled A boolean to check if the timeout method should be invoked (to avoid invoking it after the success of the behaviour).
(package private) boolean	updatedOnce true if the observer value has been queried at least one time.
(package private) Date	wakeUpDate Instead of a timeout value, one can use a wake up date.

Constructor Summary

Constructors

Constructor and Description
Observer(KBase kbase, Formula formula) Build an Observer for the KBase given as an argument.
Observer(KBase kbase, Formula formula, Date wakeupDate) Builds an Observer for the kbase given as an argument.
Observer(KBase kbase, Formula formula, long timeOut) Builds an Observer for the kbase given as an argument.

Method Summary

Modifier and Type	Method and Description
void	addFormula(Formula formula) Add a formula to observe.
void	disableTimeout() Method to disable the timeout method.
KBase	getMyKBase()
Formula[]	getObservedFormulas() This method returns all observed formulas
Long	getTimeOut()
Date	getWakeUpDate()
boolean	isEnabledTimeout() Method used in the timeout method of subclasses to know if it should be executed (if the timeout is enabled) or not.
private void	setupAwakeningThread() Local method called during the initialisation of the observer (method update).
void	timeout() Timeout method called by the awakening behaviour that is triggered at the end of the timeout or at the wakeUpDate.
String	toString()
boolean	update(Formula formula) This method is called to update the observer according to the change that has just occurred on the given formula.

Methods inherited from class java.lang.Object

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

Field Detail

DEBUG

private static final boolean DEBUG

See Also:

Constant Field Values

DIRECTLY_OBSERVED

static final int DIRECTLY_OBSERVED

See Also:

Constant Field Values

observedFormulas

ArrayList observedFormulas

Stores the formulas to be observed. Among these formulas, the first one is the one directly observed, while the other ones are the associated pattern that could also trigger this observer.

lastQueryResultOnDirectlyObserved

QueryResult lastQueryResultOnDirectlyObserved

Store the last queried value of the DIRECTLY_OBSERVED formula.

myKBase

KBase myKBase

The KBase the observer belongs to.

updatedOnce

boolean updatedOnce

true if the observer value has been queried at least one time.

timeout

long timeout

Timeout value to avoid to wait endlessly. At the end of the timeout, triggers an exit behaviour.

wakeUpDate

Date wakeUpDate

Instead of a timeout value, one can use a wake up date. When this date is reached, the same exit behaviour is triggered.

awakeningThread

Thread awakeningThread

The waker behaviour triggered at the end of the timeout or when the wake up date is reached. It is only necessary to know it inside the class in order to remove it from the behaviour queue when it becomes unnecessary.

timeoutDisabled

boolean timeoutDisabled

A boolean to check if the timeout method should be invoked (to avoid invoking it after the success of the behaviour). Warning : when the observer is suppressed, this boolean must also be set to true to avoid triggering the timeout method.

Constructor Detail

Observer

public Observer(KBase kbase,
                Formula formula)

Build an Observer for the KBase given as an argument. Warning: if no timeout is given, no awakeningBehaviour is programmed so this observer could observe endlessly...

Parameters:

kbase - the KBase the observer belongs to. It should not be null.

Observer

public Observer(KBase kbase,
                Formula formula,
                long timeOut)

Builds an Observer for the kbase given as an argument. This observer expires at the end of the given timeout.

Parameters:

kbase - the kbase the observer belongs to. It should not be null.

timeOut - the value of the timeout. It should be positive.

Observer

public Observer(KBase kbase,
                Formula formula,
                Date wakeupDate)

Builds an Observer for the kbase given as an argument. This observer expires at the end of the given timeout

Parameters:

kbase - the kbase the observer belongs to. It should not be null.

wakeupDate - the date of wake up. It should not be null.

Method Detail

getObservedFormulas

public Formula[] getObservedFormulas()

This method returns all observed formulas

Returns:

an array of all observed formulas

getTimeOut

public Long getTimeOut()

Returns:

the value of the timeout (java.lang.Long) for this observer.

getWakeUpDate

public Date getWakeUpDate()

Returns:

the wakeUpDate (java.util.Date) for this observer.

getMyKBase

public KBase getMyKBase()

Returns:

the KBase to which this observer belongs to

addFormula

public void addFormula(Formula formula)

Add a formula to observe. Notice that observe f means observe f and (not f).

Parameters:

the - formula to observe.

setupAwakeningThread

private void setupAwakeningThread()

Local method called during the initialisation of the observer (method update). It sets up an awakening thread that runs the timeout method at the end of the delay (timeout or time to wakeUpDate) FIXME : use JADE behaviour instead of JAVA thread

timeout

public void timeout()

Timeout method called by the awakening behaviour that is triggered at the end of the timeout or at the wakeUpDate. By default it does nothing, should be overridden in subclasses when necessary.

disableTimeout

public void disableTimeout()

Method to disable the timeout method. Useful to prevent the timeout method to be executed when the observer has been removed or after the watched formula has been observed (this could happen since the timeout method is invoked by a thread, independently from the Observer itself). FIXME this method should be automatically invoked each time an observer is removed from the KBase: modify the KBase class and subclasses ?? For now: be careful and do not forget to disable timeout when removing an observer.

isEnabledTimeout

public boolean isEnabledTimeout()

Method used in the timeout method of subclasses to know if it should be executed (if the timeout is enabled) or not.

Returns:

a boolean indicating if the timeout is still enabled

update

public boolean update(Formula formula)

This method is called to update the observer according to the change that has just occurred on the given formula. Do not forget to call update(null) to initialise the observer once added in the KBase (unless it is added in the setupKBase method: in this case the initialisation is automatic).

Parameters:

formula - the formula which has just changed (newly asserted or removed) or null to force the update of the observer.

Returns:

true if one of the observed formulas is concerned by this recent change.

toString

public String toString()

Overrides:

toString in class Object