PBDOM_COMMENT

Append
Clone
Detach
Equals
GetObjectClass
GetObjectClassString
GetOwnerDocumentObject
GetParentObject
GetText
GetTextNormalize
GetTextTrim
SetParentObject
SetText

Description

The PBDOM_COMMENT class represents a DOM Comment Node within an XML document. The PBDOM_COMMENT class is derived from the PBDOM_CHARACTERDATA class and is intended to extend the PBDOM_CHARACTERDATA class with a set of methods intended specifically for manipulating DOM comment nodes.

You can use comments to annotate an XML document with user-readable information.

In PBDOM, when a document is parsed, any comments found within the document persist as part of the resultant DOM tree in memory. A PBDOM_COMMENT created at runtime also becomes part of the DOM tree. However, an XML comment does not usually form part of the content model of a document.

The presence or absence of comments has no bearing on a document's validity. There is no requirement that comments must be predeclared in a DTD.

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_COMMENT
GetContent	false
GetName	a string "#comment"
HasChildren	false
InsertContent	current PBDOM_COMMENT
IsAncestorObjectOf	false
RemoveContent	false
SetContent	current PBDOM_COMMENT
SetName	false

PBDOM_COMMENT has the following non-trivial methods:

GetOwnerDocumentObject

Append

Append Syntax 1
Append Syntax 2

Description

The Append method is overloaded:

Syntax 1 appends an input string to the text content that already exists within the current PBDOM_COMMENT object.
Syntax 2 appends the text data of a PBDOM_CHARACTERDATA object to the text content that already exists within the current PBDOM_COMMENT object.

Syntax

For this syntax	See
Append(string strAppend)	Append Syntax 1
Append(pbdom_characterdata pbdom_characterdata_ref)	Append Syntax 2

Append Syntax 1

Description

Appends an input string to the text content that already exists within the current PBDOM_COMMENT object.

Syntax

pbdom_comment_name.Append(string strAppend)

Argument	Description
pbdom_comment_name	The name of a PBDOM_COMMENT
strAppend	The string you want to append to the existing text of the current PBDOM_COMMENT object

Return value

PBDOM_CHARACTERDATA. The current PBDOM_COMMENT modified and returned as a PBDOM_CHARACTERDATA object.

Append Syntax 2

Description

Appends the text data of a PBDOM_CHARACTERDATA object to the text content that exists within the current PBDOM_COMMENT object.

Syntax

pbdom_comment_name.Append(pbdom_characterdata pbdom_characterdata_ref)

Argument	Description
pbdom_comment_name	The name of a PBDOM_COMMENT
pbdom_characterdata_ref	The referenced PBDOM_CHARACTERDATA object whose text data is to be appended to the existing text of the current PBDOM_COMMENT object

Return value

PBDOM_CHARACTERDATA. The current PBDOM_COMMENT modified and returned as a PBDOM_CHARACTERDATA object.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If the input PBDOM_CHARACTERDATA is not a reference to a PBDOM_CHARACTERDATA-derived object.

Usage

Note that JDOM does not define an Append method for its COMMENT class. Because PBDOM implements its Append method in the base PBDOM_CHARACTERDATA class, a PBDOM_TEXT object, a PBDOM_CDATA object, and a PBDOM_COMMENT object can append their internal text data to each other because they are all PBDOM_CHARACTERDATA-derived objects.

Clone

Description

Creates and returns a clone of the current PBDOM_COMMENT.

Syntax

pbdom_comment_name.Clone(boolean bDeep)

Argument	Description
pbdom_comment_name	The name of a PBDOM_COMMENT
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.

Examples

This example creates an XML document that, when serialized, appears as follows:

<!DOCTYPE root
[
<!ELEMENT root (level_1)*>
<!ELEMENT level_1 (level_2)*>
<!ELEMENT level_2 (#PCDATA)*>
]>
<root>
   <level_1>
      <!--Element at level : 1-->
      <level_2>
         <!--Element at level : 2-->
      </level_2>
   </level_1>
</root>

The definition of the DTD shows that the document is required to have the following composition:

The document contains a root element with the name root.
The root element contains zero or more occurrences of level_1 elements.
A level_1 element contains zero or more level_2 elements.
A level_2 element is expected to contain text.

The following PowerScript code supplies annotations within the document by including comments to mark level_1 and level_2 elements. The sample code creates a PBDOM_DOCUMENT from an XML string that contains a DTD and a minimal root element. Then, it creates a comment that serves as a template. The template comment is then cloned, and instance-specific text is added for each element:

PBDOM_COMMENT pbdom_comm
PBDOM_COMMENT pbdom_comm_clone
PBDOM_ELEMENT pbdom_elem
PBDOM_DOCUMENT pbdom_doc
PBDOM_BUILDER pbdom_buildr
string strXML = "<!DOCTYPE root [<!ELEMENT root (level_1)*><!ELEMENT level_1 (level_2)*><!ELEMENT level_2 (#PCDATA)>]><root/>"

try
  // Create a PBDOM_DOCUMENT from the XML string that
  // contains a DTD and a minimal root element.
  pbdom_buildr = Create PBDOM_BUILDER
  pbdom_doc = pbdom_buildr.BuildFromString(strXML)

  // Create a template comment that can be reused.
  pbdom_comm = Create PBDOM_COMMENT
  pbdom_comm.SetText ("Element at level : ")
  
  // Create a level_1 element.
  pbdom_elem = Create PBDOM_ELEMENT
  pbdom_elem.SetName("level_1")

  // Clone the template comment, append instance-
  // specific text, and add it to the level_1 element.
  pbdom_comm_clone = pbdom_comm.Clone(true)
  pbdom_elem.AddContent(pbdom_comm_clone.Append("1"))
  
  // Add a level_1 element into the root element 
  // as stipulated by the DTD.
  pbdom_doc.GetRootElement().AddContent(pbdom_elem)
  
  // Create a level_2 element.
  pbdom_elem = Create PBDOM_ELEMENT
  pbdom_elem.SetName("level_2")

  // Clone the template comment, append instance-
  // specific text, and add it to the level_2 element.
  pbdom_comm_clone = pbdom_comm.Clone(true)
  pbdom_elem.AddContent(pbdom_comm_clone.Append("2"))
  
  // Add a level_2 element into the level_1 element
  // as stipulated by the DTD.
  pbdom_doc.GetRootElement().GetChildElement &
    ("level_1").AddContent(pbdom_elem)

  // Finally, serialize the document.
  pbdom_doc.SaveDocument("sample.xml")
  
catch(PBDOM_EXCEPTION pbdom_e)
  MessageBox ("PBDOM_EXCEPTION", pbdom_e.GetMessage())
end try

Usage

The Clone method creates a new PBDOM_COMMENT object that is a duplicate of, and a separate object from, the original. Whether true or false is supplied, the clone is always identical to its original, because a PBDOM_COMMENT does not contain a subtree of child PBDOM_OBJECTs.

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

Detach

Description

Detaches a PBDOM_COMMENT from its parent PBDOM_OBJECT.

Syntax

pbdom_comment_name.Detach()

Argument	Description
pbdom_comment_name	The name of a PBDOM_COMMENT

Return value

PBDOM_OBJECT.

The current PBDOM_COMMENT is detached from its parent.

Usage

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

Equals

Description

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

Syntax

pbdom_comment_name.Equals(pbdom_object pbdom_object_ref)

Argument	Description
pbdom_comment_name	The name of a PBDOM_COMMENT.
pbdom_object_ref	A PBDOM_OBJECT to test for equality with the current PBDOM_COMMENT

Return value

Boolean.

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

Throws

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

Usage

True is returned only if the referenced PBDOM_OBJECT is also a derived PBDOM_COMMENT object and refers to the same DOM object as the current PBDOM_COMMENT. Two separately created PBDOM_COMMENTs, for example, can contain exactly the same text but are not 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_COMMENT, the returned value is 9.

See also

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_COMMENT, the returned string is "pbdom_comment".

See also

GetObjectClass

GetOwnerDocumentObject

Description

Returns the owning PBDOM_DOCUMENT of the current PBDOM_COMMENT.

Syntax

pbdom_comment_name.GetOwnerDocumentObject()

Argument	Description
pbdom_comment_name	The name of a PBDOM_COMMENT

Return value

PBDOM_OBJECT.

Usage

If there is no owning PBDOM_DOCUMENT, null is returned.

GetParentObject

Description

Returns the parent PBDOM_OBJECT of the current PBDOM_COMMENT.

Syntax

pbdom_comment_name.GetParentObject()

Argument	Description
pbdom_comment_name	The name of a PBDOM_COMMENT

Return value

PBDOM_OBJECT.

Usage

The GetParentObject method returns the parent PBDOM_OBJECT of the current PBDOM_COMMENT. If the PBDOM_COMMENT has no parent, null is returned.

See also

SetParentObject

GetText

Description

Allows you to obtain the text data that is contained within the current PBDOM_COMMENT object.

Syntax

pbdom_comment_name.GetText()

Argument	Description
pbdom_comment_name	The name of a PBDOM_COMMENT

Return value

String.

The textual content of the current PBDOM_COMMENT object.

Examples

If you have the comment <!- A COMMENT->, the GetText method returns the string A COMMENT.

See also

GetTextNormalize

GetTextTrim

SetText

GetTextNormalize

Description

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

Syntax

pbdom_comment_name.GetTextNormalize()

Argument	Description
pbdom_comment_name	The name of a PBDOM_COMMENT

Return value

String.

Examples

If you have the comment , which has three spaces before and after the text and between the two words, the GetTexNormalizet method returns the string A COMMENT, which has a single space between the words.

Usage

This method allows the caller to obtain the text data that is contained within the current PBDOM_COMMENT with all surrounding whitespace characters removed and internal whitespace characters normalized to single spaces. If no textual value exists for the current PBDOM_COMMENT, 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_COMMENT object with all surrounding whitespace characters removed.

Syntax

pbdom_comment_name.GetTextTrim()

Argument	Description
pbdom_comment_name	The name of a PBDOM_COMMENT

Return value

String.

Examples

If you have the comment , which has three spaces before and after the text and between the two words, the GetTextTrim method returns the string A COMMENT. The whitespace characters between the words are preserved.

Usage

This method allows the caller to obtain the text data that is contained within the current PBDOM_COMMENT with all surrounding whitespace characters removed. Internal whitespace characters are preserved. If no textual value exists for the current PBDOM_COMMENT, 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_COMMENT.

Syntax

pbdom_comment_name.SetParentObject(pbdom_object pbdom_object_ref)

Argument	Description
pbdom_comment_name	The name of a PBDOM_COMMENT
pbdom_object_ref	A PBDOM_OBJECT to be set as the parent of the current PBDOM_COMMENT

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_COMMENT already has a parent.

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

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

Usage

This method sets the input PBDOM_OBJECT as the parent of this PBDOM_COMMENT. The caller is responsible for ensuring that the current PBDOM_COMMENT and the input PBDOM_OBJECT can have a legal parent-child relationship. Currently, only a PBDOM_ELEMENT and a PBDOM_DOCUMENT can be set as the parent of a PBDOM_COMMENT.

The PBDOM_COMMENT SetParentObject method differs from the JDOM Comment setParent method in two ways:

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 for polymorphism.
The JDOM Comment's setParent method takes only an Element class object as a parameter:
```
COMMENT::setParent(Element parent)
```

To set a Document as the parent owner of a Comment using JDOM, you use the setDocument method:

COMMENT::setDocument(Document document)

In PBDOM, SetParentObject takes a reference to a PBDOM_OBJECT, so that both a PBDOM_ELEMENT and a PBDOM_DOCUMENT can be set as a parent.

See also

GetOwnerDocumentObject

GetParentObject

SetText

Description

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

Syntax

pbdom_comment_name.SetText(string strSet)

Argument	Description
pbdom_comment_name	The name of a PBDOM_COMMENT
strSet	The string you want set as the text of the PBDOM_COMMENT

Return value

String.

See also

GetText

GetTextNormalize

GetTextTrim

Prev	Up	Next
PBDOM_COMMENT Class	Home	PBDOM_DOCTYPE Class

PowerBuilder Extension ReferencePBDOM_COMMENT Class

PBDOM_COMMENT

Append

Append Syntax 1

Append Syntax 2

Clone

Detach

Equals

GetObjectClass

GetObjectClassString

GetOwnerDocumentObject

GetParentObject

GetText

GetTextNormalize

GetTextTrim

SetParentObject

SetText

PowerBuilder Extension Reference
PBDOM_COMMENT Class