AddXml (HttpRequest subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
 
(40 intermediate revisions by 7 users not shown)
Line 1: Line 1:
<span class="pageSubtitle"><section begin=dpl_desc/>Add XmlDoc object to HTTP Post data<section end=dpl_desc/></span>
{{Template:HttpRequest:AddXml subtitle}}
[[Category:HTTPRequest methods|AddXML subroutine]]
The <var>AddXml</var> subroutine adds a <var class="product">[[Janus SOAP]]</var> <var>[[XmlDoc_API#The_XmlDoc_class|XmlDoc]]</var> object instance to the HTTP Post data that is subsequently sent on a <var>[[Post (HttpRequest function)|Post]]</var> method invocation.
 
This subroutine adds a [[Janus SOAP]]
XmlDoc object instance to the HTTP Post data that is subsequently
sent on a <var>[[Post (HTTPRequest function)|Post]]</var> method invocation.


==Syntax==
==Syntax==
<p class="syntax">
{{Template:HttpRequest:AddXml syntax}}
%httpreq:AddXML(%xmldoc, [xmloptions])
</p>
 
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%httpreq</th>
<tr><th>httpRequest</th>
<td>A previously defined and instantiated HTTPRequest object.
<td>A previously defined and instantiated <var>HttpRequest</var> object.
</td></tr>
</td></tr>
<tr><th>%xmldoc</th>
 
<td>An XmlDoc object that contains an instantiated XmlDoc object.
<tr><th>doc</th>
<td>A previously defined and instantiated <var>XmlDoc</var> object.
</td></tr>
</td></tr>
<tr><th>xmloptions</th>
 
<td>Any combination of the following options (but single occurrences only):  
<tr><th>options</th>
<td>Any combination of the following options (but single occurrences only).
<p class="note">'''Note:''' These options are described in greater detail in [[XmlDoc API serialization options|"XmlDoc API serialization options"]]. </p>
<ul>  
<ul>  
<li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b>
<li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b><br>
AllowXmlDecl, the default, produces the XML declaration (that is, <?xml&thinsp.version=...?>) if the declaration was already defined in ''%xmldoc''. NoXmlDecl omits the XML declaration.  
AllowXmlDecl, the default, produces the "XML Declaration" (that is, <code><?xml version=...?></code>) if the value of the <var>[[Version (XmlDoc property)|Version]]</var> property in <var class="term">doc</var> is a non-null string. <var>NoXmlDecl</var> omits the XML declaration.</li>
<li><b>Indent</b> <i><b>n</b></i>
 
The display of each lower level in the serialized subtree is indented ''n'' spaces from the previous level's starting point, where <i>n</i> is a non-negative integer.
<li><b>Indent</b> <i><b>n</b></i><br>
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.
Inserts space characters and line-ends into the serialized string such that if the string is broken at the line-ends 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. You may also specify <var>CR</var>, <var>LF</var>, <var>CRLF</var>, or <var>Newline</var> (see below). If <var>Indent</var> is specified and no line-end options are also specified, <var>Newline</var> is implied. </li>
Indent 2 (with a line-end option) would produce: <p class="code"> <top>    <leaf1 xx="yy">value</leaf1>   <sub>      <leaf2>value</leaf2>    </sub>  </top> </p> <li>One of the '''line-end options''' below, to provide line breaks in the output after any of the following in ''%xmldoc'' is serialized:


<ul> <li>An element start-tag, if it has any non-text node children
<li><b>CR</b> (carriage-return), <b>LF</b> (linefeed), <b>CRLF</b> (carriage-return followed by a linefeed), or <b>Newline</b> (line-end set for the <var class="product">Janus Web</var> connection)<p>
<li>An empty element tag, or an empty element end-tag <li>A processing instruction (PI)  
Inserts one of these line-end options to provide line breaks in the serialized output. </p></li>
<li>A comment <li>A text node, if it has any siblings </ul>  


<dl>  
<li><b>NoEmptyElt</b><br>
<dt>CR <dd>Insert a carriage-return character as the line-end sequence in the above cases.
This deprecated option serializes all empty elements with a start tag followed by an end tag.  The default is to serialize an empty element with an empty element tag (as in <code><middleName/></code>).
<dt>LF <dd>Insert a line-feed character as the line-end sequence in the above cases.  
<p>
<dt>CRLF <dd>Insert a carriage-return character followed by a line-feed character as the line-end sequence in the above cases. <dt>Newline <dd>Insert the <var>[[LineEnd (HTTPRequest property)|line-end]]</var> sequence defined for this HTTP Request object, if any, as the line-end sequence in the above cases. </dl>  
<var>NoEmptyElt</var> is deprecated in order to deter users from using it to serialize HTML: The recommended approach for HTML is shown on the <var>[[NoEmptyElement (XmlNode property)#browserExample|NoEmptyElement]]</var> property page &mdash; some tags (<code>&#x3c;div></code>) <b>require</b> separate start and end tags, while other tags (<code>&#x3c;br></code>) <b>do not allow</b> separate start and end tags. </p></li>


<li><b>NoEmptyElt</b>
<li><b>OmitNullElement</b><br>
This indicates that an empty element in ''%xmldoc'' is serialized with its start tag followed by an end tag. For example: <p class="code"> <middleName></middleName> </p> If this option is not specified, the default is to serialize an empty element with an empty element tag: <p class="code"> <middleName/> </p> <li><b>OmitNullElement</b>
An <var>Element</var> node that has no children and no <var>Attributes</var> will not be serialized, unless it is the top level <var>Element</var> in the subtree being serialized.</li>
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:
<p class="code"> <top>    <middle>        <empty/>       <p:empty2 xmlns:p="uri:stuff"/>    </middle>  </top> </p>
This is the display of ''%xmldoc'' with the OmitNullElement option specified:
<p class="code"> <top>    <middle>    </middle>  </top> </p>
The OmitNullElement option is available as of <var class="product">Sirius Mods</var> version 7.3.


<li><b>SortCanonical</b>
<li><b>SortCanonical</b><br>
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.
This deprecated option, serializes namespace declarations and attributes in sorted order (from lowest to highest with Unicode code ordering). It is superseded by the <var>[[Serial (XmlDoc/XmlNode function)|Serial]]</var> method <var>ExclCanonical</var> option.</li>
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).
</ul>
This option was added in <var class="product">Sirius Mods</var> 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 &ldquo;Usage notes,&rdquo; below. </ul>
</td></tr></table>
</td></tr></table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>The <var>XmlDoc</var> that is passed is serialized into the post data of the request
<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.
being built.
<li>Invoking this method erases any post data previously added by <var>AddXml</var> or <var>[[AddLongstring (HttpRequest subroutine)|AddLongstring]]</var> method calls.
It is not required that you serialize the <var>XmlDoc</var> first.
<li>If you do not explicitly set a content-type HTTP request header via <var>[[AddHeader (HttpRequest subroutine)|AddHeader]]</var>, <var>AddXml</var> 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 <code>False</code>.
<li>Invoking this method erases any post data previously
<li>The <var class="term">options</var> may be specified in any case, for example, you can use
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 &ldquo;text/xml&rdquo; 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.
either <code>NoXmlDecl</code> or <code>noxmldecl</code>, interchangeably.
<li>If one of the line-end
<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
(<code>CR</code>, <code>LF</code>, <code>CRLF</code>) options or if
within the serialization of that element and its descendants, no line-end (nor indentation) characters are inserted to provide readability.
<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
Additionally, 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>.
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>
</ul>
<div id="sortcan"></div>


Since the character references are not subject to the standard XML whitespace
==Examples==
normalization (so not removed),
The following example shows the effect of the <var>NoEmptyElt</var> option:
a serialized document (or subtree) that is then deserialized
<p class="code">begin 
will retain this whitespace.
  %d is object [[XmlDoc_API#The_XmlDoc_class|xmlDoc]]
  %d = [[New_(XmlDoc_constructor)|new]]
  %htr is object httpRequest 
  %htr = [[New_(HttpRequest_constructor)|new]]
  %sl is object [[Stringlist_class|stringlist]]
  %sl = [[New_(Stringlist_constructor)|new]]
  [[Text_and_Html_statements#toOption|text to]] %sl 
  <top p:abc="p" q:xyz="q"   
      xmlns:p="urn:p" xmlns:q=<nowiki>"http://q.com"</nowiki>
      name="t" id="z15" 
  /> 
  end text 
  %d:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]](%sl)
  %htr:addXml(%d, 'NoEmptyElt') 
  print %d:[[Serial (XmlDoc/XmlNode function)|Serial]](, 'EBCDIC NoEmptyElt') 
end
</p>
The <var>print</var> statement above (which uses the <var class="product">[[Janus SOAP]]</var> [[XmlDoc API]] <var>Serial</var> method) 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:p="urn:p" xmlns:q=<nowiki>"http://q.com"</nowiki>   
  p:abc="p" q:xyz="q"
  name="t" id="z15"> 
</top>
</p>
Comments:
<ul><li>
<var>NoEmptyElt</var> produces an STag (<code><top ...></code>) and an ETag (<code></top></code>) for an empty element, rather than just the EmptyElemTag (<code><top ...></code>).
</ul>


These character references are used:
==See also==
<table>
<ul>
<tr><th>tab
<li>For additional discussion about serialization, see [[XmlDoc API#Transport: receiving and sending XML|Transport: receiving and sending XML]].</li>
</th><td>&amp;#x9;
</td></tr>
<tr><th>CR
</th><td>&amp;#xD;
</td></tr>
<tr><th>LF
</th><td>&amp;#xA;
</td></tr></table>


The EBCDIC and corresponding ASCII encodings of the characters is:
<li>Additional non-<var>HttpRequest</var> serializing methods include:
<table>
<ul>
<tr><th>&nbsp;</th>
<li><var>[[Print (XmlDoc/XmlNode subroutine)|Print]]</var>
<th>EBCDIC</th>
<li><var>[[Serial (XmlDoc/XmlNode function)|Serial]]</var>  
<th>ASCII</th></tr>
<li><var>[[WebSend (XmlDoc subroutine)|WebSend]]</var>  
<tr><th>tab</th>
</ul> </li>
<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>
</ul>
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 
{{Template:HttpRequest:AddXml footer}}
%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 </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&hyph.c14n) and the <i><b>Exclusive Canonical XML Recommendation</b></i> (http://www.w3.org/TR/xml&hyph.exc&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>

Latest revision as of 21:04, 18 March 2014

Add an XmlDoc to POST data for this request (HttpRequest class)

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

Syntax

httpRequest:AddXml( doc, [options])

Syntax terms

httpRequest A previously defined and instantiated HttpRequest object.
doc A previously defined and instantiated XmlDoc object.
options Any combination of the following options (but single occurrences only).

Note: These options are described in greater detail in "XmlDoc API serialization options".

  • AllowXmlDecl or NoXmlDecl
    AllowXmlDecl, the default, produces the "XML Declaration" (that is, <?xml version=...?>) if the value of the Version property in doc is a non-null string. NoXmlDecl omits the XML declaration.
  • Indent n
    Inserts space characters and line-ends into the serialized string such that if the string is broken at the line-ends 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. You may also specify CR, LF, CRLF, or Newline (see below). If Indent is specified and no line-end options are also specified, Newline is implied.
  • CR (carriage-return), LF (linefeed), CRLF (carriage-return followed by a linefeed), or Newline (line-end set for the Janus Web connection)

    Inserts one of these line-end options to provide line breaks in the serialized output.

  • NoEmptyElt
    This deprecated option serializes all empty elements with a start tag followed by an end tag. The default is to serialize an empty element with an empty element tag (as in <middleName/>).

    NoEmptyElt is deprecated in order to deter users from using it to serialize HTML: The recommended approach for HTML is shown on the NoEmptyElement property page — some tags (<div>) require separate start and end tags, while other tags (<br>) do not allow separate start and end tags.

  • 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.
  • SortCanonical
    This deprecated option, serializes namespace declarations and attributes in sorted order (from lowest to highest with Unicode code ordering). It is superseded by the Serial method ExclCanonical option.

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.
  • If you do not explicitly set a content-type HTTP request header via AddHeader, AddXml generates a content-type header of "text/xml" upon a Post. To suppress this automatic header generation, you can set the AutoSendXmlContentType property to False.
  • The options 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. Additionally, 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".

Examples

The following example shows the effect of the NoEmptyElt 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" name="t" id="z15" /> end text %d:loadXml(%sl) %htr:addXml(%d, 'NoEmptyElt') print %d:Serial(, 'EBCDIC NoEmptyElt') end

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

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

Comments:

  • NoEmptyElt produces an STag (<top ...>) and an ETag (</top>) for an empty element, rather than just the EmptyElemTag (<top ...>).

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=AddXml_(HttpRequest_subroutine)&oldid=68073"