Mulgara | Semantic Store - Descriptors FAQ

Descriptors FAQ

Debugging Descriptors can be difficult unless you are knowledgeable in the underlying technologies, including XSL, Servlets and SOAP. Some of the most common problems and their solutions are summarized below.

How do I create a Descriptor?

Use the Create Descriptor Using Wizard task on the Descriptor Management page.

How do I execute an iTQL command?

There are two ways to execute an iTQL^TM command:

The iTQL command line
The built-in Mulgara Viewer^TM

See the iTQL Reference Guide for more information.

How do I deploy the built-in Descriptors?

Use either the Deploy Descriptors or Redeploy Descriptors task on the Descriptor Management page.

The Redeploy Descriptors task completely removes all Descriptors before redeploying the built-in ones, while the Deploy Descriptors task deploys the built-in Descriptors and preserves the existing Descriptors.

How do I deploy my Descriptor?

The RDF embedded in the Descriptor XSL file needs to be loaded into a model in a Mulgara database, using the following steps:

Start an iTQL client.
Check that the Descriptor model already exists on the Mulgara server.
Load the Descriptor XSL file into the Descriptor model using the iTQL load command. For example:
load <file:/home/joe/work/helloworld.xsl>
into <rmi://mysite.com/server1#descriptors>;

Note - The location of the Descriptor must be readable by the Mulgara server. For systems running a Windows® operating system, the file specification looks something like <file:/C:/work/helloworld.xsl>.

If there are no errors in the XSL, then the Descriptor is deployed and available for use. Otherwise, check your XML for bad syntax, such as unclosed tags. The Create Descriptor Using Wizard task generates correct XML and XSL.

Note - When invoking the Descriptor from a client (SOAP, Java or another Descriptor), you must use the exact URL used to load the Descriptor. That is, you cannot load a Descriptor using a file: URL and then try and use if from a HTTP: URL, even if its on a web server.

If a Descriptor is to be used from a web server, then it should be loaded with a HTTP URL after it has been put on the web server. For example, if the file in the example above was on a web server in the work directory /home/joe/work/, and this is equivalent to http://foo/joe/work, then the Descriptor should be deployed as follows:

load <http://foo/joe/work/helloworld.xsl>
into <rmi://mysite.com/server1#descriptors>;

When Descriptors are deployed as HTTP URLs, they are accessible by any client with HTTP access, including any on the Internet, provided they have access through a firewall.

I can't invoke my Descriptor.

First, check that the Descriptor model exists on the Mulgara server.

If it does, then check that the Descriptor is deployed in the Descriptor model. If you changed anything from the time when you deployed it using the Create Descriptor Using Wizard task, then you have to redeploy the built-in Descriptors and redeploy your Descriptor.

How do I check that the Descriptor model exists on a Mulgara server?

There are two ways to check if the Descriptor model exists:

Use the List of Descriptors Available on this Host task from the Descriptor Management page. If it fails, no Descriptor model exists and the built-in Descriptors need to be deployed.
Use an iTQL command. For example:
select $model from <rmi://mysite.com/server1#>
where $model <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>
<http://mulgara.org/mulgara#Model>;

Note - In the above command, replace mysite.com with the fully qualified hostname of the Mulgara server. For example, foo.bar.com rather than just foo.

This query returns all models on the server. If there is no #descriptor model, then you need to deploy the built-in Descriptors and any Descriptors you have developed.

How do I check if my Descriptor is deployed?

Descriptors must be deployed before use. The Mulgara code that invokes a Descriptor looks up the parameters that a Descriptor uses, as well as other information, before it invokes the Descriptor. If the Descriptor has not been deployed, then the code does not know how to invoke it and fails.

First, make sure that the built-in Descriptors are deployed. Then select the List of Descriptors Available on this Host task from the Descriptor Management page.

What is the life cycle of a Descriptor?

When a Descriptor is first invoked, the Descriptor code retrieves the Descriptor from its URL and creates a java object representing that Descriptor.

For the first invocation only, the XSL transformer processes the XSL stylesheet into an internal form and places it in a free pool for use. When used, it is placed in a busy pool until it has performed its duty, then returned to the free pool. If a client requests a Descriptor and an instance is already in the busy pool, a new instance is created and made available.

Eventually, both Descriptors are returned to the free pool. The pool grows to the size needed and stays that size. It is not expected that these pools will get very large, especially in comparison to resources on a Mulgara server.

How do I empty the Descriptor cache?

Use the Purge all Cached Descriptors Available on this Host task from the Descriptor Management page.

I've changed my Descriptor XSL code but when invoked it does not notice my changes.

Descriptors are downloaded and processed into Java^TM Objects that are cached and reused.

If you have changed the logic in a Descriptor but not the parameters or mime type (that is, everything specified with the Create Descriptor Using Wizard task) then you need to clear the Descriptor cache using the Purge All Cached Descriptors Available on this Host task from the Descriptor Management page.

If you have added or removed a parameter or mime type then you will need to redeploy your Descriptor.

If the Descriptor is on a web server, check that you have published it to the web server.

My Descriptor doesn't work. Where are errors logged?

The file descriptor-errors.log, created in the directory where Mulgara is run from, contains the reasons for Descriptors failing. The file might also contain stack traces for more detailed error explanations, such as when the XML or XSL parser fails.

'Can't have more than one ROOT in a DOM !' or 'org.w3c.dom.DOMException: DOM006 Hierarchy request' Errors.

This happens when calling one Descriptor from another. The called Descriptor returns XML with more than one root, and if you try and store this in a variable, or pass it to something expecting a single root, this error returns.

For example, Descriptor A returns:

<price>17.55</price>
<album>Is This It</album>
<artist>The Strokes</artist>

Descriptor B calls Descriptor A and tries to store the result in a variable, but cannot because the XML is not in a tree. Descriptor A needs to return something similar to:

<cd>
<price>17.55</price>
<album>Is This It</album>
<artist>The Strokes</artist>
</cd>

The XML now has one root.

This can also happen when there is some text after a node. For example:

<price>17.55</price>
The Strokes

In this case, there is an invisible text node that needs outer <cd> tags.

If Descriptor B calls Descriptor A and Descriptor C (similar to Descriptor A) and simply copies their results to the output stream, then there are now two root nodes. As stated previously, you need to put a tag around where the two Descriptors are called.

Can I see how other Descriptors work? Can I get their source?

Yes. Download them with a web browser or some other mechanism. The List of Descriptors Available on this Host task from the Descriptor Management page allows you to list Descriptors available on your host or other hosts. The list of Descriptors also includes links to download the Descriptors.

Note - Some web browsers have trouble displaying the Descriptor. If this is the case, right-click on it and choose the option to download the link directly.

Some links to local Descriptors with file URLs, such as file:/home/joe/work/helloworld.xsl, do not work from some web browsers. This is a security feature designed to stop web pages accessing local files. You need to retrieve the file using a local file manager, such as Windows^® Explorer.

How do I store the result of a Mulgara command in a variable?

Use the following example as a guide.

How do I store the returned data from a Descriptor invoked from another Descriptor?

Use the following example as a guide.

<xsl:variable name="answer">

<mulgaraDescriptor:descriptor
_target="otherDescriptor.xsl
_source="{$_self}"
model="{$model}"
myParameter="aParameter"/>
</xsl:variable>

What is the 'Can not convert TREEFRAG into NodeSet' error?

The Tree fragment must be converted into a NodeSet using a XALAN extension. See the next question for more information.

How do I apply the current stylesheets rules to XML returned from a query or another Descriptor?

XSL does not directly allow for this and a XALAN extension must be used. The XML must be converted from a Tree fragment to a proper DOM NodeSet. To apply XML to the stylesheet, use the following example as a guide.

<xsl:variable name="answer">

<mulgaraDescriptor:query model="{$model}" node="{$node}">
<![CDATA[
select $predicate from <@@model@@>
where <@@node@@> $predicate $object;
]]>
</mulgaraDescriptor:query>

</xsl:variable>


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

How can I see the raw XML result from a Mulgara command?

Copy the result to the output stream as follows:

If you are viewing the response in a web browser, the XML tags may not be visible, so wrap them in <xmp> tags to see them. For example:

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

Why are some XSL parameters or variables written like $model and some like {$model}?

When referring to a parameter from an element in the XSL namespace, it is sufficient to refer to it using a dollar sign ($) prefix. For example:

However when referring to parameters from any other namespace they must be surrounded with braces ({}). For example:

<xhtml:a href="{$homepage}">Home Page</xhtml:a>

Even when using no namespace, braces ({}) must be used. For example:

mulgara - semantic store

Descriptors FAQ