TMV Developer Guide

This document describes the TMV architecture and explains how developers can use and extend it.

Introduction

The k42 API exposes the topicmap model to developers, allowing them to access and create topicmap JAVA objects programmatically. In order to create applications on top of this, such as web sites, developers must turn these JAVA objects into information that can be displayed by different types of devices, such as a Web Browser. In order to facilitate our own efforts in providing k42 applications on top of our API, as well as providing an example architecture that other developers could use, we developed the TMV (TopicMap View) module that makes XML representations of objects in the topicmap.

TMV

TMV is coined "TopicMap View" because it creates XML instances based on topicmaps, topics and topic associations. Methods in the TopicMapView.class can be called from other programs, in order to return XML data that is of a set structure described by the TMV DTD. The DTD allows users to understand the nature of the XML output that they can expect from TMV and it is consequently a relatively easy task to create XSLT to transform TMV XML to the appropriate requirements for different devices.

WebAuthor and "TMV Navigator"

A good example of this in practise, is seen in our own k42 applications WebAuthor and TMV Navigator. Both of these web interfaces use the TMV architecture and they only differ from the XSLT layer upwards. The navigator application uses TMV XML to create information pages and indexes for objects in the topicmap, whereas WebAuthor uses the same data, but different XSLT stylesheets to create web forms for users to interact with the model.

You can see this for yourself by comparing topic.xsl with tmv.xsl in the tmv folder in your web server.

Architecture

The diagram below shows the architecture diagram for TMV. The diagram on the left shows the architecture for client-side XML transformation, whereas the right hand diagram shows the alternative option of sever-side XML transformation. Both of this options are configurable for tmv.

Requests are made to the web server which are turned into calls to the TMV class in the k42 server. The TMV class then makes calls to ik42 and uses the resulting JAVA objects to create XML.

Extending and Developing TMV

This architecture is easily extensible because the TMV XML data is a stable format, as defined in the DTD. Designing and modifying applications on top of this, is a matter of applying XSLT to the XML output and designing an appropriate interface. For example, any user could create their own "WebAuthor" or TMV Navigator by writing their own XSLT and making the appropriate calls through servlets to the TMV class. In fact, as the TMV class itself is based on ik42, users could write their own "TMV" classes to output whatever data they needed. For simple navigation applications and for getting to know k42 and topicmaps, our own TMV is sufficient. The following paragraphs show how this can be used.

Getting XML from TMV

Users can use their web browser to make requests to TMV to obtain XML. Currently there are four requests that can be made using http query string parameters. These are GET requests. They are:

	getTMVTopics which returns XML with structure for each topic in the topicmap.
	getTMVTopicByName which returns XML representing the topic whose unconstrained name value matches the parameter value given for the parameter name "name". This XML contains all of the characteristics for the topic and information on the associations that it is involved in.
	getTMVTopicByID which returns XML with structure for a topic matching the ID supplied in the query string parameter value for the "oid" parameter.
	getTMVTopicsInRange which returns an XML instance representing a list of topics that have a name within the range values supplied using the"from" and "to"parameters.

These are the full http requests as they would be used in the browser:


http://domain:port/k42/tmv/tmvclient?method=getTMVTopics

http://domain:port/k42/tmv/tmvclient?method=getTMVTopicByName&name=namestr

http://domain:port/k42/tmv/tmvclient?method=getTMVTopicByID&oid=idstr

http://domain:port/k42/tmv/tmvclient?method=getTMVTopicsInRange&from=startstr&to=endstr

Specifying a stylesheet

It is also possible to specify an extra parameter in each request that will be used to set the <?xml-stylesheet?> processing instruction for the returned XML instance, or alternatively the stylesheet to use for server-side transformation. This can be appended to the query string as an extra parameter as shown:


http://domain:port/k42/tmv/tmvclient?method=getTMVTopics&stylesheet=example.xsl

and when this is returned in the browser, the XML will be transferred by the stylesheet. By default, the stylesheet path is mapped to the tmv folder in the web server - so if you add your stylsheets in the same place on the file system as the current tmv and webAuthor xsl they will be picked up without needing to specify the path in the query string. Otherwise developers can make their parameter value relative to this folder.

When the execute parameter is set tofalse, the stylesheet parameter value is including as a processing instructing within the XML returned, otherwise it is is mapped to the servlet context and used for the serv-side transformation.

Server-side versus Client-side XSLT

Many browsers do not support XML and are therefore not capable of transforming XML content into HTML for display to the user. Like many web technologies, it is therefore often sensible to do as much processing into neutral data formats on the server as possible in order to capture as much of the client platform specification as possible. The TMV servlet that we use to handle TMV requests can be configured to either return an XML stream to the client or to invoke an XSLT processor and return HTML instead. By default, it uses a server-side XALAN XSLT processor, however this can be disabled using an extra parameter in the HTTP request headers or POST data:


http://domain:port/k42/tmv/tmvclient?method=getTMVTopics&execute=false

This extra parameter will disable server-side transformation so that the requesting client will receive and XML instance to transform itself. For server-side transformation, TMV will map the stylesheet parameter relative to the Servlet Context and then the /tmv folder. Therefore stylesheet=example.xsl will use the following path: servletcontext/tmv/example.xsl

Creating an application

This is all that is needed to make a simple Topic Map application. For example, to create a utility for browsing topics in a topic map all that is needed is an initial call forgetTMVTopicsorgetTMVTopicsInRange and then a stylesheet that turns the resulting XML into a HTML list that has links containing thegetTMVTopicByID call using the id attributes that are present in the XML instance (see below). TMV displays both topics and topic associations, so getTMVTopicByID will return information for an association if the id supplied is for a topic association object. For an understanding of the XML that is returned by TMV look at the DTD in the tmv folder. This contains comments explaining each element. The DTD is for information and is not actually used to validate the XML that is returned by TMV.

The following XSLT will create a basic index of topics from thegetTMVTopics request:

<xsl:template match="tmv:topics">
 <tr>
  <td>        
   <xsl:for-each select="tmv:k42Ref">
    <div>
     <xsl:value-of select="@tmv:costume" />
      <a>
       <xsl:attribute name="href">
        ../tmv/tmvclient?method=getTMVTopicByID&oid=
        <xsl:value-of select="@tmv:oref" />
        &stylesheet=example.xsl
       </xsl:attribute>
       <xsl:value-of select="tmv:names/tmv:name/text()" />
      </a> 		
    </div>
   </xsl:for-each>       
  </td>
 </tr>
</xsl:template>

To see this in full examine theexample.xslfile included with the download and enter the following URL into your XML enabled web browser:http://domain:port/k42/tmv/tmvclient?method=getTMVTopics&stylesheet;=example.xsl