AddXml (HttpRequest subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 93: Line 93:
These character references are used:
These character references are used:
<table>
<table>
<tr><th>tab</th><td>&amp;amp;amp;amp;amp;#x9;
<tr><th>tab</th><td>&amp;#x9;
</td></tr>
</td></tr>
<tr><th>CR</th><td>&amp;amp;amp;amp;amp;#xD;
<tr><th>CR</th><td>&amp;#xD;
</td></tr>
</td></tr>
<tr><th>LF</th><td>&amp;amp;amp;amp;amp;#xA;
<tr><th>LF</th><td>&amp;#xA;
</td></tr></table>
</td></tr></table>


The EBCDIC and corresponding ASCII encodings of the characters is:
The EBCDIC and corresponding ASCII encodings of the characters is:
<table>
<table>
<tr><th>&amp;amp;amp;amp;nbsp;</th>
<tr><th>&nbsp;</th>
<th>EBCDIC</th>
<th>EBCDIC</th>
<th>ASCII</th></tr>
<th>ASCII</th></tr>
Line 145: Line 145:
</ul>
</ul>


==Usage notes==
<ul>
<li>The <var>XmlDoc</var> that is passed is serialized into the post data of the request
being built.
It is not required that you serialize the <var>XmlDoc</var> first.
<li>Invoking this method erases any post data previously
added by <var>AddXML</var> or <var>[[AddLongString (HTTPRequest subroutine)|AddLongString]]</var> method calls.
<li>As of <var class="product">Sirius Mods</var> version 6.6, if you do not explicitly set a
content-type HTTP request header via <var>[[AddHeader (HTTPRequest subroutine)|AddHeader]]</var>,
AddXml generates a content-type header of "text/xml" upon a Post.
To suppress this automatic header generation, you can set the
<var>[[AutoSendXMLContentType (HTTPRequest property)|AutoSendXMLContentType]]</var> property
to False.
<li>The <i>xmloptions</i> may be specified in any case, for example, you can use
either <code>NoXmlDecl</code> or <code>noxmldecl</code>, interchangeably.
<li>If one of the line-end
(<code>CR</code>, <code>LF</code>, <code>CRLF</code>) options or if
<code>Indent</code> is specified, and an element to be serialized has the
<code>xml:space="preserve"</code> attribute, then
within the serialization of that element and its descendants, no line-end
(nor indentation) characters are inserted to provide readability.


In addition, the <code>xml:space="default"</code> attribute has no effect
under these options:
specified by itself, it does not influence serialization, nor
does it cause resumption of readability line-ends or indents if they were
suspended by a containing <code>xml:space="preserve"</code>.
<li>As of version 6.7, the AddXml method uses the
character references specified in the XML Canonicalization specification
(http://www.w3.org/TR/xml-c14n) to
display the following characters:
<ul>
<li>For Attribute nodes: tab, carriage return, and linefeed
<li>For Text nodes: carriage return
</ul>
Since the character references are not subject to the standard XML whitespace
normalization (so not removed),
a serialized document (or subtree) that is then deserialized
will retain this whitespace.
These character references are used:
<table>
<tr><th>tab
</th><td>&amp;amp;amp;amp;amp;amp;#x9;
</td></tr>
<tr><th>CR
</th><td>&amp;amp;amp;amp;amp;amp;#xD;
</td></tr>
<tr><th>LF
</th><td>&amp;amp;amp;amp;amp;amp;#xA;
</td></tr></table>
The EBCDIC and corresponding ASCII encodings of the characters is:
<table>
<tr><th>&amp;amp;amp;amp;amp;nbsp;</th>
<th>EBCDIC</th>
<th>ASCII</th></tr>
<tr><th>tab</th>
<td>X'05'</td> <td>X'09'</td></tr> <tr><th>CR</th> <td>X'0D'</td> <td>X'0D'</td></tr> <tr><th>LF</th> <td>X'25'</td> <td>X'0A'</td></tr></table>
For more information about XML document whitespace handling, see [[XML processing in Janus SOAP#Normalizing whitespace characters|"Normalizing whitespace characters"]].
<li>The following example shows the effect of the <var>SortCanonical</var> option:<p class="code"> Begin 
%d is object Xmldoc 
%d = new 
%htr is object HttpRequest 
%htr = new 
%sl is object <var>Stringlist</var> 
%sl = new 
Text To %sl 
<top p:abc="p" q:xyz="q"   
  xmlns:p="urn:p" xmlns:q="http://q.com" 
  xmlns="urn:default"   
  name="t" id="z15" 
/> 
End Text 
%d:LoadXml(%sl) 
%htr:AddXml(%d, 'SortCanonical NoEmptyElt') 
Print %d:Serial(, 'EBCDIC SortCanonical NoEmptyElt') 
End </p>
The <var>Print</var> statement above (which uses the <var>[[Serial (XmlDoc/XmlNode function)]]</var> method of the <var class="product>[[Janus SOAP]]</var> [[XmlDoc API]]) displays the resulting <var>XmlDoc</var> content added to the <var>HTTPRequest</var> object (formatted with some newlines for the sake of instruction): <p class="code"><top
  xmlns="urn:default"   
  xmlns:p="urn:p" xmlns:q="http://q.com"   
  id="z15" name="t"   
  q:xyz="q" p:abc="p"  > 
</top> </p>
Comments:
<ul>
<li>The reason for the name (<var>SortCanonical</var>) is that this ordering is part of the specification of the <i><b>Canonical XML Recommendation</b></i> (http://www.w3.org/TR/xml&amp;amp;amp;amp;amp;hyph.c14n) and the <i><b>Exclusive Canonical XML Recommendation</b></i> (http://www.w3.org/TR/xml&amp;amp;amp;amp;amp;hyph.exc&amp;amp;amp;amp;amp;hyph.c14n), which constrain serializations to facilitate processing such as digital signatures.
<li>Notice the use of the <var>NoEmptyElt</var> option above. This produces an STag (<code><top ...></code>) and an ETag (<code></top></code>) for an empty element, rather than just the EmptyElemTag (<code><top ...></code>).
The canonical XML recommendations state that an STag/ETag pair, rather than an EmptyElemTag, is the serialization for an empty element.
<li>Although <var>SortCanonical</var> uses the Unicode sort sequence, this is limited to Unicode values less than 256 (as of version 6.9 of <var class="product">Janus SOAP</var>, so it is accomplished with an 8-byte EBCDIC to 8-byte Unicode table, which is (for all intents and purposes) merely an EBCDIC-to-ASCII translation. </ul>
</ul>
==See also==
==See also==
{{Template:HTTPRequest:AddXML footer}}
{{Template:HTTPRequest:AddXML footer}}

Revision as of 23:17, 15 June 2011

Template:HTTPRequest:AddXML subtitle

This subroutine adds a Janus SOAP XmlDoc object instance to the HTTP Post data that is subsequently sent on a Post method invocation.

Syntax

Template:HTTPRequest:AddXML syntax

Syntax terms

%httpreq A previously defined and instantiated HTTPRequest object.
%xmldoc An XmlDoc object that contains an instantiated XmlDoc object.
xmloptions Any combination of the following options (but single occurrences only):
  • AllowXmlDecl or NoXmlDecl AllowXmlDecl, the default, produces the XML declaration (that is, <?xml&amp;amp;amp;amp;thinsp.version=...?>) if the declaration was already defined in %xmldoc. NoXmlDecl omits the XML declaration.
  • Indent n The display of each lower level in the serialized subtree is indented n spaces from the previous level's starting point, where n is a non-negative integer. This option may be used with one of the line-end options, below, including Newline. If Indent is specified and no line-end options are also specified, Newline is implied. Indent 2 (with a line-end option) would produce:

    <top> <leaf1 xx="yy">value</leaf1> <leaf2>value</leaf2> </top>

  • One of the line-end options below, to provide line breaks in the output after any of the following in %xmldoc 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 line-feed character as the line-end sequence in the above cases.
    CRLF
    Insert a carriage-return character followed by a line-feed character as the line-end sequence in the above cases.
    Newline
    Insert the line-end sequence defined for this HTTP Request object, if any, as the line-end sequence in the above cases.
  • NoEmptyElt This indicates that an empty element in %xmldoc 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 Attibute-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 a tree display of %xmldoc is the following when OmitNullElement is not specified:

    <top> <middle> <empty/> <p:empty2 xmlns:p="uri:stuff"/> </middle> </top>

    This is the display of %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, 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). This option was added in Sirius Mods version 6.9 as a step towards support for canonicalization. As of version 7.0, comprehensive support for canonicalized serialization is provided (only) by the Serial method ExclCanonical option, described in the Janus SOAP Reference Manual. SortCanonical is described in greater detail at the end of "Usage notes,&amp;amp;amp;amp;rdquo; below.

Usage notes

  • The XmlDoc that is passed is serialized into the post data of the request being built. It is not required that you serialize the XmlDoc first.
  • Invoking this method erases any post data previously added by AddXML or AddLongString method calls.
  • As of Sirius Mods version 6.6, if you do not explicitly set a content-type HTTP request header via AddHeader, AddXml generates a content-type header of &amp;amp;amp;ldquo;text/xml" upon a Post. To suppress this automatic header generation, you can set the AutoSendXMLContentType property to False.
  • The xmloptions may be specified in any case, for example, you can use either NoXmlDecl or noxmldecl, interchangeably.
  • If one of the line-end (CR, LF, CRLF) options or if Indent is specified, and an element to be serialized has the xml:space="preserve" attribute, then within the serialization of that element and its descendants, no line-end (nor indentation) characters are inserted to provide readability. In addition, the xml:space="default" attribute has no effect under these options: specified by itself, it does not influence serialization, nor does it cause resumption of readability line-ends or indents if they were suspended by a containing xml:space="preserve".
  • As of version 6.7, the AddXml method uses the character references specified in the XML Canonicalization specification (http://www.w3.org/TR/xml-c14n) 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 (so not removed), 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:

      EBCDIC ASCII
    tab X'05' X'09'
    CR X'0D' X'0D'
    LF X'25' X'0A'

    For more information about XML document whitespace handling, see "Normalizing whitespace characters".

  • The following example shows the effect of the SortCanonical option:

    Begin %d is object Xmldoc %d = new %htr is object HttpRequest %htr = new %sl is object Stringlist %sl = new Text To %sl <top p:abc="p" q:xyz="q" xmlns:p="urn:p" xmlns:q="http://q.com" xmlns="urn:default" name="t" id="z15" /> End Text %d:LoadXml(%sl) %htr:AddXml(%d, 'SortCanonical NoEmptyElt') Print %d:Serial(, 'EBCDIC SortCanonical NoEmptyElt') End

    The Print statement above (which uses the Serial (XmlDoc/XmlNode function) method of the Janus SOAP XmlDoc API) displays the resulting XmlDoc content added to the HTTPRequest object (formatted with some newlines for the sake of instruction):

    <top xmlns="urn:default" xmlns:p="urn:p" xmlns:q="http://q.com" id="z15" name="t" q:xyz="q" p:abc="p" > </top>

    Comments:

    • The reason for the name (SortCanonical) is that this ordering is part of the specification of the Canonical XML Recommendation (http://www.w3.org/TR/xml&amp;amp;amp;hyph.c14n) and the Exclusive Canonical XML Recommendation (http://www.w3.org/TR/xml&amp;amp;amp;hyph.exc&amp;amp;amp;hyph.c14n), which constrain serializations to facilitate processing such as digital signatures.
    • Notice the use of the NoEmptyElt option above. This produces an STag (<top ...>) and an ETag (</top>) for an empty element, rather than just the EmptyElemTag (<top ...>). The canonical XML recommendations state that an STag/ETag pair, rather than an EmptyElemTag, is the serialization for an empty element.
    • Although SortCanonical uses the Unicode sort sequence, this is limited to Unicode values less than 256 (as of version 6.9 of Janus SOAP, so it is accomplished with an 8-byte EBCDIC to 8-byte Unicode table, which is (for all intents and purposes) merely an EBCDIC-to-ASCII translation.


See also

Template:HTTPRequest:AddXML footer