org.tm4j.topicmap.utils
Class TopicMapMerger

java.lang.Object
  org.tm4j.topicmap.utils.HelperBase
      org.tm4j.topicmap.utils.TopicMapMerger

public class TopicMapMerger

extends HelperBase

A "beanish" helper class for merging topic maps. This class is a bean-like utility to merge multiple SourceAddressPairs into one result TopicMap. A common usage pattern for instances of this class is this:

• Construct an instance of TopicMapMerger.
• (optional) Register event listeners so you can deal with property changes. See below for a list of bound properties supported by this class. Changes to most of the properties supported by this class are vetoable, so you are able to register a VetoableChangeListener and provide for consistency or sanity checks.
• (optional) Register a jakarta-commons Log to receive log messages.
• (optional) Set properties using their setter methods. You can skip this step if you prefer to use the default property values.
• (optional) Add sources to the merger. For this purpose, you can either invoke addSource(InputStream, Locator) or one of the other addSource() methods, or you can set all the sources at once, providing setSources(List) with a List of TopicMapSources. If you omit this step, the application must pipe a topic map to stdin.
• Invoke merge() to perform the actual merging operation.
• Retrieve the merged result topic map using getResult().

This class supports the following "bound" properties. You can retrieve these using getPropertyName and set them using setPropertyName. Changes to these bound properties are vetoable and may be rolled back by a registered VetoableChangeListener.

• "defaultBaseUri" (String, read/write). The URI to serve as the default base Locator in case none has been specified on a SourceAddressPair being processed. The default for this value is a file: URI pointing to the user's current working directory.
• "makeConsistent" (boolean, read/write). If true, the result topic map will be post-processed to make sure it is consistent. If false, that step is skipped. The default is true.
• "mergeExternalTopicMaps" (boolean, read/write). If false, <mergeMap> elements in the source topic maps will be ignored. If true, they will be processed and merged into the result topic map. The default is false as this may be a costly and time-consuming operation.
• "mergeMapsForExternallyReferencedTopics" (boolean, read/write). If true, the topic maps of externally referenced (via <topicRef>) topics are merged into the result. If false, they will not be merged in. The default is false as this may be a costly and time-consuming operation.
• "sources" (List, read/write). The list of TopicMapSources to be processed while merging. The default is an empty List.
• "logger" (org.apache.commons.logging.Log, read/write). The jakarta-commons log to receive logging messages. The default is null, which will cause any debugging output, except "fatal" messages, to be suppressed. This property is inherited from the superclass.

In addition, this class also supports the following non-vetoable bound properties. Changes to these properties cannot be rolled back, but an application may still register a PropertyChangeListener to deal with such changes in an appropriate manner.

• "initialized" (boolean, read-only). true if the instance has been properly initialized, false otherwise. The default (prior to initialization) is false.
• "merged" (boolean, read-only). true if the topic map merge has been completed, false otherwise. The default (prior to the merging operation) is false.
• "result" (TopicMap, read-only). The topic map created as the result of the merge. The default (prior to the merging operation) is null.

Note: As for now, this class is capable of processing SourceAddressPairs in addition to TopicMapSources. Don't count on this being available in future versions; SourceAddressPair is now deprecated and will go away in future releases.

Since:

0.8.4

Author:

Florian G. Haas

Field Summary

protected static boolean	DEFAULT_MAKE_CONSISTENT The default value to be used for the "makeConsistent" property.
protected static boolean	DEFAULT_MERGE_MAPS_FOR_EXTREF_TOPICS The default value to be used for the "mergeMapsForExternallyReferencedTopics" property.
protected static boolean	DEFAULT_PROCESS_MERGEMAP The default value to be used for the "processMergeMap" property.

Constructor Summary

TopicMapMerger()

Method Summary

void	addSource(java.io.File in) Constructs a TopicMapSource from the given File and a corresponding Locator, and adds it to the list of sources.
void	addSource(java.io.File in, Locator baseLocator) Constructs a TopicMapSource from the given File and locator, and adds it to the list of sources.
void	addSource(java.io.InputStream in) Constructs a SourceAddressPair from the given InputStream and the default base locator, and adds it to the list of sources.
void	addSource(java.io.InputStream in, Locator baseLocator) Constructs a TopicMapSource from the given InputStream and locator, and adds it to the list of sources.
void	addSource(TopicMapSource source) Adds a configured TopicMapSource to the list of sources to be processed.
void	addSource(java.net.URL in) Constructs a TopicMapSource from the given URL and a corresponding Locator, and adds it to the list of sources.
void	addSource(java.net.URL in, Locator baseLocator) Constructs a TopicMapSource from the given URL and locator, and adds it to the list of sources.
protected Locator	getDefaultBaseLocator() Returns the default base locator.
java.lang.String	getDefaultBaseUri() Returns the default base URI.
TopicMapProvider	getProvider() Returns the topic map provider used during merging.
TopicMap	getResult() Retrieves the TopicMap that results from the merge operation.
java.util.List	getSources() Retrieves the list of sources to be merged.
protected void	init() Initializes the object.
boolean	isInitialized() Determines whether the instance has been properly initialized.
boolean	isMakingConsistent() Determines whether the instance has been set to post-process merged topic maps to ensure consistency.
boolean	isMerged() Determines whether the instance has completed the merging process.
boolean	isMergingMapsForExternallyReferencedTopics() Determines whether the instance is configured to merge in the topic maps associated with any externally referenced topics present in one of the source topic maps.
boolean	isProcessingMergeMap() Determines whether the instance has been set to include externally referenced topic maps in the merge by processing <mergeMap> elements.
protected Locator	makeDefaultBaseLocator() Creates the default base locator from the configured default base URI.
protected TopicMapProvider	makeProvider() Sets up a new TopicMapProvider.
protected void	makeRawMergedTopicMap() Creates a "raw" merged topic map from the configured sources.
protected void	makeResultConsistent() Creates a consistent topic map from the "raw" result.
void	merge() Performs the actual merge.
protected void	mergeExternallyReferencedTopicMaps() Merges in the topic maps of any externally referenced (via <topicRef>) topics present in the source topic maps.
protected void	mergeMergedMaps() Merges externally referenced topic maps, by processing <mergeMap> elements.
protected void	setDefaultBaseLocator(Locator newLocator) Sets the default base locator.
void	setDefaultBaseUri(java.lang.String newVal) Sets the default base URI.
protected void	setInitialized(boolean newVal) Sets the initialization state of the instance.
void	setMakeConsistent(boolean newVal) Instructs the instance to post-process merged topic maps to ensure consistency.
protected void	setMerged(boolean newVal) Sets the state of completion for the merging process.
void	setMergeMapsForExternallyReferencedTopics(boolean newVal) Configures the instance to load the topic maps associated with any externally referenced topics (via <topicRef> elements) in the merge result.
void	setProcessMergeMap(boolean newVal) Configures the instance to include externally referenced topic maps in the merge by processing <mergeMap> elements.
void	setProvider(TopicMapProvider newProvider) Sets the topic map provider to be used during merging.
protected void	setResult(TopicMap newResult) Sets the result of the topic map merge.
void	setSources(java.util.List newList) Sets the list of sources to be processed during merging.

Methods inherited from class org.tm4j.topicmap.utils.HelperBase

addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, debug, error, error, fatal, fatal, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, getLogger, hasLogger, info, logVetoedChange, removeLogger, setLogger, trace, warn, warn

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_MAKE_CONSISTENT

protected static final boolean DEFAULT_MAKE_CONSISTENT

The default value to be used for the "makeConsistent" property.

See Also:

Constant Field Values

DEFAULT_PROCESS_MERGEMAP

protected static final boolean DEFAULT_PROCESS_MERGEMAP

The default value to be used for the "processMergeMap" property.

See Also:

Constant Field Values

DEFAULT_MERGE_MAPS_FOR_EXTREF_TOPICS

protected static final boolean DEFAULT_MERGE_MAPS_FOR_EXTREF_TOPICS

The default value to be used for the "mergeMapsForExternallyReferencedTopics" property.

See Also:

Constant Field Values

Constructor Detail

TopicMapMerger

public TopicMapMerger()

Method Detail

addSource

public void addSource(java.io.File in)
               throws java.io.IOException

Constructs a TopicMapSource from the given File and a corresponding Locator, and adds it to the list of sources. This is merely a convenience method which constructs a URL from the given File, and then invokes addSource(URL).

Parameters:

in - the file from which to read the topic map. Must not be null.

Throws:

java.io.IOException - if the file representing the topic map cannot be accessed.

addSource

public void addSource(java.io.File in,
                      Locator baseLocator)
               throws java.io.IOException

Constructs a TopicMapSource from the given File and locator, and adds it to the list of sources. This is merely a convenience method which constructs a URL from the given File, and then invokes addSource(URL, Locator).

Parameters:

in - the file from which to read the topic map. Must not be null.

baseLocator - the base locator to be used with the topic map. May be null, in which case it will be silently ignored and the default base locator will be used instead.

Throws:

java.io.IOException - if the file representing the topic map cannot be accessed.

addSource

public void addSource(java.io.InputStream in)

Constructs a SourceAddressPair from the given InputStream and the default base locator, and adds it to the list of sources.

Parameters:

in - the stream from which to read the topic map. Must not be null.

addSource

public void addSource(java.io.InputStream in,
                      Locator baseLocator)

Constructs a TopicMapSource from the given InputStream and locator, and adds it to the list of sources. All other addSource() methods invoke this one, so this method is a good one to override if a subclass chooses to alter the mechanism of adding sources to be processed.

Parameters:

in - the stream from which to read the topic map. Must not be null.

baseLocator - the base locator to be used with the topic map. May be null, in which case it will be ignored, a warning will be issued to the registered Log (if any), and the default base locator will be used instead.

addSource

public void addSource(TopicMapSource source)

Adds a configured TopicMapSource to the list of sources to be processed.

Parameters:

source - the topic map source to be added.

addSource

public void addSource(java.net.URL in)
               throws java.io.IOException

Constructs a TopicMapSource from the given URL and a corresponding Locator, and adds it to the list of sources. This is merely a convenience method which constructs an InputStream from the given URL, and then invokes addSource(InputStream).

Parameters:

in - the URL from which to read the topic map. Must not be null.

Throws:

java.io.IOException - if the URL is inaccessible.

addSource

public void addSource(java.net.URL in,
                      Locator baseLocator)
               throws java.io.IOException

Constructs a TopicMapSource from the given URL and locator, and adds it to the list of sources. This is merely a convenience method which constructs an InputStream from the given URL, and then invokes addSource(InputStream, Locator).

Parameters:

in - the URL from which to read the topic map. Must not be null.

baseLocator - the base locator to be used with the topic map. May be null, in which case it will be silently ignored and the default base locator will be used instead.

Throws:

java.io.IOException - if the URL is inaccessible.

getDefaultBaseLocator

protected Locator getDefaultBaseLocator()

Returns the default base locator.

Returns:

the Locator being used for those topic maps in the merging operation that don't come with an explicitly defined base locator.

getDefaultBaseUri

public java.lang.String getDefaultBaseUri()

Returns the default base URI.

Returns:

the URI being used for those topic maps in the merging operation that don't come with an explicitly defined base URI.

getProvider

public TopicMapProvider getProvider()

Returns the topic map provider used during merging.

Returns:

the topic map provider. The provider is initialized by init() or during object creation, using the appropriate factory class.

getResult

public TopicMap getResult()

Retrieves the TopicMap that results from the merge operation.

Returns:

the merged topic map as generated by the merge() method. If the merge has not yet been performed (i.e. merge() has not yet been called), the returned result is null.

getSources

public java.util.List getSources()

Retrieves the list of sources to be merged.

Returns:

a List of TopicMapSources to be merged when merge() is invoked. If no sources have been added yet, the returned List is empty, it is never null.

init

protected void init()
             throws java.lang.InstantiationException,
                    java.lang.IllegalAccessException,
                    TopicMapProviderException,
                    LocatorFactoryException,
                    java.lang.ClassNotFoundException

Initializes the object. Invoked by the constructor, so there is no need for explicitly invoking this method when creating a new instance.

Specified by:

init in class HelperBase

Throws:

java.lang.InstantiationException

java.lang.IllegalAccessException

TopicMapProviderException

LocatorFactoryException

java.lang.ClassNotFoundException

isInitialized

public boolean isInitialized()

Determines whether the instance has been properly initialized.

Returns:

true if the initialization process completed without errors, false otherwise.

isMakingConsistent

public boolean isMakingConsistent()

Determines whether the instance has been set to post-process merged topic maps to ensure consistency.

Returns:

true if the instance will post-process merged topic maps for consistency, false otherwise.

isMerged

public boolean isMerged()

Determines whether the instance has completed the merging process.

Returns:

true if merging has completed, false otherwise. If the instance has been configured to post-process the result topic map for consistency or external topic map merging, this method will not return true until these additional operations have been completed as well.

isMergingMapsForExternallyReferencedTopics

public boolean isMergingMapsForExternallyReferencedTopics()

Determines whether the instance is configured to merge in the topic maps associated with any externally referenced topics present in one of the source topic maps.

Returns:

true if the instance will include the topic maps associated with externally referenced topic in the merge result, false otherwise.

isProcessingMergeMap

public boolean isProcessingMergeMap()

Determines whether the instance has been set to include externally referenced topic maps in the merge by processing <mergeMap> elements.

Returns:

true if the instance will include externally referenced topic maps in the merge result, false otherwise.

makeDefaultBaseLocator

protected Locator makeDefaultBaseLocator()
                                  throws LocatorFactoryException

Creates the default base locator from the configured default base URI.

Returns:

a newly created Locator representing the default base locator.

Throws:

LocatorFactoryException - if the locator could not be created.

makeProvider

protected TopicMapProvider makeProvider()
                                 throws java.lang.InstantiationException,
                                        java.lang.IllegalAccessException,
                                        TopicMapProviderException

Sets up a new TopicMapProvider.

Returns:

a newly created TopicMapProvider.

Throws:

java.lang.InstantiationException - if the TopicMapProviderFactory could not be instantiated.

java.lang.IllegalAccessException - if access to the TopicMapProviderFactory class has been denied by a security manager.

TopicMapProviderException - if something else went wrong during TopicMapProvider setup.

makeRawMergedTopicMap

protected void makeRawMergedTopicMap()
                              throws TopicMapProviderException

Creates a "raw" merged topic map from the configured sources. The topic map is not post-processed to ensure consistency, nor does it include externally referenced topic maps.

Throws:

TopicMapProviderException - if a source could not be read, parsed, or loaded.

makeResultConsistent

protected void makeResultConsistent()
                             throws TopicMapProcessingException

Creates a consistent topic map from the "raw" result.

Throws:

TopicMapProcessingException - if an unexpected condition occurs during post-processing.

merge

public void merge()
           throws TopicMapProviderException,
                  TopicMapProcessingException

Performs the actual merge. After merging is completed, the result can be retrieved via getResult().

Throws:

TopicMapProviderException

TopicMapProcessingException

mergeExternallyReferencedTopicMaps

protected void mergeExternallyReferencedTopicMaps()
                                           throws TopicMapProviderException

Merges in the topic maps of any externally referenced (via <topicRef>) topics present in the source topic maps.

Throws:

TopicMapProviderException - if the attempt to merge in the external topic map fails.

mergeMergedMaps

protected void mergeMergedMaps()
                        throws TopicMapProviderException

Merges externally referenced topic maps, by processing <mergeMap> elements.

Throws:

TopicMapProviderException - if an external topic map couldn't be accessed, parsed, loaded, or merged into the "raw" result.

setDefaultBaseLocator

protected void setDefaultBaseLocator(Locator newLocator)

Sets the default base locator.

Parameters:

newLocator - the new default base locator to be used.

setDefaultBaseUri

public void setDefaultBaseUri(java.lang.String newVal)

Sets the default base URI. Since changes to this property are vetoable, a registered VetoableChangeListener may determine that the property change is inappropriate or invalid, and ask for it to be rolled back. In that case, the property's original value is restored, and a warning is issued to any registered logger.

Parameters:

newVal - the URI being used for those topic maps in the merging operation that don't come with an explicitly defined base URI.

setInitialized

protected void setInitialized(boolean newVal)

Sets the initialization state of the instance.

Parameters:

newVal - true if the instance is to be considered properly initialized, false otherwise.

setMakeConsistent

public void setMakeConsistent(boolean newVal)

Instructs the instance to post-process merged topic maps to ensure consistency. Since changes to this property are vetoable, a registered VetoableChangeListener may determine that the property change is inappropriate or invalid, and ask for it to be rolled back. In that case, the property's original value is restored, and a warning is issued to any registered logger.

Parameters:

newVal - true if the instance will post-process merged topic maps for consistency, false otherwise.

setMerged

protected void setMerged(boolean newVal)

Sets the state of completion for the merging process.

Parameters:

newVal - true if merging has completed, false otherwise. If the instance has been configured to post-process the result topic map for consistency or external topic map merging, this method should not be invoked with true until these additional operations have been completed as well.

setMergeMapsForExternallyReferencedTopics

public void setMergeMapsForExternallyReferencedTopics(boolean newVal)

Configures the instance to load the topic maps associated with any externally referenced topics (via <topicRef> elements) in the merge result. Since changes to this property are vetoable, a registered VetoableChangeListener may determine that the property change is inappropriate or invalid, and ask for it to be rolled back. In that case, the property's original value is restored, and a warning is issued to any registered logger.

Parameters:

newVal - true if the instance will include the topic maps associated with any externally referenced topics in the merge result, false otherwise.

setProcessMergeMap

public void setProcessMergeMap(boolean newVal)

Configures the instance to include externally referenced topic maps in the merge by processing <mergeMap> elements. Since changes to this property are vetoable, a registered VetoableChangeListener may determine that the property change is inappropriate or invalid, and ask for it to be rolled back. In that case, the property's original value is restored, and a warning is issued to any registered logger.

Parameters:

newVal - true if the instance will include externally referenced topic maps in the merge result, false otherwise.

setProvider

public void setProvider(TopicMapProvider newProvider)

Sets the topic map provider to be used during merging.

Parameters:

newProvider - the new TopicMapProvider to be used for merging operations.

setResult

protected void setResult(TopicMap newResult)

Sets the result of the topic map merge.

Parameters:

newResult - the TopicMap that represents the result of the merging operation.

setSources

public void setSources(java.util.List newList)

Sets the list of sources to be processed during merging.

Parameters:

newList - a List of TopicMapSources to be processed during the merge. If this argument is null, it is ignored and the property is reinitialized with an empty List.