SerializationSpec

Specify serialization of query output.


Syntax

SerializationSpec

graphics/SerializationSpec.png

QuotedQName StringLiteral StringLiteral StringLiteral

Description

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 option omit-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

Examples

  • 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='"'>&lt;</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='"'>&lt;</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="&quot;">&lt;</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='"'>&lt;</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="&quot;">&lt;</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(), "&#x09;")
    return
    ( "Published: ", $year/text(), "&#x0A;",
      "Author(s): ", $authors, "&#x0A;",
      "Title    : ", $book/title/text(), "&#x0A;&#x0A;" )

    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(), "&#x09;")
    return
    ( "Published: ", $book/@year, "&#x0A;",
      "Author(s): ", $authors, "&#x0A;",
      "Title    : ", $book/title/text(), "&#x0A;&#x0A;" )

    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.

Related Syntax Construct

The following construct(s) refer to this construct:

This construct is also related to the following construct(s):

Prolog