NetworkedPlanet

Topic Map Web Services

Topic Map Web Services provide an open, standards based interface to accessing and manipulating topic map data. TMCore from NetworkedPlanet provides a generic Topic Map Web Service for performing key topic map operations such as retrieving information about a single topic through to creating new topic associations.

A topic map web service is like any other web service in that in combines operation definitions, data structures and semantics. The following sections cover all of these aspects. This article assumes that you are already familiar with the basic principles of topic maps. To learn more about topic maps read our Introduction to Topic Maps. To explore the capabilities of the web service in more detail, apply for the free evaluation.

Topic Map Web Service Use Cases

The topic map web service can be used in a number of applications. The following ideas are just some of the exciting ways that we see the topic map web service being utilised.

System Integration The topic map paradigm is ideal for providing a view onto distributed data stores. However, with these systems it is necessary to push information to the topic map. The kind of information pushed is likely to be occurrences for a topic that link back to another data source, or the addition of a new topic. In this model the web service can be invoked from event handlers in existing enterprise information systems.

Client Applications Topic map data can be updated and amended from a number of different sources including by manual classifiers. The kind of work carried out for a particular user scenario and thus the kind of user interface required can be quite varied. In these scenarios it is useful to be able to build a custom user application as a thick client tool. The smart client can make use of the web service as a way to interact with the topic map to add and modify topics and associations. Unlike the in-process API, a web services interface is accessible from a wide variety of platforms and programming languages.

Topic Map Integration Applications such as web portals can use the web service to fetch and merge information from multiple topic map servers. This allows information from multiple sources to be presented seamlessly to information users.

The XML Data Structures

Before we consider the operations that occur on the topic map, it is necessary to look at the nature of the data that is passed to, and returned from, the service.

The Topic Maps standard defines an XML interchange syntax called XTM 1.0 which is verbose, difficult to process with XSLT and contains a number of naming and structural inconsistencies that can make it difficult to understand.

The ISO committee responsible for topic maps are aware of some of the failings of the XTM 1.0 specification and have decided to address these issues by first defining a data model for topic maps (called the Topic Maps Data Model or TMDM) and then creating an XTM 1.1 specification which cleans up the inconsistencies in XTM 1.0 and maps cleanly to the TMDM. As the TMDM is a data model expressed in simple UML diagrams, it is not only more clear, but a lot easier to grasp and more clearly represents exactly what a topic map is, rather than focussing on how it is represented in XML.

For the topic map web services provided by TMCore, we have defined an XML Schema that captures the Topic Maps Data Model in a clean, easy to understand, and most importantly, easy to process way. This XML representation is used by many of the operations of the topic map web service to return information about a topic, a list of topics, or a complete topic map fragment.

The following is a small piece of XML that represents a topic.

  <topicmap>
    <topiclist>
      <topic oid="t234">
        <topicTypes>
          <topicref displayname="Person" tref="345" />
        </topicTypes>
        <names>
          <name>
           <namestring>Bob Dylan</namestring>
          </name>
        </names>
      </topic>
    </topiclist>
  </topicmap>
			

The biggest difference between the XML here and the XTM is that all merging has been completed and all topic references are direct ID references rather than allowing the multiple topic reference mechanism of XTM such as subject identifiers and subject locators. That is not to say that these important properties of a topic are not represented in the topic map web services XML, just that your processing code does not have to use them to resolve references from one topic to another as this is all performed by the TMCore server.

Although topic maps allow arbitrarily complex graphs of concepts, there is still a great deal of information which can be most easily managed as a hierarchy. TMCore provides support for a commonly used set of Published Subject Identifiers for representing hierarchies in topic maps. The web service interface provides high-level operations for retrieving a list of all hierarchies contained in a single topic map and the entire tree for a single hierarchy. These methods use a tree-oriented schema which is more easily processed as a hierarchy. Again this schema uses topic references which include both an ID that can be used to retrieve the full detail of a topic and a display name which can be used to render a link to the topic without having to retrieve the full set of topic details. An example of the tree representation is shown below.

<nodelist>
  <node>
    <topic id="100" displayname="fruit"/>
    <children>
      <node>
        <topic id="101" displayname="Citrus Fruit"/>
        <children>
        ...
        </children>
      </node>
      <node>
        <topic id="102" displayname="Berries"/>
        ...
      </node>
    </nodelist>
  </node>
</nodelist>
			

The Service Interface

A service interface is a definition of the set of operations or behaviours exposed by a service. The Topic Map Service is expressed as a WSDL file that captures these operations.

A single TMCore server can manage multiple topic maps. Each topic map has its own name which uniquely identifies that topic map on the server. Many methods take this topic map name as a parameter.

The service is designed to provide the most common topic map operations, such as retrieving topics, topic types etc. and updating the topic map. The list below describes the key operations that comprise the web service.

• GetTopic(topicmapname, topic_id) This returns an XML representation of the specified topic from the named topic map.

• GetTopicMapNames() A topic map system such as TMCore can store and manage many topic maps. This operation returns a list of names of the topic maps currently available.

• GetTopicTypes(topicmapname) A topic map can contain topics that are topic types, such as the topic for 'Person'. This returns a list of topics that serve as types in the named topic map.

• GetTopicBySubjectIdentifier(topicmapname, locator) This returns an XML representation of the topic identified by the subject identifier locator supplied.

• GetTopicsByType(topicmapname, topictype_id) This operation allows users to fetch a list of all the topics that are instances of the given type.

• DeleteTopics(topicmapname, topic_id[]) The web service allows for users to delete topics simply by passing through the topic system identifier. This is the value stored in the 'oid' attribute on the topic element.

• SaveTopic(topicmapname, topicmap_fragment) Save topic is used to both update an existing topic and add new ones. This operation is covered in more detail below.

• GetHierarchyRoots(topicmapname) This operation returns a list of all of the hierarchies contained in the named topic map. Each root description includes a name for the hierarchy as well as an ID which can be used in subsequent calls to the GetHierarchy() method.

• GetHierarchy(topicmapname, rootid) This operation returns the entire tree for the specified hierarchy.

• Query(queryname, params[]) The web service does not allow the execution of arbitrary queries against the topic maps. Instead the administrator may configure any number of named queries that are accessible via the web services API. This operation invokes the named query, passing in parameters which are used as direct value replacements in the query string. The structure of the XML returned from this method is dependent upon the results table structure defined by the query.

Using the Web Service

The web service can be invoked in many ways - as it is a standard SOAP-based web-service, any programming language on any platform providing support for the SOAP standard can easily make use of the web service. However, to help developers working on the .NET platform we have created a client proxy that simplifies interactions with the web service.

  using NetworkedPlanet.TMService.Client;

  TMSClient client = new TMSClient("http://localhost/tmws/TMService.asmx");
  XmlDocument topicxml = client.GetTopic("mytopicmap.xml", 456);  

The code snippet (in C#) above shows how easy it is to create a client that interacts with the topic map web service. In the example the XML representation for a known topic is being returned. All of the other operations can be invoked in a similar fashion. The returned value is an XmlDocument instance which can then be processed using the full range of XML document processing functions provided by the .NET Framework, including XSLT.

With the web service and the generated client proxy it is a simple matter to write powerful applications that make use of the full topic map model. These applications can be other server applications or smart client applications that reside on users' desktops.

Updating the Topic Map

As mentioned above, the Save method acts as both a way to update topics but also to add new topics and associations. It works by taking the XML representation of the topic(s) and association(s) present in the topicmap_fragment and either adding them into the map if new, or updating the existing topic if it already exists. It should be noted though that the representation of the topic will be exactly as passed up; i.e. the semantics of the operation are not to append to the topic characteristics but to replace them.

Summary

Topic Map Web Services provide a rich and flexible way to perform batch operations and highly granular operations on topic map data. The topic map web service WSDL file provides all the details of the service, but at a higher level it is sufficient to understand that the web service provides cross platform access to topic map data and topic map operations.

Future articles in this section of the website will look at the use of the topic map web service in real-world applications in more detail.