ImportXTM()

ImportXTM()
	Chapter 7. Importing and Exporting XTM Files

This method allows topic map data to be imported from any stream into either an existing topic map or a new topic map within the TMCore system. The signature of the method is :

NetworkedPlanet.TMAPI.ITopicMap ImportXTM(System.IO.Stream inputStream,
                                          System.Uri sourceLocator,
                                          string name);

The XTM data is read from the stream inputStream. This stream may be from a local file, from an HTTP or FTP connection or from any other data source that supports the System.IO.Stream interface.

The second parameter, sourceLocator, specifies the URI address that is used for the resolution of any relative links found in the XTM data. This parameter has a number of effects on the addresses imported into the TMCore system:

The sourceLocator parameter value plus the value of the id attribute of the topicMap element (if any) will be added to the SourceLocators property of the ITopicMap instance into which the data is read. If the topicMap element has an id attribute value, then the source locator added will have a trailing # with the id attribute value, otherwise only the complete document path part of the URI will be used.
e.g. If the sourceLocator parameter is "http://www.example.com/topicmaps/mymap.xtm" and the id attribute of the topicMap element is "tm", then the value of the locator added to the SourceLocators property will be "http://www.example.com/topicmaps/mymap.xtm#tm".
Note
If the sourceLocator parameter has fragment and/or query parts such as "http://www.example.com/topicmaps/maps.asp?param=mymap", then these will be removed from the locator before adding the fragment id (if any) for the topicMap element.
Any relative references in resourceRef elements will be resolved against the sourceLocator parameter value. This can be useful when you want to import from a local XTM file but have references to content resolve to a remote web server - as long as your XTM file has relative references, you can set the sourceLocator parameter so that the resulting references imported into TMCore resolve to the remote server.
For example if the topic map contains an <occurrence> with a <resourceRef> which references the relative URI "../docs/mydoc.html" and that topic map is imported with the sourceLocator "http://www.example.com/topicmaps/mymap.xtm", then the reference stored in TMCore will be the fully resolved reference "http://www.example.com/docs/mydoc.html", even if the source stream is read from a local file.
Any relative references to topics by a topicRef element and any references to other topic maps to be merged by a mergeMap element will be resolved against the sourceLocator parameter. The import process will always attempt to merge all maps referenced from a mergeMap element and any external topic maps that contain topics referenced by a topicRef element unless the address of the referenced topic map is already contained in the source locators for the current topic map (i.e. if that topic map was already imported and merged with the current topic map, it will not be imported again).

The final parameter, name, specifies the name of the topic map into which the data will be imported. If this parameter is null, then the name will default to the string value of the sourceLocator parameter. If the name, after the default value has been applied if necessary, matches the name of a topic map that already exists in the TMCore system, then the data will be merged into the topic map with that name. If the name does not match any topic map already in the system, then a new topic map will be created. In either case, the method will return an ITopicMap instance that references the topic map that was modified or created as a result of the import.

Example 7.1. Examples of Importing Into TMCore

// Import from a local file into a new topic map named after the file:
File f = new File("C:\topicmaps\import.xtm");
Uri srcLoc = new Uri(f.FullName);
IXTMProcessor xtmp = m_topicMapSystem.GetXTMProcessor()
Stream input = f.OpenRead();
ITopicMap tm = xtmp.ImportXTM(input, srcLoc, srcLoc.ToString());
input.Close();

The code above reads XTM data from a local file into a topic map with a name based on the file name. In line [2] a new File object is created using the path to the file to be imported. In line [3], that full name is converted into URI syntax (e.g. file:///c/topicmaps/import.xtm). In line [5] a new IXTMProcessor is retrieved from the TopicMapSystem. The import is performed in line [6], using the stream opened in line [5], the Uri representation of the full file path for resolution of any relative paths; and the same Uri (cast to a string) as the name of the topic map to be populated. The return from this call will be an ITopicMap instance representing the topic map that received the XTM data. Finally, the input stream must be closed by the local code as the ImportXTM method will not modify the open state of a stream.

// Import from a local file but resolve to remote references:
File f = new File("C:\topicmaps\import.xtm");
Uri srcLoc = new Uri("http://www.example.com/topicmaps/example1.xtm");
IXTMProcessor xtmp = m_topicMapSystem.GetXTMProcessor()
Stream input = f.OpenRead();
ITopicMap tm = xtmp.ImportXTM(input, srcLoc, srcLoc.ToString());
input.Close();

The code above also reads XTM data from a local file. However in this case, any relative URIs contained in the source XTM data will be resolved against the URI "http://www.example.com/topicmaps/example1.xtm".

ImportXTM()

Note