List Models Descriptor

The purpose of this tutorial is to create and deploy a Descriptor that returns an HTML page with a list of models available on a Kowari^TM database.

In this tutorial you will to do the following:

Execute an iTQL^TM command inside a Descriptor
Pass parameters to the iTQL command
Transform the query results into HTML

Note - It is assumed have already completed the Hello World tutorial. If any steps in this tutorial are unclear refer back to the Hello World tutorial for a complete explanation.

Complete the following steps:

Start the Descriptor Wizard.
Use the Create Descriptor Using Wizard task from the Descriptor Management page. The Descriptor Wizard page displays.
Enter a Descriptor title.
Enter a title of Lists models in a Kowari Database as HTML.
Enter Descriptor parameters.
To make the Descriptor reusable across different Kowari databases, enter a parameter of server. It is a string parameter.
Enter the mime type of text/html.
The Descriptor Wizard page should now look similar to the following:
Generate the Descriptor template.
Click on the Generate Descriptor Template button.
Save the Descriptor XSL file.
Your browser now shows an XSL file, or it may ask you if you want to download it. In either case, save the file where you can edit it. Save it as modellist.xsl.
Edit the Descriptor XSL file.
Using your preferred text editor, edit the Descriptor XSL file and change the main template rule at the top to look like this:




<xsl:template match="/">
<xsl:choose>
<xsl:when test="$_usage">
<xsl:call-template name="usage"/>
</xsl:when>
<xsl:otherwise>


<xsl:variable name="answer">

<tucanaDescriptor:query server="{$server}">
<![CDATA[
select $model from <@@server@@#> where
$model <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://tucana.org/tucana#Model>;
]]>
</tucanaDescriptor:query>
</xsl:variable>


<xsl:copy-of select="xalan:nodeset($answer)/*"/>

</xsl:otherwise>
</xsl:choose>
</xsl:template>

Several new concepts are introduced in this Descriptor as opposed to the Hello World Descriptor.

The <tucanaDescriptor:query> Tag


<tucanaDescriptor:query server="{$server}">
<![CDATA[
select $model from <@@server@@> where
$model <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://tucana.org/tucana#Model>;
]]>
</tucanaDescriptor:query>

This tag is an extension to XSL allowing queries to be made to a Kowari database. See The <query> Tag section for more information.

In a text child of this tag (that is, between the open and closing tags) an iTQL command is placed. The query text is stored in a CDATA section so as to stop the XML parser having problems with the angle brackets surrounding resources. The use of the @@server@@ is a simple token replacement mechanism. Any time a piece to text is found surrounded by '@@' the Descriptor looks for the text as an attribute of the query tag and replaces it with that value.

In this case the text @@server@@ is replaced with the value of the server attribute {$server} which is the server parameter passed to the Descriptor on invocation. The client using this Descriptor must supply a server parameter. This contract (the interface in software engineering terms) is specified in the RDF of the Descriptor.

Looking further down the modellist.xsl file is the parameter section like this:



<desc:hasParam xmlns:desc="http://tucana.org/descriptor#" xmlns="http://www.w3.org/1999/xhtml">

<desc:Param>

<desc:name>server</desc:name>
<desc:type>String</desc:type>
<desc:required>Yes</desc:required>
<desc:description>The server to get a model list from</desc:description>

</desc:Param>
</desc:hasParam>

This RDF reflects the information the developer entered into the Descriptor wizard. The Descriptor code checks for parameters and reports any violations such as parameters not present or of the wrong type.

Once the interface is decided, you can change the logic of the XSL file (that is, the rules) without needing to redeploy the Descriptor. This means that Descriptors can be developed interactively. For example, a developer can be editing a Descriptor XSL file, make a change, save it, and invoke the Descriptor for immediate results. However, if any of the parameters change, then the Descriptor must be redeployed.

Note - Descriptors are cached by Kowari. If you change a Descriptor, then the cache must be cleared. This is available as a task from the Descriptor Management page.

The <tucanaDescriptor:query> tag is surrounded by a <xsl:variable> tag that stores the results of the query in the variable answer. This is because the raw XML returned from an iTQL command is not very useful on its own. If you want to work with the raw XML directly, then you should work with the Java API interface to Kowari.

The tag <xsl:copy-of select="xalan:nodeset($answer)/*"/> is very useful for debugging. It copies the response from the Kowari (that is, the raw XML) to the output. This is useful when working with new Descriptors where you do not know exactly what their output looks like.

Note - Future versions of Descriptors will also declare an XML Schema of the results they produce.

At this stage, it is advisable to temporarily jump to the next step and invoke the Descriptor as is. You should see a raw XML response something like the following:

<?xml version="1.0" encoding="UTF-8"?>
<answer xmlns="http://tucana.org/tql#">
<query>
<variables>
<model/>
</variables>
<solution><model resource="rmi://mysite.com/server1#"/></solution>
<solution><model resource="rmi://mysite.com/server1#_"/></solution>
<solution><model resource="rmi://mysite.com/server1#descriptors"/></solution>
<solution><model resource="rmi://mysite.com/server1#customer"/></solution>
<solution><model resource="rmi://mysite.com/server1#sun"/></solution>
<solution><model resource="rmi://mysite.com/server1#nytimes"/></solution>
</query>
</answer>

If you do this, and then make further changes to your Descriptor (as you now will) you must clear the Descriptor cache. This is available as a task from the Descriptor Management page.

You now need to transform the above XML into an HTML list of the models. Writing a rule to match the <answer> tag is a good way to write the HTML header and body tags. The <solution> tag holds each solution to the query, like a row in a result set of an SQL query. First you must change the top most rule where you have the tag <xsl:copy-of select="xalan:nodeset($answer)/*"/> to <xsl:apply-templates select="xalan:nodeset($answer)/*"/>.

This applies the XSL template rules to the XML we received from Kowari. That is, its as if the raw XML was the input document to the XSL transformer. Now you need to write the two rules, one to match the answer and one to match the solution.

Answer Rule:




<xsl:template match="tucanaAnswer:answer">
<html>
<head>
<title>Kowari models</title>
</head>
<body>

List of models on server <xsl:value-of select="$server"/>
<ol>
<xsl:apply-templates/>
</ol>

</body>
</html>
</xsl:template>

This matches with an answer, writes out an HTML header and body and starts an ordered list, then applies the rest of the rules before closing the ordered list and closing all the HTML tags.

Solution Rule:




<xsl:template match="tucanaAnswer:solution">
<li><xsl:value-of select="tucanaAnswer:model/@resource"/></li>
</xsl:template>

This takes a solution and inserts the resource attribute of the <tucanaAnswer:model> tag (refer to the raw XML response if this is unclear) into a list element tag <li>. This effectively adds the Model URI to the HTML list.

Once you have entered both rules save the file again. You might want to check that the file is valid XML using a tool such as xmllint.
Deploy the Descriptor in Kowari.
Start an iTQL client.

Check if the Descriptor model already exists by querying for a list of models.

If the #descriptors model does not exist then you need to deploy the local Descriptors. This creates the Descriptors model and loads some useful Descriptors. It is one of the tasks available from the Descriptor Management page.

Deploy the Descriptor by loading the Descriptor XSL file into the #descriptor model, as follows:

load <file:/home/joe/work/modellist.xsl> into <rmi://mysite.com/server1#descriptors>;

Note - The location of the Descriptor must be accessible by Kowari. For systems running a Windows^® operating system, the file specification would look something like <file:/C:/work/modellist.xsl>.

If there were no errors in the XSL, then the Descriptor is deployed and available for use. If there were errors, check your XML for bad syntax such as unclosed tags. The Descriptor Wizard generates correct XML and XSL.
Invoke the Descriptor.
From the Descriptor Management page choose the Lists all Descriptors on this Host task. The Tucana Descriptor List displays. Click on the Usage button for your Descriptor to see details about the Descriptor, similar to the following screen.

Enter a server parameter such as rmi://mysite.com/server1 and invoke the Descriptor by clicking on the Invoke button.

The result displays in a window similar to the following:

The Descriptor can be used to get a list of models on any Kowari server, providing security allows it. Correspondingly, if this Descriptor is put onto a web server it can be deployed onto a remote Kowari server as follows:

load <http://www.mysite.com/descriptors/utils/modellist.xsl>
into <rmi://othersite.com/server1#descriptors>;

Many Descriptors can be developed to perform many different tasks. When developing or modifying an application to work with a Kowari database, it may be as simple as browsing the available Descriptors and choosing the ones appropriate for the applications needs.

In This Section

Where To From Here?

Another powerful feature of Descriptors is the ability to invoke one Descriptor from another. This allows complex Descriptors to be developed and for Descriptors to be changed without affecting clients (as long as the interfaces don't change). An example of this is a portal where one Descriptor calls on other Descriptors to assemble a custom HTML page or WML page.

See the VCard example for information on how to invoke one Descriptor from another.

Latest News

Kowari 1.1.0 Pre-release 1 Released

Kowari 1.0.5 Released

Kowari 1.0.4.1 Released

Kowari 1.0.4 Released

DAWG Evaluates iTQL

Kowari article in XML.com

Kowari mentioned on XML.com

Kowari 1.0.3 Released

Kowari Lite Introduced

Kowari 1.0.2 Released

Kowari 1.0.1 Released

View all news items