org.tm4j.topicmap.utils
Class XTMUtils

java.lang.Object
  org.tm4j.topicmap.utils.XTMUtils

public class XTMUtils

extends java.lang.Object

Utility class containing methods to reduce the number of objects in a TM4J topic map.

The static methods contained in this class implement one or more of the XTM duplicate suppression rules. This class also contains an implementation of the XTM topic merging rules.

The implementations in this class are safe to use with any TM4J backend.

Warning Many of the duplicate suppression algorithms are brute-force algorithms and may take some time to execute against large topic maps.

Field Summary

protected static org.apache.commons.logging.Log

m_log

Constructor Summary

XTMUtils()

Method Summary

protected static void	flattenTopicRefs(TopicMap tm) Performs a single pass through the topic map, replacing all topic references with a reference to the base topic of the merged topic set.
static TopicMap	makeConsistent(TopicMap tm) Creates a "consistent" topic map representation by applying the duplicate suppression rules of XTM 1.0 Annex F (section 6) This means that 1) All topics which are merged together are replaced by a single topic having the characteristics of all the merged ones (XTM 1.0 F.5.1) 2) Duplicate subject indicators on the same topic are collapsed into a single subject indicator (XTM 1.0 F.6.1) 3) Duplicate names in the same scope on the same topic are collapsed into a single name (XTM 1.0 F.6.2) 4) Duplicate role players in associations are removed (XTM 1.0 F.6.4) 5) Duplicate associations are collapsed into a single association (XTM 1.0 F.6.3) Note that F.6.4 is applied before F.6.3 as the XTM definition of a duplicate association uses a definition of equivalence which is affected by the aplication as F.6.4.
protected static void	removeDuplicateAssociations(java.util.Collection assocs, TopicMapUtils utils)
static void	removeDuplicateAssociations(TopicMap tm)
static void	removeDuplicateNames(Topic t)
static void	removeDuplicateOccurrences(Topic t)
static void	removeDuplicateSubjectIndicators(Topic t)
static Topic	staticMerge(Topic t) Takes all topics merged with t and adds their characteristics to t.
protected static Topic	staticMerge(Topic t, boolean swapTopics) Internal implementation of the static merge algorithm.
static void	swapTopic(Topic from, Topic to) Exchanges all uses of the topic from to use the topic to.

Methods inherited from class java.lang.Object

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

Field Detail

m_log

protected static final org.apache.commons.logging.Log m_log

Constructor Detail

XTMUtils

public XTMUtils()

Method Detail

makeConsistent

public static TopicMap makeConsistent(TopicMap tm)
                               throws TopicMapProcessingException,
                                      java.beans.PropertyVetoException

Creates a "consistent" topic map representation by applying the duplicate suppression rules of XTM 1.0 Annex F (section 6) This means that 1) All topics which are merged together are replaced by a single topic having the characteristics of all the merged ones (XTM 1.0 F.5.1) 2) Duplicate subject indicators on the same topic are collapsed into a single subject indicator (XTM 1.0 F.6.1) 3) Duplicate names in the same scope on the same topic are collapsed into a single name (XTM 1.0 F.6.2) 4) Duplicate role players in associations are removed (XTM 1.0 F.6.4) 5) Duplicate associations are collapsed into a single association (XTM 1.0 F.6.3) Note that F.6.4 is applied before F.6.3 as the XTM definition of a duplicate association uses a definition of equivalence which is affected by the aplication as F.6.4.

Parameters:

tm - The topic map to be processed

Returns:

The input topic map after all merging and duplicate supression has taken place. This method does not invalidate the reference originally passed in, so the return value is redundant.

Throws:

TopicMapProcessingException - If errors are encountered during merge or duplicate supression.

java.beans.PropertyVetoException - If a change to the topic map is vetoed during merge or duplicate suppression.

staticMerge

public static Topic staticMerge(Topic t)
                         throws TopicMapProcessingException,
                                java.beans.PropertyVetoException

Takes all topics merged with t and adds their characteristics to t. These merged topics are then also removed from the parent topic map.

Parameters:

t - The topic to be merged. This object may or may not survive the processing of this method. Callers should always use the returned Topic object in preference to the one passed in.

Returns:

The statically merged topic. The returned Topic object may not be the same as the Topic passed into this method.

Throws:

TopicMapProcessingException - If a processing error occurs during the static merge of the topic.

java.beans.PropertyVetoException - If a change to the topic is vetoed by a listener to the topic map.

staticMerge

protected static Topic staticMerge(Topic t,
                                   boolean swapTopics)
                            throws TopicMapProcessingException,
                                   java.beans.PropertyVetoException

Internal implementation of the static merge algorithm.

Parameters:

swapTopics - If this parameter is set to true then all refernecs to the merged topics will be replaced with a reference to the base topic.

Returns:

The statically merged topic. The returned Topic object may not be the same as the Topic passed into this method.

Throws:

TopicMapProcessingException - If a processing error occurs during the static merge of the topic.

java.beans.PropertyVetoException - If a change to the topic is vetoed by a listener to the topic map.

swapTopic

public static void swapTopic(Topic from,
                             Topic to)
                      throws TopicMapProcessingException,
                             java.beans.PropertyVetoException

Exchanges all uses of the topic from to use the topic to. This includes usages as type, as a theme in a scope, and as a roleSpec. from and to must both belong to the same TopicMap object. NOTE: The current implementation of this method uses the brute-force approach of enumerating all of the objects in the topic map, and so may be very slow for large topic maps.

Parameters:

from - The topic to be swapped in all of its uses

to - The topic to replace from.

Throws:

TopicMapProcessingException - If a processing error occurs while modifying the topic map.

java.beans.PropertyVetoException - If a swap of the topics is vetoed by a listener to the topic map.

flattenTopicRefs

protected static void flattenTopicRefs(TopicMap tm)
                                throws java.beans.PropertyVetoException

Performs a single pass through the topic map, replacing all topic references with a reference to the base topic of the merged topic set.

Throws:

java.beans.PropertyVetoException

removeDuplicateSubjectIndicators

public static void removeDuplicateSubjectIndicators(Topic t)
                                             throws java.beans.PropertyVetoException

Throws:

java.beans.PropertyVetoException

removeDuplicateNames

public static void removeDuplicateNames(Topic t)
                                 throws java.beans.PropertyVetoException

Throws:

java.beans.PropertyVetoException

removeDuplicateOccurrences

public static void removeDuplicateOccurrences(Topic t)
                                       throws java.beans.PropertyVetoException

Throws:

java.beans.PropertyVetoException

removeDuplicateAssociations

public static void removeDuplicateAssociations(TopicMap tm)
                                        throws java.beans.PropertyVetoException,
                                               IntegrityViolationException

Throws:

java.beans.PropertyVetoException

IntegrityViolationException

removeDuplicateAssociations

protected static void removeDuplicateAssociations(java.util.Collection assocs,
                                                  TopicMapUtils utils)
                                           throws java.beans.PropertyVetoException,
                                                  IntegrityViolationException

Throws:

java.beans.PropertyVetoException

IntegrityViolationException