PBDOM_OBJECT

Description

A PBDOM_OBJECT serves as the base class for all the PBDOM classes. It contains all the basic methods required by derived classes. The derived classes of a PBDOM_OBJECT each inherit the base methods of a PBDOM_OBJECT, and additionally contain their own specialized methods.

Methods

PBDOM_OBJECT has the following methods:

AddContent

Clone

Detach

Equals

GetContent

GetOwnerDocumentObject

GetName

GetObjectClass

GetObjectClassString

GetParentObject

GetText

GetTextNormalize

GetTextTrim

HasChildren

InsertContent

IsAncestorObjectOf

RemoveContent

SetContent

SetName

SetParentObject

AddContent

Description

Adds a new PBDOM_OBJECT into the current PBDOM_OBJECT.

Syntax

pbdom_object_name.AddContent(pbdom_object pbdom_object_ref)

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT

pbdom_object_ref

The PBDOM_OBJECT to add


Return value

PBDOM_OBJECT.

The return value is the newly modified PBDOM_OBJECT.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object or the input PBDOM_OBJECT is not associated with a derived PBDOM_OBJECT class object.

EXCEPTION_INVALID_ARGUMENT -- Input argument is invalid.

Usage

When a new PBDOM_OBJECT is added to the current one, the new PBDOM_OBJECT becomes a child node of the current PBDOM_OBJECT.

See also

GetContent

InsertContent

RemoveContent

SetContent

Clone

Description

Creates a general duplicate of the current PBDOM_OBJECT.

Syntax

pbdom_object_name.Clone(boolean bDeep)

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT.

bDeep

A boolean specifying whether a deep or shallow clone is returned. Values are true for a deep clone and false for a shallow clone.


Return value

PBDOM_OBJECT. The return value is the clone of the PBDOM_OBJECT.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.

Usage

The Clone method creates a general duplicate of the current PBDOM_OBJECT. If the bDeep parameter is true, a deep clone is returned; otherwise, a shallow clone is returned.

A PBDOM_OBJECT clone does not have a parent; however, it resides in the same PBDOM_DOCUMENT as its original. If the original PBDOM_OBJECT is standalone, the clone is also standalone.

If general, if bDeep is true, the Clone method recursively clones the subtree under the PBDOM_OBJECT. If bDeep is false, the Clone method clones only the PBDOM_OBJECT itself, together with as much information as possible.

Cloning is class specific

Cloning is not uniform across all PBDOM_OBJECT classes. See the documentation for each class for specific information.

Detach

Description

Detaches a PBDOM_OBJECT from its parent.

Syntax

pbdom_object_name.Detach()

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT


Return value

PBDOM_OBJECT.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.

Examples

This example detaches the root element of a PBDOM_DOCUMENT called pbdom_doc from its parent object -- that is, from the PBDOM_DOCUMENT itself. Then, it attempts to obtain the parent PBDOM_OBJECT and tests whether it is null using the IsValid method:

pbdom_obj = pbdom_doc.GetRootElement()
pbdom_obj.Detach()
pbdom_parent_obj = pbdom_obj.GetParentObject()
if (not IsValid(pbdom_parent_obj)) then
     MessageBox ("Invalid", "Root Element has no Parent")
end if

Usage

If the PBDOM_OBJECT has no parent, this method does nothing.

Equals

Description

Tests for the equality of a referenced PBDOM_OBJECT.

Syntax

pbdom_object_name.Equals(pbdom_object pbdom_object_ref)

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT

pbdom_object_ref

The PBDOM_OBJECT to test for equality with the current PBDOM_OBJECT


Return value

Boolean.

Returns true if the current PBDOM_OBJECT is equivalent to the input PBDOM_OBJECT, and false otherwise.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object or the input PBDOM_OBJECT is not associated with a derived PBDOM_OBJECT class object.

EXCEPTION_INVALID_ARGUMENT  -- The input PBDOM_OBJECT is invalid. This can happen if the object has not been initialized properly or is a null object reference.

GetContent

Description

Obtains an array of PBDOM_OBJECT objects, each of which is a child node of the called PBDOM_OBJECT.

Syntax

pbdom_object_name.GetContent(ref pbdom_object pbdom_object_array[ ])

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT

pbdom_object_array

A reference to an array of PBDOM_OBJECT objects that will receive the PBDOM_OBJECT objects


Return value

Boolean.

Returns true for success, and false otherwise.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.

Usage

The returned array is passed by reference, with items in the same order in which they appear in the PBDOM_OBJECT. Any changes to any item of the array affect the actual item to which it refers.

See also

AddContent

InsertContent

RemoveContent

SetContent

GetName

Description

Obtains the name of the current PBDOM_OBJECT. The returned string depends on the type of DOM Object that is contained within a PBDOM_OBJECT.

DOM Object Type

Return Value

PBDOM_DOCTYPE

"#document"

PBDOM_ELEMENT

The local tag name of the element, without any namespace prefixes.

For example, if the element is: <abc>Value</abc>, then the string returned from GetName is "abc".

Also, if the tag name of the element contains a namespace prefix, the prefix is not included in the returned string.

For example, if the element is:

<MyMusic:CD xmlns:MyMusic=, then the string returned from GetName is "CD".

"http://www.MyMusicDiscs.com"/>

PBDOM_ATTRIBUTE

The local name of the attribute itself, without a namespace.

For example, if the element with the attribute is: <abc ATTRIBUTE_1="My Attribute">, then GetName returns "ATTRIBUTE_1".

If the name of the attribute contains a namespace prefix, then the prefix is not included in the returned string.

For example, if the element with an attribute is: <MyMusic:CD xmlns:MyMusic=, then GetName returns the string "Type".

"http://www.MyMusicDiscs.com" MyMusic:Type="Jazz"/>

PBDOM_CDATA

"#cdata-section"

PBDOM_COMMENT

"#comment"

PBDOM_DOCTYPE

The name that was given to the doctype object itself.

For example, if the DOCTYPE declaration is: <!DOCTYPE d_grid_object >, then GetName returns "d_grid_object".

PBDOM_PROCESSINGINSTRUCTION

The name that was given to the processing instruction itself.

For example, if the processing instruction definition is: <?works document="hello.doc" data="hello.wks" ?>, then GetName returns "works".

PBDOM_TEXT

"#text"


Syntax

pbdom_object_name.GetName()

Argument

Description

pbdom_object_name

The name of the PBDOM_ OBJECT


Return value

The following table lists the return values, based on the type of DOM Object contained within the PBDOM_OBJECT:

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- If this PBDOM_OBJECT is not a reference to an object derived from PBDOM_OBJECT.

EXCEPTION_MEMORY_ALLOCATION_FAILURE  -- Insufficient memory was encountered while executing this method.

Usage

A PBDOM_OBJECT cannot be instantiated directly.

See also

SetName

GetObjectClass

Description

Returns a long integer code that indicates the class of this PBDOM_OBJECT.

Syntax

pbdom_object_name.GetObjectClass()

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT


Return value

Long.

A code that indicates the class of the current PBDOM_OBJECT.

Usage

This method returns the following possible values:

Class

Long integer value

UNKNOWN (indicates an error)

0

PBDOM_OBJECT (the base class)

1

PBDOM_DOCUMENT

2

PBDOM_ELEMENT

3

PBDOM_DOCTYPE

4

PBDOM_ATTRIBUTE

5

PBDOM_CHARACTERDATA

6

PBDOM_TEXT

7

PBDOM_CDATA

8

PBDOM_COMMENT

9

PBDOM_PROCESSINGINSTRUCTION

10

PBDOM_ENTITYREFERENCE

11


See also

GetObjectClassString

GetObjectClassString

Description

Returns a string form of the class of the PBDOM_OBJECT.

Syntax

pbdom_object_name.GetObjectClassString()

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT


Return value

String.

A string that indicates the class of the current PBDOM_OBJECT.

Usage

This method returns the following possible values:

Class

String returned

PBDOM_OBJECT

pbdom_object

PBDOM_DOCUMENT

pbdom_document

PBDOM_ELEMENT

pbdom_element

PBDOM_ENTITYREFERENCE

pbdom_entityreference

PBDOM_DOCTYPE

pbdom_doctype

PBDOM_ATTRIBUTE

pbdom_attribute

PBDOM_CHARACTERDATA

pbdom_characterdata

PBDOM_TEXT

pbdom_text

PBDOM_CDATA

pbdom_cdata

PBDOM_COMMENT

pbdom_comment

PBDOM_PROCESSINGINSTRUCTION

pbdom_processinginstruction


See also

GetObjectClass

GetOwnerDocumentObject

Description

Returns the owning PBDOM_DOCUMENT of the current PBDOM_OBJECT.

Syntax

pbdom_object_name.GetOwnerDocumentObject()

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT


Return value

PBDOM_DOCUMENT.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.

EXCEPTION_MEMORY_ALLOCATION_FAILURE  -- Insufficient memory was encountered while executing this method.

Usage

The owning PBDOM_DOCUMENT of the current PBDOM_OBJECT is null if PBDOM_OBJECT is not owned by any PBDOM_DOCUMENT, or if the current PBDOM_OBJECT is itself a PBDOM_DOCUMENT object.

See also

GetParentObject

SetParentObject

GetParentObject

Description

Returns the parent PBDOM_OBJECT of the current PBDOM_OBJECT.

Syntax

pbdom_object_name.GetParentObject()

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT


Return value

PBDOM_OBJECT.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.

EXCEPTION_MEMORY_ALLOCATION_FAILURE  -- Insufficient memory was encountered while executing this method.

Examples

Using the GetRootElement method, the root element of a PBDOM_DOCUMENT called pbdom_doc is returned into a PBDOM_OBJECT called pbdom_obj. The GetParentObject method returns the parent of the root element, which is the PBDOM_DOCUMENT itself, and stores it in pbdom_parent_obj.

The GetObjectClassString method returns the class name of pbdom_parent_obj as a string that is displayed in a message box:

pbdom_document pbdom_doc
pbdom_object pbdom_obj
pbdom_object pbdom_parent_obj
string strClassName
// code omitted
…
pbdom_doc = pbdombuilder_new.BuildFromString (strXML)
pbdom_obj = pbdom_doc.GetRootElement()
pbdom_parent_obj = pbdom_obj.GetParentObject()
strClassName = pbdom_parent_obj.GetObjectClassString()
MessageBox ("Parent Class Name", strClassName)

Usage

If the PBDOM_OBJECT has no parent, null is returned.

See also

GetOwnerDocumentObject

SetParentObject

GetText

Description

Obtains the text data that is contained within the current PBDOM_OBJECT.

Syntax

pbdom_object_name.GetText()

Argument

Description

pbdom_object_name

The name of the PBDOM_ OBJECT


Return value

String.

The following table lists the return values, based on the type of DOM Object contained within a PBDOM_OBJECT:

DOM Object Type

Return Value

PBDOM_ELEMENT

The concatenation of the text values of all the TEXT nodes contained within the PBDOM_ELEMENT.

If the PBDOM_ELEMENT definition is <abc>Root Element Data<data>ABC Data </data> now with extra info   </abc>, then GetText returns "Root Element Data   now with extra info   ".

Extra Spaces

There are extra spaces between the word "Data" and "now" and again after the word "info". They are there because they originally exist in the text.

If the PBDOM_ELEMENT definition is: <abc>Root Element Data</abc>, then GetText returns "Root Element Data".

PBDOM_ATTRIBUTE

The text data contained within the PBDOM_ATTRIBUTE object.

If the element with an attribute is <abc ATTRIBUTE_1="My Attribute">, then GetText returns "My Attribute".

PBDOM_TEXT

The text data contained within the PBDOM_TEXT object itself.

For example, suppose there is the following element:

<abc>MY TEXT</abc>

If there is a PBDOM_TEXT object to represent the text node "MY TEXT", then calling GetText on the PBDOM_TEXT returns the string "MY TEXT"

PBDOM_CDATA

The string data that is contained within the CDATA section itself. For example, suppose there is the following CDATA:

<![CDATA[ They're saying "x < y" & that "z 
> y" so I guess that means that z > x ]]>

If there is a PBDOM_CDATA to represent the above CDATA section, then calling GetText on it returns the following string:

They're saying "x < y" & that "z > y" so I 
guess that means that z > x 

PBDOM_COMMENT

The string data that is contained within the COMMENT itself. For example, suppose there is the following COMMENT:

<!--This is some comment. -->

If there is a PBDOM_COMMENT to represent the above COMMENT, then calling GetText on it returns the following string:

This is some comment.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.

EXCEPTION_MEMORY_ALLOCATION_FAILURE  -- Insufficient memory was encountered while executing this method.

Usage

This method returns meaningful data only if the PBDOM_OBJECT is of a type that can contain text nodes, CDATA sections, or basic text. These include:

  • PBDOM_ELEMENT

  • PBDOM_ATTRIBUTE

  • PBDOM_TEXT

  • PBDOM_CDATA

  • PBDOM_COMMENT

The PBDOM_TEXT, PBDOM_CDATA, and PBDOM_COMMENT objects are special cases that cause the GetText method to return the text data that is intrinsically contained within the objects. A PBDOM_TEXT object is basically a DOM text node and therefore does not hold any child text nodes. A PBDOM_CDATA object represents a DOM CDATA object, and therefore does not hold any child DOM nodes. The same rule applies to a PBDOM_COMMENT object.

See also

GetTextNormalize

GetTextTrim

GetTextNormalize

Description

Gets the text data that is contained in the current PBDOM_OBJECT with all surrounding whitespace characters removed and internal whitespace characters normalized to a single space.

Syntax

pbdom_object_name.GetTextNormalize()

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT


Return value

String.

The normalized text content of the current PBDOM_OBJECT, or an empty string if there is no text content.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.

EXCEPTION_MEMORY_ALLOCATION_FAILURE  -- Insufficient memory was encountered while executing this method.

Usage

This method returns meaningful data only if the PBDOM_OBJECT is of a type that can contain text nodes or CDATA sections, or of a type that intrinsically contains basic text. These types are:

  • PBDOM_ELEMENT

  • PBDOM_ATTRIBUTE

  • PBDOM_TEXT

  • PBDOM_CDATA

  • PBDOM_COMMENT

The PBDOM_TEXT, PBDOM_CDATA, and PBDOM_COMMENT classes are special cases that cause the GetTextNormalize method to return the intrinsic text data contained within their instances. A PBDOM_TEXT object represents a DOM text node, therefore it does not hold any child DOM Nodes. PBDOM_CDATA object is a representation of a DOM CDATA object and does not hold any child DOM Nodes. Nor does PBDOM_COMMENT contain any child DOM Nodes.

The following table lists the return values based on the type of actual DOM Object contained within PBDOM_OBJECT:

DOM Object Type

Return Value

PBDOM_ELEMENT

The normalized text of the concatenation of the text values of all the TEXT Nodes and CDATA Sections contained within the PBDOM_ELEMENT.

Suppose there is a PBDOM_ELEMENT defined as follows:

<abc>    Root    Element Data    <data>ABC Data 
</data> now with extra info    </abc>

GetTextNormalize returns Root Element Data now with extra info.

Suppose there is a PBDOM_ELEMENT defined as follows:

<abc> Root   Element   Data  </abc>

GetTextNormalize returns Root Element Data.

Suppose there is a PBDOM_ELEMENT defined as follows:

<abc>   Root    Element    Data    <![CDATA
[ with some cdata text]]></abc>

GetTextNormalize returns "Root Element Data with some cdata text".

PBDOM_ATTRIBUTE

The normalized text data contained within the PBDOM_ATTRIBUTE object.

Suppose there is an element with an attribute as follows:

<abc ATTRIBUTE_1="  My      Attribute   ">

GetTextNormalize returns My Attribute.

PBDOM_TEXT

The normalized text data contained within the PBDOM_TEXT object itself.

For example, suppose there is the following element:

<abc>  MY TEXT  </abc>

If there is a PBDOM_TEXT object to represent the text node "MY TEXT", then calling GetTextNormalize on the PBDOM_TEXT returns the string MY TEXT.

PBDOM_CDATA

The normalized string data that is contained within the CDATA section itself. For example, suppose there is the following CDATA:

<![CDATA[     They're saying "x < y" & that "z > 
y" so I guess     that means that z > x    ]]>

If there is a PBDOM_CDATA to represent the above CDATA section, then calling GetTextNormalize on it returns the string:

They're saying " x < y " & that "z > y" so I 
guess that means that z > x 

Note that the initial spaces before "They're" and the trailing space after the last "x" have been removed. Additionally, the spaces between the word "guess" and "that" have been reduced to just one space.

PBDOM_COMMENT

The normalized string data that is contained within the COMMENT itself. For example, suppose there is the following COMMENT:

<!--   Comment    Here !-->

Calling GetTextNormalize on the COMMENT returns the string Comment Here !


See also

GetText

GetTextTrim

GetTextTrim

Description

Gets the text data that is contained in the current PBDOM_OBJECT with all surrounding whitespace characters removed.

Syntax

pbdom_object_name.GetTextTrim()

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT


Return value

String.

The trimmed text content of the current PBDOM_OBJECT, or an empty string if there is no text content or only whitespace characters.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.

EXCEPTION_MEMORY_ALLOCATION_FAILURE  -- Insufficient memory was encountered while executing this method.

Usage

This method returns meaningful data only if the PBDOM_OBJECT is of a type that can contain TEXT NODEs or CDATA Sections, or of a type that intrinsically contains basic text. These types are:

  • PBDOM_ELEMENT

  • PBDOM_ATTRIBUTE

  • PBDOM_TEXT

  • PBDOM_CDATA

  • PBDOM_COMMENT

The PBDOM_TEXT, PBDOM_CDATA, and PBDOM_COMMENT classes are special cases that cause the GetTextTrim method to return the intrinsic text data contained within their instances. A PBDOM_TEXT object represents a DOM text node, so it does not hold any child DOM Nodes. PBDOM_CDATA object is a representation of a DOM CDATA object and does not hold any child DOM Nodes, nor does PBDOM_COMMENT contain any child DOM Nodes.

The following table lists the return values based on the type of actual DOM Object contained within PBDOM_OBJECT:

DOM Object Type

Return Value

PBDOM_ELEMENT

The trimmed concatenation of the text values of all the TEXT Nodes and CDATA Sections contained within the PBDOM_ELEMENT. Surrounding whitespace characters are removed.

Suppose there is a PBDOM_ELEMENT defined as follows:

<abc>   Root Element Data<data>ABC Data </data> now with 
extra info   </abc>

GetTextTrim returns Root Element Data now with extra info.

Suppose there is a PBDOM_ELEMENT defined as follows:

<abc>  Root Element Data  </abc>

GetTextTrim returns Root Element Data.

Suppose there is a PBDOM_ELEMENT defined as follows:

<abc>Root Element Data <![CDATA[ with some cdata text]]></abc>

GetTextTrim returns Root Element Data with some cdata text.

PBDOM_ATTRIBUTE

The trimmed text data contained within the PBDOM_ATTRIBUTE object with surrounding whitespace characters removed.

Suppose there is an element with an attribute as follows:

<abc ATTRIBUTE_1="My     Attribute     ">

GetTextTrim returns:

My     Attribute

Note, however, that the spaces between "My" and "Attribute" are still present.

PBDOM_TEXT

The trimmed text data contained within the PBDOM_TEXT object itself with surrounding whitespace characters removed.

For example, suppose there is the following element:

<abc>  MY TEXT  </abc>

If there is a PBDOM_TEXT object to represent the text node "MY     TEXT ", then calling GetTextTrim on the PBDOM_TEXT returns the string MY TEXT.

PBDOM_CDATA

The trimmed string data that is contained within the CDATA section itself with surrounding whitespace characters removed. For example, suppose there is the following CDATA:

<![CDATA[   They're saying "x < y" & that "z > y" so I 
guess   that means that z > x    ]]>

If there is a PBDOM_CDATA to represent the above CDATA section, then calling GetTextTrim on it returns the string:

They're saying " x < y " & that "z > y" so I 
guess   that means that z > x 

Note that the initial spaces before "They're" and the trailing space after the last "x" have been removed.

PBDOM_COMMENT

The trimmed string data that is contained within the COMMENT itself. For example, suppose there is the following COMMENT:

<!--   Comment   Here !   -->

Note the spaces before the word "Comment" and after the exclamation mark "!".

Calling GetTextTrim on the COMMENT returns the string Comment   Here !


See also

GetText

GetTextNormalize

HasChildren

Description

Determines whether the PBDOM_OBJECT has any child objects.

Syntax

pbdom_object_name.HasChildren()

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT


Return value

Boolean.

Returns true if the current PBDOM_OBJECT has at least one child PBDOM_OBJECT, and false if it has none.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.

Examples

In the following example, a PBDOM_DOCUMENT is created from a simple XML string. The root element abc has a child text node that encapsulates the text "abc data". Calling HasChildren on the root element returns true. The message box displays Has Children. If the method returns false, the message box displays Has No Children

PBDOM_Builder pbdombuilder_new
pbdom_document pbdom_doc
pbdom_object pbdom_root_element
string strXML = "<abc>abc data</abc>"

pbdombuilder_new = Create PBDOM_Builder
pbdom_doc = pbdombuilder_new.BuildFromString (strXML)
pbdom_root_element = pbdom_doc.GetRootElement()
if (pbdom_root_element.HasChildren()) then
     MessageBox ("pbdom_root_element", "Has Children")
else
     MessageBox ("pbdom_root_element", "Has No Children")
end if
Destroy pbdombuilder_new

Usage

True is returned if the PBDOM_OBJECT has at least one child, and false if there are no children.

InsertContent

Description

Inserts a new PBDOM_OBJECT into the current PBDOM_OBJECT.

Syntax

pbdom_object_name.InsertContent(pbdom_object_new, pbdom_object_ref)

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT

pbdom_object_new

The referenced name of a PBDOM_OBJECT you want to insert

pbdom_object_ref

The name of the PBDOM_OBJECT in front of which you want to insert the new PBDOM_OBJECT


Return value

PBDOM_OBJECT. The return value is the newly modified PBDOM_OBJECT.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object or the new PBDOM_OBJECT or the reference PBDOM_OBJECT is not associated with a derived PBDOM_OBJECT class object.

EXCEPTION_INVALID_ARGUMENT  -- One of the input arguments is invalid. This can happen if the input argument has not been initialized properly or is a null object reference.

Usage

When a new PBDOM_OBJECT is inserted into the current PBDOM_OBJECT, the new PBDOM_OBJECT becomes a child node of the current PBDOM_OBJECT. Also, the new PBDOM_OBJECT is to be positioned specifically before another PBDOM_OBJECT, designated using the second parameter.

If the second PBDOM_OBJECT is specified as null, then the new PBDOM_OBJECT is to be inserted at the end of the list of children of the current PBDOM_OBJECT.

Derived Classes

Methods of classes that derive from the PBDOM_OBJECT class return trivial results when the derived classes can have no child objects and when the methods concern manipulation of child-node content.

See also

AddContent

GetContent

RemoveContent

SetContent

IsAncestorObjectOf

Description

Determines whether the current PBDOM_OBJECT is the ancestor of another PBDOM_OBJECT.

Syntax

pbdom_object_name.IsAncestorObjectOf(pbdom_object_ret)

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT

pbdom_object_ref

The PBDOM_OBJECT to check against


Return value

Boolean.

Returns true if the current PBDOM_OBJECT is the ancestor of the referenced PBDOM_OBJECT, and false otherwise.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.

EXCEPTION_INVALID_ARGUMENT  -- The input PBDOM_OBJECT is invalid. This can happen if it has not been initialized properly or it is a null object reference.

Examples

The following code fragment uses the IsAncestorObjectOf method and creates a structured document. In the fragment, pbdom_elem_1 represents the  pbdom_elem_1 element. Because it is an ancestor of pbdom_elem_3, which represents the  pbdom_elem_ element, the call to IsAncestorObjectOf returns true.

PBDOM_ELEMENT pbdom_elem_1
PBDOM_ELEMENT pbdom_elem_2
PBDOM_ELEMENT pbdom_elem_3
PBDOM_ELEMENT pbdom_elem_root
PBDOM_DOCUMENT pbdom_doc1

pbdom_doc1 = Create PBDOM_DOCUMENT
pbdom_elem_1 = Create PBDOM_ELEMENT
pbdom_elem_2 = Create PBDOM_ELEMENT
pbdom_elem_3 = Create PBDOM_ELEMENT

pbdom_elem_1.SetName("pbdom_elem_1")
pbdom_elem_2.SetName("pbdom_elem_2")
pbdom_elem_3.SetName("pbdom_elem_3")

pbdom_elem_1.AddContent(pbdom_elem_2)
pbdom_elem_2.AddContent(pbdom_elem_3)

pbdom_doc1.NewDocument("", "", &
   "Root_Element_From_Doc_1" , "", "")
pbdom_elem_root = pbdom_doc1.GetRootElement()
pbdom_elem_root.AddContent(pbdom_elem_1)

IF (pbdom_elem_1.IsAncestorObjectOf(pbdom_elem_3)) THEN
   MessageBox ("Ancestry", &
      "pbdom_elem_1 Is The Ancestor Of pbdom_elem_3")
ELSE
   MessageBox ("Ancestry", &
    "pbdom_elem_1 Is NOT The Ancestor Of pbdom_elem_3")

END IF

destroy pbdom_elem_1
destroy pbdom_elem_2
destroy pbdom_elem_3
destroy pbdom_elem_root
destroy pbdom_doc1

The preceding code fragment creates the following document:

<!DOCTYPE Root_Element_From_Doc_1>
<Root_Element_From_Doc_1>
  <pbdom_elem_1>
    <pbdom_elem_2>
      <pbdom_elem_3 />
    </pbdom_elem_2>
  </pbdom_elem_1>
</Root_Element_From_Doc_1>

Usage

The IsAncestorObjectOf method determines whether the current PBDOM_OBJECT is the ancestor of another PBDOM_OBJECT.

RemoveContent

Description

Removes a child PBDOM_OBJECT from the current PBDOM_OBJECT.

Syntax

pbdom_object_name.RemoveContent(pbdom_object_ref)

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT

pbdom_object_ref

The PBDOM_OBJECT to remove


Return value

Boolean.

Returns true if the content was removed, and false otherwise.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object or the input PBDOM_OBJECT is not associated with a derived PBDOM_OBJECT class object.

EXCEPTION_INVALID_ARGUMENT  -- The input PBDOM_OBJECT to be removed is invalid. This can happen if this object has not been initialized properly or is a null object reference.

Usage

When a new PBDOM_OBJECT is removed from the current one, all children under the removed PBDOM_OBJECT are also removed.

See also

AddContent

GetContent

InsertContent

SetContent

SetContent

Description

Sets the entire content of the PBDOM_OBJECT.

Syntax

pbdom_object_name.SetContent(pbdon_objectpbdom_object_array)

Argument

Description

pbdom_object_name

The name of the PBDOM object

pbdom_object_array

An array of PBDOM_OBJECT objects to be set as the contents of the PBDOM_OBJECT


Return value

PBDOM_OBJECT. Returns the newly modified PBDOM_OBJECT.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.

Usage

The supplied array contains PBDOM_OBJECT objects that are legal for the particular derived PBDOM_OBJECT that is associated with this PBDOM_OBJECT.

For example, a PBDOM_DOCUMENT accepts only an array that contains PBDOM_ELEMENT, PBDOM_COMMENT, PBDOM_DOCTYPE, or PBDOM_PROCESSINGINSTRUCTION objects. In addition, the array can contain only one PBDOM_ELEMENT object that it sets as its root element, and only one PBDOM_DOCTYPE object that is set as its DOCTYPE.

If illegal objects are included in the array, exceptions (specific to the particular derived PBDOM_OBJECT) are thrown. For more details, please refer to the SetContent method of the objects derived from PBDOM_OBJECT.

In the event of an exception, the original contents of this PBDOM_OBJECT are unchanged, and the PBDOM_OBJECT objects contained in the supplied array are unaltered.

See also

AddContent

GetContent

InsertContent

RemoveContent

SetName

Description

Sets the name of the PBDOM_OBJECT.

Syntax

pbdom_object_name.SetName(stringstrName)

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT

strName

The new name you want to set for PBDOM_OBJECT


Return value

Boolean.

Returns true if the name of the PBDOM_OBJECT was changed, and false otherwise.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.

EXCEPTION_INVALID_ARGUMENT  -- Input name string is invalid. This can happen if the string has been specifically set to null.

EXCEPTION_MEMORY_ALLOCATION_FAILURE  -- Insufficient memory was encountered while executing this method.

EXCEPTION_INVALID_NAME  -- The input name string does not conform to the W3C standards for XML names.

Usage

This name refers to the name of the particular derived PBDOM_OBJECT to which this PBDOM_OBJECT refers. Certain types of PBDOM_OBJECT do not have any name associated with them. See the description of GetName.

For example, PBDOM_DOCUMENT does not have any name, so calling the SetName method returns false.

See also

GetName

SetParentObject

Description

Sets the referenced PBDOM_OBJECT as the parent of the current PBDOM_OBJECT.

Syntax

pbdom_object_name.SetParentObject(pbdom_object pbdom_object_ref)

Argument

Description

pbdom_object_name

The name of the PBDOM_OBJECT

pbdom_object_ref

The PBDOM_OBJECT to be set as the parent of the current PBDOM_OBJECT


Return value

PBDOM_OBJECT. The current PBDOM_OBJECT is appended as a child node of the referenced parent.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object or the input PBDOM_OBJECT is not associated with a derived PBDOM_OBJECT class object.

EXCEPTION_INVALID_ARGUMENT  -- The input PBDOM_OBJECT is invalid. This can happen if it has not been initialized properly, or if it is a null object reference.

EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT  -- The current PBDOM_OBJECT already has a parent.

EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT  -- If the input PBDOM_OBJECT is of a class that cannot have a legal parent-child relationship with this PBDOM_OBJECT.

Examples

In the following code example, a PBDOM_ELEMENT object is created and called pbdom_elem_1. Its parent is set to be the root element of the PBDOM_DOCUMENT called pbdom_doc. Once this is done, pbdom_elem_1 is immediately transferred to the pbdom_doc document and pbdom_elem_1 is immediately appended as a child node of the root element of pbdom_doc.

The following method call returns the string "pbdom_element", because the root element is a PBDOM_ELEMENT:

pbdom_elem_1.GetParentObject().GetObjectClassString() 

The following method call returns the string "Root_Element", which is the name of the root element:

pbdom_elem_1.GetParentObject().GetName()

Here is the complete example:

PBDOM_ELEMENT pbdom_elem_1
PBDOM_ELEMENT pbdom_elem_root
PBDOM_DOCUMENT pbdom_doc1

pbdom_doc1 = Create PBDOM_DOCUMENT
pbdom_elem_1 = Create PBDOM_ELEMENT
pbdom_elem_1.SetName ("pbdom_elem_1")

pbdom_doc1.NewDocument ("", "", "Root_Element", "", "")
pbdom_elem_root = pbdom_doc1.GetRootElement()
pbdom_elem_1.SetParentObject(pbdom_elem_root)

MessageBox ("Parent Class", &
   pbdom_elem_1.GetParentObject(). &
   GetObjectClassString())
MessageBox ("Parent Name", &
   pbdom_elem_1.GetParentObject().GetName())

destroy pbdom_elem_1
destroy pbdom_elem_root
destroy pbdom_doc1

Usage

The caller is responsible for ensuring that the current PBDOM_OBJECT and the referenced PBDOM_OBJECT can have a legal parent-child relationship. The caller is also responsible for making sure pre-existing parentage is legal.

The PBDOM SetParentObject method differs from the JDOM SetParent method in that JDOM defines a setParent method for several specific classes, including Element, Comment, and CDATA. PBDOM implements the SetParentObject method in the base PBDOM_OBJECT class to allow polymorphism.

See the SetParentObject documentation of derived PBDOM_OBJECT classes for more details on implementation of specific classes.

See also

GetOwnerDocumentObject

GetParentObject