PBDOM_ELEMENT – PB Docs 125

Methods

In addition to the methods inherited from PBDOM_OBJECT,
the PBDOM_ELEMENT class has the following methods:

• AddNamespaceDeclaration and RemoveNamespaceDeclaration to
  add namespace declarations to and remove them from the PBDOM_ELEMENT

• GetAttribute, GetAttributes, GetAttributeValue, HasAttributes, RemoveAttribute, SetAttribute,
  and SetAttributes to manipulate the attributes
  of the PBDOM_ELEMENT

• GetChildElement, GetChildElements, HasChildElements, RemoveChildElement,
  and RemoveChildElements to manipulate the children
  of the PBDOM_ELEMENT

• GetNamespacePrefix and GetNamespaceURI to
  get the prefix and URI of the namespace associated with the PBDOM_ELEMENT

• GetQualifiedName to
  get the full name of the PBDOM_ELEMENT including the prefix
  (if any)

• SetDocument to
  set a PBDOM_DOCUMENT as the parent of the PBDOM_ELEMENT

• SetNamespace to
  set the namespace of the PBDOM_ELEMENT

• SetText to
  set the text content of the PBDOM_ELEMENT

The relationship between PBDOM_ELEMENT and PBDOM_ATTRIBUTE

In PBDOM, an XML element’s attributes are not its
children. They are properties of elements rather than having a separate
identity from the elements they are associated with.

Consider the following simple XML document :

The equivalent PBDOM tree is shown in Figure 14-2:

Figure 14-2: Relationship between PBDOM_ELEMENTs
and PBDOM_ATTRIBUTEs

The solid line joining root with child represents
a parent-child relationship. The dashed lines represent a “property-of”
relationship between an attribute and its owner element.

The PBDOM_ELEMENT content management methods do not
apply to PBDOM_ATTRIBUTE objects. There are separate get,
set, and remove methods for attributes.

Because they are not children of their owner elements, PBDOM
does not consider attributes as part of the overall PBDOM document
tree, but they are linked to it through their owner elements.

An attribute can contain child objects (XML text and entity
reference nodes), so an attribute forms a subtree of its own.

Because an element’s attributes are not considered
its children, they have no sibling relationship among themselves
as child objects do. In the sample XML document and in Figure 14-2, attr_1 and attr_2 are
not siblings. The order of appearance of attributes inside its owner
element has no significance.

Attribute setting and creation

In PBDOM, an XML element’s attribute is set using
the PBDOM_ELEMENT SetAttribute and SetAttributes methods.
These methods always attempt to create new attributes for the PBDOM_ELEMENT
and attempt to replace existing attributes with the same name and
namespace URI.

If the PBDOM_ELEMENT already contains an existing
attribute with the same name and namespace URI, these methods first
remove the existing attribute and then insert a new attribute into
the PBDOM_ELEMENT. Calling the SetAttribute method
can cause a PBDOM_ATTRIBUTE (representing an existing attribute
of the PBDOM_ELEMENT) to become detached from its owner
PBDOM_ELEMENT.

For example, consider the following element:

If a PBDOM_ELEMENT object pbdom_an_elem represents
the element an_element and the following
statement is issued, the method first attempts to create a new attribute
for the an_element element:

Then, because an_element already
contains an attribute with the name an_attr, the
attribute is removed. If there is an existing PBDOM_ATTRIBUTE
object that represents the original an_attr attribute,
this PBDOM_ATTRIBUTE is detached from its owner element
(an_element).

For more information about attributes and namespaces, see “XML namespaces”.