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:
|
Method |
Always returns |
|---|---|
|
AddContent |
current PBDOM_ENTITYREFERENCE |
|
GetContent |
false |
|
GetText |
an empty string |
|
GetTextNormalize |
an empty string |
|
GetTextTrim |
an empty string |
|
HasChildren |
false |
|
InsertContent |
current PBDOM_ENTITYREFERENCE |
|
IsAncestorObjectOf |
false |
|
RemoveContent |
false |
|
SetContent |
current PBDOM_ENTITYREFERENCE |
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)
|
Argument |
Description |
|---|---|
|
pbdom_entityref_name |
The name of a PBDOM_ENTITYREFERENCE 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. This parameter is currently ignored. |
Return value
PBDOM_OBJECT. A clone of the current PBDOM_ENTITYREFERENCE object housed in a PBDOM_OBJECT.
Examples
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()
Return value
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)
Return value
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()
Return value
String.
See also
Description
Returns a long integer code that indicates the class of the current PBDOM_OBJECT.
Syntax
pbdom_object_name.GetObjectClass()
Return value
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()
Return value
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()
Return value
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()
Return value
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)
|
Argument |
Description |
|---|---|
|
pbdom_entityref_name |
The name of a PBDOM_ENTITYREFERENCE object |
|
strName |
The new name you want to set for the current PBDOM_ENTITYREFERENCE object |
Return value
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)
|
Argument |
Description |
|---|---|
|
pbdom_entityref_name |
The name of a PBDOM_ENTITYREFERENCE object |
|
pbdom_object_ref |
The PBDOM_OBJECT to be set as the parent of the current PBDOM_ENTITYREFERENCE object |
Return value
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
