The class org.tm4j.topicmap.utils.XTMUtils provides a collection of methods which may be used to ensure that topic maps in TM4J meet all of the criteria for being a "consistent" topic map according to the definitions in the XTM specification. In brief, a "consistent" topic map is one in which all topics are merged according to the subject identity rules of XTM, leaving only one topic for each subject identified by these rules. In addition, duplicate names, occurrences, and associations are eliminated from the topic map. [2]
The static method makeConsistent() processes the TopicMap object provided as an input parameter to ensure that it meets all of the criteria for being a "consistent" topic map as defined by the XTM specification. To do this, the method will modify the topic map to replace all merged Topic objects with a single Topic object and to eliminate any duplicate names, occurrences and associations from the topic map. The TopicMap object is modified "in-place" that is the same TopicMap object is returned by the function as is specified in the input. When calling this method, you must expect that any externally maintained references to objects inside the topic map will become invalid for use after the method is called.
The makeConsistent() method is somewhat processor-intensive and may take a while to complete on large topic maps.
In addition to providing the method to automatically apply all of the criteria of a consistent topic map, the XTMUtils class also provides methods for selectively applying each of the criteria. The method staticMerge(Topic) causes all Topics merged with the specified Topic to be removed and their characteristics (their subject, subject indicators, names, occurrences and roles played in any associations) to be transferred to the specified topic. In addition, anywhere that a previously merged topic is used for typing or scoping, it will be replaced by the topic specified as the parameter to this method.
The methods removeDuplicateAssociations(TopicMap), removeDuplicateNames(Topic), removeDuplicateOccurrences(Topic), and removeDuplicateSubjectIndicators(Topic) perform each of the specified duplicate suppresion processes on the specified Topic or TopicMap.
Finally, the method flattenTopicRefs(TopicMap) walks through the entire topic map and makes sure that wherever a typing or scoping topic is used, that the reference to it is replaced (if necessary) with a reference to the baseTopic property of the Topic. This makes all such typing and scoping references consistently point to the same member of a set of merged topics.
With TM4J's dynamic merging model, forcing this referential consistency may be undesirable as if topics are merged, then references flattened and then topics are demerged, it is possible for the typing or scoping to get transferred from one Topic to another. For this reason, it is strongly recommended that you do not use this method in isolation, but instead at the very least perform a staticMerge() of the topics in the topic map.
[2] The full definition of what constitutes a "consistent" topic map can be found in the XTM specification Annex F.