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 developer.

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.

Figure15.1.Conceptual View of XML Templates

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 the URL.

[Important] Important

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.

[Tip] See Also:

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.