PBDOM_ENTITYREFERENCE

Description

The PBDOM_ENTITYREFERENCE class defines behavior for an XML Entity reference Node. It allows you to insert entity references within element nodes as well as attribute nodes. The PBDOM_ENTITYREFERENCE class is derived from PBDOM_OBJECT.

Methods

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

PBDOM_ENTITYREFERENCE has the following non-trivial methods:

Description

Creates and returns a clone of the current PBDOM_ENTITYREFERENCE object.

Syntax

pbdom_entityref_name.Clone(boolean bDeep)

Returns

PBDOM_OBJECT. A clone of the current PBDOM_ENTITYREFERENCE object housed in a PBDOM_OBJECT.

Examples

Example 1

This example creates a PBDOM_DOCUMENT based on a string that contains an XML document, and creates a PBDOM_ENTITYREFERENCE object to reference the ENTITY my_er defined in the DOCTYPE. The DOCTYPE also indicates that the root element must contain zero or more child elements named child, and that each child can contain only parsed character data.

The FOR loop creates ten child elements and inserts a new clone of pbdom_er into each child element. You must use a clone, because the same object cannot be inserted as a child of more than one parent:

PBDOM_BUILDER           pbdom_buildr
PBDOM_DOCUMENT          pbdom_doc
PBDOM_ENTITYREFERENCE   pbdom_er
string strXML = "<!DOCTYPE root [<!ELEMENT root (child)*><!ELEMENT child (#PCDATA)><!ENTITY my_er ~"MY ENTITY~">]><root/>"
long l = 0

TRY
  pbdom_buildr = Create PBDOM_BUILDER
  pbdom_doc = pbdom_buildr.BuildFromString(strXML)
  pbdom_er = Create PBDOM_ENTITYREFERENCE
  pbdom_er.SetName("my_er")
  
// Create 10 child elements for the root element
  for l = 1 to 10
    PBDOM_ELEMENT pbdom_elem_child
    
    pbdom_elem_child = Create PBDOM_ELEMENT
    pbdom_elem_child.SetName("child")
    // Add a clone of pbdom_er as content
    pbdom_elem_child.AddContent(pbdom_er.Clone(true))
    
    pbdom_doc.GetRootElement(). &
      AddContent(pbdom_elem_child)
  next
  
  pbdom_doc.SaveDocument("clone_er.xml")
CATCH(PBDOM_EXCEPTION pbdom_e)
  MessageBox ("PBDOM_EXCEPTION", pbdom_e.GetMessage())
END TRY

When the PBDOM_DOCUMENT object is serialized, it produces the following XML document :

<!DOCTYPE root
[
<!ELEMENT root (child)*>
<!ELEMENT child (#PCDATA)*>
<!ENTITY my_er "MY ENTITY">
]
> 
<root> <child>MY ENTITY</child> 
<child>MY ENTITY</child> 
<child>MY ENTITY</child> 
<child>MY ENTITY</child> 
<child>MY ENTITY</child> 
<child>MY ENTITY</child> 
<child>MY ENTITY</child> 
<child>MY ENTITY</child> 
<child>MY ENTITY</child> 
<child>MY ENTITY</child> 
</root>

Usage

The Clone method creates a new PBDOM_ENTITYREFERENCE object which is a duplicate of the original. A PBDOM_ENTITYREFERENCE object cannot contain any child PBDOM_OBJECTs, so there is no subtree beneath a PBDOM_ENTITYREFERENCE object. A shallow clone is therefore structurally no different than a deep clone of a PBDOM_ENTITYREFERENCE object.This method allows you to use an entity reference node more than once. You cannot add a PBDOM_ENTITYREFERENCE object as the child of more than one PBDOM_OBJECT, but you can clone it and then add the clone as the child of another PBDOM_OBJECT.A PBDOM_ENTITYREFERENCE clone does not have any parent. However, the clone resides in the same PBDOM_DOCUMENT as its original. If the original PBDOM_ENTITYREFERENCE object is standalone, the clone is also standalone.

Description

Detaches a PBDOM_ENTITYREFERENCE object from its parent PBDOM_OBJECT.

Syntax

pbdom_entityref_name.Detach()

Returns

PBDOM_OBJECT. The current PBDOM_ENTITYREFERENCE object detached from its parent.

Usage

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

Description

Tests for the equality of the current PBDOM_ENTITYREFERENCE object and a referenced PBDOM_OBJECT.

Syntax

pbdom_entityref_name.Equals(pbdom_object pbdom_object_ref)

Returns

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

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If the input PBDOM_OBJECT is not an object derived from PBDOM_OBJECT.

Usage

This method returns true only if the referenced PBDOM_OBJECT is also a derived PBDOM_ENTITYREFERENCE object and it refers to the same DOM object as the current PBDOM_ENTITYREFERENCE object. Two separately created PBDOM_COMMENTs, for example, can contain exactly the same text but not be equal.

Description

Obtains the name of the current PBDOM_ENTITYREFERENCE object.

Syntax

pbdom_entityref_name.GetName()

Returns

String.

See also

Description

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

Syntax

pbdom_object_name.GetObjectClass()

Returns

Long. A code that indicates the class of the current PBDOM_OBJECT. If pbdom_object_name is a PBDOM_ENTITYREFERENCE object, the returned value is 11.

See also

Description

Returns a string form of the class of the PBDOM_OBJECT.

Syntax

pbdom_object_name.GetObjectClassString()

Returns

String. A string that indicates the class of the current PBDOM_OBJECT. If pbdom_object_name is a PBDOM_ENTITYREFERENCE object, the returned string is “pbdom_entityreference”.

See also

Description

The GetOwnerDocumentObject method returns the owning PBDOM_DOCUMENT of the current PBDOM_ENTITYREFERENCE object.

Syntax

pbdom_entityref_name.GetOwnerDocumentObject()

Returns

PBDOM_DOCUMENT.

Usage

If there is no owning PBDOM_DOCUMENT, null is returned.

See also

Description

The GetParentObject method returns the parent PBDOM_OBJECT of the current PBDOM_ENTITYREFERENCE object.

Syntax

pbdom_entityref_name.GetParentObject()

Returns

PBDOM_OBJECT.

Usage

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

See also

Description

Changes the name of the PBDOM_ENTITYREFERENCE object, effectively making it refer to another DOM entity object.

Syntax

pbdom_entityref_name.SetName(string strName)

Returns

Boolean. Returns true if the name of the current PBDOM_ENTITYREFERENCE object was changed, and false if it was not.

See also

Description

The SetParentObject method sets the referenced PBDOM_OBJECT to be the parent of the current PBDOM_ENTITYREFERENCE object.

Syntax

pbdom_entityref_name.SetParentObject(pbdom_object pbdom_object_ref)

Returns

PBDOM_OBJECT.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If the input PBDOM_OBJECT is not an object derived from PBDOM_OBJECT.

EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT – If the current PBDOM_ENTITYREFERENCE object 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_ENTITYREFERENCE class.

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT – If the input PBDOM_OBJECT requires a user-defined name and it has not been named, or the name of the entity reference object has not been set.

Usage

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

See also