15.6. XML Templates
Virtuoso XML templates allow execution of queries over HTTP in order to achieve any combination of the following:
|Execution of SQL queries returned in an XML formatted resultset.|
|Execution of XQuery and XPath queries against XML and SQL-XML documents in the Virtuoso WebDAV repository.|
|Use an XML notation (Updategrams) to insert/update/delete SQL data.|
An XML template is an XML file containing a query, optional parameters with default values for the query, a place to specify an XSL stylesheet, and a section for specifying updatagram based synchronization metrics. They are meant to be executed as an XML described short-cut to an query result, an XML document. The XML document returned from calling an XML template can be served raw, or transformed using XSLT.
XML templates can be executed from within Virtuoso procedure
language using the
xml_template() function, or published as SOAP
compliant XML Web Services, which makes them accessible to any SOAP
and WSDL aware environment.
XML templates provide quick easy access to results from a SQL query as usual, but now this can be saved to a file. The results are not saved, just the query definition. You can use this feature to rapidly produce dynamic reports that can potentially be rendered in different ways by providing an alternate stylesheet. The report can be refined on the fly by providing parameters for the query. The output is reachable via HTTP directly by providing the URL to the template.
When XML templates are executed via HTTP, the XSLT
transformation will be performed automatically if the "sql:xsl"
attribute is specified in the templates root element. This means
that the default XSLT transformation cannot be avoided if the
template is executed over HTTP. However, you have the option
whether to apply the transformation or not when using the
xml_template() function. XML
templates containing <sql:query> elements return either
results or messages regarding the queries. An XSLT transformation
can be made on the result from
xml_template() using the returned XSLT sheet URL.
Hence it is conditional in PL programming. The application
developers can choose to either use the style sheet specified in
the template, use another style sheet, or skip XSLT transformation
entirely. This feature provides full flexibility for the procedure
XML templates are intended for execution over HTTP. The template file can be stored either on the file system, WebDAV repository or stored on another HTTP server being referenced by a URL parameter. Specifying a template as a URL parameter naturally introduces a new potential security risk associated with the template owners web server.
Figure 15.1. Conceptual View of XML Templates
Queries and updategrams can be parameterized. The parameters
must be defined in the header element, which consists of zero or
more param elements. The default value of the parameter is enclosed
within the param element whose values are typically replaced during
the execution phases. When XML templates are executed from the
xml_template() function the
parameters are specified in a vector as an input parameter. When
XML templates are executed via HTTP the parameters are contained in
All <sql:param> parameter definitions in the template for SQL queries need to be named parameters, and the names must be preceded by a colon i.e. :ParamName (note colon at the front)
. The colon is not required for updategrams.
If an error occurs as a result of executing a SQL query or updategram, the comment will be included in the result detailing the error. The subsequent queries and updategrams will still be executed.
The Exposing Persistent Stored Modules as Web Services section as this also describes how XML Templates can be published to web services as a SOAP messages using a PL Wrapper. This is achieved using the Administrative Interface.