Package net.ontopia.topicmaps.utils

Class AssociationWalker

java.lang.Object
net.ontopia.topicmaps.utils.AssociationWalker
public class AssociationWalker extends 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

    Fields
    Modifier and Type
    Field
    Description
    protected Predicate<AssociationIF>
    assocDecider
    PROTECTED: The decider used to filter associations to only those which are being walked
    protected Predicate<AssociationRoleIF>
    leftRoleDecider
    PROTECTED: The decider used to filter the left-hand role of the transitive association
    protected List<AssociationWalkerListenerIF>
    listeners
    PROTECTED: The listeners to be informed as the walker processes the topic map.
    protected Predicate<AssociationRoleIF>
    rightRoleDecider
    PROTECTED: The decider used to filter the right-hand role of the transitive association.

  • Constructor Summary

    Constructors
    Constructor
    Description
    AssociationWalker(Predicate<AssociationIF> assocDecider, Predicate<AssociationRoleIF> fromRoleDecider, Predicate<AssociationRoleIF> 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

    Modifier and Type
    Method
    Description
    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.
    Collection<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.
    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 Details

    • assocDecider

      protected Predicate<AssociationIF> assocDecider
      PROTECTED: The decider used to filter associations to only those which are being walked

    • leftRoleDecider

      protected Predicate<AssociationRoleIF> leftRoleDecider
      PROTECTED: The decider used to filter the left-hand role of the transitive association

    • rightRoleDecider

      protected Predicate<AssociationRoleIF> rightRoleDecider
      PROTECTED: The decider used to filter the right-hand role of the transitive association.

    • listeners

      protected List<AssociationWalkerListenerIF> listeners
      PROTECTED: The listeners to be informed as the walker processes the topic map.

  • Constructor Details

    • 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(Predicate<AssociationIF> assocDecider, Predicate<AssociationRoleIF> fromRoleDecider, Predicate<AssociationRoleIF> toRoleDecider)
      PUBLIC: Creates a walker which uses deciders to traverse the associations.
      Parameters:
      assocDecider - ; an object implementing Predicate.
      fromRoleDecider - ; an object implementing Predicate.
      toRoleDecider - ; an object implementing Predicate.

  • Method Details

    • walkTopics

      public 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 Collection<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:

    • 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: