biz.chitec.quarterback.util
Class Controllable

java.lang.Object
  java.util.Observable
      biz.chitec.quarterback.util.Controllable

public class Controllable

extends java.util.Observable

"Brain" class. Mixture of Observable and Map. A controllable holds objects and flags. Moreover, it's an Observable, so it holds (GUI) object references of (GUI) objects that want to be informed of changes of the state of this Controllable.

Anyone can put (or change) objects into the Controllable (though most times this will be done through one of the Controllers of the Controllable). If appropriate, anyone can call notifyObservers() which will propagate the new state(s) of the Controllable to all registered Controllers by calling their update() method.

Controllers can check by calling hasChanged() if the state of a certain property has changed since the last notifyObservers(). A property can be obtained by calling get().

It must be noted that get() returns (a pointer to) the object actually stored by the Controllable. If a controller wants to make changes to this object, it is very strongly recommended to make a copy of it first. Otherwise, the object stored in the Controllable will be changed, which will cause predictable but almost certainly unwanted results. Once again: MAKE A COPY BEFORE CHANGING THE RESULT OF get()! If you change the object (and know what you do!) you can normalize the Controller's state by calling setChanged() for the changed object explicitily.

Controllables can be stacked: If get() would return null (no object found) and there is a father-Controllable, get() of that one is called. Note that changes are (in the moment) not propagated through the Controllable hierarchy.

A Controllable supports also "flags", these can be set or reset using (re)setFlag() and checked using getFlag(). Flags are always cleared after a notifyObservers(). Flags are not propagated through the hierarchy.

Version:

$Id: a6d81955767656fca1629fb485cb5285bc0df88b $

Author:

Dirk Hillbrecht 1997-1999, chitec/Dirk Hillbrecht 2000. Distributed under the terms of the GNU LGPL.

Field Summary

protected Controllable	father
protected java.util.Map	mychanges
protected java.util.Map	mydata
protected java.util.Map	myflags
protected boolean	notifying
protected boolean	renotify
protected java.util.List	sons

Fields inherited from class java.util.Observable

Constructor Summary

Controllable()
init the Controllable.

Method Summary

boolean	containsKey(java.lang.String key) Return whether there is a property "key" or not.
boolean	containsKey(java.lang.String key, boolean askfather) Return whether there is a property "key" or not.
protected void	fatherChanged(java.lang.String key)
java.lang.Object	get(java.lang.String key) return a stored object.
Controllable	getFather()
boolean	getFlag(java.lang.String key) return the state of a flag.
boolean	hasChanged(java.lang.String key) return if the state of a certain property has changed.
protected void	informSonsOfChange(java.lang.String key)
void	invalidateFather()
java.util.Iterator	keys() returns all available keys.
void	notifyObservers() notify all observers.
void	notifyObservers(java.lang.Object arg) notify all observers.
java.lang.Object	put(java.lang.String key, java.lang.Object value) put a property into the Controllable.
java.lang.Object	remove(java.lang.String key) remove a property from the Controllable.
protected void	removeSon(Controllable s)
void	resetFlag(java.lang.String key) reset a flag explicitly.
void	setChanged(java.lang.String key) set the changed flag for an object explicitily.
void	setFather(Controllable f) set a father which is asked when a value is not found in this controllable
void	setFlag(java.lang.String key) set a flag.
protected void	setSon(Controllable s)
java.lang.String	toString()

Methods inherited from class java.util.Observable

addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, setChanged

Methods inherited from class java.lang.Object

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

Field Detail

mydata

protected java.util.Map mydata

mychanges

protected java.util.Map mychanges

myflags

protected java.util.Map myflags

sons

protected java.util.List sons

notifying

protected boolean notifying

renotify

protected boolean renotify

father

protected Controllable father

Constructor Detail

Controllable

public Controllable()

init the Controllable. No properties, no changes

Method Detail

setSon

protected void setSon(Controllable s)

removeSon

protected void removeSon(Controllable s)

setFather

public void setFather(Controllable f)

set a father which is asked when a value is not found in this controllable

invalidateFather

public void invalidateFather()

getFather

public Controllable getFather()

fatherChanged

protected void fatherChanged(java.lang.String key)

informSonsOfChange

protected void informSonsOfChange(java.lang.String key)

put

public java.lang.Object put(java.lang.String key,
                            java.lang.Object value)

put a property into the Controllable. A change flag for this property is raised automatically. The call may fail (in this case nothing is inserted), which is marked by a return value different from null. In this implementation this never happens.

setFlag

public void setFlag(java.lang.String key)

set a flag. The global change flag of the Controllable is raised.

resetFlag

public void resetFlag(java.lang.String key)

reset a flag explicitly. Note that the global change flag of the Controllable is NOT reset. This may cause a state where the Controllable in fact has not changed, but its flag indicates it has changed.

setChanged

public void setChanged(java.lang.String key)

set the changed flag for an object explicitily. Can be used for somehow dirty speedup tricks

get

public java.lang.Object get(java.lang.String key)

return a stored object. The object itself is returned, not a copy!

getFlag

public boolean getFlag(java.lang.String key)

return the state of a flag. A not-set flag cannot be distinguished from a non-existable flag.

hasChanged

public boolean hasChanged(java.lang.String key)

return if the state of a certain property has changed. This does not cover flags (as they do always change when they are set).

containsKey

public boolean containsKey(java.lang.String key)

Return whether there is a property "key" or not. This does not cover flags. It does not include the father, either.

Parameters:

key - The key to ask for.

Returns:

boolean value indicating whether the key is known or not.

containsKey

public boolean containsKey(java.lang.String key,
                           boolean askfather)

Return whether there is a property "key" or not. Does not cover any flags. If unknown in myself, asks father if second paramter is true.

Parameters:

key - The key to search.

askfather - Flag to indicate whether father should be asked.

Returns:

boolean value indicating whether the key is known by this or any father (if fathers are asked).

keys

public java.util.Iterator keys()

returns all available keys. This does not cover flags.

notifyObservers

public void notifyObservers()

notify all observers. Will only do something if anything (property, flag) has changed. In this case, all observers' update() method is called. The observers can react as they need to.

notifyObservers

public void notifyObservers(java.lang.Object arg)

notify all observers. Will only do something if anything (property, flag) has changed. In this case, all observers' update() method is called. The observers can react as they need to.

remove

public java.lang.Object remove(java.lang.String key)

remove a property from the Controllable. This raises the changed-flag for this property!

toString

public java.lang.String toString()