Mulgara | Semantic Store - Hello World Descriptor

Hello World Descriptor

The purpose of this example is to create and deploy a simple Descriptor that returns an HTML page with the text Hello World. The Descriptor does not query a Mulgara database, but the principles outlined in this tutorial also apply to more advanced Descriptor development.

In this example you will to do the following:

Use the Create Descriptor Using Wizard task.
Add logic to output Hello World when the Descriptor is invoked.
Deploy the Descriptor into Mulgara.
Invoke the Descriptor.

Complete the following steps:

Start the Descriptor Wizard.
The Descriptor Management page is available from the /descriptor directory when Mulgara is running.

Use the Create Descriptor Using Wizard task to begin the Descriptor creation process. The Descriptor Wizard page displays.

Note - The wizard only creates a template. You need to edit the template, adding logic to issue iTQL^TM commands or to call other Descriptors.
Enter a Descriptor title.
Enter a title that fully describes what the Descriptor does. Include information about the types of data it works on such as dates, people or VCards. Some example titles include:
- Extracts Titles of Documents as XML using a specified URL
- Returns an HTML table with 2 columns specifying the first and last names of all people mentioned in a Document matching a specified URL.
- Returns an XML document showing all Companies mentioned in documents that also contain a specified Date range.
  For this example enter a title of Example Descriptor Returns 'Hello World' as HTML.
Enter Descriptor parameters.
Parameters are variables required by the Descriptor or affect how the Descriptor operates. For example, if you want a list of all documents in a model, you can specify the model as a parameter, so that your Descriptor works on different models and machines.

This Descriptor does not need parameters, but most do.

Note - There is always one implicit parameter, _self. This parameter must always be the URL of the Descriptor.
Enter the mime type.
The mime type allows the Descriptor servlet, if used, to set the appropriate HTTP headers when returning data. Most importantly, it allows other Descriptors or applications to programmatically search for Descriptors that perform certain tasks. For example, an application could ask a Descriptor to find out everything about a certain person. The person Descriptor may return a VCard that the application does not know how to handle or render, so it searches for a Descriptor that works with VCards and returns HTML.

The mime type is optional but recommended. It should only be set to unknown if the Descriptor itself cannot know what kind of data it will return.

For this example choose text/html.

The Descriptor Wizard page should now look similar to the following:
Generate the Descriptor Template.
Click on the Generate Descriptor Template button.

If any required fields are blank, the Descriptor Wizard page redisplays.
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 helloworld.xsl.
Edit the Descriptor XSL file.
Using your preferred text editor, edit the Descriptor XSL file. Find the following commented section:



Replace this with the following HTML:

<html>
<head>
<title>My First Descriptor</title>
</head>
<body>
Hello World!
</body>
</html>

Save the file. You may want to check that the file is valid XML using a tool such as xmllint.
Deploy the Descriptor in Mulgara.
To use a Descriptor it must be deployed in a Mulgara database. The RDF embedded in the Descriptor XSL file is loaded into a model in a Mulgara database.

Start an iTQL client.

Check if the Descriptor model already exists by querying for a list of models. 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 - Replace mysite.com with the fully qualified hostname (FQHN) of your machine/server.

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

Create the Descriptor model. For example:

create <rmi://mysite.com/server1#descriptors>;

Deploy the Descriptor by loading the Descriptor XSL file into the #descriptor model. For example:

load <file:/helloworld.xsl> into <rmi://mysite.com/server1#descriptors>;

Note - The location of the Descriptor must be accessible by Mulgara. In Windows, the file specification would look something like <file:/C:/work/helloworld.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.
There are several tools available to list, create and invoke Descriptors from the Descriptor Management page. Most of the tools, such as the Descriptor Wizard, are other Descriptors that are run by a Descriptor servlet.

From the Descriptor Management page choose the Lists all Descriptors on this Host task. The Mulgara Descriptor List displays.

Click on the Usage button for your Descriptor to see details about the Descriptor, similar to the window below.

Since there are no parameters (other than the implicit _self parameter and the usage parameter that returns the RDF of the XSL file), click on the Invoke button to invoke the Descriptor.

The result displays in a window similar to the following.

You have now successfully developed, deployed and invoked a Mulgara Descriptor.

Where To From Here?

The real power of Descriptors is when you query Mulgara databases or call other Descriptor from within your Descriptor. Descriptors are fast, distributable and cross platform. They are capable of creating simple web applications, such as the Descriptor Wizard.

Look at some of the bundled Descriptors for examples of sophisticated usage (you can click on the link to the source from the Descriptor List task from the Descriptor Management page).

See the List Models example for information on how to issue iTQL commands from within a Descriptor.

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

mulgara - semantic store

Hello World Descriptor

Where To From Here?