PBDOM_CDATA

Description

The PBDOM_CDATA class represents an XML DOM CDATA section. The PBDOM_CDATA class is derived from PBDOM_TEXT, which inherits from the PBDOM_CHARACTERDATA class.

A PBDOM_CDATA object is used to hold text that contains characters that are prohibited in text objects, such as "<" and "&", without using entity references. For example, consider the following PBDOM_CDATA object:

<some_text>
   <![CDATA[ (x < y) & (y < z) => x < z ]]>
</some_text>

A PBDOM_TEXT object with the same text content must be written like this:

<some_text>
   (x &lt; y) &amp; (y &lt; z) =&gt; x &lt; z
</some_text>

However, although the PBDOM_CDATA class is derived from PBDOM_TEXT, a PBDOM_CDATA object cannot always be inserted in the same context as a PBDOM_TEXT. For example, a PBDOM_TEXT object can be added as a child of a PBDOM_ATTRIBUTE, but a PBDOM_CDATA object cannot.

Methods

Some of the inherited methods from PBDOM_OBJECT serve no meaningful objective, and only default or trivial functionalities result. These are described in the following table:

Method

Always returns

AddContent

current PBDOM_CDATA

GetContent

false

GetName

a string "#cdata"

HasChildren

false

InsertContent

current PBDOM_CDATA

IsAncestorObjectOf

false

RemoveContent

false

SetContent

current PBDOM_CDATA

SetName

false


PBDOM_CDATA has the following non-trivial methods:

Append

Clone

Detach

Equals

GetObjectClass

GetObjectClassString

GetOwnerDocumentObject

GetParentObject

GetText

GetTextNormalize

GetTextTrim

SetParentObject

SetText

Append

Description

Appends the input string or the input text data of the PBDOM_CHARACTERDATA object to the text content that already exists within the current PBDOM_CDATA object.

Syntax

pbdom_cdata_name.Append(string strAppend)
pbdom_cdata_name.Append(pbdom_characterdata pbdom_characterdata_ref)

Argument

Description

pbdom_cdata_name

The name of a PBDOM_CDATA

strAppend

The string you want appended to the existing text of the current PBDOM_CDATA object

pbdom_characterdata_ref

The referenced PBDOM_CHARACTERDATA object whose text data is to be appended to the existing text of the current PBDOM_CDATA object


Return value

PBDOM_CHARACTERDATA.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If the input PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA (applies to second syntax).

Clone

Description

Creates and returns a clone of the current PBDOM_CDATA.

Syntax

pbdom_cdata_name.Clone(boolean bDeep)

Argument

Description

pbdom_cdata_name

The name of a PBDOM_CDATA.

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. This argument is currently ignored.


Return value

PBDOM_OBJECT. The return value is a clone of the current PBDOM_CDATA housed in a PBDOM_OBJECT.

Examples

This example tests the following characteristics of a cloned PBDOM_CDATA object:

  • The contents of an original and cloned PBDOM_CDATA object are exactly the same

  • A cloned PBDOM_CDATA initially has no parent object

  • A cloned PBDOM_CDATA is initially contained within the same owner document as the original

    PBDOM_BUILDER     pbdom_buildr
    PBDOM_DOCUMENT    pbdom_doc
    PBDOM_CDATA       pbdom_cdat
    PBDOM_OBJECT      pbdom_obj_array[]
    string strXML = "<!DOCTYPE root [<!ELEMENT root (#PCDATA)>]><root><![CDATA[This is a CDATA Section.]]></root>"
    
    try
      // Build a PBDOM_DOCUMENT based on strXML.
      pbdom_buildr = Create PBDOM_BUILDER
      pbdom_doc = pbdom_buildr.BuildFromString (strXML)
    
      // Get the contents of the root element.
      pbdom_doc.GetRootElement().GetContent(pbdom_obj_array)
      
      // Test if the root element contains only one child object.
      if (UpperBound(pbdom_obj_array) = 1) then
        MessageBox ("Pass", "Root Element has only one child.")
      else
        MessageBox ("Fail", "Root Element must have only one child.")
      end if
    
      // Make a clone of the only child of the root element.
      pbdom_cdat = pbdom_obj_array[1].Clone(true)
    
      // Test if the clone is a PBDOM_CDATA object.
      if (pbdom_cdat.GetObjectClassString() = "pbdom_cdata") then
        MessageBox ("Pass", &
         "The first child, after being cloned, is indeed a PBDOM_CDATA object.")
      else
        MessageBox ("Fail", "The first child, after being cloned, " &
          + "is found to be a " + pbdom_cdat.GetObjectClassString() + " object.")
      end if
    
      // Test if the clone is a CDATA section.
      if (pbdom_cdat.GetText() = "This is a CDATA Section.") then
        MessageBox ("Pass", "The text contents of the clone is correct.")
      else
        MessageBox ("Fail", "The text contents of the clone is : [" &
          + pbdom_cdat.GetText() + "]. This is incorrect.")
      end if
      
      // Test that the clone has no parent.
      if (Not IsValid(pbdom_cdat.GetParentObject())) then
        MessageBox ("Pass", "The clone has no parent.")
      else
        MessageBox ("Fail", "The clone should have no parent.")
      end if
      
      // Test that the clone's owner document is the same 
      // as the original's owner document.
      if (pbdom_cdat.GetOwnerDocumentObject() = pbdom_doc) then
        MessageBox ("Pass", "The clone's owner document is correct.")
      else
        MessageBox ("Fail", "The clone's owner document is incorrect.")
      end if
      
    catch (PBDOM_EXCEPTION pbdom_except)
      MessageBox ("PBDOM_EXCEPTION", pbdom_except.GetMessage())
    end try

Usage

The Clone method creates a new PBDOM_CDATA object that is a duplicate of, and a separate object from, the original. The clone of a PBDOM_CDATA is always identical to its original whether deep or shallow cloning is invoked, because a PBDOM_CDATA object does not contain any subtree of child PBDOM_OBJECTs.

A PBDOM_CDATA clone has no parent. However, the clone resides in the same PBDOM_DOCUMENT as its original, and if the original PBDOM_CDATA is standalone, the clone is standalone.

Detach

Description

Detaches a PBDOM_CDATA from its parent PBDOM_OBJECT.

Syntax

pbdom_cdata_name.Detach()

Argument

Description

pbdom_cdata_name

The name of a PBDOM_CDATA


Return value

PBDOM_OBJECT. The current PBDOM_CDATA detached from its parent.

Usage

If the current PBDOM_CDATA object has no parent, no modifications occur.

Equals

Description

Tests for the equality of the current PBDOM_CDATA and a referenced PBDOM_OBJECT.

Syntax

pbdom_cdata_name.Equals(pbdom_object pbdom_object_ref)

Argument

Description

pbdom_cdata_name

The name of a PBDOM_CDATA

pbdom_object_ref

A PBDOM_OBJECT to test for equality with the current PBDOM_CDATA


Return value

Boolean.

Returns true if the current PBDOM_CDATA object is equivalent to the referenced PBDOM_OBJECT and false otherwise.

Throws

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

Usage

True is returned only if the referenced PBDOM_OBJECT is also a derived PBDOM_CDATA object and refers to the same DOM object as the current PBDOM_CDATA. Two separately created PBDOM_CDATA objects, for example, can contain exactly the same text but not be equal.

GetObjectClass

Description

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

Syntax

pbdom_object_name.GetObjectClass()

Argument

Description

pbdom_object_name

The name of a PBDOM_OBJECT


Return value

Long.

GetObjectClass returns a long integer code that indicates the class of the current PBDOM_OBJECT. If pbdom_object_name is a PBDOM_CDATA object, the returned value is 8.

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 a PBDOM_OBJECT


Return value

String.

GetObjectClassString returns a string that indicates the class of the current PBDOM_OBJECT. If pbdom_object_name is a PBDOM_CDATA object, the returned string is "pbdom_cdata".

See also

GetObjectClass

GetOwnerDocumentObject

Description

Returns the owning PBDOM_DOCUMENT of the current PBDOM_CDATA.

Syntax

pbdom_cdata_name.GetOwnerDocumentObject()

Argument

Description

pbdom_cdata_name

The name of a PBDOM_CDATA


Return value

PBDOM_OBJECT.

Usage

If there is no owning PBDOM_DOCUMENT, null is returned.

See also

GetParentObject

SetParentObject

GetParentObject

Description

Returns the parent PBDOM_OBJECT of the PBDOM_CDATA. If there is no parent, null is returned.

Syntax

pbdom_cdata_name.GetParentObject()

Argument

Description

pbdom_cdata_name

The name of a PBDOM_CDATA


Return value

PBDOM_OBJECT.

See also

GetOwnerDocumentObject

SetParentObject

GetText

Description

Returns the text data that is contained within the current PBDOM_CDATA object.

Syntax

pbdom_cdata_name.GetText()

Argument

Description

pbdom_cdata_name

The name of a PBDOM_CDATA


Return value

String.

The textual content of the current PBDOM_CDATA object.

See also

GetTextNormalize

GetTextTrim

SetText

GetTextNormalize

Description

Returns the text data that is contained within the current PBDOM_CDATA object, with all surrounding whitespace characters removed and internal whitespace characters normalized to a single space.

Syntax

pbdom_cdata_name.GetTextNormalize()

Argument

Description

pbdom_cdata_name

The name of a PBDOM_CDATA


Return value

String.

Usage

If no textual value exists for the current PBDOM_OBJECT, or if only whitespace characters exist, an empty string is returned.

See also

GetText

GetTextTrim

SetText

GetTextTrim

Description

Returns the textual content of the current PBDOM_CDATA object with all surrounding whitespace characters removed.

Syntax

pbdom_cdata_name.GetTextTrim()

Argument

Description

pbdom_cdata_name

The name of a PBDOM_CDATA


Return value

String.

Usage

If no textual value exists for the current PBDOM_CDATA, or if only whitespace characters exist, an empty string is returned.

See also

GetText

GetTextNormalize

SetText

SetParentObject

Description

Sets the referenced PBDOM_OBJECT to be the parent of the current PBDOM_CDATA.

Syntax

pbdom_cdata_name.SetParentObject(pbdom_object pbdom_object_ref)

Argument

Description

pbdom_cdata_name

The name of a PBDOM_CDATA

pbdom_object_ref

A PBDOM_OBJECT to be set as the parent of this PBDOM_CDATA object


Return value

PBDOM_OBJECT.

Throws

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

EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT -- If the current PBDOM_CDATA already has a parent.

EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT -- If the input PBDOM_OBJECT is of a class that does not have a legal parent-child relationship with the PBDOM_CDATA class.

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT -- If the input PBDOM_OBJECT requires a user-defined name and it has not been named.

Usage

The PBDOM_OBJECT that you set to be the parent of the current PBDOM_CDATA must have a legal parent-child relationship. If it does not, an exception is thrown. Only a PBDOM_ELEMENT object can be set as the parent of a PBDOM_CDATA object.

See also

GetParentObject

SetText

Description

Sets the input string to be the text content of the current PBDOM_CDATA object.

Syntax

pbdom_cdata_name.SetText(string strSet)

Argument

Description

pbdom_cdata_name

The name of a PBDOM_CDATA

strSet

The string you want set as the text of the PBDOM_CDATA


Return value

PBDOM_CHARACTERDATA. This PBDOM_CDATA modified and returned as a PBDOM_CHARACTERDATA object.

See also

GetText

GetTextNormalize

GetTextTrim