AddNamespace (XmlNode subroutine)

From m204wiki
Revision as of 00:44, 21 May 2011 by Goff (talk | contribs) (better looking link name)
Jump to navigation Jump to search

Add namespace declaration to Element node (XmlNode class)

[Requires Janus SOAP]

This subroutine adds a namespace declaration to an Element node.

Syntax

nod:AddNamespace( prefix, uri)

Syntax terms

nod An XmlNode that points to the Element node where the namespace declaration is added.
prefix The prefix that is being declared. It must conform to the XML syntax rules for a namespace prefix; the maximum length of the prefix is 127 characters (100 characters prior to Version 7.7 of "Janus Soap").
uri An absolute Uniform Resource Identifier, identifying the namespace the prefix is declared within.

Usage notes

  • If a URI argument is specified, the XmlDoc's Namespace property must be On.
  • As of Sirius Mods Version 7.3, the AddNamespace method arguments may include only non-null EBCDIC characters that translate to Unicode. As of "Sirius Mods" version 7.6, these argument strings are Unicode or are converted to Unicode. For more information about the effects of this Version 7.6 change, see "Strings and Unicode with the XmlDoc API".
  • Namespace declarations are serialized in the order in which they are added.
  • Adding the same declaration multiple times on an element is allowed.
  • To ensure that URIs of already added nodes are preserved:
    • A namespace declaration may not be added to an Element that has the same prefix (including no prefix, in the case of the default namespace declaration) if the Element's URI differs from the AddNamespace URI.
    • A namespace declaration may not be added to an Element that has an attribute with the same prefix if the attribute's URI differs from the AddNamespace URI.
      • Prior to Version 7.7, a namespace declaration may not be added to an Element that has Element children. See the "Namespace conflict" example below.
      • Starting with version 7.7, this restriction does not apply when a non-default namespace declaration is being added to the top-level Element of the XmlDoc. See the "Add to top element" example below.
      • Starting with version 7.9, a default namespace declaration can be added to a prefixed Element if all of its Element children themselves have default namespace declarations. See the "Add default namespace" example below.
  • All well-formed XmlDocs implicitly include this namespace declaration in scope at the top-level document element:

    xmlns:xml="http://www.w3.org/XML/1998/namespace"

    The "xml" prefix is currently valid only for the special attributes xml:space and xml:lang. You are not allowed to:

    • Use any other "xml" prefixed element or attribute names
    • Add a namespace declaration for the "xml" prefix for a URI other than "http://www.w3.org/xml/1998/namespace";
    • Add a namespace declaration for "http://www.w3.org/xml/1998/namespace" that has any other prefix besides "xml"

Example

Add namespace to "leaf" element

In the following example, the AddNamespace method adds a namespace to a node that has an existing namespace. Subsequent elements are added to that node using each of the eligible namespace prefixes.

begin %doc is object xmlDoc %doc = new %doc:loadXml('<top - xmlns:SOAP="http://SCHEMAS.XMLSOAP.ORG/soap/"> - <a><SOAP:b></SOAP:b></a></top>') %n1 is object xmlNode %n2 is object xmlNode %n3 is object xmlNode %n1 = %doc:selectSingleNode('top/*/*') call %n1:addNamespace('sirius', 'http://sirius-software.com') print 'The URI of node SOAP:b is: ' %n1:URI %n2 = %n1:addElement('sirius:c') %n3 = %n1:addElement('SOAP:c') call %doc:print print 'The URI of node sirius:c is: ' %n2:URI print 'The URI of node SOAP:c is: ' %n3:URI end

The example result follows:

The URI of node SOAP:b is: http://SCHEMAS.XMLSOAP.ORG/soap/ <top xmlns:SOAP="http://SCHEMAS.XMLSOAP.ORG/soap/"> <a> <SOAP:b xmlns:sirius="http://sirius-software.com"> <sirius:c/> <SOAP:c/> </SOAP:b> </a> </top> The URI of node sirius:c is: http://sirius-software.com The URI of node SOAP:c is: http://SCHEMAS.XMLSOAP.ORG/soap/

When the method object Element node has children

As mentioned in the Usage notes above, URIs of already added nodes are preserved.

Namespace conflict

Here is an example which shows a AddNamespace which is disallowed to preserve a URI:

%top = %doc:AddElement('p1:top', , 'u:p1') %lev2 = %top:AddElement('p2:lev2', , 'u:p2') %lev2:AddElement('p1:lev3') %doc:Print %lev2:AddNamespace('p1', 'u:p3')

The result of the above fragment is:

<p1:top xmlns:p1="u:p1"> <p2:lev2 xmlns:p2="u:p2"> <p1:lev3/> </p2:lev2> </p1:top> *** 1 CANCELLING REQUEST: MSIR.0750: Class XmlNode, subroutine AddNamespace: can't expose descendants to new non-default namespace in line ...

If the namespace declaration xmlns:p1="u:p3" were simply inserted in the start tag of <p2:lev2...>, that would change the URI of element p1:lev3, and so it is prohibited.

Add to top element

Since the top element of an XmlDoc cannot "block" a namespace declaration, the general restriction against AddNamespace on an Element with child Elements was removed in Version 7.7, for the top element, when the namespace being added has a prefix:

%top = %doc:AddElement('top') %top:AddElement('p2:lev2', , 'u:p2') %top:AddNamespace('p1', 'u:px') %doc:Print

The result of the above fragment is:

<top xmlns:p1="u:px"> <p2:lev2 xmlns:p2="u:p2"/> </top>

Add default namespace

Since a default namespace declaration is "blocked" if all children of the Element have default namespace declarations, the general restriction against AddNamespace on an Element with child Elements was removed in version 7.9, if a default namespace is being added in such a situation:

%top = %doc:AddElement('p1:top', , 'u:p1') %top:AddElement('lev2', , 'u:x') %top:AddNamespace(, 'u:y') %doc:Print

The result of the above fragment is:

<p1:top xmlns:p1="u:p1" xmlns="u:y"> <lev2 xmlns="u:x"/> </p1:top>

Request-Cancellation Errors

  • nod does not point to an Element node.
  • Element pointed to by nod contains one or more child Element nodes.
  • prefix is an invalid prefix.
  • URI is an invalid URI.
  • prefix is the same as the prefix of the Element that nod points to, but URI is different from the namespace URI of the Element.
  • A declaration for the same prefix with a different URI is already present (not merely in scope) at the Element pointed to by nod.
  • The XmlDoc's Namespace property is not On.

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=AddNamespace_(XmlNode_subroutine)&oldid=9996"