Traverser (Ceryle API Documentation)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.ceryle.tm
Class Traverser

java.lang.Object
  org.ceryle.tm.Traverser

public class Traverser
extends Object
extends Object

A utility class containing one method for traversing TopicMap graphs, directed or undirected.

At their most basic, graphs consist of nodes and edges (aka "arcs"). In some graph representations, there are simply Nodes and Edges (the Edges being the lines between Nodes):


                       Topic3
                        /
                       /
          Topic1----Topic2
                       \
                        \
                       Topic4

Figure 1.

A Topic Map graph is bipartite, composed of two types of nodes: Topics and the Associations (between Topics). In this form of graph, the semantics of an Association are contained entirely within its node; graph edges are merely connectors and have no meaning of their own, though they may be directed, based on the role played by the connected Topic. Therefore, the equivalent of the above diagram in this mode of displaying a graph might appear as follows:



                                 Topic3
                                   /
                                  /
                              Assoc2
                                /
                               /
         Topic1----Assoc1----Topic2
                               \
                                \
                              Assoc3
                                  \
                                   \
                                 Topic4

Figure 2.

Because this style of graph never connects Topics directly to other Topics or Associations directly to other Associations (i.e., one only finds Topic-to-Association-to-Topic connections), in the Topic Map graph one traverses from a specific Topic to other Topics only via Associations.

Determining Traversal Direction

Traversal direction is determined via two supplied Locators, whose addresses are considered as role player topic type PSIs for 'From' and 'To' directions. Topics playing directed roles in Associations are typed with Topics whose subjects are these two PSIs.

For example, the XTM 1.0 PSI set includes superclass-subclass and class-instance relationships. There are a total of six PSIs involved: two association types, with each having two role player types. The original association types did not indicate direction, but common synonyms for these two relationships are predicates in a form that implies a direction. Essentially, the specific language chosen will indicate the direction. E.g., the superclass-subclass relation may be expressed either as:

   [subclass] "is a specialization of" [superclass]

   [superclass] "is a generalization of" [subclass]

Below are shown the two groupings, showing the original XTM PSI title, the common predicate chosen, and the indicated directions for the role players:

superclass-subclass association type ("kind of", or "is a specialization of")
superclass role player type (To)
subclass role player type (From)

class-instance association type ("is a", or "has class of")
class role player type (To)
instance role player type (From)

To traverse forward/to, say from a subclass to its superclass, to a depth of three from a starting topic, the method call would be:

      Locator supsub = locatorFactory.createLocator("URI",
              "http://www.topicmaps.org/xtm/1.0/core.xtm#superclass-subclass");
      Locator sup = locatorFactory.createLocator("URI",
              "http://www.topicmaps.org/xtm/1.0/core.xtm#superclass");
      Locator sub = locatorFactory.createLocator("URI",
              "http://www.topicmaps.org/xtm/1.0/core.xtm#subclass");
      Set set = Traverser.traverse(topic,Traverser.TRAVERSE_TO,3,supsub,sup,sub);

If traversal of multiple association types is desired, all "From" and "To" role player Topics may be typed by superclasses, with these superclass Topics being provided as parameters to this method. In this case, set the static boolean checkRolePlayerSubject to false (default is true), to check the role player Topic's type instead of its subject identity. This only checks the parent type, and does not traverse any type hierarchy.

Note:

Traversal currently does not currently include Scope nodes, which are avoided/ignored. This also pays no attention to the semantics of the traversal, only any potential direction (ie., traversal will not occur against an edge when the Association role indicates that its relationship has direction.

Since:: JDK1.3
Version:: $Id: Traverser.java,v 3.4 2007-06-15 12:09:33 altheim Exp $
Author:: Murray Altheim

Field Summary
`protected static boolean`	`checkRolePlayerSubject` A boolean that when true (the default) indicates that the basic check on the Topic used for role player direction should be a subject identity check.
`static int`	`maxDepth` The maximum allowed depth (100).
`static int`	`TRAVERSE_ANY` An int constant indicating any traversal direction, i.e., in any direction, ignoring arrow directions.
`static int`	`TRAVERSE_FROM` An int constant indicating a 'From' traversal direction, i.e., against the direction of arrows, to-to-from.
`static int`	`TRAVERSE_TO` An int constant indicating a 'To' traversal direction, i.e., in the direction of arrows, from-to-to.

Constructor Summary
`Traverser()`

Method Summary
`static String`	`getDirectionLabel(int dir)` Returns a String description of the provided direction.
`protected static boolean`	`roleCheck(Topic t, int d, Locator fwd, Locator rev)` Returns true if the direction and role match.
`static Set`	`traverse(Topic topic, int direction, int depth, Topic associationType, Locator toLocator, Locator fromLocator)` Returns a Set containing all Topics the provided Topic `topic` is connected to via Associations.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

checkRolePlayerSubject

protected static boolean checkRolePlayerSubject

A boolean that when true (the default) indicates that the basic check on the Topic used for role player direction should be a subject identity check. When false, the check is on the Topic's type (<instanceOf>).

TRAVERSE_FROM

public static final int TRAVERSE_FROM

An int constant indicating a 'From' traversal direction, i.e., against the direction of arrows, to-to-from.

See Also:: Constant Field Values

TRAVERSE_ANY

public static final int TRAVERSE_ANY

An int constant indicating any traversal direction, i.e., in any direction, ignoring arrow directions.

See Also:: Constant Field Values

TRAVERSE_TO

public static final int TRAVERSE_TO

An int constant indicating a 'To' traversal direction, i.e., in the direction of arrows, from-to-to.

See Also:: Constant Field Values

maxDepth

public static int maxDepth

The maximum allowed depth (100).

Constructor Detail

Traverser

public Traverser()

Method Detail

traverse

public static Set traverse(Topic topic,
                           int direction,
                           int depth,
                           Topic associationType,
                           Locator toLocator,
                           Locator fromLocator)

Returns a Set containing all Topics the provided Topic topic is connected to via Associations. If the enumerated int direction parameter is TRAVERSE_TO or TRAVERSE_FROM, traversal will pay attention to direction and only include those Topics which follow the traversal direction. If set to TRAVERSE_ANY, traversal will ignore direction and return all connected Topics. In this case, the directional Locators are ignored and can be supplied as null values. If the Topic associationType is non-null, it acts as a constraint, being the required type of traversed associations.

The depth of traversal depth should be set to 1 to return only those Topics one Association away from topic. Setting it to zero (or less) returns an empty Set, not null. Note that providing null values for either Locator causes role checking for that role to be ignored, such that providing two null Locators on a directed traversal will provide the same result set as an adirectional traversal.

As mentioned above, allowable values for direction include TRAVERSE_TO (in the direction of arrows, from-to-to; TRAVERSE_FROM (against the direction of arrows, to-to-from; or TRAVERSE_ANY (in any direction).

Parameters:: topic - the Topic from which the traversal begins; direction - an enumerated int setting traversal direction; depth - an int setting traversal depth (eg., '1' is one level from topic); associationType - the typing Topic of traversed associations (ignored if null); toLocator - the Locator typing 'To' roles; fromLocator - the Locator typing 'From' roles
Returns:: a Set containing the connected Topics, empty if none

roleCheck

protected static boolean roleCheck(Topic t,
                                   int d,
                                   Locator fwd,
                                   Locator rev)

Returns true if the direction and role match. This always returns true when the direction is TRAVERSE_ANY; also, null values for the Locators will cause checks in that direction to be ignored.

getDirectionLabel

public static String getDirectionLabel(int dir)

Returns a String description of the provided direction.