WebSend (XmlDoc subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (1 revision)
Line 1: Line 1:
{{Template:XmlDoc:WebSend subtitle}}
{{Template:XmlDoc:WebSend subtitle}}


This subroutine converts an XmlDoc to its textually represented XML document
This subroutine converts an <var>XmlDoc</var> to its textually represented XML document
to be sent in a response on a [[Janus Web Server]] thread.
to be sent in a response on a [[Janus Web Server]] thread.
(The process of converting to a text string is called '''serialization''',
(The process of converting to a text string is called '''serialization''',
Line 7: Line 7:
form).
form).


The serialized output of WebSend is a UTF-8 text string.
The serialized output of <var>WebSend</var> is a UTF-8 text string.
This output is added to the output buffer that is sent by a subsequent
This output is added to the output buffer that is sent by a subsequent
invocation of $Web_done or $Web_form_done.
invocation of $Web_done or $Web_form_done.
Line 15: Line 15:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>doc</th>
<tr><th>doc</th>
<td>An expression that points to the XmlDoc whose content is to be serialized. </td></tr>
<td>An expression that points to the <var>XmlDoc</var> whose content is to be serialized. </td></tr>
<tr><th>options</th>
<tr><th>options</th>
<td>Any combination of the following options (but single occurrences only): <ul> <li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b>
<td>Any combination of the following options (but single occurrences only): <ul> <li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b>
Line 38: Line 38:
An Element node that has no children and no Attributes will not be serialized, unless it is the top level Element in the subtree being serialized. The serialization of a child-less and Attribute-less Element is omitted, even if the Element's serialization would contain Namespace declarations in its start tag.
An Element node that has no children and no Attributes will not be serialized, unless it is the top level Element in the subtree being serialized. The serialization of a child-less and Attribute-less Element is omitted, even if the Element's serialization would contain Namespace declarations in its start tag.
If an Element node has no Attributes, but has (only) Element children (one or more), and all of its children are Attribute-less and child-less, then that parent Element is serialized, even though its content in the serialization is empty. That parent is serialized with a start tag and an end tag (and an inserted line separator, if called for by the serializing method's parameter options).
If an Element node has no Attributes, but has (only) Element children (one or more), and all of its children are Attribute-less and child-less, then that parent Element is serialized, even though its content in the serialization is empty. That parent is serialized with a start tag and an end tag (and an inserted line separator, if called for by the serializing method's parameter options).
For example, if the Serial method display of an XmlDoc in tree format is the following when OmitNullElement is ''not'' specified: <pre>    <top>        <middle>          <empty/>          <p:empty2 xmlns:p="uri:stuff"/>        </middle>    </top> </pre>
For example, if the Serial method display of an <var>XmlDoc</var> in tree format is the following when OmitNullElement is ''not'' specified: <pre>    <top>        <middle>          <empty/>          <p:empty2 xmlns:p="uri:stuff"/>        </middle>    </top> </pre>
Here is the display of the XmlDoc with the OmitNullElement option specified: <pre>    <top>        <middle>        </middle>    </top> </pre>
Here is the display of the <var>XmlDoc</var> with the OmitNullElement option specified: <pre>    <top>        <middle>        </middle>    </top> </pre>
The OmitNullElement option is available as of ''Sirius Mods'' version 7.3. <li><b>SortCanonical</b>
The OmitNullElement option is available as of ''Sirius Mods'' version 7.3. <li><b>SortCanonical</b>
This indicates that namespace declarations (based on the prefix being declared) and attributes (based on the namespace URI followed by the local name) are serialized in sorted order. This can be useful, for instance, when using the Serial method to serialize a portion of an XML document for a signature.
This indicates that namespace declarations (based on the prefix being declared) and attributes (based on the namespace URI followed by the local name) are serialized in sorted order. This can be useful, for instance, when using the Serial method to serialize a portion of an XML document for a signature.
The sort order for namespace declarations and attributes is from lowest to highest, and it uses the Unicode code ordering (for example, numbers are lower than letters).
The sort order for namespace declarations and attributes is from lowest to highest, and it uses the <var>Unicode</var> code ordering (for example, numbers are lower than letters).
Added in ''Sirius Mods'' version 6.9 as a step towards support for canonicalization, this option is superseded by the Serial method ExclCanonical option ([[??]] refid=exclcan.), which provides full support for canonicalized serialization. </ul></td></tr>
Added in ''Sirius Mods'' version 6.9 as a step towards support for canonicalization, this option is superseded by the Serial method ExclCanonical option ([[??]] refid=exclcan.), which provides full support for canonicalized serialization. </ul></td></tr>
</p>
</p>
Line 49: Line 49:


<ul>
<ul>
<li>The <i>XmlDoc</i> method object must be well-formed (that is,
<li>The <i><var>XmlDoc</var></i> method object must be well-formed (that is,
it must contain an Element node).
it must contain an Element node).
For more information about well-formed documents, see [[??]] refid=welform..
For more information about well-formed documents, see [[??]] refid=welform..
Line 55: Line 55:
easier to read, for example, for a browser's "view page source" facility
easier to read, for example, for a browser's "view page source" facility
to display XHTML produced with [[Janus SOAP]].
to display XHTML produced with [[Janus SOAP]].
<li>As of version 6.7, the WebSend method uses the hexadecimal
<li>As of version 6.7, the <var>WebSend</var> method uses the hexadecimal
character references specified in the XML Canonicalization specification
character references specified in the XML Canonicalization specification
(:hp0 color=SirLink.http://www.w3.org/TR/xml-c14n:ehp0.)  to
(:hp0 color=SirLink.http://www.w3.org/TR/xml-c14n:ehp0.)  to
Line 101: Line 101:
The following [[Janus Web Server]] program uses
The following [[Janus Web Server]] program uses
WebReceive to obtain the XML document from the HTTP request,
WebReceive to obtain the XML document from the HTTP request,
then uses WebSend to buffer some of the received data:
then uses <var>WebSend</var> to buffer some of the received data:
<p class="code">Begin
<p class="code">Begin
%d Object XmlDoc
%d <var>Object</var> <var>XmlDoc</var>
%d = New
%d = New
%d:WebReceive
%d:WebReceive
%d2 Object XmlDoc
%d2 <var>Object</var> <var>XmlDoc</var>
%d2 = New
%d2 = New
%d2:LoadXml('<sum>' With -
%d2:LoadXml('<sum>' With -
   %d:Value('/*/*[1]') + %d:Value('/*/*[2]') -
   %d:Value('/*/*[1]') + %d:Value('/*/*[2]') -
   With '</sum>')
   With '</sum>')
%d2:WebSend
%d2:<var>WebSend</var>
End
End
</p>
</p>
Line 117: Line 117:
===Request-Cancellation Errors===
===Request-Cancellation Errors===
<ul>
<ul>
<li>XmlDoc does not contain an Element.
<li><var>XmlDoc</var> does not contain an Element.
<li><i>options</i> is invalid.
<li><i>options</i> is invalid.
<li>Insufficient free space exists in CCATEMP.
<li>Insufficient free space exists in CCATEMP.
Line 128: Line 128:
<ul>
<ul>
<li>Use the [[Serial (XmlDoc/XmlNode function)|Serial]] function to
<li>Use the [[Serial (XmlDoc/XmlNode function)|Serial]] function to
serialize an XmlDoc for sending in some other fashion than as a Web response.
serialize an <var>XmlDoc</var> for sending in some other fashion than as a Web response.
<li>Additional serializing methods include:
<li>Additional serializing methods include:
<ul>
<ul>

Revision as of 17:46, 25 January 2011

Serialize XmlDoc as Web response (XmlDoc class)


This subroutine converts an XmlDoc to its textually represented XML document to be sent in a response on a Janus Web Server thread. (The process of converting to a text string is called serialization, because the text representation of a document is called the serial form).

The serialized output of WebSend is a UTF-8 text string. This output is added to the output buffer that is sent by a subsequent invocation of $Web_done or $Web_form_done.

Syntax

doc:WebSend[( [options])]

Syntax terms

doc An expression that points to the XmlDoc whose content is to be serialized.
options Any combination of the following options (but single occurrences only):
  • AllowXmlDecl or NoXmlDecl

    AllowXmlDecl, the default, produces the XML declaration (that is, <?xml&thinsp.version=...?>) if the declaration was set (see Version). NoXmlDecl indicates that the XML declaration is not produced.

  • Indent n Inserts space characters (and line-ends, as described for the next option) into the serialized string such that if the string is broken and displayed as a tree, the display of each lower level in the subtree is indented n spaces from the previous level's starting point. For example, Indent 2 would produce spacing like the following:
         <top>       <leaf1 xx="yy">value</leaf1>       <sub>         <leaf2>value</leaf2>       </sub>     </top> 

    n is a non-negative integer, and its maximum value (as of Sirius Mods version 7.0) is 254.

    Indent may be used with one of the line-end options, above, including Newline. If Indent is specified and no line-end options are also specified, Newline is implied.
  • One of the line-end options below, to provide line breaks in the output after any of the following is serialized:
    • An element start-tag, if it has any non-text node children
    • An empty element tag, or an empty element end-tag
    • A processing instruction (PI)
    • A comment
    • A text node, if it has any siblings

    CR Insert a carriage-return character as the line-end sequence in the above cases.
    LF Insert a linefeed character as the line-end sequence in the above cases.
    CRLF Insert a carriage-return character followed by a linefeed character as the line-end sequence in the above cases.
    Newline Insert the line-end sequence defined for this Janus Web Server connection (by the JANUS DEFINE command or $WEB_SET) as the line-end sequence in the above cases.


  • NoEmptyElt This indicates that an empty element is serialized with its start tag followed by an end tag. For example:
         <middleName></middleName> 
    If this option is not specified, the default is to serialize an empty element with an empty element tag:
         <middleName/> 
  • OmitNullElement

    An Element node that has no children and no Attributes will not be serialized, unless it is the top level Element in the subtree being serialized. The serialization of a child-less and Attribute-less Element is omitted, even if the Element's serialization would contain Namespace declarations in its start tag. If an Element node has no Attributes, but has (only) Element children (one or more), and all of its children are Attribute-less and child-less, then that parent Element is serialized, even though its content in the serialization is empty. That parent is serialized with a start tag and an end tag (and an inserted line separator, if called for by the serializing method's parameter options).

    For example, if the Serial method display of an XmlDoc in tree format is the following when OmitNullElement is not specified:
         <top>        <middle>           <empty/>           <p:empty2 xmlns:p="uri:stuff"/>        </middle>     </top> 
    Here is the display of the XmlDoc with the OmitNullElement option specified:
         <top>        <middle>        </middle>     </top> 
    The OmitNullElement option is available as of Sirius Mods version 7.3.
  • SortCanonical This indicates that namespace declarations (based on the prefix being declared) and attributes (based on the namespace URI followed by the local name) are serialized in sorted order. This can be useful, for instance, when using the Serial method to serialize a portion of an XML document for a signature. The sort order for namespace declarations and attributes is from lowest to highest, and it uses the Unicode code ordering (for example, numbers are lower than letters). Added in Sirius Mods version 6.9 as a step towards support for canonicalization, this option is superseded by the Serial method ExclCanonical option (?? refid=exclcan.), which provides full support for canonicalized serialization.

Usage notes

  • The XmlDoc method object must be well-formed (that is, it must contain an Element node). For more information about well-formed documents, see ?? refid=welform..
  • The output line-breaking options make the serialized stream easier to read, for example, for a browser's "view page source" facility to display XHTML produced with Janus SOAP.
  • As of version 6.7, the WebSend method uses the hexadecimal character references specified in the XML Canonicalization specification (:hp0 color=SirLink.http://www.w3.org/TR/xml-c14n:ehp0.) to display the following characters:
    • For Attribute nodes: tab, carriage return, and linefeed
    • For Text nodes: carriage return

    Since the character references are not subject to the standard XML whitespace normalization (?? refid=normwhi.), a serialized document (or subtree) that is then deserialized will retain this whitespace.

    These character references are used:

    tab
    &#x9;
    CR
    &#xD;
    LF
    &#xA;

    The EBCDIC and corresponding ASCII encodings of the characters is:

    &thinsp.
    EBCDIC ASCII
    tab
    X'05' X'09'
    CR
    X'0D' X'0D'
    LF
    X'25' X'0A'
  • As of Sirius Mods version 7.6, Attribute values are always serialized within double-quotation-mark (") delimiters, and a double-quotation mark character in an attribute value is serialized as &quot;. Prior to version 7.6, this convention was not strictly observed.

Example

The following Janus Web Server program uses WebReceive to obtain the XML document from the HTTP request, then uses WebSend to buffer some of the received data:

Begin %d Object XmlDoc %d = New %d:WebReceive %d2 Object XmlDoc %d2 = New %d2:LoadXml('<sum>' With - %d:Value('/*/*[1]') + %d:Value('/*/*[2]') - With '</sum>') %d2:WebSend End

Request-Cancellation Errors

  • XmlDoc does not contain an Element.
  • options is invalid.
  • Insufficient free space exists in CCATEMP.


See also

  • Use the Serial function to serialize an XmlDoc for sending in some other fashion than as a Web response.
  • Additional serializing methods include:
  • The function that receives and deserializes a Web XML request is ??WebReceive.