<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head profile="http://internetalchemy.org/2003/02/profile">
<link rel="foaf" type="application/rdf+xml" title="FOAF" href="http://www.openlinksw.com/dataspace/uda/about.rdf" />
<link rel="schema.dc" href="http://purl.org/dc/elements/1.1/" />
<meta name="dc.title" content="17. Internet Services" />
<meta name="dc.subject" content="17. Internet Services" />
<meta name="dc.creator" content="OpenLink Software Documentation Team ; " />
<meta name="dc.copyright" content="OpenLink Software, 1999 - 2009" />
<link rel="top" href="index.html" title="OpenLink Virtuoso Universal Server: Documentation" />
<link rel="search" href="/doc/adv_search.vspx" title="Search OpenLink Virtuoso Universal Server: Documentation" />
<link rel="parent" href="internetservices.html" title="Chapter Contents" />
<link rel="prev" href="webdavserver.html" title="WebDAV Server" />
<link rel="next" href="maildelivstore.html" title="Mail Delivery & Storage" />
<link rel="shortcut icon" href="../images/misc/favicon.ico" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="doc.css" />
<link rel="stylesheet" type="text/css" href="/doc/translation.css" />
<title>17. Internet Services</title>
<meta http-equiv="Content-Type" content="text/xhtml; charset=UTF-8" />
<meta name="author" content="OpenLink Software Documentation Team ; " />
<meta name="copyright" content="OpenLink Software, 1999 - 2009" />
<meta name="keywords" content="" />
<meta name="GENERATOR" content="OpenLink XSLT Team" />
</head>
<body>
<div id="header">
<a name="uriqa" />
<img src="../images/misc/logo.jpg" alt="" />
<h1>17. Internet Services</h1>
</div>
<div id="navbartop">
<div>
<a class="link" href="internetservices.html">Chapter Contents</a> | <a class="link" href="webdavserver.html" title="WebDAV Server">Prev</a> | <a class="link" href="maildelivstore.html" title="Mail Delivery & Storage">Next</a>
</div>
</div>
<div id="currenttoc">
<form method="post" action="/doc/adv_search.vspx">
<div class="search">Keyword Search: <br />
<input type="text" name="q" /> <input type="submit" name="go" value="Go" />
</div>
</form>
<div>
<a href="http://www.openlinksw.com/">www.openlinksw.com</a>
</div>
<div>
<a href="http://docs.openlinksw.com/">docs.openlinksw.com</a>
</div>
<br />
<div>
<a href="index.html">Book Home</a>
</div>
<br />
<div>
<a href="contents.html">Contents</a>
</div>
<div>
<a href="preface.html">Preface</a>
</div>
<br />
<div class="selected">
<a href="internetservices.html">Internet Services</a>
</div>
<br />
<div>
<a href="webdavserver.html">WebDAV Server</a>
</div>
<div class="selected">
<a href="uriqa.html">URIQA Semantic Web Enabler</a>
<div>
<a href="#uriqamethods" title="URIQA HTTP Methods">URIQA HTTP Methods</a>
<a href="#uriqaws" title="URIQA Web Service">URIQA Web Service</a>
<a href="#uriqainifile" title="URIQA Section in Virtuoso Configuration File">URIQA Section in Virtuoso Configuration File</a>
<a href="#uriqamatching" title="URI Matching Rules">URI Matching Rules</a>
</div>
</div>
<div>
<a href="maildelivstore.html">Mail Delivery & Storage</a>
</div>
<div>
<a href="nntpnewsgroups.html">NNTP Newsgroups</a>
</div>
<div>
<a href="mime.html">MIME & Internet Messages</a>
</div>
<div>
<a href="ftpservices.html">FTP Services</a>
</div>
<div>
<a href="vspguide.html">VSP Guide</a>
</div>
<div>
<a href="ldap.html">LDAP</a>
</div>
<br />
</div>
<div id="text">
<a name="uriqa" />
<h2>17.2. URIQA Semantic Web Enabler</h2>
<p>
Virtuoso supports the URIQA (URI Query Agent) extension of HTTP WebDAV protocol.
URIQA adds three new methods to HTTP in order to retrieve, add and remove RDF metadata about a given subject.
The subject is identified by its URI. If the subject is a DAV resource then URIQA will usually reuse the DAV URI of the resource.
If the subject is not a resource but something else (physical entity, imaginary thing or vocabulary item) then URIQA can
be used to process metadata about the subject even if the subject itself can not be accessed via HTTP.</p>
<p>
URIQA-specific HTTP methods are called MGET (to retrieve existing metadata), MPUT (to add or update RDF triples) and
MDELETE (to remove some or all triples). A single URIQA request usually deals with a single subject that is specified by request URI.
The MGET response, however, can return metadata about more than one RDF subject, e.g., the request about a book can return both
data about the book itself plus some data about persons who are known as authors of the book.</p>
<p>
In addition to URIQA-specific HTTP methods, Virtuoso implements a semantic web service interface that allows plain HTTP clients to access metadata using
traditional GET or POST HTTP methods.
</p>
<p>
The Virtuoso URIQA implementation allows flexible configuration using an ordered list of request handlers. Every handler has a pattern for URIs;
if the URI in the request does not match the pattern then the handler is ignored, otherwise a callback function of the handler is called to
process the request. The default configuration of Virtuoso server will try three sorts of actions.
</p>
<ul>
<li>If the URI points to a resource located at the server then the first handler returns DAV metadata of the resource.</li>
<li>If the URI points to a resource that is outside the server, and URI is of sort 'http://...' then Virtuoso will send a URIQA web service
request to the remote server specified in URI in hope that it will return at least something, the response is passed to the client unchange.</li>
<li>Any other URI results in an error.</li>
</ul>
<div class="note">
<div class="notetitle">Note:</div>
<p>URIQA is not yet a stable standard. Virtuoso implements draft of URIQA proposal from Nokia, dated 2004.
As URIQA will evolve, future versions of Virtuoso will implement updated versions of the specification.
There is no warranty that future implementations will be compatible with the current one.</p>
</div>
<div class="tip">
<div class="tiptitle">See Also: External References</div>
<p>
<a href="http://sw.nokia.com/uriqa/URIQA.html">The Nokia URI Query Agent Model</a>
</p>
</div>
<a name="uriqamethods" />
<h3>17.2.1. URIQA HTTP Methods</h3>
<p>
All three methods have a set of HTTP header parameters to specify the precise URI of the subject. HTTP does not require that every resource
is accessible via a single valid URI, so many equivalent URLs can point to same resource and the result of typical HTTP request does not change
if one of equivalent URLs is replaces with some other. Unlike HTTP GET, HTTP PUT etc., metadata methods may return different results for
different URLs even if these URLs are equivalent for other methods. URIQA rules are very simple.
</p>
<ul>
<li>If the URIQA request header contains 'URIQA-uri' parameter line then the value of this parameter is used and any other URI data are ignored.</li>
<li>If the URIQA request header contains 'Host' parameter line then the URL from the first line of the request is patched to contain host name specified by 'Host' parameter, no matter whether the
original URL contains host or what host name or network interface or port is user by client to connect to the server.</li>
<li>If the URIQA request header does not contain 'URIQA-uri' or 'Host' line then the URL from the first line of the request is used 'as is',
extended by host name from 'DefaultHost' URIQA configuration parameter if needed.
</li>
</ul>
<a name="uriqamethodsuri" />
<div class="example">
<div class="exampletitle">Examples of MGET Requests</div>
<p>The following requests are all equivalent:</p>
<p>Request 1. 'URIQA-uri' is used, the rest does not matter.</p>
<div>
<pre class="programlisting">
MGET /foo HTTP/1.1
Host: example.com
URIQA-uri: http://example.com/foo
</pre>
</div>
<p>Request 2. 'URIQA-uri' is missing, 'Host' is used, the host name www.example.com is ignored.</p>
<div>
<pre class="programlisting">
MGET http://www.example.com/foo HTTP/1.1
Host: example.com
</pre>
</div>
<p>Request 3. The URI from the first line is used verbatim. This is unsafe, because proxy servers can alter the URI, e.g. by adding port number.</p>
<div>
<pre class="programlisting">
MGET http://example.com/foo HTTP/1.1
</pre>
</div>
<p>Request 4. The URI from the first line is used, but host name is retrieved from 'DefaultHost' URIQA configuration parameter.
If the parameter is set to example.com then the request is equivalent to previous.</p>
<div>
<pre class="programlisting">
MGET /foo HTTP/1.1
</pre>
</div>
</div>
<a name="uriqamget" />
<h4>17.2.1.1. MGET Method</h4>
<p>
MGET request contains a subject URI and the response consists of RDF/XML representation of an RDF graph with metadata about the subject.
In many cases, the returned graph is a Concise Bounded Description of the resource or something similar, but it can be of any sort.
</p>
<p>
There are no integrity rules. E.g., if a response for request about subject A contains some data about B
then the request about B may return same or different data, or even report that B does not exists.
If URI refers to non-existing resource or even to a non-existing server or protocol then the response can be an 'not found' error or
an empty graph or even a non-empty graph, depending on the handler that processed the request.
</p>
<p>
Usually MGET request consists of only subject URI specification, but it can contain any other parameters such as an authentication
or even the HTTP request body with extra data for some particular handler.
For Virtuoso DAV resources, MGET will need read permission on the subject resource, because the resulting RDF is retrieved from
'http://local.virt/DAV-RDF' property of the resource.
</p>
<br />
<a name="uriqamput" />
<h4>17.2.1.2. MPUT Method</h4>
<p>
MPUT request contains an HTTP header that describe a subject URI and contains Content-Length,
and the body must be an RDF/XML that consist of triples that should be added.
The server will try to add new RDF triples from the body to the description of the subject.
In some cases, the server will replace obsolete triples with triples from the body,
e.g., if some RDF Schema is in use that states for a predicate that it can not have more than one value for any given subject.
</p>
<p>
There are no integrity rules. If MPUT request with subject A submits data about resource B then the updated data may become visible
via MGET request with subject A and stay unchanged if retrieved directly by MGET with subject B. For instance, the default request handler for DAV
will update only 'http://local.virt/DAV-RDF' DAV property of the subject resource not touching any DAV properties of resources named in the request.
</p>
<p>
A client application can not use MPUT with subject URI that refers to a non-DAV Virtuoso resource, because disk-resident resources do not have
DAV properties, including DAV metadata properties. MPUT can refer to nonexisting Virtuoso DAV resource only if the name
of this resource has been already locked for uploading of the resource. The most reliable way, however, is to
upload the resource first and update metadata only after the uploading. There are two reasons to do operations in this sequence.
First of all, Virtuoso can automatically extract some metadata from the content of uploaded resource and if MPUT happens after the upload then
MPUT data can properly overwrite automatically extracted values. An additional reason is that resource uploading will set the MIME-type of the resource
and may associate some RDF Schemas with the resource; hence MPUT can properly update some triples instead of storing multiple values for some
predicate that should have only one value according to RDF Schema.
</p>
<p>
For Virtuoso DAV resources, MPUT will need both read and write permissions on the subject resource,
because 'http://local.virt/DAV-RDF' property of the resource is first retrieved and then updated.
</p>
<br />
<a name="uriqamdelete" />
<h4>17.2.1.3. MDELETE Method</h4>
<p>
MDELETE request contains an HTTP header that describe a subject URI and may contain the body. If present then the body must be an RDF/XML that consist of triples that should be deleted.
If the body is totally missing then MDELETE removes all metadata associated with the subject URI.
</p>
<p>
There are no integrity rules. If MDELETE request with subject A removes triples about resource B then these triples may stay visible
if retrieved directly by MGET with subject B. For instance, the default request handler for DAV
will update only 'http://local.virt/DAV-RDF' DAV property of the subject resource not touching any DAV properties of resources named in the request.
</p>
<p>
For Virtuoso DAV resources, MPUT will need both read and write permissions on the subject resource,
because 'http://local.virt/DAV-RDF' property of the resource is first retrieved and then updated.
</p>
<br />
<br />
<a name="uriqaws" />
<h3>17.2.2. URIQA Web Service</h3>
<p>
Virtuoso provides the '/uriqa/' web service for clients that do not support URIQA-specific methods.
Instead of passing URI and method name in HTTP parameter lines, web service calls pass them as
part of web service URI. The beginning of the path can be any, starting from '/uriqa/' or '/URIQA/'.
The following two requests are to retrieve metadata about 'http://example.com/foo'.
</p>
<div>
<pre class="programlisting">
GET /uriqa?uri=http%3a%2f%2fexample%2ecom%2ffoo HTTP/1.1
</pre>
</div>
<div>
<pre class="programlisting">
GET /uriqa?uri=http%3a%2f%2fexample%2ecom%2ffoo&method=MGET HTTP/1.1
</pre>
</div>
The following request header is for MPUT
<div>
<pre class="programlisting">
GET /uriqa?uri=http%3a%2f%2fexample%2ecom%2ffoo&method=MPUT HTTP/1.1
</pre>
</div>
<p>
The URIQA web service does not need complicated rules for URI passing because the request can not be significantly changed by any proxy.
The value of the 'uri' parameter should be an absolute URI.
</p>
<br />
<a name="uriqainifile" />
<h3>17.2.3. URIQA Section in Virtuoso Configuration File</h3>
<p>
By default,the Virtuoso server acts only as URIQA proxy, i.e. it redirects incoming requests to other servers without trying to return metadata about
DAV resources or other data stored on the server itself.
To let URIQA retrieve local metadata, the Virtuoso server should know names that can be used by clients to access it.
Virtuoso configuration file, e.g., virtuoso.ini, can contain these names as parameters in "[URIQA]" section
</p>
<ul>
<li>"DefaultHost" is the "canonical" server name that is used to identify the service.
It should be either server name including domain name, or an IP address in standard notation, if the server does not have any name.
If Virtuoso default HTTP port is not equal to 80 then the port should be mentioned, e.g. "www.example.com:8088".</li>
<li>"LocalHostNames" lists all names that can be used to access the server, such as server names with and without domain name,
IP addresses in Internet and intranets etc. The list is comma-delimited string of names. If an URIQA client can reside on server's box,
e.g. for debugging purposes, then it may be worth to add names "localhost, localhost.localdomain, 127.0.0.1" to this list.
</li>
<li>"LocalHostMasks" is similar to "LocalHostNames" but it lists patterns for names in SQL "like" operator style.
If Virtuoso listens at multiple ports and it is the only URIQA enabled service on the machine then it can be convenient to specify
"LocalHostMasks = www.example.com:%" instead of "LocalHostNames = www.example.com:8088, www.example.com:8089, www.example.com:8090 ...".
</li>
<li>
"Fingerprint" is a string that identifies a group of servers that shares same metadata, such as servers that replicate each other.
It is an error if two servers have the same fingerprint string and one of them tries to redirect a URIQA request to another instead of prepare an
response locally. Such behavior indicates configuration error, and the use of fingerprints help administrator to get a meaningful diagnostics,
because suspicious URIQA requests become signed by all intermediate Virtuoso proxies. If this parameter is not specified then a random unique
string is created and stored in the database, so you don't have to specify this parameter for typical installations.
</li>
<li>
"DynamicLocal" is a flag (1 or 0), when it is on and the host part of the IRI matches the Host header of the HTTP request in context or the DefaultHost if outside of HTTP context, then this is replaced with local: before looking up the IRI ID. Even if DynamicLocal is not on and the <span class="computeroutput">local:</span> prefix occurs in the IRI string being translated to IRI_ID, the translating the IRI_ID back to the IRI name will depend on the context as described as follows: When returning IRI's from id's, this prefix is replaced by the Host header of the HTTP request
and if not running with HTTP, with the DefaultHost from this section.
The effects of DynamicLocal = 1 can be very confusing since many names can refer to the exact same thing. For example, if the DefaultHost is http://dbpedia.org, <span class="computeroutput">iri_to_id ('http://dbpedia.org/resource/Paris') = iri_to_id ('local:///resource/Paris) </span> is true and so is <span class="computeroutput">'http://dbpedia.org/resource/Paris' = id_to_iri (iri_to_id ('local:///resource/Paris'))</span> These hold in a SQL client context, i.e. also when connected through RDF frameworks like Jena or Sesame. When running a SPARQL protocol request, the Host: header influences the behavior, likewise when using web interactive SQL in Conductor.
</li>
</ul>
<p>
These configuration parameters are "sticky". If they're found in configuration file then they are preserved in the database registry.
If configuration file has changed then new values will be used after server restart. If database dump is replayed on a server whose configuration file does
not contain these parameters then values from dump will stay in the registry. If database dump is replayed on a server whose configuration file contains
other values then values from dump will stay in the registry till server restart.
</p>
<br />
<a name="uriqamatching" />
<h3>17.2.4. URI Matching Rules</h3>
<p>
A simple installation does not require any special configuration of URIQA except specifying server names in the [URIQA] section of configuration file (virtuoso.ini).
However complex applications may need from URIQA more than simple retrieval of metadata of DAV resources.
Like HTTP virtual hosts, URIQA may require different processing for different URIs, so Virtuoso offers appropriate tools.
</p>
<p>
When the URIQA server gets an URI to process, it reads the system table WS.WS.URIQA_HANDLER to find out the procedure that can access metadata about some range of URIs.
This table is defined as follows:
</p>
<div>
<pre class="programlisting">
create table WS.WS.URIQA_HANDLER
(
UH_ID integer not null primary key,
UH_ORDER integer not null,
UH_NAME varchar not null unique,
UH_MATCH_COND varchar not null,
UH_MATCH_ENV any,
UH_HANDLER varchar not null,
UH_HANDLER_ENV any
)
create index URIQA_HANDLER_ORDER_NAME on WS.WS.URIQA_HANDLER (UH_ORDER, UH_NAME)
;
</pre>
</div>
<p>
The server scans the table in order of ascending values in UH_ORDER column,
and checks whether the request URI matches the condition specified by UH_MATCH_COND and UH_MATCH_ENV.
As soon as an appropriate row is found, a function with name specified by UH_HANDLER is called with parameters that describe the request plus any
extra application-specific data as stored in UH_HANDLER_ENV. The function should either compose a response and set a flag to 1 or do nothing and set a flag to 0.
If 1 is set then the processing of the request is complete, otherwise the server resumes table scan.
</p>
<p>
At server startup, up to three records are automatically added into WS.WS.URIQA_HANDLER.
</p>
<ul>
<li>First record has UH_ORDER equal to 100.
It tells the server that if an URI has server name equal to one of names listed in "LocalHostNames" configuration parameter
then metadata should be retrieved from local DAV of the server.</li>
<li>
Second record is very similar, it also has UH_ORDER equal to 100, but uses SQL 'like' operator instead of '='.
It tells the server that if an URI has server name like one of masks listed in "LocalHostMasks" configuration parameter
then metadata should be retrieved from local DAV of the server.</li>
<li>
The third record has UH_ORDER equal to 999, and tells the server to act as URIQA proxy if the requested URI starts with "http" protocol name.
</li>
</ul>
<p>
Applications can add more lines to the table to handle different sorts of URIs via different application specific functions. The name of function
should begin with "WS.WS.URIQA_HANDLER_", the rest is as specified by UH_HANDLER of the row. The signature of function should be
</p>
<div>
<pre class="programlisting">
function WS.WS.URIQA_HANDLER_myexample (
inout op varchar, -- operation name, 'MGET', 'MPUT' or 'MDELETE';
inout uri varchar, -- request URI;
inout split any, -- request URI split by WS.WS.PARSE_URI into parts;
inout body any, -- the body of the request;
inout params any, -- get_keyword style vector of parameters of the request;
inout lines any, -- vector of lines of HTTP request header;
inout app_env any, -- any application-specific data from UH_HANDLER_ENV;
inout is_final integer -- status flag. Function sets the flag to 1 to report that the request response is prepared.
) re0turns any -- returns a status vector, see below.
</pre>
</div>
<p>
Status vector describes either the reason why the request has failed, or the success status. It consists of four elements:
</p>
<ul>
<li>SQL_STATE as five-char string, "00000" if success;</li>
<li>DAV error code as an integer, if the operation has failed due to DAV error, 0 if success or an error other than DAV;</li>
<li>HTTP status as three-digit string, such as "200" for "OK" or "404" for "not found";</li>
<li>Brief description of an error, such as HTTP response status ("OK", "not found" etc.) or SQL_MESSAGE, "OK" if success;</li>
</ul>
<p>
In case of DAV error, elements 3 and 4 can be set to NULL to generate proper values automatically.
</p>
<p>
Examples are:
</p>
<div>
<pre class="programlisting">
vector ('00000', 0, '200', 'OK');
vector ('URIQA', 0, '500', 'The remote URIQA server returned an invalid header');
vector ('URIQA', -1, '404', 'Invalid URI; Ill formed or missing path to the resource');
vector ('URIQA', -12, null, null);
</pre>
</div>
<p>
The current version of Virtuoso supports the following names of matching operations for use in UH_MATCH_COND:
</p>
<ul>
<li>"schema =" -- URI schema name should be equal to UH_MATCH_ENV;</li>
<li>"server =" -- URI server name (including port, if specified) should be equal to UH_MATCH_ENV;</li>
<li>"server like" -- URI server name (including port, if specified) should be "like" to UH_MATCH_ENV;</li>
<li>"server in" -- URI server name (including port, if specified) should be member of UH_MATCH_ENV vector of strings;</li>
<li>"server like in" -- URI server name (including port, if specified) should be "like" to one of members of UH_MATCH_ENV vector of strings;</li>
<li>"default" -- Any URI will match so any request is passed to the handler if not handled before.</li>
</ul>
<br />
<table border="0" width="90%" id="navbarbottom">
<tr>
<td align="left" width="33%">
<a href="webdavserver.html" title="WebDAV Server">Previous</a>
<br />WebDAV Server</td>
<td align="center" width="34%">
<a href="internetservices.html">Chapter Contents</a>
</td>
<td align="right" width="33%">
<a href="maildelivstore.html" title="Mail Delivery & Storage">Next</a>
<br />Mail Delivery & Storage</td>
</tr>
</table>
</div>
<div id="footer">
<div>Copyright© 1999 - 2009 OpenLink Software All rights reserved.</div>
<div id="validation">
<a href="http://validator.w3.org/check/referer">
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" />
</a>
<a href="http://jigsaw.w3.org/css-validator/">
<img src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" height="31" width="88" />
</a>
</div>
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
71d40963b505df4524269198e237b3e3
>
files
>
910
