APIExample3 : Reading And Writing XTM with IXTMProcessor

Running The Example

APIExample3 extends the file system topic map example from the previous section to show how XTM files can be imported into and exported from TMCore. The APIExample3 application :

  1. Reads the basic ontology from an XTM file.

  2. Writes the file system topic map to an XTM file.

Example 3.12. Reading An XTM File

/// <summary>
/// Reads the topics for the basic types used by this topic map.
/// </summary>
private void ReadOntology(string ontologyName, string tmName) 
{
  IXTMProcessor ixtmp = m_tmSystem.GetXTMProcessor();
  ixtmp.ImportXTM(File.OpenRead(ontologyName), 
    new Uri("http://www.networkedplanet.com/examples/directory.xtm"),
    tmName);
  string idBase = "http://www.networkedplanet.com/psi/examples/";
  m_tFile = GetTopic(idBase + "#File");
  m_tDirectory = GetTopic(idBase + "#Directory");
  m_tParentChild = GetTopic(idBase + "#ParentChild");
  m_tParent = GetTopic(idBase + "#Parent");
  m_tChild = GetTopic(idBase + "#Child");
}

The code example above shows how to import an XTM file into the TMCore system. The import is done using an IXTMProcessor instance. The IXTMProcessor interface defines methods for the import and export of XTM syntax topic maps from TMCore. An IXTMProcessor instance is retrieved using the method ITopicMapSystem.GetXTMProcessor(). The import is performed using the ImportXTM method which has the following method signature:

ITopicMap ImportXTM(System.IO.Stream input,
                    System.Uri srcLoc,
                    string name);

The parameter input specifies the stream from which the XTM data is to be read. The stream may be from an open file, from an HTTP connection or from any other data source that can provide a stream. The srcLoc parameter specifies the source URI for the data stream. The source URI is used for the resolution of any relative paths found in the XTM data. For example, in the code snippet above the srcLoc parameter is specified as "http://www.networkedplanet.com/examples/directory.xtm". If that XTM file contained a reference "../index.html", then the reference would be expanded to "http://www.networkedplanet.com/examples/index.html. The source URI is also recorded in the SourceLocators property of the ITopicMap instance that receives the XTM data. The name parameter specifies the name of the topic map into which the data is to be imported. If a topic map with the specified name does not already exist, it will be created. If a topic map with the specified name does exist, then the topic map data will be merged into the existing topic map.

Example 3.13. Writing An XTM File

private void WriteTopicMap(FileStream outputStream) 
{
  IXTMProcessor xtmp = m_tmSystem.GetXTMProcessor();
  xtmp.ExportXTM(new StreamWriter(outputStream), m_tm);
}

The code example above shows that exporting a topic map as XTM data is even more straightforward. The method IXTMProcessor.ExportXTM() has the following signature:

void ExportXTM(System.IO.StreamWriter ouput,
               ITopicMap tm);

The parameter output provides a StreamWriter instance that will output to the stream on which the XTM data is to be written. This stream may connect to a file or to any other sink which accepts streamed data. The parameter tm specifies the ITopicMap instance to be exported.