Specify serialization of query output.
A SerializationSpec
is a query pragma that has the form of a
QPI (query processing instruction), i.e., it is enclosed by
"{?" and "?}". It
specifies how Tamino returns the output of a query by applying a serialization
method. One common effect is that Tamino does not wrap the output with the
standard response wrapper using the document element
ino:response
.
The following methods for serializing the query output are available:
QuotedQName
Specify an output handler that performs serialization in place of the standard XQuery processor. It must have been registered as a server extension and can take zero or more parameters separated by whitespace. Since the name of the output handler is the value of
method
, it cannot be "text" or "xml" (names are case-sensitive).text
The query output is treated as text. If it is not followed by a media type then "text/xml" is assumed and set as the Content-Type value in the HTTP response header.
xml
The query output is treated as XML. If it is not followed by a media type then "text/xml" is assumed and set as the Content-Type value in the HTTP response header. Although the query output is expected to be XML there are two exceptions that may violate the rules of an XML document:
No XML Declaration
You can use the additional optionomit-xml-declaration="yes"
to omit the XML declaration. Note that no value other than "yes" is allowed, but you may use single quote characters instead of double quote characters. This is for example useful when embedding the query result as a tree fragment into other XML documents.Multiple Document Nodes
The XML specification requires a single document element, but you may output more than one document element. Normally this is prevented by the Tamino response wrapper.ino:document
retrieve non-XML documents
Report patient records in a way that is determined by an XSL stylesheet:
{?serialization method="XSLT.transform" parameter="stylesheets" parameter="stylesheets/patientRecords.xsl"?} <report> { for $a in collection('Hospital')/patient return <patient>{ $a/name, $a/sex, $a/born, $a/address }</patient> } </report>
Consider the following query:
let $a := <A attr='"'><</A> let $b := <B/> return ($a,$b)
Tamino returns the following document: (It is indented for better readability; please note that the encoding value may differ depending on your browser settings):
<?xml version="1.0" encoding="ISO-8859-1" ?> <ino:response xmlns:ino="http://namespaces.softwareag.com/tamino/response2" xmlns:xql="http://metalab.unc.edu/xql/"> <xq:query xmlns:xq="http://namespaces.softwareag.com/tamino/XQuery/result"> <![CDATA[let $a := <A attr='"'><</A> let $b := <B/> return ($a,$b)]]></xq:query> <ino:message ino:returnvalue="0"> <ino:messageline>XQuery Request processing</ino:messageline> </ino:message> <xq:result xmlns:xq="http://namespaces.softwareag.com/tamino/XQuery/result"> <A attr="""><</A> <B/> </xq:result> <ino:message ino:returnvalue="0"> <ino:messageline>XQuery Request processed</ino:messageline> </ino:message> </ino:response>
As an effect of the Tamino response wrapper the resulting nodes
<A>
and <B>
are child element nodes of
xq:result
. Also, named entity references are used
for the five character references predefined in XML. Now we repeat the query
and specify serialization methods. First, we use
"xml":
{?serialization method="xml"?} let $a := <A attr='"'><</A> let $b := <B/> return ($a,$b)
The result is an XML document that is no longer well-formed, since it contains two document elements.
<?xml version="1.0" encoding="ISO-8859-1" ?> <A attr="""><</A><B></B>
Using the serialization method "text" yields a different output: The XML declaration is not used and the XML entity references are resolved now:
<
Retrieve basic book information in tabular form:
{?serialization method="text" media-type="text/plain"?} declare namespace tf = "http://namespaces.softwareag.com/tamino/TaminoFunction" declare namespace xs = "http://www.w3.org/2001/XMLSchema" for $book in input()/bib/book let $year := <year>{ tf:createTextNode(xs:string($book/@year)) }</year> let $authors := for $i in $book/author return ( $i/last/text(), ", ", $i/first/text(), "	") return ( "Published: ", $year/text(), "
", "Author(s): ", $authors, "
", "Title : ", $book/title/text(), "

" )
This query is in some respect similar to the one used to exemplify EnclosedExpr, but delivers a pure text instead of an XML document. Here, multiple author names are separated by a horizontal tab character (U+0009):
Published: 1994 Author(s): Stevens, W. Title : TCP/IP Illustrated Published: 1992 Author(s): Stevens, W. Title : Advanced Programming in the Unix environment Published: 2000 Author(s): Abiteboul, Serge Buneman, Peter Suciu, Dan Title : Data on the Web Published: 1999 Author(s): Title : The Economics of Technology and Content for Digital TV
The difficult part is extracting the year
attribute. A
straightforward version of this query would be to directly return the
attribute:
{?serialization method="text" media-type="text/plain"?} for $book in input()/bib/book let $authors := for $i in $book/author return ( $i/last/text(), ", ", $i/first/text(), "	") return ( "Published: ", $book/@year, "
", "Author(s): ", $authors, "
", "Title : ", $book/title/text(), "

" )
But this yields an error, since an attribute can not be serialized
without an element context and here a sequence is returned. Therefore, the
variable $year
is used: it contains an element
year
whose content is the attribute value as a
string. The text node of the year
element is then
used in the return
clause.
The following construct(s) refer to this construct:
This construct is also related to the following construct(s):
Prolog
|