TMCore Engine API Guide

Portions of this document are based on the TMAPI Developer's Guide and Quickstart document produced by the TMAPI project team.

This document uses a number of typographical convetions to highlight particular types of words or sections of text.

In addition the following conventions are used to highlight sections of the text:

      [1] // This is a program listing
      [2] // It contains a code snippet which is relevant to the text
      [3] // Lines may be numbered for references from the text

The following list shows the major changes to the API since TMCore05 SP1. Changes are listed as CRITICAL, NEW or UPDATED. A CRITICAL change is one which requires attention to any applications written with an older version of TMCore - this category includes all changes that might break an existing application when moving to the new version of the library. A NEW change is one which introduces new functionality to TMCore. An UPDATED change is one which modifies existing functionality without causing backwards compatibility issues.

The full source code for these examples can be found in the examples/ directory of the TMCore distribution. The directory contains both C# and VB.NET versions of the examples in the subdirectories CS and VB respectively. Each example is provided in a separate directory with its own project file. To compile and run an example, open Visual Studio.NET and create a new blank solution; then add the .csproj or .vbproj for the example to the solution. The project can then be built using the Build > Build Solution menu item. If the solution contains multiple projects, set the new example project to be the start-up project by right clicking the project in the Solution Explorer pane and selecting "Set as StartUp Project" from the pop-up menu.

Some of the examples allow command line parameters to be specified. From within Visual Studio, you can assign the command line parameters to be used when running an example by bringing up the Properties pane for the project (right click on the project in the Solution Explorer and select "Properties"). In the Properties Pane select the item "Debugging" under "Configuration Properties" and in the field labelled "Command line arguments", enter the parameters. However, all of the example programs are written so that they can be run from within Visual Studio without specifying any command line parameters.

Finally, to run the project, press F5 or choose the Debug > Start menu item.

This section contains a little example of how to create a topic map including two topics and an association. This example also prints the content of the topic map. This example can be found in the directory examples/CS/APIExample1 or examples/VB/APIExample1.

      [1] // Initialise the TMCore connection using applicaton configuration settings
      [2] ITopicMapSystem tmSystem = TopicMapSystemFactory.GetTopicMapSystem();
      [4] // Create a new topic map to work in
      [5] ITopicMap tm = tmSystem.CreateTopicMap("http://www.example.com/topicmaps/MyFirstTopicMap");

In line 2 the static method TopicMapSystemFactory.GetTopicMapSystem() is invoked to create and return a new ITopicMapSystem instance. The no-arguments version of GetTopicMapSystem() uses the application's configuration file (APIExample1.exe.config) to provide the necessary configuration information. If you are running this application in the Visual Studio.NET IDE, the file used is the file App.config. An example App.config is shown below. For a more in-depth look on whats happening here, please refer to the section called “ITopicMapSystem and TopicMapSystemFactory”. In line 4 a topic map with the name "http://www.example.com/topicmaps/MyFirstTopicMap" is created.

      [1] <configuration>
      [2]   <appSettings>
      [3]     <add key="networkedplanet.tmcore.dbconnect"
      [4]          value="Data Source=localhost;Integrated Security=SSPI; Initial Catalog=topicmap" />
      [5]   </appSettings>
      [6] </configuration>

A topic map's name is a unique identifier for the topic map within the TMCore system. Because of this, if you ran an application with the above example code in it twice, you would get a TopicMapExistsException thrown on the second occasion, informing you that a topic map with the specified name already exists. Instead, you should write code that checks that you are not about to create a topic map with a name that is already in use and take the appropriate action if there is. So rather than use the simple code shown in Example 3.1, “Creating a Topic Map”, something like the following code should be invoked:

      [1] private static ITopicMap SafeCreateTM(ITopicMapSystem tms, string name) 
      [2] {
      [3]   ITopicMap tm = tms.GetTopicMap(name);
      [4]   if (tm != null) 
      [5]   {
      [6]     tm.Remove();
      [7]   }
      [8]   return tms.CreateTopicMap(name);
      [9] }

On line 3, an attempt is made to retrieve a topic map with the base locator of the topic map we want to create. If a topic map is found, we cannot create the new topic map directly. In this example, the solution is simply to remove the topic map from the system. This is done using the call to ITopicMap.Remove() on line 6. The Remove() method removes the topic map and all topics and associations that it contains from the system. Alternatively you may choose to retry using some algorithm for generating a new name string that does not already exist or perhaps even prompt the application user for a new topic map name. Finally on line 8 the topic map is created. In this case, because any pre-existing topic map with the same name has been removed, the call to the CreateTopicMap() method will succeed.

      [1] // Create topics
      [2] ITopic t1 = tm.CreateTopic();
      [3] t1.CreateTopicName("hello");
      [4] t1.Save();
      [6] ITopic t2 = tm.CreateTopic();
      [7] t2.CreateTopicName("world");
      [8] t2.Save();

Creating a new topic in a topic map is as easy as calling the CreateTopic() method on the ITopicMap instance. The result of this method is a new ITopic instance. The ITopic interface provides methods for creating new topic names and occurrences. This is the pattern used throughout the TMCore API - to create a new object, you call the appropriate Create...() method on the parent object. Some Create...() methods are overloaded with different parameter lists to allow you to specify the content of the new object, so in this example the call to CreateTopicName() on lines 3 and 7 take a single string parameter which is the string value of the newly created ITopicName instance.

When an object is modified, the changes are not committed to the topic map until the Save() method is called. The Save() method is provided on the ITopic and the IAssociation interfaces only. To save a change to a topic name or occurrence you must call the Save() method on the containing ITopic. To save a change to an IAssociationRole instance you must call the Save() method on the containing IAssociation instance. Calling the Save() method saves all of the changes made to the ITopic or IAssociation instance and the saving takes place in a single database transaction - either all updates are saved or, in the case of an error, none of the changes are saved.

In addition to Save() methods on ITopic and IAssociation, the ITopicMap interface also provides a Save() method. Invoking this ITopicMap.Save() on a topic map will result in all changes to contained ITopic and IAssociation instances being committed in a single transaction.

      [1] // Create an association between the topics
      [2] IAssociation a = tm.CreateAssociation();
      [3] a.CreateAssociationRole(t1, null);
      [4] a.CreateAssociationRole(t2, null);
      [5] a.Save();

Creating an association follows the same pattern as creating a topic. The IAssociation instance is created using the CreateAssociation() method of the ITopicMap interface (line [2]). IAssociationRole instances specify the topics that participate in the association and are created using the CreateAssociationRole() method of the IAssociation interface. This method takes two parameters, the first is the ITopic that is participating in the association and the second is an ITopic instance that specifies the type of role played by the first topic in the association. Either of these parameters may be null. As with the ITopic interface, changes made are not committed to the database until the ITopic.Save() method is called.

// Print out the names of each topic in the topic map
foreach(ITopic t in tm.Topics) 
{
  PrintTopicNames(t);
}

// Print out the role players of each association in the topic map
foreach(IAssociation assoc in tm.Associations) 
{
  PrintAssociation(assoc);
}

The ITopicMap interface provides read-only properties Topics and Associations. These return an IList of the topics or associations in the topic map. Although these properties make it extremely easy to iterate over the contents of a topic map in a simple application like this, with large topic maps any simple listing of all topics or all associations will quickly become difficult to display and potentially quite slow as you trawl through the whole database! However, for our simple Hello World application, these properties are extremely convenient.

private static void PrintTopicNames(ITopic t) 
{
  System.Console.Write("Topic: ");
  foreach(ITopicName tn in t.TopicNames) 
  {
    System.Console.Write("{0} ", tn.Value);
  }
  System.Console.WriteLine();
}

Accessing data is as simple as using the properties defined by each interface. In the example code above, the names of a topic are returned by the ITopic.TopicNames property which is a read-only IList of ITopicName instances. The string value of a topic name is accessed using the ITopicName.Value property which is a read-write property.

The rule-of-thumb for whether a property will be read-only or read-write is that if the property gives access to the parent or children of an object, it will be read-only (you must use the Create...() and Remove() methods to manage parent-child relationships). For other properties, access is read-write. So if we wanted to update a topic name's string value it would be as simple as :

tn.Value = "My New Name";

APIExample2 is a simple application which shows the basics of using the programmatic indexes provided by TMCore. The program creates a topic map from a directory (specified on the command line) and all its subdirectories. For each directory and file in the hierarchy a topic is created and assigned either the type "File" or "Directory" (these are defined by separate topics created when the program first initialises). For each file and for each subdirectory of the starting directory an association is created to the containing directory. That association is typed as "Parent-Child" with the containing directory playing a role of type "Parent" and the contained file or directory topic playing the role "Child". In addition, every file with a file name extension (eg. MyFile.txt ) is also typed by a topic that describes the extension (e.g. ".TXT"). The first time that a file with a particular extension is encountered, the typing topic is created. For each subsequent file with the same extension, that same topic is used. To assign the right extension type topic to a file topic, the org.tmapi.index.core.TopicsIndex is used to look up the extension type topic.

This example can be found in the file examples/CS/APIExample2 for C# code and examples/VB/APIExample2 for VB code.

public void Run(string startDirectory) 
{
  // Initialise a new ITopicMapSystem and create the topic map
  m_tmSystem = TopicMapSystemFactory.GetTopicMapSystem();
  m_tm = SafeCreateTM(m_tmSystem, "http://www.example.com/topicmaps/MyFileSystem");

  // Add the basic topics required for creating our file-system topic map
  CreateOntology();

  ProcessDirectory(new DirectoryInfo(startDirectory), null);

  ListTopicsAndAssociations();
  ListTopicTypes();
  ListDLLs();
}

When the program is run, the name of the directory to process is retrieved from the command-line (not shown in the code above). This is passed into the main program loop as the parameter startDirectory. In the main program loop, the following is done:

/// <summary>
/// Creates the topics for the basic types used by this topic map.
/// </summary>
private void CreateOntology() 
{
  // Topic to type all topics that represent files
  m_tFile = CreateTopic("File", "http://www.networkedplanet.com/psi/examples/#File")
  // Topic to type all topics that represent directories
  m_tDirectory = CreateTopic("Directory", "http://www.networkedplanet.com/psi/examples/#Directory");

  // Topics for creating the Parent/Child associations
  m_tParent = CreateTopic("Parent", "http://www.networkedplanet.com/psi/examples/#Parent");
  m_tChild = CreateTopic("Child", "http://www.networkedplanet.com/psi/examples/#Child");
  m_tParentChild = CreateTopic("Parent-Child", "http://www.networkedplanet.com/psi/examples/#ParentChild");
}

/// <summary>
/// Utility method to create a topic with a single name and a 
/// single subject identifier.
/// </summary>
/// <param name="name">The name to add to the new topic</param>
/// <param name="subjectIdentifier">The subject identifier URL for the new topic</param>
/// <returns>The newly created topic</returns>
private ITopic CreateTopic(string name, string subjectIdentifier) 
{
  ITopic ret = m_tm.CreateTopic();
  ret.CreateTopicName(name);
  if (subjectIdentifier != null) 
  {
    ret.AddSubjectIdentifier(m_tm.CreateLocator(subjectIdentifier));
  }
  ret.Save();
  return ret;
}

The above code shows one simple pattern for populating a new topic map with the basic typing topics for an application (often called an 'ontology'). The method CreateTopic() is used to create a single topic with a given name and subject identifier. This method is then invoked from the CreateOntology() method for each topic to be created. Of course, if your application will make use of the same topic map each time, you should check that a particular topic does not exist before creating a new one with the same subject identifier - we will see how to use indexes to achieve this in the next section. In this code, the topics are then stored as member variables of the main program class - in more complex applications you may want to create a specific "Ontology" class to manage these topics.

      [1] /// <summary>
      [2] /// Adds a topic representing a file into the topic map.
      [3] /// </summary>
      [4] /// <param name="fileInfo">The file to be processed.</param>
      [5] /// <param name="parentDir">The topic representing the directory that contains this file.</param>
      [6] private void ProcessFile(FileInfo fileInfo, ITopic parentDir) 
      [7] {
      [8]   // Create a topic representing the file
      [9]   ITopic fileTopic = m_tm.CreateTopic();
      [10]   fileTopic.AddType(m_tFile);
      [11]   fileTopic.CreateTopicName(fileInfo.FullName);
      [12]   fileTopic.CreateTopicName(fileInfo.Name, new ITopic[] {parentDir});
      [14]   if (fileInfo.Extension != null) 
      [15]   {
      [16]     // Lookup the topic that represents this file's file extension
      [17]     string fileTypeIdentifier = 
      [18]       "http://www.networkedplanet.com/psi/examples/extensions/#" + 
      [19]       fileInfo.Extension.Substring(1).ToUpper();
      [21]     ITopic extensionType = m_tm.TopicsIndex.GetTopicBySubjectIdentifier(fileTypeIdentifier);
      [22]     if (extensionType == null) 
      [23]     {
      [24]       // Create a topic to represent this files's file extension
      [25]       extensionType = m_tm.CreateTopic();
      [26]       extensionType.CreateTopicName("File Type: " + fileInfo.Extension.ToUpper());
      [27]       extensionType.AddSubjectIdentifier(fileTypeIdentifier);
      [28]       extensionType.Save();
      [29]     }
      [30]     fileTopic.AddType(extensionType);
      [31]   }
      [33]   fileTopic.Save();
      [34]   ...
      [35] }

The code snippet above shows part of the process of creating a topic to represent a file. From line [14] to line [31] is code for assigning a type to the file topic based on the extension of the file name. So for example all files representing .DLL files will be typed by a topic "DLL", all .TXT files by a topic "TXT" and so on. We want to be sure that we only create the "DLL" or "TXT" topic on the first time we encounter a file with that extension and not on subsequent files with the same extension. The best way to identify topics is by assigning a subject identifier to them. A subject identifier is simply a unique URI identifier for the topic. In our example we create a subject identifier with the URI "http://www.networkedplanet.com/psi/examples/extensions/#{extension}". Note that we force the file name extension to upper case to ensure that "X.DLL" and "y.dll" both receive the same typing topic as subject identifiers are case-sensitive. Having created a locator string with the appropriate URL (lines [17]-[19]), we then look up the topic with that subject identifier using the TopicsIndex . Every ITopicMap provides access to a set of indexes of the different objects in the topic map. All of these indexes are accessed through read-only properties of the ITopicMap interface - they are easily identified as each property name ends with "Index". Each of the indexes provide a different set of look-up methods. The index we are using here, the TopicsIndex provides methods to look up a topic by its subject identifier, its subject locator, or its type(s). On line 21, the method ITopicsIndex.GetTopicBySubjectIdentifier() is invoked. Because a topic map can only ever have one topic with a given subject identifier, this method will either return a single ITopic instance or null. If the method returns null, a new topic is created on lines 24-28. Finally the topic (either the one returned by GetTopicBySubjectIdentifier() or the newly created topic) is added to the types for the file topic using the method ITopic.AddType(), and the file topic is saved to commit all the changes.

      [1] /// <summary>
      [2] /// Displays the topics which are used to type other topics in the topic map.
      [3] /// </summary>
      [4] private void ListTopicTypes()
      [5] {
      [6]   System.Console.WriteLine("All Topic Types:");
      [7]   IList topicTypes = m_tm.TopicsIndex.GetTopicTypes();
      [8]   foreach(ITopic t in topicTypes) 
      [9]   {
      [10]     PrintTopicNames(t);
      [11]   }
      [12]   System.Console.WriteLine();
      [13] }

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 :

/// <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");
}

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

APIExample4 shows how to use the TMRQL query language from your own code. TMRQL is simply SQL applied to a defined set of relational views of your topic map data. This makes TMRQL easy to use for anyone already familiar with SQL and also has the advantage of extensive support in tools an in code from the .NET Framework.

The code in APIExample4 performs the following steps:

The code for importing the XTM file is contained in the method ImportXTMFile() - this is similar to the code already seen in APIExample3 for XTM import.

The query for the direct children of William I is done in the method QueryChildren(). In this query, we want to find all topics associated with the topic for William I where the association type is "child-of" and William I plays the role "parent". William I, "child-of" and "parent" are all topics in the topic map an need to be found in the database to perform this query. In this example, this is done as part of th query itself, using the topic subject identifiers and looking up the topic's unique identifiers using SQL sub-selects. The actual query string used is slightly obscured by the use of string constants for the base URIs of the subject identifiers, so is reproduced here in its complete form except for the string {topicmap ID} which is replaced with the ObjectID of the ITopicMap object passed into the QueryChildren() method:

SELECT r2p, dbo.tm_displayName(r2p) FROM tm_assoc2 WHERE
  topicmap = {topicmap ID} AND 
  r1p in (SELECT topic_id from tm_si where subj_id='http://www.example.com/psi/uk-monarchs/william-i') AND 
  association_type in (SELECT topic_id from tm_si where subj_id='http://www.example.com/psi/family/child-of') AND
  r1t in (SELECT topic_id from tm_si where subj_id='http://www.example.com/psi/family/parent')

The principal selection is done using the tm_assoc2 view which presents pairs of topics that are in the same association, giving the association type and the role type played by each topic. Each of the topics William I, "child-of" and "parent" are found using a lookup in the tm_si view which maps a topic's subject identifier to its unique object identifier. In the SELECT part of the query, the tm_displayName function is used to select one name from the topic specified in the function parameter. The query is executed using the ExecuteQuery() method of the ITopicMapSystem interface, not on the ITopicMap interface. Although this query specifically restricts itself to a single topic map, but you can write queries that span multiple topic maps in the same database (although you will then need to be responsible for working out which results came from which topic map!). The exection and procesing of the results set is shown in the code snippet below.

ITMCoreDataReader dr = tm.TopicMapSystem.ExecuteQuery(query);
System.Console.WriteLine("Children of William I:");
try 
{
  while (dr.Read()) 
  {
    int id = dr.GetInt32(0);
    string name = dr.GetString(1);
    System.Console.WriteLine("  {0} - {1}", id, name);
  }
} 
finally 
{
  dr.Close();
}

The ExecuteQuery() method returns an instance of the ITMCoreDataReader interface which extends the standard SQL DataReader implementation with additional methods that can return full TMAPI objects from object identifiers in the results set. As with a normal DataReader, you can call the Read() method to retrieve results row by row until the method returns false (at which point you have reached the end of the results set). You can then use the various GetXXX() methods to retrieve individual items from the row - in this case the unique object identifier is retrieved as a 32-bit integer, and the topic name is retrieved as a string.

The method QueryDescendents() prints a tree-view of all descendants of William I. This list is found by following the "child-of" associations (from "parent" role to "child" role") starting from William I. We call this traversal of a specific type of association in a specific direction (from one role type to another role type) as transitive closure. TMRQL provides two functions for retrieving this transitive closure. The tm_tc function is provided for backwards compatibility, but we recommend you use the tm_tc2 function which returns a table listing each path in the transitive closure as a pair of topics - the "from" topic and the "to" topic. If you think of the transitive closure like a tree, the "from" topic is the parent node and the "to" topic is the child node.

This method also shows a different way of constructing a query that requires topic identifiers. Rather than querying for the identifiers within the query string itself, the topics are first located using the Index APIs to lookup the topics one by one. This can be useful when you write a lot of queries that use the same topics over and over again. The code for the QueryDescendants() method is shown below.

string familyPsiBase = "http://www.example.com/psi/family/";
string monarchyPsiBase = "http://www.example.com/psi/uk-monarchs/";
ITopic childOf = tm.TopicsIndex.GetTopicBySubjectIdentifier(familyPsiBase + "child-of");
ITopic child = tm.TopicsIndex.GetTopicBySubjectIdentifier(familyPsiBase + "child");
ITopic parent = tm.TopicsIndex.GetTopicBySubjectIdentifier(familyPsiBase + "parent");
ITopic william = tm.TopicsIndex.GetTopicBySubjectIdentifier(monarchyPsiBase + "william-i");
string query = String.Format(
  "SELECT from_id, to_id, dbo.tm_displayName(to_id) as child_name from tm_tc2({0},{1},{2},{3})",
  william.ObjectID, childOf.ObjectID, parent.ObjectID, child.ObjectID);
try 
{
  ITMCoreDataReader dr = tm.TopicMapSystem.ExecuteQuery(query);
  System.Data.DataTable tbl = dr.GetDataTable();
  System.Console.WriteLine("William I:");
  ListChildren(tbl, Int32.Parse(william.ObjectID), 2);
} 
catch (Exception ex) 
{
  System.Console.WriteLine("ERROR: Caught error in processing query.");
  System.Console.WriteLine(ex.ToString());
}

The first 6 lines of the code are used to find the topics that are required to execute the tm_tc2 function. This function requires the identifiers of the starting topic for the closure, the type of the association to be traversed, the type of role played by the "from" topic at each link in the path and the type of role played by the "to" topic at each link. Because these topics are located first using the Index API, the query string can be much simpler - requiring only that the ObjectID of each topic be inserted into the correct place in the query. This code example differs from the previous query in another way too. Rather than reading the results set row by row, the code makes use of the GetDataTable() method provided by the ITMCoreDataReader interface. This method reads all the rows from the results set into a local System.Data.DataTable instance and then closes the DataReader. For large results sets, this could potentially require a lot of memory, but it has several advantages. Firstly it means that you do not have to explicitly close the DataReader as this is done by the code that constructs the DataTable. Secondly, the DataTable interface provides a number of methods that allow you to filter and select from the results data without executing further queries against the database. This second feature is used by the method ListChildren() which is a recursive method used to construct the tree view. Each time the ListChildren() method is invoked, it selects from the DataTable all those rows where the "from" topic identifier matches the identifier specified in the input parameter. Then for each row it prints the id and name of the "to" topic (the child) and then calls itself with the child topic identifier as the parameter to print the list of the child's children and so on. This code is shown in the snippet below.

private void ListChildren(System.Data.DataTable descendantsTable, int parentId, int indent)
{
  System.Data.DataRow[] children = descendantsTable.Select("from_id=" + parentId, "child_name");
  foreach(System.Data.DataRow childRow in children)
  {
    int childId = (int)childRow[1];
    string childName = childRow[2] as String;
    System.Console.WriteLine("{0}{1} - {2}", new String(' ', indent), childId, childName);
    ListChildren(descendantsTable, childId, indent + 2);
  }
}

Removing existing topic map...
Importing XTM file kings_and_queens.xtm. Please wait...
XTM import was successful!
Children of William I:
  2612 - Adela
  2566 - Robert Curthose, Duke Of Normandy
  2598 - William II
  2596 - Henry I

William I:
  2612 - Adela
    2606 - Stephen
  2596 - Henry I
    2592 - Matilda, Daugher Of Henry I
      2580 - Henry II
        2582 - John
          2676 -
        2602 - Richard I
    2600 - William, Son of Henry I
  2566 - Robert Curthose, Duke Of Normandy
  2598 - William II

You will have seen from the previous section, that coding TMRQL statements can require quite a lot of work in locating the topics that are input parameters into each query. You either end up writing code to find the topics using the Index API or you need to write long TMRQL queries that use sub-selects to find the topics. Most of the time, these topics are related to the system of topic, association, role and occurrence types in your topic map data and should be assigned URI subject identifiers to enable them to be found in the database. The ApplicationOntology object gives you a convenient API for managing these topics as well as an efficient local cache that can both improve query performance and make TMRQL queries more readable. You can read more about the ApplicationOntology object in the section called “The ApplicationOntology Object”. For the purposes of this section, you can think of the ApplicationOntology as a special form of cache in which short string keys can be used to retrieve full ITopic instances. The keys used can be directly tied to the URIs assigned to the topics in the topic map.

APIExample5 is a rewrite of APIExample4 using the ApplicationOntology object. The main order of processing is now:

The initialisation of the ApplicationOntology object is performed in the method GetApplicationOntology(). The code for this method is shown below.

private ApplicationOntology GetApplicationOntology(ITopicMap tm)
{
  // Retrieve the inner ontology from the app settings file.
  ApplicationOntology innerOnt = System.Configuration.ConfigurationSettings.GetConfig("ontology") as ApplicationOntology;
  innerOnt.AddTopicMap(tm);
  // Create an outer ontology with the inner ontology nested.
  ApplicationOntology outerOnt = new ApplicationOntology(innerOnt);
  outerOnt.AddPrefix("monarchs", "http://www.example.com/psi/uk-monarchs/");
  outerOnt.AddTopicMap(tm);
  return outerOnt;
}

This code shows three important features of the ApplicationOntology object. Firstly an ApplicationOntology object can be constructed from the configuration settings for an application. This allows users to specify their ontology mappings using XML in the application's .config or Web.config file. Secondly, an ApplicationOntology can be intialised purely in code - this allows you to write code that uses specific mappings regardless of configuration file settings. Finally, ApplicationOntology objects can be nested one inside another - if the outer object cannot map an key to an ITopic instance, it passes the request to its nested ApplicationOntology object (which can in turn pass the request to its nested ApplicationOntology object and so on).

This code also shows how much of the cache mapping of the ApplicationOntology object works. You do not need to specify a cache key for every topic (although you can if you want to). Instead you declare a prefix string and the URI prefix that it maps to. You can then look up a topic using the prefix string followed by a colon and the rest of the URI. The ApplicationOntology will then expand the prefix and rest of URI into a full URI and search for a topic with that expanded URI as its subject identiifer. So in the code example above we add a prefix string "monarchs" for the URI prefix "http://www.example.com/psi/uk-monarchs/" - we can then find the topic for William I using the cache key "monarchs:william-i" which gets expanded to "http://www.example.com/psi/uk-monarchs/william-i" and locates the topic with that URI as a subject identifier. Once an ApplicationOntology object performs this expansion and finds a match, it then caches the direct topic reference, meaning that all future requests for the same item can be resolved without a look-up in the database. When you use the same topics time after time, this can provide a significant performance boost.

Looking up a topic using a cache key is simple in code - the ApplicationOntology acts like a normal .NET dictionary, returning ITopic instances from string keys, so you can write look-up code like this:

ITopic william = ontology["monarchs:william-i"];

However, the ApplicationOntology object also provides a method that assists in writing TMRQL statements by pre-processing them to replace cache key strings in curly braces with the object ID of the topic that is indexed against that cache key. This is shown in the QueryChildren() method by the following code:

private void QueryChildren(ITopicMap tm, ApplicationOntology ontology) 
{
  string query = 
    "SELECT r2p, dbo.tm_displayName(r2p) FROM tm_assoc2 WHERE" +
    "  topicmap = " + tm.ObjectID + " AND " +
    "  r1p={william} AND association_type={family:child-of} AND r1t={family:parent}";
  query = ontology.ReplaceReferences(query);
  try 
  {
    ITMCoreDataReader dr = tm.TopicMapSystem.ExecuteQuery(query);
  ...

The cache keys are written in the TMRQL statement surrounded by curly braces ({}). In this example the ApplicationOntology has been configured withs a direct mapping for the cache key "william" to the subject identifier "http://www.example.com/psi/uk-monarchs/william-i" as well as a prefix mapping for the string "family" to the URI prefix "http://www.example.com/psi/family/". The call to the ReplaceReferences() method of the ApplicationOntology object replaces these cache keys with the object identifiers of the topics "William I", "child-of" and "parent" respectively.

As you can see by comparing with the code from APIExample4, the ApplicationOntology object makes queries easier to write and to read and, because you avoid the need to do index lookups multiple times or to make use of SQL sub-selects in your queries, your code will execute faster too.

The interface NetworkedPlanet.TMAPI.ITopicMapSystem represents a connection to a TMCore system. In the TMCore system, the topic maps that it manages are each assigned a unique identifier string specifed by the Name property of the ITopicMap instance. The property ITopicMapSystem.TopicMapNames returns a read-only IList containing the Name property value of all topic maps that are currently accesible through the ITopicMapSystem. The ITopicMapSystem method GetTopicMap(String)is an access method to retrieve an ITopicMap from the ITopicMapSystem using the value of its Name property as a key.

In addition, the ITopicMapSystem interface allows you to create a new topic map in the TMCore system. To create a new topic map, you will need to specify the unqiue name under which the topic map should be stored. If you specify a name which is already in use, a TopicMapExists exception will be thrown.

An ITopicMapSystem instance cannot be created directly, the TMCore API does not publicly expose a class that implements this interface. Instead you must use the class NetworkedPlanet.TMAPI.TopicMapSystemFactory to configure and initialise an ITopicMapSystem instance. The configuration required for an ITopicMapSystem is specified as a collection of name/value pairs as shown in the following table:

The TopicMapSystemFactory class provides an overloaded method GetTopicMapSystem() that accepts this configuration information in a number of different ways. The method GetTopicMapSystem() with no arguments will configure the ITopicMapSystem instance using the local application configuration file. This file is an XML file that is named either Web.config for web applications or AppName.config for applications (e.g. MyApp.exe.config for an application called MyApp.exe). The configuration information must go in the <appSettings> element of the config file. More information about the appSettings and configuration files can be found here on the Microsoft MSDN site. An example of an application configuration file is shown below:

<?xml version="1.0" encocing="utf-8" ?>
<configuration>
  ...
  <appSettings>
    <add key="networkedplanet.tmcore.dbconnect"
         value="Data Source=localhost;Integrated Security=SSPI; Initial Catalog=topicmap" />
    ...
  </appSettings>
  ...
</configuration>

If you wish to retrieve the configuration information in some other way, or wish to include a hard-coded set of configuration parameters in your application, you can instead use the method GetTopicMapSystem(NameValueCollection). The NameValueCollection parameter contains the property/value pairs to configure the ITopicMapSystem that will be returned.

Each of the types of item defined by the topic maps data model is represented in the TMCore API by an interface. The names of the interfaces may be slightly unfamiliar to users of the XTM syntax because they are based on a more abstract model of a topic map called the "Topic Maps Data Model" (TMDM). This model is currently under development as part of the next version of ISO 13250 and so the TMCore interfaces cover both this model and a slightly modified version of it for XTM 1.0 topic maps. For more information about TMDM see the ISO Topic Maps website.

The interface IIndex defines a generic interface for an index over the data in a single TopicMap instance. The IIndex interface provides methods for opening and closing an index; and for determining whether an index is currently open or closed.

The methods IIndex.Open() and Close() are used to modify the open state of the index. The property IsOpen is a boolean value which is true when the index is open. Calling any index retrieval methods on an index which is not open will result in an exception being thrown.

The namespace NetworkedPlanet.TMAPI.Index.Core defines a collection of index interfaces all of which are derived from IIndex. Each of these index interface provides additional methods for accessing indexed information about one of the types of object in a topic map. The following table summarises the core index interfaces and the indexes they provide access to.

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 :

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 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.

// 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();

// 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 IXTMProcessor.ExportXTM() method allows the content of a single topic map in the TMCore system to be written to a stream in XTM syntax. The method has the following signature:

The parameter writer specifies the output stream writer that is to receive the XTM data and the parameter topicMap specifies the ITopicMap instance whose content is to be exported.

The change notification support of TMCore allows any thread to monitor the database for changes made by other threads to a specific topic map. The thread receives notification of the addition, removal or modification of all topics and associations in a topic map. Any changes to an object contained by a topic or association, including creation and removal are reported as a modification of the containing topic or association object.

The interface IChangeNotifier defines an abstract interface for this change notification system. This interface defines two events, AssociationChange and TopicChange. These two events are both of type ObjectChangeNotification which have the following signature:

VB:
Public Delegate Sub ObjectChangeNotification( _
   ByVal objectID As String, _
   ByVal topicmapID As String, _
   ByVal changeType As ChangeType, _
   ByVal changeID As Integer _
)

C#:
public delegate void ObjectChangeNotification(
   string objectID,
   string topicmapID,
   ChangeType changeType,
   int changeID
);

The objectID and topicmapID parameters specify the unique identifier of the object that was modified and of the topic map that contains the modified object. The changeType parameter is an enumerated type with the values CREATE, UPDATE and DELETE to notify creation, modification and removal events respectively. The changeID integer is a unique identifier for this change event. The identifier is a simple incrementing integer and so can be used to track the last event notified across multiple sessions (e.g. to determine if the listener missed an event for some reason).

The IChangeNotifier interface also defines methods for starting and stopping the polling of the database. The method StartPolling(long interval) begins the polling of the database with an interval between polls specified in milliseconds by the parameter interval. When the startPolling() method is invoked, the first poll will be performed immediately, with subsequent polls ocurring each time the polling interval elapses. The method StopPolling() can be used to halt polling immediately. The method SetPollingInterval(long interval) can be used to modify the polling interval while the polling loop is running. The IChangeNotifier implementation is responsible for its own thread management, so the calling application does not need to create a new thread to run the IChangeNotifier instance in.

Every topic map application will be governed by its own unique topic map schema and its own unique system of topic instances. In most applications, the schema will be used to represent all the types of concepts presented by the site and the types of relationships between those concepts and between the concepts and other resources. You may also have a set of predefined topics that are used for classification purposes (often referred to as a taxonomy) - some more complex applications may include several taxonomies.

The class NetworkedPlanet.TMCore.Utils.ApplicationOntology provides a fast and convenient means of accessing the key topics that are part of both the topic map schema and any taxonomies that govern your application. Most importantly, the ApplicationOntology class provides a string replacement method that can be used in conjunction with the TMRQL query language, allowing you to embed human-readable references to topics within TMRQL queries without the need to do an explicit query of the subject identifiers table.

Before you can use the ApplicationOntology object effectively, you must assign a subject identifier to the topics you wish to be accessible. A subject identifier is simply a unique URI identifier for a topic.

<ontology>
  <identifierPrefix prefix="..." value="..."/>
  <subject key="..." identifier="..."/>
</ontology>

<section name="ontology" type="NetworkedPlanet.TMCore.Utils.OntologySectionHandler, tmcore"/>

ApplicationOntology ontology = 
  System.Configuration.ConfigurationSettings.GetConfig(
    "ontology") as ApplicationOntology;

ApplicationOntology applicationOntology;
XmlDocument configDoc = new XmlDocument();
configDoc.Load("myconfig.xml")
XmlElement ontologyElement = configDoc.SelectSingleNode("/config/ontology");
if (ontologyElement != null) {
  applicationOntology = new ApplicationOntology(ontologyElement);
} else {
  applicationOntology = new ApplicationOntology();
}

ApplicationOntology ontology = new ApplicationOntology();
ontology.AddPrefix("org", "http://www.networkedplanet.com/2005/01/organisation/");
ontology.AddIdentifier("title", "http://purl.org/dc/1.1/title");

ITopicMap coreMap = m_topicMapSystem.GetTopicMap("core.xtm");
ontology.AddTopicMap(coreMap)

// Get the inner ontology from the application configuration file
ApplicationOntology innerOntology = 
  System.Configuration.ConfigurationSettings.GetConfig(
    "ontology") as ApplicationOntology;

// Create an outer ontology programatically:
ApplicationOntology outerOntology = new ApplicationOntology(innerOntology);
outerOntology.AddPrefix("org", "http://www.networkedplanet.com/2005/01/organisation/");

// Create a new ontology with one prefix mapping and one short identifier mapping
ApplicationOntology ontology = new ApplicationOntology();
ontology.AddPrefix("org", "http://www.networkedplanet.com/2005/01/organisation/");
ontology.AddIdentifier("title", "http://purl.org/dc/1.1/title");
ontology.AddTopicMap(myTopicMap);

ITopic person = ontology["org:person"];
ITopic title = ontology["title"];

// Assuming ontology is already configured as shown in the previous example

// A query string containing a replacement value
string query = "select topic_id from tm_topic where type_id={org:person}";

// Expand the query using the application ontology
string expandedQuery = ontology.ReplaceReferences(query);

// Finally, execute the expanded query
ITMCoreDataReader dr = myTopicMapSystem.ExecuteQuery(expandedQuery);

The class NetworkedPlanet.TMCore.Utils.HierarchyManager provides a simple means of managing multiple topic hierarchies in a topic map. The HierarchyManager class is capable of scanning a topic map for all topic hierarchies which are defined in a particular way and then extracting and caching the details of the hierarchy in memory for fast access to the hierarchy of topics.

Creating a Hierarchy

In order for the HierarchyManager class to recognise a hierarchy, it is necessary to provide a hierarchy topic which defines the hierarchy itself. This hierarchy topic contains associations to:

• the root topic of the hierarchy

• a set of association type topics that will connect parent and child nodes.

• a set of topics that represent the parent type roles between nodes of the hierarchy.

• a set of topics that represent the child type roles between nodes of the hierarchy.

Two topics are connected to partipicate in a hierarchy in a parent-child relationship iff:

• There is an association between the parent and child where the association type topic of the association is connected to the hierarchy topic.

• There is an association between the parent and child where the parent topic plays one of the roles identified by the hierarchy topic.

• There is an association between the parent and child where the child topic plays one of the roles identified by the hierarchy topic.

The hierarchy topic and the types of associations used to specify the root topic and the hierarchy association types all use a fixed set of PSIs which are defined by Techquila (see http://www.techquila.com/psi/).

In the model specified by Techquila, each hierarchy must be defined by a topic of type "Facet". This topic represents the entire hierarchy as a whole and so should be given a name that reflects the name of the whole hierarchy. This topic is not the root of the hierarchy - it only acts to define how to find the hierarchy and how to traverse it. The root of the hierarchy is identified using an association of the type "Facet-Has-Root". This association must be a binary association between the topic representing the hierarchy (playing the role "Facet") and the topic which is the root of the hierarchy (playing the role "Facet-Root"). The hierarchy must be constructed as a set of topics all connected together using the same type of association. The type of association used to construct the hierarchy is identified using an association of the type "Facet-Has-Hierarchy-Type". This association must also be a binary association between the topic representing the hierarchy (playing the role "Facet") and the topic which types the associations used to construct the hierarchy (playing the role "Facet-Hierarchy-Type"). Finally, the association roles played by the topics in the hierarchy must be divided into superordinate roles (i.e. the role played by the "parent" in the hierarchy) and subordinate roles (the role played by the "child" in the hierarchy). This is done by creating associations of type "Facet-Has-Superordinate-Role-Type" and "Facet-Has-Subordinate-Role-Type" between the facet topic and the topics defining the parent role type and child role type respectively.

All of the types described above have a Published Subject Identifier (PSI) defined for them by Techquila and summarised in the table below. If you follow the PSI URL you will be taken to pages which provide the official Techquila description for each of these topics.

Table 8.1. Topic PSIs for Topic Hierarchies

Topic	PSI
Facet	http://www.techquila.com/psi/faceted-classification/#facet
Facet-Has-Hierarchy-Type	http://www.techquila.com/psi/faceted-classification/#facet-has-hierarchy-type
Facet-Hierarchy-Type	http://www.techquila.com/psi/faceted-classification/#facet-hierarchy-type
Facet-Has-Root	http://www.techquila.com/psi/faceted-classification/#facet-has-root
Facet-Root	http://www.techquila.com/psi/faceted-classification/#facet-root
Facet-Has-Subordinate-Role-Type	http://www.techquila.com/psi/faceted-classification/#facet-has-subordinate-role-type
Subordinate-Role-Type	http://www.techquila.com/psi/hierarchy/#subordinate-role-type
Facet-Has-Superordinate-Role-Type	http://www.techquila.com/psi/faceted-classification/#facet-has-superordinate-role-type
Superordinate-Role-Type	http://www.techquila.com/psi/hierarchy/#superordinate-role-type

The diagram below shows this model in a schematic form.

Figure 8.1. Defining A Hierarchy Model

Although this may seem a little complex from the description above, it is actually very straightforward. The following procedure takes you through the process of defining a new hierarchy in an XTM topic map step by step.

Procedure 8.1. Creating a Topic Hierarchy

1. Create Or Import Techquila PSIs

   This step only has to be performed once for each topic map and can be skipped by using subjectIndicatorRef rather than topicRef elements to refer to the Techquila topics. This can also be done through the TMCore Topic Map Editor web application or by invoking the static CreateHierarchySchemaTopics(ITopicMap) method on the NetworkedPlanet.TMCore.Utils.HierarchyManager class.

2. Create The Hierarchy Facet

   This is the topic which defines the hierarchy as a whole. This topic must be an instance of the Techquila topic "Facet". In XTM this can be achieved as follows:

   <topic id="places">
     <instanceOf>
       <subjectIndicatorRef xlink:href="http://www.techquila.com/psi/faceted-classification/#facet"/>
     </instanceOf>
     <baseName>
       <baseNameString>Places</baseNameString>
     </baseName>
     <!-- Any other topic data -->
   </topic>

   Note

   The baseName elements shown in this and all following examples are illustrative only - they are not required in constructing your hierarchy.

3. Create The Hierarchy Root

   This is the topic that will be at the root of the hierarchy. Hierarchies can only have a single root topic. The root topic can be of any type (or types) you like. For example:

   <topic id="the-world">
     <instanceOf><topicRef xlink:href="planet"/></instanceOf>
     <baseName>
       <baseNameString>The World</baseNameString>
     </baseName>
   </topic>

   To identify this topic as the hierarchy root, you must create a "Facet-Has-Root" association between the facet topic created in step 2 and this root topic:

   <!-- The root of the "Places" hierarchy is "The World" -->
   <association>
     <instanceOf>
       <subjectIndicatorRef 
         xlink:href="http://www.techquila.com/psi/faceted-classification/#facet-has-root"/>
     </instanceOf>
     <member>
       <roleSpec>
         <subjectIndicatorRef
           xlink:href="http://www.techquila.com/psi/faceted-classification/#facet"/>
       </roleSpec>
       <topicRef xlink:href="#places"/>
     </member>
     <member>
       <roleSpec>
         <subjectIndicatorRef
           xlink:href="http://www.techquila.com/psi/faceted-classification/#facet-root"/>
       </roleSpec>
       <topicRef xlink:href="#the-world"/>
     </member>
   </association>
   

4. Specify The Hierarchy Association Type

   All topics in our hierarchy must be associated with one another using a single type of association. The topic for that association type must be identified using a "Facet-Has-Hierarchy-Type" association between the facet topic created in step 2 and the association typing topic. For example:

   <topic id="contains">
     <baseName>
       <baseNameString>Contains</baseNameString>
     </baseName>
   </topic>
   
   <!-- The hierarchy association for "Places" hierarchy is "Contains" -->
   <association>
     <instanceOf>
       <subjectIndicatorRef 
         xlink:href="http://www.techquila.com/psi/faceted-classification/#facet-has-hierarchy-type"/>
     </instanceOf>
     <member>
       <roleSpec>
         <subjectIndicatorRef
           xlink:href="http://www.techquila.com/psi/faceted-classification/#facet"/>
       </roleSpec>
       <topicRef xlink:href="#places"/>
     </member>
     <member>
       <roleSpec>
         <subjectIndicatorRef
           xlink:href="http://www.techquila.com/psi/faceted-classification/#facet-hierarchy-type"/>
       </roleSpec>
       <topicRef xlink:href="#contains"/>
     </member>
   </association>

5. Specify the Subordinate and Superordinate Roles

   The subordinate role is the role played by the child in a hierarchy association; the superordinate role is the role played by the parent. These are identified by creating additional associations between the topic that defines the hierarchy and the topics that define the subordinate and superordinate role types. So for our "Contains" association type, we have the role types "Container" (the superordinate role type) and "Containee" (the subordinate role type):

   <!-- Container role is a superordinate role type -->
   <topic id="container">
     <baseName>
       <baseNameString>Container</baseNameString>
     </baseName>
   </topic>
   
   <association>
     <instanceOf>
       <subjectIndicatorRef
         xlink:href="http://www.techquila.com/psi/faceted-classification/#facet-has-superordinate-role-type"/>
     </instanceOf>
     <member>
       <roleSpec>
         <subjectIndicatorRef xlink:href="http://www.techquila.com/psi/faceted-classification/#facet"/>
       </roleSpec>
       <topicRef xlink:href="#places"/>
     </member>
     <member>
       <roleSpec>
         <subjectIndicatorRef
           xlink:href="http://www.techquila.com/psi/hierarchy/#superordinate-role-type"/>
       </roleSpec>
       <topicRef xlink:href="#container"/>
     </member>
   </association>
   
   <!-- Containee role is a subordinate role type -->
   <topic id="containee">
     <baseName>
       <baseNameString>Containee</baseNameString>
     </baseName>
   </topic>
   
   <association>
     <instanceOf>
       <subjectIndicatorRef
         xlink:href="http://www.techquila.com/psi/faceted-classification/#facet-has-subordinate-role-type"/>
     </instanceOf>
     <member>
       <roleSpec>
         <subjectIndicatorRef xlink:href="http://www.techquila.com/psi/faceted-classification/#facet"/>
       </roleSpec>
       <topicRef xlink:href="#places"/>
     </member>
     <member>
       <roleSpec>
         <subjectIndicatorRef
           xlink:href="http://www.techquila.com/psi/hierarchy/#subordinate-role-type"/>
       </roleSpec>
       <topicRef xlink:href="#containee"/>
     </member>
   </association>

6. Create Hierarchy Associations

   Now create as many hierarchy associations as necessary. When specifiying all the children of a single topic in the hierarchy you can use either one association with multiple subordinate role players or multiple binary associations. Note that these associations are completely free of the supporting topic infrastructure used to create the hierarchy. This means that any other topic map application that is not aware of the significance of the Techquila PSIs will still present the container/containee relationships as intended.

   <!-- The World contains Europe -->
   <association>
     <instanceOf><topicRef xlink:href="#contains"/></instanceOf>
     <member>
       <roleSpec><topicRef xlink:href="#container"/></instanceOf>
       <topicRef xlink:href="#the-world"/>
     </member>
     <member>
       <roleSpec><topicRef xlink:href="#containee"/></instanceOf>
       <topicRef xlink:href="#europe"/>
     </member>
   </association>
   
   <!-- Europe contains UK and France -->
   <association>
     <instanceOf><topicRef xlink:href="#contains"/></instanceOf>
     <member>
       <roleSpec><topicRef xlink:href="#container"/></instanceOf>
       <topicRef xlink:href="#europe"/>
     </member>
     <member>
       <roleSpec><topicRef xlink:href="#containee"/></instanceOf>
       <topicRef xlink:href="#uk"/>
       <topicRef xlink:href="#france"/>
     </member>
   </association>

The TMCore engine installs a number of public views and user-defined functions into the SQL database. These views and functions are easily identified as they have names starting with the prefix "tm_". These views and functions are documented in the TMCore Query Reference Sheet.

You can use these views and functions in exactly the same way as you would use any normal SQL view or function. For example you can use the tm_displayName function to transform a topic id into a display name for the topic. For example the query:

would return the display name for each topic which plays a role in the association with the ID "123". Some of the functions defined by TMCore return table values which allows you to use them in a select or sub-select. For example you can use the tm_instanceOf function to return the classes and superclasses of a topic with a query such as:

where tm and topic should be replaced with the ID value of the topic map and the instance topic respectively.

A full tutorial on the SQL query language is beyond the scope of this document. The TMCore Query Reference Sheet gives full documentation of each view and query provided by TMCore.

The interface ITopicMapSystem provides a single method ITopicMapSystem.ExecuteQuery(string) through which an SQL query can be executed against the TMCore system. The method returns an instance of the ITMCoreDataReader interface which gives read-only access to the results of the query.

The ITMCoreDataReader interface extends the standard System.Data.IDataReader interface with the following additional methods:

Each of the methods listed above take as their single parameter the zero-based position of the column from which the object's ObjectID value is to be retrieved. The method then loads any additional data required from the database and returns an instance of the appropriate topic map object interface. The method GetTopicMapObject() will determine the type of the object and return an instance of the appropriate dervied interface (e.g. an IOccurrence instance if the identifier is from an occurrence object). If the content of the specified column is not the object identifier of the requested type of topic map object, then an InvalidCastException will be raised.

As with other IDataReaders, the ITMCoreDataReader must be closed once it is no longer needed by calling the Close() method. The TMCore code will create a new connection for each concurrent ITMCoreDataReader instance that your program holds open and unless these readers are closed when not needed, your application will quickly use up all the available connections leading to unexpected failures.

The code listing below shows an example of using the ITopicMapSystem.ExecuteQuery() method to retrieve the topic names which contain the string "foo" and have a particular topic in their scope. Note that the call to the ITMCoreDataReader.Close() method is enclosed in the finally block to ensure that it gets called even if the processing of a topic name results in an exception being raised.

ITopic scopingTopic;
ITopicMap tm;

// ... set up scopingTopic and tm

string query = "select v.name_id from " +
  "TM_nameValue join TM_nameScope on TM_nameValue.name_id=TM_nameScope.name_id" +
  "where TM_nameValue.name_value like '%foo%' and TM_nameScope.scoping_topic_id=" + scopingTopic.ObjectID;

ITMCoreDataReader dr = tm.TopicMapSystem.ExecuteQuery(query);
try {
  while (dr.Read()) {
    ITopicName tn = dr.GetTopicName(0);
    // Do something with the scoped name
  }
} finally {
  dr.Close();
}

The TopicMapSystem interface also supports executing queries with a set of parameters. This is STRONGLY RECOMMENDED when one or more parameters come from user input as SQL parameter values are properly escaped and checked for SQL injection attacks. There are two overrides of the ExecuteQuery method that support parameters. The method ExecuteQuery(String queryString, IList parameters) takes a list of System.Data.IDataParameter instances (e.g. System.Data.SqlClient.SqlParameter), this method gives you the most control over the parameters you pass at the expense of requiring you to instantiate each parameter object explicitly. The second override is ExecuteQuery(String queryString, Hashtable parameters), which takes a Hashtable of parameter values where the Hashtable key is the parameter name and the value is the parameter value. The parameter type is automatically inferred from the parameter value.

The code samples below show how these two overrides can be used.

string query = "select v.name_id " +
  "from tm_nameValue join tm_nameScope on tm_nameValue.name_id=tm_nameScope.name_id "+
  "where tm_nameValue.name_value like @name and tm_nameScope.scoping_topic_id=@scopingTopic";

ArrayList parameters = new ArrayList();
IDataParameter param = new SqlParameter();
param.Name = "@name";
param.DbType = DbType.String;
param.Value = "%foo%";
parameters.add(param);
param = new SqlParameter();
param.Name = "@scopingTopic";
param.DbType = DbType.Int32;
param.Value = scopingTopic.ID;
parameters.add(param);
ITMCoreDataReader dr = tm.TopicMapSystem.ExecuteQuery(query, parameters);

string query = "select v.name_id " +
  "from tm_nameValue join tm_nameScope on tm_nameValue.name_id=tm_nameScope.name_id "+
  "where tm_nameValue.name_value like @name and tm_nameScope.scoping_topic_id=@scopingTopic";

Hashtable parameters = new Hashtable();
parameters["@name"] = "%foo%";
parameters["@scopingTopic"] = scopingTopic.ID;
ITMCoreDataReader dr = tm.TopicMapSystem.ExecuteQuery(query, parameters);

There are three keys to efficient use of the TMCore's query facilities:

The TMAPI-based interfaces such as ITopic, IAssociation and so on provide methods for both topic map read and update. These interfaces are relatively efficient when the topics and associations you access are small and / or you are modifying all of the topic or association structure. This is because the implementations of these classes retrieve the entire topic or association from the database, perform any modifications locally and then only return the state to the database when you call the Save() method.

However there are many cases where an application is required to only perform some relatively small incremental update on a large number of topics or associations in a database and in those cases, the overhead of retrieving the entire structure for an ITopic or IAssociation instance from the database can cause performance problems. For these circumstances we have provided a transaction-oriented API for topic map updates.

Unlike TMAPI which deals with objects and object states, the transactional API deals with operations on a topic map. Each operation in the transactional API is processed by a database stored procedure call which updates some part of a topic or association. Individual calls are therefore processed much more quickly than if the equivalent operation was implemented using TMAPI.

Some sample code that uses the transactional API can be found in the sample code that comes with the TMCore installation.

This section introduces the key concepts of NPCL.

A set of NPCL types and constraints can be represented in a topic map as a collection of topics, occurrences and associations. This feature enables a topic map to carry its own type and constraint information without the need to use any external files. It also enables the use of generic topic map editing and processing tools to create and update the type and constraint information for a topic map. This section describes how an NPCL schema can be represented in a topic map.

<xtm:topicMap xmlns:xtm="..." xmlns:xlink="...">
  <!-- 'person' can be used as a topic type -->
  <xtm:topic id="person">
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef 
xlink:href="http://www.networkedplanet.com/psi/npcl/meta-types/topic-type"/>
    </xtm:instanceOf>
    ...
  </xtm:topic>
</xtm:topicMap>

<xtm:topicMap xmlns:xtm="..." xmlns:xlink="...">

  <!-- Topic type meta-type -->
  <xtm:topic id="topic-type">
    <xtm:subjectIdentity>
      <xtm:subjectIndicatorRef
xlink:href="http://www.networkedplanet.com/psi/npcl/meta-types/topic-type"/>
    </xtm:subjectIdentity>
    ...
  </xtm:topic>

  <xtm:topic id="person">
    <xtm:instanceOf>
      <xtm:topicRef xlink:href="#topic-type"/>
    </xtm:instanceOf>
  </xtm:topic>

  <xtm:topic id="company">
    <xtm:instanceOf>
      <xtm:topicRef xlink:href="#topic-type"/>
    </xtm:instanceOf>
  </xtm:topic>
</xtm:topicMap>

<xtm:topicMap xmlns:xtm="..." xmlns:xlink="...">

  <!-- Legal Entity is an abstract Topic Type -->
  <xtm:topic id="legal-entity">
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef
xlink:href="http://www.networkedplanet.com/psi/npcl/meta-types/topic-type"/>
    </xtm:instanceOf>
    <!-- Is Abstract Facet = true -->
    <xtm:occurrence>
      <xtm:instanceOf>
        <xtm:subjectIndicatorRef
xlink:href="http://www.networkedplanet.com/psi/npcl/facets/is-abstract-facet"/>
      </xtm:instanceOf>
      <xtm:resourceData>true</xtm:resourceData>
    </xtm:occurrence>
  </xtm:topic>

</xtm:topicMap>

<xtm:topicMap xmlns:xtm="..." xmlns:xlink="...">

  <xtm:topic id="age">
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef xlink:href="htttp://www.networkedplanet.com/psi/npcl/meta-types/occurrence-type"/>
    <xtm:instanceOf>
    <xtm:baseName>
      <xtm:baseNameString>Age (in years)</xtm:baseName>
    </xtm:baseName>

    <!-- data-type is integer -->
    <xtm:occurrence>
      <xtm:instanceOf>
        <xtm:subjectIndicatorRef xlink:href="htttp://www.networkedplanet.com/psi/npcl/facets/value-datatype-facet"/>
      </xtm:instanceOf>
      <xtm:resourceData>http://www.w3.org/2001/XMLSchema#int</xtm:resourceData>
    </xtm:occurrence>

    <!-- minimum value is 0 -->
    <xtm:occurrence>
      <xtm:instanceOf>
        <xtm:subjectIndicatorRef xlink:href="htttp://www.networkedplanet.com/psi/npcl/facets/minimum-value-facet"/>
      </xtm:instanceOf>
      <xtm:resourceData>0</xtm:resourceData>
    </xtm:occurrence>

    <!-- maximum value is 125 -->
    <xtm:occurrence>
      <xtm:instanceOf>
        <xtm:subjectIndicatorRef xlink:href="htttp://www.networkedplanet.com/psi/npcl/facets/maximum-value-facet"/>
      </xtm:instanceOf>
      <xtm:resourceData>125</xtm:resourceData>
    </xtm:occurrence>
  </xtm:topic>

</xtm:topicMap>

<xtm:topicMap xmlns:xtm="..." xmlns:xlink="...">

  <xtm:topic id="language">
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef xlink:href="htttp://www.networkedplanet.com/psi/npcl/meta-types/topic-type"/>
    <xtm:instanceOf>
    <xtm:baseName>
      <xtm:baseNameString>Language</xtm:baseName>
    </xtm:baseName>

    <!-- Language topics can scope topic names and occurrences -->
    <xtm:occurrence>
      <xtm:instanceOf>
        <xtm:subjectIndicatorRef xlink:href="htttp://www.networkedplanet.com/psi/npcl/facets/scoping-facet"/>
      </xtm:instanceOf>
      <xtm:resourceData>NAME OCCURRENCE</xtm:resourceData>
    </xtm:occurrence>

  </xtm:topic>

</xtm:topicMap>

<xtm:topicMap xmlns:xtm="...">

  <xtm:topic id="employment">
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef xlink:href="http://www.networkedplanet.com/psi/npcl/meta-types/association-type" />
    </xtm:instanceOf>
    <xtm:subjectIdentity>
      <xtm:subjectIndicatorRef xlink:href="http://www.networkedplanet.com/npcl/tests/employment" />
    </xtm:subjectIdentity>
    <xtm:baseName>
      <xtm:baseNameString>Employment</xtm:baseNameString>
    </xtm:baseName>

    <!-- Arc Label for the Employee Association Role -->
    <xtm:baseName>
      <xtm:scope><xtm:topicRef xlink:href="#employee"/></xtm:scope>
      <xtm:baseNameString>Works For</xtm:baseNameString>
    </xtm:baseName>

    <!-- Arc Label for the Employer Association Role -->
    <xtm:baseName>
      <xtm:scope><xtm:topicRef xlink:href="#employer"/></xtm:scope>
      <xtm:baseNameString>Employs</xtm:baseNameString>
    </xtm:baseName>
  </xtm:topic>

  <xtm:topic id="employer">
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef xlink:href="http://www.networkedplanet.com/psi/npcl/meta-types/association-role-type" />
    </xtm:instanceOf>
    <xtm:subjectIdentity>
      <xtm:subjectIndicatorRef xlink:href="http://www.networkedplanet.com/npcl/tests/employer" />
    </xtm:subjectIdentity>
    <xtm:baseName>
      <xtm:baseNameString>Employer</xtm:baseNameString>
    </xtm:baseName>
  </xtm:topic>

  <xtm:topic id="employee">
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef xlink:href="http://www.networkedplanet.com/psi/npcl/meta-types/association-role-type" />
    </xtm:instanceOf>
    <xtm:subjectIdentity>
      <xtm:subjectIndicatorRef xlink:href="http://www.networkedplanet.com/npcl/tests/employee" />
    </xtm:subjectIdentity>
    <xtm:baseName>
      <xtm:baseNameString>Employee</xtm:baseNameString>
    </xtm:baseName>
  </xtm:topic>

</xtm:topicMap>

<xtm:topicMap xmlns:xtm="..." xmlns:xlink="...">

  <!-- Not shown : Definitions of person and age topics. -->

  <!-- Person-Age Occcurrence Constraint -->
  <xtm:topic id="person-age-constraint">
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef 
           xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/occurrence-constraint"/>
    </xtm:instanceOf>
    <!-- Person must have 0 or 1 Age occurrence -->
    <xtm:occurrence>
      <xtm:instanceOf>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/facets/minimum-cardinality-facet"/>
      </xtm:instanceOf>
      <xtm:resourceData>0</xtm:resourceData>
    </xtm:occurrence>
    <xtm:occurrence>
      <xtm:instanceOf>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/facets/maximum-cardinality-facet"/>
      </xtm:instanceOf>
      <xtm:resourceData>1</xtm:resourceData>
    </xtm:occurrence>
  </xtm:topic>

  <!-- Person-Age constraint applies to Person topic type -->
  <xtm:association>
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef 
           xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/oc-applies-to-tt"/>
    </xtm:instanceOf>
    <xtm:member>
      <xtm:roleSpec>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/oc-applies-to-tt-source"/>
      </xtm:roleSpec>
      <xtm:topicRef xlink:href="#person-age-constraint"/>
    </xtm:member>
    <xtm:member>
      <xtm:roleSpec>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/oc-applies-to-tt-target"/>
      </xtm:roleSpec>
      <xtm:topicRef xlink:href="#person"/>
    </xtm:member>
  </xtm:association>

  <!-- Person-Age constraint constrains occurrences of type Age -->
  <xtm:association>
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef 
           xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/oc-allows-ot"/>
    </xtm:instanceOf>
    <xtm:member>
      <xtm:roleSpec>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/oc-allows-ot-source"/>
      </xtm:roleSpec>
      <xtm:topicRef xlink:href="#person-age-constraint"/>
    </xtm:member>
    <xtm:member>
      <xtm:roleSpec>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/oc-allows-ot-target"/>
      </xtm:roleSpec>
      <xtm:topicRef xlink:href="#age"/>
    </xtm:member>
  </xtm:association>

</xtm:topicMap>

<xtm:topicMap xmlns:xtm="..." xmlns:xlink="...">

  <!-- Not shown: Definitions of person, employee and employment topics -->

  <!-- Person-Employee Role Player Constraint -->
  <xtm:topic id="person-employee-constraint">
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef 
           xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/role-player-constraint"/>
    </xtm:instanceOf>
  </xtm:topic>

  <!-- Person-Employee constraint applies to Person topic type -->
  <xtm:association>
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef 
           xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/rpc-applies-to-tt"/>
    </xtm:instanceOf>
    <xtm:member>
      <xtm:roleSpec>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/rpc-applies-to-tt-source"/>
      </xtm:roleSpec>
      <xtm:topicRef xlink:href="#person-employee-constraint"/>
    </xtm:member>
    <xtm:member>
      <xtm:roleSpec>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/rpc-applies-to-tt-target"/>
      </xtm:roleSpec>
      <xtm:topicRef xlink:href="#person"/>
    </xtm:member>
  </xtm:association>

  <!-- Person-Employee constraint constrains roles of type Employee -->
  <xtm:association>
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef 
           xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/rpc-allows-rt"/>
    </xtm:instanceOf>
    <xtm:member>
      <xtm:roleSpec>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/rpc-allows-rt-source"/>
      </xtm:roleSpec>
      <xtm:topicRef xlink:href="#person-employee-constraint"/>
    </xtm:member>
    <xtm:member>
      <xtm:roleSpec>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/rpc-allows-rt-target"/>
      </xtm:roleSpec>
      <xtm:topicRef xlink:href="#employee"/>
    </xtm:member>
  </xtm:association>

  <!-- Person-Employee constraint constrains roles in associations of type Employment -->
  <xtm:association>
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef 
           xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/rpc-allows-at"/>
    </xtm:instanceOf>
    <xtm:member>
      <xtm:roleSpec>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/rpc-allows-at-source"/>
      </xtm:roleSpec>
      <xtm:topicRef xlink:href="#person-employee-constraint"/>
    </xtm:member>
    <xtm:member>
      <xtm:roleSpec>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/rpc-allows-at-target"/>
      </xtm:roleSpec>
      <xtm:topicRef xlink:href="#employment"/>
    </xtm:member>
  </xtm:association>

</xtm:topicMap>

<xtm:topicMap xmlns:xtm="..." xmlns:xlink="...">

  <!-- Not defined : The topics employment and employee. -->

  <!-- Employment-Employee Constraint. -->
  <topic id="employment-employee-constraint">
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef 
           xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/association-role-constraint"/>
    </xtm:instanceOf>
    <!-- Employment association must have exactly 1 employee role -->
    <xtm:occurrence>
      <xtm:instanceOf>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/facets/minimum-cardinality-facet"/>
      </xtm:instanceOf>
      <xtm:resourceData>1</xtm:resourceData>
    </xtm:occurrence>
    <xtm:occurrence>
      <xtm:instanceOf>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/facets/maximum-cardinality-facet"/>
      </xtm:instanceOf>
      <xtm:resourceData>1</xtm:resourceData>
    </xtm:occurrence>
  </topic>

  <!-- Employment-Employee constraint applies to Employment association type -->
  <xtm:association>
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef 
           xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/arc-applies-to-at"/>
    </xtm:instanceOf>
    <xtm:member>
      <xtm:roleSpec>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/arcc-applies-to-at-source"/>
      </xtm:roleSpec>
      <xtm:topicRef xlink:href="#employment-employee-constraint"/>
    </xtm:member>
    <xtm:member>
      <xtm:roleSpec>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/arc-applies-to-at-target"/>
      </xtm:roleSpec>
      <xtm:topicRef xlink:href="#employment"/>
    </xtm:member>
  </xtm:association>

  <!-- Employment-Employee constraint constrains roles of type employee -->
  <xtm:association>
    <xtm:instanceOf>
      <xtm:subjectIndicatorRef 
           xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/arc-allows-rt"/>
    </xtm:instanceOf>
    <xtm:member>
      <xtm:roleSpec>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/arc-allows-rt-source"/>
      </xtm:roleSpec>
      <xtm:topicRef xlink:href="#employment-employee-constraint"/>
    </xtm:member>
    <xtm:member>
      <xtm:roleSpec>
        <xtm:subjectIndicatorRef 
             xlink:href="http://www.networkedplanet.com/psi/npcl/constraints/arc-allows-rt-target"/>
      </xtm:roleSpec>
      <xtm:topicRef xlink:href="#employee"/>
    </xtm:member>
  </xtm:association>

</xtm:topicMap>

All of the functionality of the TMCore implementation of NPCL is contained in a single namespace, NetworkedPlanet.Npcl and the entire implementation is contained in the assembly NetworkedPlanet.Npcl.dll. The HTML Help file for the TMCore API contains a detailed description of every public interface, class and method in this namespace. This chapter deals with the general principals of the API and gives some short code examples of using the API.

The NPCL data model is represented by a collection of interfaces as shown in the table below.

To work with the API it is important to understand the containment hierarchy of the NPCL model - that is, which items in the model are "parents" that contain other items in the model. The containment hierarchy is quite simple and is shown in the UML diagram below - the black diamond indicates the "container" and the undecorated end indicates the "contained" item.

Figure 12.1. NPCL Containment Hierarchy

In addition to the interfaces that represent the schema model, the NetworkedPlanet.Npcl namespace provides classes for loading schema information from an XML file or from a topic map and for writing schema information to an XML file or topic map. In addition several convenience methods are provided in the class NetworkedPlanet.Npcl.SchemaUtils. These utility classes are described in more detail in the following chapter on using the API.

This chapter desribes the principal operations that you can perform through the NPCL API.

// Every type will use the same base URI for its subject identifier
string psiBase = "http://www.networkedplanet.com/npcl/tests/";

// Get a new blank schema
ISchema schema = SchemaUtils.CreateSchema();

// Person Topic Type
ITopicType person = schema.CreateTopicType("person", psiBase + "person");
person.DisplayName = "Person";

// Company Topic Type
ITopicType company = schema.CreateTopicType("company", psiBase + "company");
company.DisplayName = "Company";

// Employment Association Type
IAssociationType employment = schema.CreateAssociationType("employment", psiBase + "employment");
employment.DisplayName = "Employment";

// Employer Role Type
IRoleType employer = schema.CreateRoleType("employer", psiBase + "employer");
employer.DisplayName = "Employer";

// Employee Role Type
IRoleType employee = schema.CreateRoleType("employee", psiBase + "employee");
employee.DisplayName = "Employee";

// Employment association allows exactly 1 Employer role
employment.CreateAssociationRoleConstraint(employer, 1, 1, "Employs");
// Employment association allows exactly 1 Employee role
employment.CreateAssociationRoleConstraint(employee, 1, 1, "Works For");

// A Person can play the role of Employee 0 or more times
person.CreateRolePlayerConstraint(employee, employment, 0, Cardinality.Unbounded);

// A Company can play the role of Employer 0 or more times
company.CreateRolePlayerConstraint(employer, employment, 0, Cardinality.Unbounded);

// Age Occurrence Type allows integer values between 0 and 120
IOccurrenceType age = schema.CreateOccurrenceType("age", psiBase + "age");
age.DatatypeConstraint = "http://www.w3.org/2001/XMLSchema#int";
age.MinValueConstraint = "0";
age.MaxValueConstraint = "120";

// Person Topic Type can have 0 or 1 Age occurrences
person.CreateOccurrenceConstraint(age, 0, 1);

// Language Topic Type
ITopicType languageTt = schema.CreateTopicType("language", psiBase + "language");
languageTt.DisplayName = "Language";
// Language topics can be used to scope Names or Occurrences (but not Associations)
languageTt.ScopingFacet = Scoping.Name | Scoping.Occurrence;

// Secret Scoping Topic
IScopingTopic secret = schema.CreateScopingTopic("secret", psiBase + "secret");

// Entity Abstract Type
IAbstractType entity = schema.CreateAbstractType("entity", psiBase + "entity");
// Legal Entity Abstract TYpe
IAbstractType legalEntity = schema.CreateAbstractType("legal-entity", psiBase + "legal-entity");

// Create A Class Hierarchy with Entity as the root.
entity.AddDirectSubclass(legalEntity);
legalEntity.AddDirectSubclass(person);
legalEntity.AddDirectSubclass(company);

FileInfo outputFile = new FileInfo("myschema.xml");
Stream output = outputFile.Open(FileMode.Create, FileAccess.Write);
XmlTextWriter xmlWriter = new XmlTextWriter(output, System.Text.Encoding.UTF8);
xmlWriter.Formatting = Formatting.Indented;
// Create a new XmlSchemaWriter to write as a full XML document 
// using the prefix "npcl" for the NPCL XML Namespace.
XmlSchemaWriter schemaWriter = new XmlSchemaWriter(xmlWriter, false, "npcl");
schemaWriter.WriteSchema(originalSchema);
// NOTE: The XmlSchemaWriter does not close the XmlWriter at the end of the document.
xmlWriter.Close();

TopicMapSchemaWriter writer = new TopicMapSchemaWriter(tm, SchemaWriterMode.ReplaceAll);
writer.WriteSchema(originalSchema);

ISchemaReader schemaReader = new XmlSchemaReader( new FileStream("simple-ontology.npcl", FileMode.Open) );
// or with an ITopicMap object called myTopicMap:
// ISchemaReader schemaReader = new XmlSchemaReader( myTopicMap );
schemaReader.Strict = false;
ISchema schema = schemaReader.ReadSchema();
foreach(NpclException error in schema.Errors) {
  System.Console.WriteLine(error.Message);
}

// Assume that tmSystem is an ITopicMapSystem object that is already initialized

// Get the topic map to process
ITopicMap tm = tmSystem.GetTopicMap("my-topicmap");
// Invoke the SchemaUtils to generate the schema
ISchema schema = SchemaUtils.InferSchema(tm, "http://www.mycompany.com/psi/");
// Write the schema to a file
XmlTextWriter xmlWriter = new XmlTextWriter("my-topicmap.npcl", System.Text.Encoding.UTF8);
xmlWriter.Formatting = Formatting.Indented;
XmlSchemaWriter writer = new XmlSchemaWriter(xmlWriter, false, "npcl");
writer.WriteSchema(schema);
xmlWriter.Close();

// Assume that tmSystem is an ITopicMapSystem object that is already initialized

// Get the topic map to process
ITopicMap tm = tmSystem.GetTopicMap("my-topicmap");

// Invoke the SchemaUtils to generate the schema
// Using null for the subject identifier base generates identifiers
// that will correctly update topics that do not currently have subject identifiers.
ISchema schema = SchemaUtils.InferSchema(tm, null);

// Write the schema back to the topic map - replacing any previous schema information
TopicMapSchemaWriter writer = new TopicMapSchemaWriter(tm, SchemaWriterMode.ReplaceAll);
writer.WriteSchema(schema);

When programming code or the TMWS web services are used to update a topic map, repeated updates can lead to the possibility of duplicate information being recorded in a topic map. TMCore provides two database stored procedures that clean up this duplicate information, reducing database size and improving topic map consistency.

This chapter describes what "duplicate information" means in the context of a topic map and goes on to describe the stored procedures that can be used to remove duplicate information.

Duplicate information in a topic map falls into one of three categories: duplicate information on a topic; duplicate information on an association; and duplicate associations.

Two stored procedures are provided by TMCore to implement the duplicate removal policies described above. These stored procedures can be invoked by any member of the tm_writer database role.

tm_RemoveDuplicates. This stored procedure is invoked with no parameters and removes all duplicate information from all topic maps in the database.

tm_RemoveDuplicatesFromTopicMap.  This stored procedure takes a topic map OID as its only parameter and removes all duplicate information from the topic map identified by that parameter.

Either of these duplicate removal stored procedures can be invoked either using TSQL in a command-line application such as the SQL Server ISQL.EXE application, or using the appropriate database management tool such as SQL Server Management Studio for SQL Server 2005. The stored procedures can also be invoked directly through code using the TMCore APIs. The following is an example of how to invoke the tm_RemoveDuplicates procedure from code:

      // Assume the tms variable holds an ITopicMapSystem instance
      // Invoking the stored procedure with a command-timeout value of
      // 0 allows for a potentially long-running procedure call.
      tms.ExecuteQuery("EXEC tm_RemoveDuplicates", 0);
    

Similar code can be used to invoke tm_RemoveDuplicatesFromTopicMap to target a specific topic map:

      private void RunTopicMapDuplicateSuppression(ITopicMap tm)
      {
        Hashtable parameters = new Hashtable();
        parameters["@tmId"] = tm.ID;
        tm.TopicMapSystem.ExecuteQuery(
	   "EXEC tm_RemoveDuplicatesFromTopicMap @tmId", 
	   parameters, 0);
      }