org.tm4j.topicmap
Class TopicMapProviderBase

java.lang.Object
  extended byorg.tm4j.topicmap.source.TopicMapSourceSupport
      extended byorg.tm4j.topicmap.TopicMapProviderBase
All Implemented Interfaces:
TopicMapProvider

public abstract class TopicMapProviderBase
extends TopicMapSourceSupport
implements TopicMapProvider

Provides a skeleton implementation of a basic TopicMapProvider with the addTopicMap() method implemented. Back-end providers are free to derive their TopicMapProvider implementation from this class. The addTopicMap() method calls the getFactory() method to instantiate the TopicMapBuilder used during parsing of the file.

If the System property org.tm4j.useCatalogResolver is set to "true" or "yes", an CatalogResolver will be created and attached to the SAXParser (as well as the embedded URILocatorResolver) for resolution of public and system identifiers. This also provides a utility method resolveEntity(String,String) for this purpose.

The resolver understands OASIS TR9401 catalogs, XCatalogs, and the current working draft of the OASIS Entity Resolution Technical Committee. For more information on XML entity resolution using catalog files, see XML Entity and URI Resolvers (version 1.1) by Norm Walsh at Sun Microsystems.

Author:
Kal Ahmed, Murray Altheim (XML catalog support), Harald Kuhn (TopicMapSource Support)

Field Summary
static java.lang.String defaultCatalogPath
          The default relative pathname for the XML Catalog file ("resource/tm4j.xcat").
protected  org.apache.xml.resolver.tools.CatalogResolver m_catalogResolver
          Reusable XML catalog resolution service.
 javax.xml.parsers.SAXParser m_parser
           
 
Fields inherited from interface org.tm4j.topicmap.TopicMapProvider
DEFAULT_OPT_MAKE_CONSISTENT, DEFAULT_OPT_MERGE_REFS, DEFAULT_OPT_NAME_MERGE, DEFAULT_OPT_STATIC_MERGE, OPT_MAKE_CONSISTENT, OPT_MERGE_REFS, OPT_NAME_MERGE, OPT_STATIC_MERGE
 
Constructor Summary
TopicMapProviderBase()
          A constructor for a skeleton TopicMapProvider.
TopicMapProviderBase(org.apache.xml.resolver.tools.CatalogResolver catalogResolver)
          A constructor for a skeleton TopicMapProvider providing XML catalog resolution services via a CatalogResolver.
 
Method Summary
 TopicMap addTopicMap(java.io.InputStream srcStream, Locator baseLocator)
          A convenience method returning the added TopicMap.
 TopicMap addTopicMap(java.io.InputStream srcStream, Locator baseLocator, TopicMap existingTopicMap)
          Deprecated. from 0.9.0 use TopicMapSourceSupport.addTopicMap(TopicMapSource)
 TopicMap addTopicMap(java.io.InputStream srcStream, Locator baseLocator, TopicMap existingTopicMap, Topic[] addedThemes)
          Deprecated. from 0.9.0 use TopicMapSourceSupport.addTopicMap(TopicMapSource, TopicMap, Topic[])
 TopicMap addTopicMap(java.io.InputStream srcStream, Locator baseLocator, TopicMap existingTopicMap, Topic[] addedThemes, TopicMapBuilder builder)
          Imports a topic map in XTM or LTM syntax into the data store managed by this TopicMapProvider.
 TopicMap addTopicMap(java.io.InputStream srcStream, Locator baseLocator, TopicMap existingTopicMap, TopicMapBuilder builder)
          Deprecated. from 0.9.0 use TopicMapSourceSupport.addTopicMap(TopicMapSource, TopicMap)
 void applyChangeListeners(TopicMap tm)
          Applies a new instance of the default vetoable change listeners specified in the initialisation properties to tm.
protected  void applyDefaultVetoListeners(TopicMap tm)
           
 void attachCatalogResolver(java.lang.Object o)
          A convenience method for attaching a CatalogResolver to an XML Parser.
 org.apache.xml.resolver.tools.CatalogResolver getCatalogResolver()
          Return the CatalogResolver used with this TopicMapProvider.
 java.util.Properties getDefaultTopicMapProperties()
           
 TopicMapBuilder getTopicMapBuilder(java.lang.String notation)
          Returns a TopicMapBuilder for building topic maps for the specified notation.
 void init(java.util.Properties props)
          Sets the runtime properties defined for this TopicMapProvider.
protected  void initialiseBuilder(TopicMap existingTopicMap, Locator srcLocator)
          Sets up the XTMParser and XTMBuilder objects to be used in constructing a new TopicMap or in merging the contents of an XTM file into an existing TopicMap.
protected  boolean isProvidedTopicMap(TopicMap tm)
          Returns true if tm is provided by this TopicMapProvider
 void mergeTopicMap(TopicMap baseTopicMap, Locator externalTopicMap, Topic[] addedThemes)
          Merges the topic map from the resource externalTopicMap into the topic map baseTopicMap.
protected  TopicMap postProcess(TopicMap tm)
           
protected  TopicMap readTopicMap(java.io.InputStream tmStream)
          Reads a topic map from the given input stream.
protected  TopicMap readTopicMap(java.io.InputStream srcStream, java.lang.String systemId)
          Reads a topic map from the given input stream using the specified system ID.
protected  TopicMap readTopicMap(java.lang.String publicId, java.lang.String systemId)
          Reads a topic map provided with both a public and system identifier.
 org.xml.sax.InputSource resolveEntity(java.lang.String publicId, java.lang.String systemId)
          A utility method providing access to the CatalogResolver's resolution features.
 void setCatalogResolver(org.apache.xml.resolver.tools.CatalogResolver catalogResolver)
          Set the CatalogResolver used with this TopicMapProvider.
protected static void setCatalogResolverDefaults()
          A static method that sets each null (previously unset) CatalogResolver property to a default value.
 boolean supportsTopicMapNotation(java.lang.String notation)
          Returns true if notation names a topic map notation that can be parsed by this provider.
 
Methods inherited from class org.tm4j.topicmap.source.TopicMapSourceSupport
addTopicMap, addTopicMap, addTopicMap, addTopicMap, getSourceBaseLocator
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.tm4j.topicmap.TopicMapProvider
addTopicMap, addTopicMap, addTopicMap, addTopicMap, close, createTopicMap, getLocatorFactory, getOpenTransaction, getTopicMap, getTopicMapBaseLocators, isTransactional, isTransactionOpen, openTransaction, removeTopicMap
 

Field Detail

defaultCatalogPath

public static java.lang.String defaultCatalogPath
The default relative pathname for the XML Catalog file ("resource/tm4j.xcat").


m_catalogResolver

protected org.apache.xml.resolver.tools.CatalogResolver m_catalogResolver
Reusable XML catalog resolution service.


m_parser

public javax.xml.parsers.SAXParser m_parser
Constructor Detail

TopicMapProviderBase

public TopicMapProviderBase()
                     throws TopicMapProviderException
A constructor for a skeleton TopicMapProvider.


TopicMapProviderBase

public TopicMapProviderBase(org.apache.xml.resolver.tools.CatalogResolver catalogResolver)
                     throws TopicMapProviderException
A constructor for a skeleton TopicMapProvider providing XML catalog resolution services via a CatalogResolver.

Method Detail

init

public void init(java.util.Properties props)
          throws TopicMapProviderException
Description copied from interface: TopicMapProvider
Sets the runtime properties defined for this TopicMapProvider. This method will be invoked by the TopicMapProviderFactory when the TopicMapProvider is first created.

Specified by:
init in interface TopicMapProvider
Parameters:
props - The parsed set of properties which may be applied to this object.
Throws:
TopicMapProviderException - If the initialisation fails for some reason.

applyChangeListeners

public void applyChangeListeners(TopicMap tm)
                          throws TopicMapProviderException
Applies a new instance of the default vetoable change listeners specified in the initialisation properties to tm.

Parameters:
tm - The topic map to apply the listeners to
Throws:
TopicMapProviderException - If one of the configured listeners cannot be instantiated and added to the topic map.

applyDefaultVetoListeners

protected void applyDefaultVetoListeners(TopicMap tm)

isProvidedTopicMap

protected boolean isProvidedTopicMap(TopicMap tm)
Returns true if tm is provided by this TopicMapProvider


initialiseBuilder

protected void initialiseBuilder(TopicMap existingTopicMap,
                                 Locator srcLocator)
                          throws TopicMapProviderException
Sets up the XTMParser and XTMBuilder objects to be used in constructing a new TopicMap or in merging the contents of an XTM file into an existing TopicMap.

Parameters:
existingTopicMap - If this parameter is not null, then the XTMBuilder will be set up to merge the results of the parse into existingTopicMap.

existingTopicMap must be a TopicMap managed by this Provider. If not, then a TopicMapProviderException will be thrown.

srcLocator - If this parameter is not null and existingTopicMap is not null, then this URL will be used as the base URL for resolving all ID attribute values to resourceID property values for the TopicMapObjects generated by the parse.
Throws:
TopicMapProviderException

addTopicMap

public TopicMap addTopicMap(java.io.InputStream srcStream,
                            Locator baseLocator)
                     throws TopicMapProviderException
A convenience method returning the added TopicMap. See addTopicMap(InputStream,Locator,TopicMap,Topic[],TopicMapBuilder).

Throws:
TopicMapProviderException

addTopicMap

public TopicMap addTopicMap(java.io.InputStream srcStream,
                            Locator baseLocator,
                            TopicMap existingTopicMap)
                     throws TopicMapProviderException
Deprecated. from 0.9.0 use TopicMapSourceSupport.addTopicMap(TopicMapSource)

A convenience method returning the added TopicMap. See addTopicMap(InputStream,Locator,TopicMap,Topic[],TopicMapBuilder).

Specified by:
addTopicMap in interface TopicMapProvider
Parameters:
srcStream - The InputStream of the XTM data to be read.
baseLocator - The base address to assign to the generated topic map only if the parsed topic map does not have an xml:base attribute on its root element.
existingTopicMap - If this parameter is not null, then the TopicMap object passed in must be a TopicMap which is provided by this TopicMapProvider. The topic map parsed from src will be merged with existingTopicMap and no new TopicMap object will be created.
Returns:
The new TopicMap object managed by the TopicMapProvider. If existingTopicMap is not null, then the return value from the function will be the same object as is passed in existingTopicMap. If existingTopicMap is null, then a new TopicMap object will be returned.
Throws:
TopicMapProviderException

addTopicMap

public TopicMap addTopicMap(java.io.InputStream srcStream,
                            Locator baseLocator,
                            TopicMap existingTopicMap,
                            TopicMapBuilder builder)
                     throws TopicMapProviderException
Deprecated. from 0.9.0 use TopicMapSourceSupport.addTopicMap(TopicMapSource, TopicMap)

A convenience method returning the added TopicMap. See addTopicMap(InputStream,Locator,TopicMap,Topic[],TopicMapBuilder).

Specified by:
addTopicMap in interface TopicMapProvider
Parameters:
srcStream - The InputStream of the topic map data to be read.
baseLocator - The base address to assign to the generated topic map only if the parsed topic map does not specify its own base address internally.
existingTopicMap - If this parameter is not null, then the TopicMap object passed in must be a TopicMap which is provided by this TopicMapProvider. The topic map parsed from src will be merged with existingTopicMap and no new TopicMap object will be created.
builder - The builder to use in parsing the input stream.
Returns:
The new TopicMap object managed by the TopicMapProvider. If existingTopicMap is not null, then the return value from the function will be the same object as is passed in existingTopicMap. If existingTopicMap is null, then a new TopicMap object will be returned.
Throws:
TopicMapProviderException - if the parse of the input stream fails for some reason.

addTopicMap

public TopicMap addTopicMap(java.io.InputStream srcStream,
                            Locator baseLocator,
                            TopicMap existingTopicMap,
                            Topic[] addedThemes)
                     throws TopicMapProviderException
Deprecated. from 0.9.0 use TopicMapSourceSupport.addTopicMap(TopicMapSource, TopicMap, Topic[])

A convenience method returning the added TopicMap. See addTopicMap(InputStream,Locator,TopicMap,Topic[],TopicMapBuilder).

Specified by:
addTopicMap in interface TopicMapProvider
Parameters:
srcStream - The InputStream of the topic map data to be read.
baseLocator - The base address to assign to the generated topic map only if the parsed topic map does not specify its own base address internally.
existingTopicMap - If this parameter is not null, then the TopicMap object passed in must be a TopicMap which is provided by this TopicMapProvider. The topic map parsed from src will be merged with existingTopicMap and no new TopicMap object will be created.
addedThemes - themes to be added to the scope of each ScopedObject created by the import process.
Returns:
The new TopicMap object managed by the TopicMapProvider. If existingTopicMap is not null, then the return value from the function will be the same object as is passed in existingTopicMap. If existingTopicMap is null, then a new TopicMap object will be returned.
Throws:
TopicMapProviderException - if the parse of the input stream fails for some reason.

addTopicMap

public TopicMap addTopicMap(java.io.InputStream srcStream,
                            Locator baseLocator,
                            TopicMap existingTopicMap,
                            Topic[] addedThemes,
                            TopicMapBuilder builder)
                     throws TopicMapProviderException
Imports a topic map in XTM or LTM syntax into the data store managed by this TopicMapProvider.

Parameters:
srcStream - The InputStream of the data to be read.
baseLocator - The base URL to assign to the generated topic map only if the parsed topic map does not have an xml:base attribute on its root element.
existingTopicMap - If this parameter is not null, then the TopicMap object passed in must be a TopicMap which is provided by this TopicMapProvider. The topic map parsed from srcStream will be merged with existingTopicMap and no new TopicMap object will be created.
addedThemes - Optional themes to be added to the resulting TopicMap.
builder - Optional TopicMapBuilder; if not provided, then the type of builder used will depend on the file extension of the baseLocator address. If the file extension is ".ltm" or ".txt", an LTMBuilder will be used, otherwise an XTMBuilder will be used.
Returns:
The new TopicMap object managed by the TopicMapProvider. If existingTopicMap is not null, then the return value from the function will be the same object as is passed in existingTopicMap. If existingTopicMap is null, then a new TopicMap object will be returned.
Throws:
TopicMapProviderException

mergeTopicMap

public void mergeTopicMap(TopicMap baseTopicMap,
                          Locator externalTopicMap,
                          Topic[] addedThemes)
                   throws TopicMapProviderException
Description copied from interface: TopicMapProvider
Merges the topic map from the resource externalTopicMap into the topic map baseTopicMap. externalTopicMap will also be removed from this list of external references and mergeMaps for baseTopicMap if it is in one of these lists.

Specified by:
mergeTopicMap in interface TopicMapProvider
Throws:
TopicMapProviderException - if baseTopicMap is not provided by this provider; or if the parse and merge operation fails for some reason.

readTopicMap

protected TopicMap readTopicMap(java.io.InputStream tmStream)
                         throws TopicMapProviderException
Reads a topic map from the given input stream. Note that when using this method, one of the following conditions must be true or an exception will be thrown:
  1. tmStream represents an XML document that does not contain a !DOCTYPE declaration, i.e. can't be validated (not recommended); or
  2. tmStream represents an XML document whose !DOCTYPE declaration, contains an absolute system ID.

Parameters:
tmStream - The input stream to load the topic map from. This input stream must represent a well-formed XML document or the underlying SAX parser will fail.
Throws:
TopicMapProviderException

readTopicMap

protected TopicMap readTopicMap(java.io.InputStream srcStream,
                                java.lang.String systemId)
                         throws TopicMapProviderException
Reads a topic map from the given input stream using the specified system ID.

Parameters:
srcStream - The input stream to load the topic map from. This input stream must represent a well-formed XML document or the underlying SAX parser will fail.
systemId - The System ID which identifies the topic map. Note that the following considerations apply when this is null:
  • If srcStream represents an XML document that does not contain a !DOCTYPE declaration, setting systemId to null will not create any additional problems. Remember, however, that there is no way for the parser to validate the document if it can't find that declaration, so you should generally ensure that it's there if you want acceptable results.
  • If srcStream represents an XML document that does contain a !DOCTYPE declaration, you should make sure that its SYSTEM identifier points to an absolute URI if you really want to invoke this method with systemId set to null. Otherwise, the parser will attempt to validate the document, but will fail to find the DTD as it is unable to correctly resolve the !DOCTYPE declaration.

readTopicMap

protected TopicMap readTopicMap(java.lang.String publicId,
                                java.lang.String systemId)
                         throws TopicMapProviderException
Reads a topic map provided with both a public and system identifier. Resolution relies on the availability of the catalog resolver.

If both the public and system identifers are provided, which has priority depends on the settings of the XML catalog file. If the public identifier is null or no mapping is found, the system will use the system identifier as if no public identifier had been provided.

Parameters:
publicId - The Public ID which identifies the topic map. This may be null.
systemId - The System ID which identifies the topic map. This is required.
Returns:
A TopicMap created by parsing the external document.
Throws:
TopicMapProviderException - If the topic map could not be created.
See Also:
setCatalogResolverDefaults()

resolveEntity

public org.xml.sax.InputSource resolveEntity(java.lang.String publicId,
                                             java.lang.String systemId)
A utility method providing access to the CatalogResolver's resolution features. This returns an InputSource created by resolving the public and system identifiers using the catalog. The public identifier is optional, the system identifier required.

Returns:
The InputSource, null if it cannot be opened.

setCatalogResolver

public void setCatalogResolver(org.apache.xml.resolver.tools.CatalogResolver catalogResolver)
Set the CatalogResolver used with this TopicMapProvider. This also sets the CatalogResolver on the existing SAXParser and on the embedded URILocatorResolver. Setting this to null will disable catalog resolution services.

Parameters:
catalogResolver - the CatalogResolver to be used.

getCatalogResolver

public org.apache.xml.resolver.tools.CatalogResolver getCatalogResolver()
Return the CatalogResolver used with this TopicMapProvider.

Returns:
The current CatalogResolver.

attachCatalogResolver

public void attachCatalogResolver(java.lang.Object o)
A convenience method for attaching a CatalogResolver to an XML Parser. The Object o argument may be an instance of: Note that if the CatalogResolver is null, this method does nothing.

Parameters:
o - The XML processor to which to attach the CatalogResolver.
Throws:
java.lang.IllegalArgumentException - If the Object's class is not recognized.

setCatalogResolverDefaults

protected static void setCatalogResolverDefaults()
A static method that sets each null (previously unset) CatalogResolver property to a default value. This method is called prior to creating the CatalogResolver. CatalogResolver properties are set as System properties, e.g.:
    System.setProperty("xml.catalog.prefer","public"); 

The following table summarizes the properties of org.apache.xml.resolver.tools.CatalogResolver:

System Property Description
xml.catalog.ignoreMissing If true, a missing CatalogManager.properties file or missing properties within that file will not generate warning messages. See also the ignoreMissingProperties method. Default is "true".
xml.catalog.files The semicolon-delimited list of catalog files. The default value for TM4J is a path relative to the TM4J base directory, equal to the String defaultCatalogPath ("resource/tm4j.xcat").
xml.catalog.verbosity If non-zero, the Catalog classes will print informative and debugging messages. The higher the number, the more messages. Default is "0" (quiet).
xml.catalog.prefer Which identifier is preferred, "public" or "system"? Default is "public".
xml.catalog.staticCatalog Should a single catalog be constructed for all parsing, or should a different catalog be created for each parser? Default is "yes" (single catalog).
xml.catalog.allowPI If the source document contains "oasis-xml-catalog" processing instructions, should they be used? Default is "yes".
xml.catalog.className If you're using the convenience classes (org.apache.xml.resolver.tools.*), this setting allows you to specify an alternate class name to use for the underlying catalog. Default is "org.apache.xml.resolver.Resolver".


getDefaultTopicMapProperties

public java.util.Properties getDefaultTopicMapProperties()

getTopicMapBuilder

public TopicMapBuilder getTopicMapBuilder(java.lang.String notation)
Description copied from interface: TopicMapProvider
Returns a TopicMapBuilder for building topic maps for the specified notation.

Specified by:
getTopicMapBuilder in interface TopicMapProvider
Parameters:
notation - the name of the notation that the returned TopicMapBuilder must support. Values of 'xtm' and 'ltm' are supported by this distribution of TM4J.
Returns:
a TopicMapBuilder implementation capable of parsing files of the specified notation or null if no such TopicMapBuilder can be found for this TopicMapProvider

supportsTopicMapNotation

public boolean supportsTopicMapNotation(java.lang.String notation)
Description copied from interface: TopicMapProvider
Returns true if notation names a topic map notation that can be parsed by this provider.

Specified by:
supportsTopicMapNotation in interface TopicMapProvider
Parameters:
notation -
Returns:
true if notation names a topic map notation that can be parsed by this provider, false otherwise.

postProcess

protected TopicMap postProcess(TopicMap tm)
                        throws TopicMapProviderException
Overrides:
postProcess in class TopicMapSourceSupport
Throws:
TopicMapProviderException