Package net.ontopia.topicmaps.utils

Class 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 Detail

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

    • 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​(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 Detail

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