casa.ontology.v3

Class HierarchicalDictionary<T extends OntologyEntity>

java.lang.Object

casa.ontology.v3.HierarchicalDictionary<T>

Type Parameters:

T - The type of info to store in this dictionary

All Implemented Interfaces:

Iterable<T>

abstract class HierarchicalDictionary<T extends OntologyEntity>
extends Object
implements Iterable<T>

A dictionary that uses it container class as an owner and uses the owner to access objects from dictionaries or its parents' dictionaries.

Author:

Rob Kremer

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) class	HierarchicalDictionary.Applier<T extends OntologyEntity,aRet,aParam> A class used by applyAllCachedSupers(Applier) and applyAllSupers(Applier) to run an algorithm on every dictionary in the "upward" part of the lattice from this one.

Field Summary

Fields

Modifier and Type	Field and Description
(package private) Vector<HierarchicalDictionary<T>>	cachedSearchPath A linear recording of a correct search order of all the ancestor dictionaries.
private CASAOntology	casaOntology
(package private) long	invalidationTimeStamp Used to record the time of the last invalidation for comparison during a search using the cached search path -- applyAllCachedSupers(Applier)
(package private) TreeMap<String,T>	map This map uses keys that are the UNQUALIFIED names (not the qualified "ontology:name" syntax).
private int	mark Used by applyAllSupers(Applier) to traverse the lattice of ontologies.
protected Ontology	owner

Constructor Summary

Constructors

Constructor and Description
HierarchicalDictionary(CASAOntology casaOntology, Ontology owner) Remembers the owner so that it can use the owner to access objects from dictionaries or its parents' dictionaries.

Method Summary

Modifier and Type	Method and Description
private void	applyAllCachedSupers(HierarchicalDictionary.Applier applier) Call HierarchicalDictionary.Applier.apply(HierarchicalDictionary) to all the dictionaries in the cached path cachedSearchPath.
private boolean	applyAllSupers(HierarchicalDictionary.Applier applier) Calls applier.apply() recursively to in all super dictionary in left-right order but with the constraint that no super dictionary is applied before all of it's sub dictionaries are applied.
private void	clearAllMarks() Sets the value of mark to zero and recursively those of all its super dictionaries.
protected boolean	consistencyCheck(Name key, T value) Subclasses should override this method to specify a consistency check between keys and values
boolean	containsKey(Name key) Determines if the key associated with this key in the dictionary.
boolean	containsKey(String key) Defers to containsKey(Name) by constructing a Name out of the key String.
T	get(Name key) Finds the object associated with this key in the dictionary.
T	get(String key) Defers to get(Name) by constructing a Name out of the key String.
protected abstract HierarchicalDictionary<T>	getDictionary(CASAOntology ontology) Subclasses should override this method to specify how to retrieve super-dictionaries from the containing ontology.
private void	incAllMarks() Increments the value of mark and recursively those of all its super dictionaries.
private void	initSuperSearch() Prepares for a search by applyAllSupers(Applier) by recursively clearing all marks and then incrementing them.
(package private) void	invalidateSearchPathCache() Invalidate the search path by setting cachedSearchPath to null and resetting invalidationTimeStamp to the current time.
Iterator<T>	iterator()
Set<String>	keySet()
T	put(Name key, T value) Adds the specified key and value to the dictionary.
T	put(String key, T value) Defers to #put(Name, Object) by constructing a Name out of the key String.
private void	resetSearchPathCache() Rebuilds the search path cache, cachedSearchPath, by climbing the hierarchy and recording an equivalent linear version of the search path.
Collection<T>	values()

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

casaOntology

private final CASAOntology casaOntology

owner

protected Ontology owner

map

TreeMap<String,T extends OntologyEntity> map

This map uses keys that are the UNQUALIFIED names (not the qualified "ontology:name" syntax).

mark

private int mark

Used by applyAllSupers(Applier) to traverse the lattice of ontologies. Note that since ontologies are shared, caution must be taken not to run into concurrency issues when using marks.

cachedSearchPath

Vector<HierarchicalDictionary<T extends OntologyEntity>> cachedSearchPath

A linear recording of a correct search order of all the ancestor dictionaries.

invalidationTimeStamp

long invalidationTimeStamp

Used to record the time of the last invalidation for comparison during a search using the cached search path -- applyAllCachedSupers(Applier)

Constructor Detail

HierarchicalDictionary

public HierarchicalDictionary(CASAOntology casaOntology,
                              Ontology owner)

Remembers the owner so that it can use the owner to access objects from dictionaries or its parents' dictionaries.

Parameters:

owner - The containing "this"

casaOntology - TODO

Method Detail

iterator

public Iterator<T> iterator()

Specified by:

iterator in interface Iterable<T extends OntologyEntity>

put

public T put(String key,
             T value)
      throws IllegalOperationException

Defers to #put(Name, Object) by constructing a Name out of the key String.

Parameters:

key -

value -

Returns:

the previous value associated with key, or null if there was no mapping for key. (A null return can also indicate that the map previously associated null with key.)

Throws:

IllegalOperationException - if the qualified syntax explicitly specifies a dictionary that is not the owner.

See Also:

#put(Name, Object)}

put

public T put(Name key,
             T value)
      throws IllegalOperationException

Adds the specified key and value to the dictionary. If the Name contains an ontology that refers to another ontology, the parent ontologies are searched. It's OK for the name to contain a null (or absent) ontology: it's just assumed to be this ontology.

Parameters:

key -

value -

Returns:

the previous value associated with key, or null if there was no mapping for key. (A null return can also indicate that the map previously associated null with key.)

Throws:

IllegalOperationException - if the qualified syntax explicitly specifies a dictionary that is not the owner.

get

public T get(Name key)

Finds the object associated with this key in the dictionary. If the Name contains an ontology that refers to another ontology, and that is an ancestor ontology, the appropriate value is returned. It's OK for the name to contain a null (or absent) ontology: it's just assumed to be either this ontology or one of the parent ontologies; in either case it is the value is returned according to the search rules specified in applyAllCachedSupers(Applier) and applyAllSupers(Applier).

Parameters:

key -

Returns:

the value to which the specified key is mapped, or null if this map contains no mapping for the key

Throws:

IllegalOperationException - if the qualified syntax explicitly specifies a dictionary that is not the owner.

incAllMarks

private void incAllMarks()

Increments the value of mark and recursively those of all its super dictionaries.

clearAllMarks

private void clearAllMarks()

Sets the value of mark to zero and recursively those of all its super dictionaries.

initSuperSearch

private void initSuperSearch()

Prepares for a search by applyAllSupers(Applier) by recursively clearing all marks and then incrementing them.

applyAllSupers

private boolean applyAllSupers(HierarchicalDictionary.Applier applier)

Calls applier.apply() recursively to in all super dictionary in left-right order but with the constraint that no super dictionary is applied before all of it's sub dictionaries are applied.

Parameters:

applier -

resetSearchPathCache

private void resetSearchPathCache()

Rebuilds the search path cache, cachedSearchPath, by climbing the hierarchy and recording an equivalent linear version of the search path. Because this must mark nodes as they are visited, this behaviour must synchronize on the CLASS of this dictionary, locking out all other similar dictionaries in the process. Because we need to assure that multiple reset's don't happen at once, this method is synchronized to the instance, and will just return if the cachedSearchPath is NOT null. Therefore, you need to set cachedSearchPath to null FIRST if you want to rebuild and exist cachedSearchPath.

invalidateSearchPathCache

void invalidateSearchPathCache()

Invalidate the search path by setting cachedSearchPath to null and resetting invalidationTimeStamp to the current time.

See Also:

applyAllCachedSupers(Applier)

applyAllCachedSupers

private void applyAllCachedSupers(HierarchicalDictionary.Applier applier)

Call HierarchicalDictionary.Applier.apply(HierarchicalDictionary) to all the dictionaries in the cached path cachedSearchPath. Note that if one the super-dictionaries has had it's search path invalidated after this search path has been invalidated, then we must invalidate ours, rebuild it and recursively start again.

Parameters:

applier -

get

public T get(String key)
      throws IllegalOperationException

Defers to get(Name) by constructing a Name out of the key String.

Parameters:

key -

Returns:

the value to which the specified key is mapped, or null if this map contains no mapping for the key

Throws:

IllegalOperationException

IllegalOperationException - if the qualified syntax explicitly specifies a dictionary that is not the owner.

See Also:

#get(Name)}

containsKey

public boolean containsKey(String key)
                    throws IllegalOperationException

Defers to containsKey(Name) by constructing a Name out of the key String.

Parameters:

key -

Returns:

true iff the specified key is mapped, or null if this map contains no mapping for the key

Throws:

IllegalOperationException - if the qualified syntax explicitly specifies a dictionary that is not the owner.

See Also:

#containsKey(Name)}

containsKey

public boolean containsKey(Name key)

Determines if the key associated with this key in the dictionary. If the Name contains an ontology that refers to another ontology, an exception is thrown. It's OK for the name to contain a null (or absent) ontology: it's just assumed to be either this ontology or one of the parent ontologies; in either case the search is performed.

Parameters:

key -

Returns:

true iff the specified key is mapped, or null if this map contains no mapping for the key

Throws:

IllegalOperationException - if the qualified syntax explicitly specifies a dictionary that is not the owner.

keySet

public Set<String> keySet()

Returns:

the set of fully-qualified ("ontology:name" syntax) of keys contained in this dictionary (but not it's parent dictionaries).

values

public Collection<T> values()

Returns:

the set of values (not keys) contained in this dictionary (but not it's parent dictionaries).

consistencyCheck

protected boolean consistencyCheck(Name key,
                                   T value)

Subclasses should override this method to specify a consistency check between keys and values

Parameters:

key -

value -

Returns:

true is the key and value are consistent with one another

getDictionary

protected abstract HierarchicalDictionary<T> getDictionary(CASAOntology ontology)

Subclasses should override this method to specify how to retrieve super-dictionaries from the containing ontology.

Parameters:

superOntology -

Returns: