net.ontopia.topicmaps.utils
Class AssociationWalker

java.lang.Object
  net.ontopia.topicmaps.utils.AssociationWalker

public class AssociationWalker
extends java.lang.Object

PUBLIC: Computes the transitive closure of a relation characterized by two specific roles within a specific association type.

The relation is characterized by an association type A and a pair of roles R1 & R2 such that two topics T1 and T2 are related if T1 plays role R1 and T2 plays role R2 in an association A. A transitive relation is where "x is related to y" and "y is related to z" always implies that "x is related to z" Here, an association type, together with two roles within that type of association, is taken as the relation which is transitive.

In topic map terms, if: T1 plays role R1 in association A1 and T2 plays role R2 in association A1 and: T2 plays role R1 in association A2 and T3 plays role R2 in association A2 then: T1 and T3 are also (transitively) related.

Field Summary

protected DeciderIF	assocDecider PROTECTED: The decider used to filter associations to only those which are being walked
protected DeciderIF	leftRoleDecider PROTECTED: The decider used to filter the left-hand role of the transitive association
protected java.util.List<AssociationWalkerListenerIF>	listeners PROTECTED: The listeners to be informed as the walker processes the topic map.
protected DeciderIF	rightRoleDecider PROTECTED: The decider used to filter the right-hand role of the transitive association.

Constructor Summary

AssociationWalker(DeciderIF assocDecider, DeciderIF fromRoleDecider, DeciderIF toRoleDecider)
PUBLIC: Creates a walker which uses deciders to traverse the associations.

AssociationWalker(TopicIF associationType, TopicIF leftRoleSpec, TopicIF rightRoleSpec)
PUBLIC: Creates a walker which determines that a topic A is related to topic B if A plays a role specified by leftRoleSpec in an association of type associationType and topic B plays a role specified by rightRoleSpec in the same association.

Method Summary

void	addListener(AssociationWalkerListenerIF listener) PUBLIC: Registers a listener with the walker.
protected void	foundLeaf(net.ontopia.topicmaps.utils.WalkerState state) PROTECTED: Invoked when the walker encounters the end of a transitive association path.
boolean	isAssociated(TopicIF start, TopicIF associated) PUBLIC: Returns true if the two topics are directly or indirectly associated under the association type and rolespec definitions provided in the constructor for this walker.
void	removeListener(AssociationWalkerListenerIF listener) PUBLIC: Unregisters a listener with the walker.
protected net.ontopia.topicmaps.utils.WalkerState	walk(TopicIF start, boolean storePaths) PROTECTED: Computes the transitive closure under the association type and rolespec definitions provided in the constructor; this method is used by both walkTopics and walkPaths.
java.util.Collection<java.util.List<TMObjectIF>>	walkPaths(TopicIF start) PUBLIC: Computes the transitive closure under the association type and rolespec definitions provided in the constructor, and returns a set containing the paths taken through the topic map in computing the closure.
java.util.Set<TopicIF>	walkTopics(TopicIF start) PUBLIC: Computes the transitive closure under the association type and rolespec definitions provided in the constructor, and returns the result as a set of topics.

Methods inherited from class java.lang.Object

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

Field Detail

assocDecider

protected DeciderIF assocDecider

PROTECTED: The decider used to filter associations to only those which are being walked

leftRoleDecider

protected DeciderIF leftRoleDecider

PROTECTED: The decider used to filter the left-hand role of the transitive association

rightRoleDecider

protected DeciderIF rightRoleDecider

PROTECTED: The decider used to filter the right-hand role of the transitive association.

listeners

protected java.util.List<AssociationWalkerListenerIF> listeners

PROTECTED: The listeners to be informed as the walker processes the topic map.

Constructor Detail

AssociationWalker

public AssociationWalker(TopicIF associationType,
                         TopicIF leftRoleSpec,
                         TopicIF rightRoleSpec)

PUBLIC: Creates a walker which determines that a topic A is related to topic B if A plays a role specified by leftRoleSpec in an association of type associationType and topic B plays a role specified by rightRoleSpec in the same association.

Parameters:

associationType - The given association type; an object implementing TopicIF.

leftRoleSpec - The first given association rolespec; an object implementing TopicIF.

rightRoleSpec - The second given association rolespec; an object implementing TopicIF.

AssociationWalker

public AssociationWalker(DeciderIF assocDecider,
                         DeciderIF fromRoleDecider,
                         DeciderIF toRoleDecider)

PUBLIC: Creates a walker which uses deciders to traverse the associations.

Parameters:

assocDecider - ; an object implementing DeciderIF.

fromRoleDecider - ; an object implementing DeciderIF.

toRoleDecider - ; an object implementing DeciderIF.

Method Detail

walkTopics

public java.util.Set<TopicIF> walkTopics(TopicIF start)

PUBLIC: Computes the transitive closure under the association type and rolespec definitions provided in the constructor, and returns the result as a set of topics.

Parameters:

start - The topic to start the computation from; an object implementing TopicIF.

Returns:

An unmodifiable Set of TopicIF objects; the topics present in the closure.

walkPaths

public java.util.Collection<java.util.List<TMObjectIF>> walkPaths(TopicIF start)

PUBLIC: Computes the transitive closure under the association type and rolespec definitions provided in the constructor, and returns a set containing the paths taken through the topic map in computing the closure. Each path is a list consisting of alternating TopicIF and AssociationIF entries. The element at the start of the list is the starting TopicIF. The following AssociationIF is an association in which the TopicIF plays the specified left-hand role. The next node is a TopicIF which plays the specified right-hand role in the association and so on. The walker algorithm avoids cycles by cutting off paths as soon as a duplicate topic is encountered.

Parameters:

start - The topic to start the computation from; an object implementing TopicIF.

Returns:

An unmodifiable Collection of List objects.

walk

protected net.ontopia.topicmaps.utils.WalkerState walk(TopicIF start,
                                                       boolean storePaths)

PROTECTED: Computes the transitive closure under the association type and rolespec definitions provided in the constructor; this method is used by both walkTopics and walkPaths. If the storePaths parameter is false then the walker will collect only the set of topics which form the transitive closure and will not store the individual paths discovered.

Parameters:

start - The topic to start the computation from; an object implementing TopicIF.

storePaths - Boolean: if true, store paths walked; if false, store only topics found.

Returns:

A WalkerState object; the state of the walk at completion.

foundLeaf

protected void foundLeaf(net.ontopia.topicmaps.utils.WalkerState state)

PROTECTED: Invoked when the walker encounters the end of a transitive association path. This function is used to store the association path for later retrieval. If the current association path is a singleton, it is not stored.

Parameters:

state - A WalkerState object; the current state of the walk.

isAssociated

public boolean isAssociated(TopicIF start,
                            TopicIF associated)

PUBLIC: Returns true if the two topics are directly or indirectly associated under the association type and rolespec definitions provided in the constructor for this walker. The calculation is performed using a depth-first traversal of the tree formed by the associations concerned, which aborts as soon as the associated topic is found.

Parameters:

start - The topic to begin computation from; an object implementing TopicIF.

associated - The topic to be found in the association; an object implementing TopicIF.

Returns:

Boolean: true iff the given topics are directly or indirectly associated

addListener

public void addListener(AssociationWalkerListenerIF listener)

PUBLIC: Registers a listener with the walker. The listener will be notified each time the walker encounters a topic, association, associated-topic triple.

Parameters:

listener - The listener to be registered; an object implementing AssociationWalkerListenerIF.

See Also:

AssociationWalkerListenerIF

removeListener

public void removeListener(AssociationWalkerListenerIF listener)

PUBLIC: Unregisters a listener with the walker.

Parameters:

listener - The listener to be unregistered; an object implementing AssociationWalkerListenerIF.

See Also:

AssociationWalkerListenerIF