PBDOM_ATTRIBUTE:
SetName method
Description
Sets
the local name of the PBDOM_ATTRIBUTE object.
Syntax
|
1 |
<span>pbdom_attribute_name.</span>SetName(string<span> strName</span>) |
|
Argument |
Description |
|---|---|
|
pbdom_attribute_name |
The name of the PBDOM_ATTRIBUTE |
|
strName |
The new local name for the PBDOM_ATTRIBUTE |
Return Values
Boolean. Returns true if
the local name of the PBDOM_ATTRIBUTE has been changed
and false otherwise.
Throws
EXCEPTION_INVALID_NAME – If
the input name is not valid for a local name of a PBDOM_ATTRIBUTE.
This happens if the name is an empty string, if the name contains
a namespace prefix, or if the name is already the name of an existing
attribute of the owning element.
EXCEPTION_MEMORY_ALLOCATION_FAILURE – Insufficient
memory was encountered while executing this method.
Examples
This example shows how to set the local name of a
PBDOM_ATTRIBUTE and demonstrates that the namespace information
it contains is not affected by a change in name.
The sample code first builds a PBDOM_DOCUMENT from
a string that contains XML that has a single root element with a
namespace declaration and an attribute a.
The GetAttribute method obtains the attribute a,
which does not belong to a namespace, and the returned PBDOM_ATTRIBUTE
is tested and should be valid. After a call to SetName,
the code confirms the name change and tests that the namespace information
remains the same (the namespace prefix and URI are both still empty
strings):
|
1 |
PBDOM_BUILDER     pbdom_buildr<br>PBDOM_DOCUMENT    pbdom_doc<br>PBDOM_ATTRIBUTE   pbdom_attr<br>string strXML = "<root xmlns:n1=~"http://www.n.com~" a=~"123~"/>"<br> <br>try<br>  pbdom_buildr = Create PBDOM_BUILDER <br>  pbdom_doc = pbdom_buildr.BuildFromString (strXML)<br>  <br>  pbdom_attr = pbdom_doc.GetRootElement(). &<br>     GetAttribute("a")<br>  <br>  if (IsValid(pbdom_attr)) then<br>    MessageBox ("Pass", &<br>      "PBDOM_ATTRIBUTE a is retrieved via the " &<br>      + "NONAMESPACE GetAttribute() method.")<br>  else<br>    MessageBox ("Fail", &<br>      "PBDOM_ATTRIBUTE should have been retrievable.")<br>  end if<br>  <br>  pbdom_attr.SetName ("b")<br>  <br>  if pbdom_attr.GetName() = "b" then<br>    MessageBox ("Pass", "Name has been changed to b.")<br>  else<br>    MessageBox ("Fail", &<br>      "Name should have been changed to b.")<br>  end if<br>  <br>  if pbdom_attr.GetNamespacePrefix() = "" then<br>    MessageBox ("Pass", &<br>      "Namespace Prefix is an empty string.")<br>  else<br>    MessageBox ("Fail", "Namespace Prefix is : " &<br>      + pbdom_attr.GetNamespacePrefix() &<br>      + " which is incorrect.")<br>  end if<br> <br>  if pbdom_attr.GetNamespaceURI() = "" then<br>    MessageBox ("Pass", &<br>      "Namespace URI is an empty string.")<br>  else<br>    MessageBox ("Fail", "Namespace URI is : " &<br>      + pbdom_attr.GetNamespaceURI() &<br>      + " which is incorrect.")<br>  end if<br>  <br>catch(PBDOM_EXCEPTION pbdom_e)<br>  MessageBox("PBDOM_EXCEPTION", pbdom_e.GetMessage())<br>end try |
Usage
This method sets the local name of the PBDOM_ATTRIBUTE.
When a PBDOM_ATTRIBUTE is first created, it has no name
and the namespace information is by default set to the NONAMESPACE
namespace. (Its NS Prefix and URI are both empty strings.)The SetName method
is used to set the local name of the PBDOM_ATTRIBUTE. The SetNamespace method
is used to set the Namespace Prefix and URI of the PBDOM_ATTRIBUTE.If
a PBDOM_ATTRIBUTE is retrieved programmatically from a
parsed document, then the name and namespace information of the PBDOM_ATTRIBUTE
are inherited from the referred attribute of the parsed document.
The name and namespace information of the PBDOM_ATTRIBUTE,
however, can still be modified using the SetName and SetNamespace methods.Note
that according to the W3C “Namespaces in XML”specification,
when the SetName method is invoked on a PBDOM_ATTRIBUTE,
if the PBDOM_ATTRIBUTE (PBDOM_ATTRIBUTE 1) has
an owner PBDOM_ELEMENT that contains an existing PBDOM_ATTRIBUTE (PBDOM_ATTRIBUTE
2) with the same name (to be set for PBDOM_ATTRIBUTE 1)
and namespace URI as PBDOM_ATTRIBUTE 1, the EXCEPTION_INVALID_NAME
exception will be thrown.