xmltooling  3.3.0
xmltooling::XMLObject Class Referenceabstract

Object that represents an XML Element that has been unmarshalled into this C++ object. More...

#include <xmltooling/XMLObject.h>

Inheritance diagram for xmltooling::XMLObject:
xmlsignature::Signature xmltooling::AbstractXMLObject xmltooling::AttributeExtensibleXMLObject xmltooling::ElementExtensibleXMLObject xmltooling::AbstractAttributeExtensibleXMLObject xmltooling::AbstractComplexElement xmltooling::AbstractDOMCachingXMLObject xmltooling::AbstractSimpleElement xmltooling::AbstractXMLObjectMarshaller xmltooling::AbstractXMLObjectUnmarshaller xmltooling::AbstractAttributeExtensibleXMLObject xmltooling::ElementProxy xmltooling::ElementProxy

Public Member Functions

virtual XMLObjectclone () const =0
 Creates a copy of the object, along with all of its children. More...
 
virtual void detach ()=0
 Specialized function for detaching a child object from its parent while disposing of the parent. More...
 
virtual const QNamegetElementQName () const =0
 Gets the QName for this element. More...
 
virtual const std::set< Namespace > & getNamespaces () const =0
 Gets the namespaces that are scoped to this element. More...
 
virtual void addNamespace (const Namespace &ns) const =0
 Adds a namespace to the ones already scoped to this element. More...
 
virtual void removeNamespace (const Namespace &ns)=0
 Removes a namespace from this element. More...
 
virtual const QNamegetSchemaType () const =0
 Gets the XML schema type of this element. More...
 
virtual const XMLCh * getXMLID () const =0
 Gets the value of the ID attribute set on this object, if any. More...
 
virtual const XMLCh * getLang () const
 Returns the xml:lang property of the object, if any. More...
 
bool nil () const
 Returns the xsi:nil property of the object, or false if not set. More...
 
virtual xmlconstants::xmltooling_bool_t getNil () const =0
 Returns the xsi:nil property as an explicit enumerated value. More...
 
virtual void nil (xmlconstants::xmltooling_bool_t value)=0
 Sets the xsi:nil property using an enumerated value. More...
 
void nil (bool value)
 Sets the xsi:nil property. More...
 
void setNil (const XMLCh *value)
 Sets the xsi:nil property using a string constant. More...
 
virtual bool hasParent () const =0
 Checks to see if this object has a parent. More...
 
virtual XMLObjectgetParent () const =0
 Gets the parent of this element or null if there is no parent. More...
 
virtual void setParent (XMLObject *parent)=0
 Sets the parent of this element. More...
 
virtual bool hasChildren () const =0
 Checks if this XMLObject has children. More...
 
virtual const std::list< XMLObject * > & getOrderedChildren () const =0
 Returns an unmodifiable list of child objects in the order that they should appear in the serialized representation. More...
 
virtual void removeChild (XMLObject *child)=0
 Used by a child's detach method to isolate the child from this parent object in preparation for destroying the parent (this object). More...
 
virtual const XMLCh * getTextContent (unsigned int position=0) const =0
 Returns the text content at the specified position relative to any child elements. More...
 
virtual void setTextContent (const XMLCh *value, unsigned int position=0)=0
 Sets (or clears) text content relative to a child element's position. More...
 
virtual xercesc::DOMElement * getDOM () const =0
 Gets the DOM representation of this XMLObject, if one exists. More...
 
virtual void setDOM (xercesc::DOMElement *dom, bool bindDocument=false) const =0
 Sets the DOM representation of this XMLObject. More...
 
virtual void setDocument (xercesc::DOMDocument *doc) const =0
 Assigns ownership of a DOM document to the XMLObject. More...
 
virtual void releaseDOM () const =0
 Releases the DOM representation of this XMLObject, if there is one.
 
virtual void releaseParentDOM (bool propagateRelease=true) const =0
 Releases the DOM representation of this XMLObject's parent. More...
 
virtual void releaseChildrenDOM (bool propagateRelease=true) const =0
 Releases the DOM representation of this XMLObject's children. More...
 
void releaseThisandParentDOM () const
 A convenience method that is equal to calling releaseDOM() then releaseParentDOM(true).
 
void releaseThisAndChildrenDOM () const
 A convenience method that is equal to calling releaseChildrenDOM(true) then releaseDOM().
 
virtual xercesc::DOMElement * marshall (xercesc::DOMDocument *document=0, const std::vector< xmlsignature::Signature *> *sigs=0, const Credential *credential=0) const =0
 Marshalls the XMLObject, and its children, into a DOM element. More...
 
virtual xercesc::DOMElement * marshall (xercesc::DOMElement *parentElement, const std::vector< xmlsignature::Signature *> *sigs=0, const Credential *credential=0) const =0
 Marshalls the XMLObject and appends it as a child of the given parent element. More...
 
virtual XMLObjectunmarshall (xercesc::DOMElement *element, bool bindDocument=false)=0
 Unmarshalls the given W3C DOM element into the XMLObject. More...
 

Detailed Description

Object that represents an XML Element that has been unmarshalled into this C++ object.

Member Function Documentation

◆ addNamespace()

virtual void xmltooling::XMLObject::addNamespace ( const Namespace ns) const
pure virtual

Adds a namespace to the ones already scoped to this element.

Parameters
nsthe namespace to add

Implemented in xmltooling::AbstractXMLObject.

◆ clone()

virtual XMLObject* xmltooling::XMLObject::clone ( ) const
pure virtual

Creates a copy of the object, along with all of its children.

The new object tree will be completely distinct and independent of the original in all respects.

Implemented in xmltooling::AbstractDOMCachingXMLObject.

◆ detach()

virtual void xmltooling::XMLObject::detach ( )
pure virtual

Specialized function for detaching a child object from its parent while disposing of the parent.

This is not a generic way of detaching any child object, but only of pruning a single child from the root of an XMLObject tree. If the detached XMLObject's parent is itself a child, an exception will be thrown. It's mainly useful for turning a child into the new root of the tree without having to clone the child.

Implemented in xmltooling::AbstractXMLObject, and xmltooling::AbstractDOMCachingXMLObject.

◆ getDOM()

virtual xercesc::DOMElement* xmltooling::XMLObject::getDOM ( ) const
pure virtual

Gets the DOM representation of this XMLObject, if one exists.

Returns
the DOM representation of this XMLObject

Implemented in xmltooling::AbstractDOMCachingXMLObject.

◆ getElementQName()

virtual const QName& xmltooling::XMLObject::getElementQName ( ) const
pure virtual

Gets the QName for this element.

This QName MUST contain the namespace URI, namespace prefix, and local element name.

Returns
constant reference to the QName for this object

Implemented in xmltooling::AbstractXMLObject.

◆ getLang()

virtual const XMLCh* xmltooling::XMLObject::getLang ( ) const
virtual

Returns the xml:lang property of the object, if any.

Returns
an xml:lang value, or nullptr

Reimplemented in xmltooling::AbstractAttributeExtensibleXMLObject.

◆ getNamespaces()

virtual const std::set<Namespace>& xmltooling::XMLObject::getNamespaces ( ) const
pure virtual

Gets the namespaces that are scoped to this element.

The caller MUST NOT modify the set returned, but may use any non-modifying operations or algorithms on it. Iterators will remain valid unless the set member referenced is removed using the removeNamespace method.

Returns
the namespaces that are scoped to this element

Implemented in xmltooling::AbstractXMLObject.

◆ getNil()

virtual xmlconstants::xmltooling_bool_t xmltooling::XMLObject::getNil ( ) const
pure virtual

Returns the xsi:nil property as an explicit enumerated value.

Returns
the xsi:nil property

Implemented in xmltooling::AbstractXMLObject.

◆ getOrderedChildren()

virtual const std::list<XMLObject*>& xmltooling::XMLObject::getOrderedChildren ( ) const
pure virtual

Returns an unmodifiable list of child objects in the order that they should appear in the serialized representation.

The validity of the returned list is not maintained if any non-const operations are performed on the parent object.

Returns
the list of children

Implemented in xmltooling::AbstractComplexElement, and xmltooling::AbstractSimpleElement.

◆ getParent()

virtual XMLObject* xmltooling::XMLObject::getParent ( ) const
pure virtual

Gets the parent of this element or null if there is no parent.

Returns
the parent of this element or null

Implemented in xmltooling::AbstractXMLObject.

◆ getSchemaType()

virtual const QName* xmltooling::XMLObject::getSchemaType ( ) const
pure virtual

Gets the XML schema type of this element.

This translates to contents the xsi:type attribute for the element.

Returns
XML schema type of this element

Implemented in xmltooling::AbstractXMLObject.

◆ getTextContent()

virtual const XMLCh* xmltooling::XMLObject::getTextContent ( unsigned int  position = 0) const
pure virtual

Returns the text content at the specified position relative to any child elements.

A zero represents leading text, 1 comes after the first child, and so forth.

Parameters
positionthe relative child element position of the text
Returns
the designated text value

Implemented in xmltooling::AbstractComplexElement, and xmltooling::AbstractSimpleElement.

◆ getXMLID()

virtual const XMLCh* xmltooling::XMLObject::getXMLID ( ) const
pure virtual

Gets the value of the ID attribute set on this object, if any.

Returns
an ID value or nullptr

Implemented in xmltooling::AbstractXMLObject, and xmltooling::AbstractAttributeExtensibleXMLObject.

◆ hasChildren()

virtual bool xmltooling::XMLObject::hasChildren ( ) const
pure virtual

Checks if this XMLObject has children.

Returns
true if this XMLObject has children, false if not

Implemented in xmltooling::AbstractComplexElement, and xmltooling::AbstractSimpleElement.

◆ hasParent()

virtual bool xmltooling::XMLObject::hasParent ( ) const
pure virtual

Checks to see if this object has a parent.

Returns
true if the object has a parent, false if not

Implemented in xmltooling::AbstractXMLObject.

◆ marshall() [1/2]

virtual xercesc::DOMElement* xmltooling::XMLObject::marshall ( xercesc::DOMDocument *  document = 0,
const std::vector< xmlsignature::Signature *> *  sigs = 0,
const Credential credential = 0 
) const
pure virtual

Marshalls the XMLObject, and its children, into a DOM element.

If a document is supplied, then it will be used to create the resulting elements. If the document does not have a Document Element set, then the resulting element will be set as the Document Element. If no document is supplied, then a new document will be created and bound to the lifetime of the root object being marshalled, unless an existing DOM can be reused without creating a new document.

Parameters
documentthe DOM document the marshalled element will be placed in, or nullptr
sigsordered array of signatures to create after marshalling is complete
credentialoptional credential to supply signing key and related info
Returns
the DOM element representing this XMLObject
Exceptions
MarshallingExceptionthrown if there is a problem marshalling the given object
SignatureExceptionthrown if a problem occurs during signature creation

Implemented in xmltooling::AbstractXMLObjectMarshaller.

◆ marshall() [2/2]

virtual xercesc::DOMElement* xmltooling::XMLObject::marshall ( xercesc::DOMElement *  parentElement,
const std::vector< xmlsignature::Signature *> *  sigs = 0,
const Credential credential = 0 
) const
pure virtual

Marshalls the XMLObject and appends it as a child of the given parent element.

NOTE: The given Element must be within a DOM tree rooted in the Document owning the given Element.

Parameters
parentElementthe parent element to append the resulting DOM tree
sigsordered array of signatures to create after marshalling is complete
credentialoptional credential to supply signing key and related info
Returns
the marshalled element tree
Exceptions
MarshallingExceptionthrown if the given XMLObject can not be marshalled.
SignatureExceptionthrown if a problem occurs during signature creation

Implemented in xmltooling::AbstractXMLObjectMarshaller.

◆ nil() [1/3]

bool xmltooling::XMLObject::nil ( ) const
inline

Returns the xsi:nil property of the object, or false if not set.

Returns
the xsi:nil property

◆ nil() [2/3]

virtual void xmltooling::XMLObject::nil ( xmlconstants::xmltooling_bool_t  value)
pure virtual

Sets the xsi:nil property using an enumerated value.

Parameters
valuevalue to set

Implemented in xmltooling::AbstractXMLObject.

◆ nil() [3/3]

void xmltooling::XMLObject::nil ( bool  value)
inline

Sets the xsi:nil property.

Parameters
valuevalue to set

◆ releaseChildrenDOM()

virtual void xmltooling::XMLObject::releaseChildrenDOM ( bool  propagateRelease = true) const
pure virtual

Releases the DOM representation of this XMLObject's children.

Parameters
propagateReleasetrue if all descendants of this element should release their DOM

Implemented in xmltooling::AbstractDOMCachingXMLObject.

◆ releaseParentDOM()

virtual void xmltooling::XMLObject::releaseParentDOM ( bool  propagateRelease = true) const
pure virtual

Releases the DOM representation of this XMLObject's parent.

Parameters
propagateReleasetrue if all ancestors of this element should release their DOM

Implemented in xmltooling::AbstractDOMCachingXMLObject.

◆ removeChild()

virtual void xmltooling::XMLObject::removeChild ( XMLObject child)
pure virtual

Used by a child's detach method to isolate the child from this parent object in preparation for destroying the parent (this object).

Parameters
childthe child object to remove

Implemented in xmltooling::AbstractComplexElement, and xmltooling::AbstractSimpleElement.

◆ removeNamespace()

virtual void xmltooling::XMLObject::removeNamespace ( const Namespace ns)
pure virtual

Removes a namespace from this element.

Parameters
nsthe namespace to remove

Implemented in xmltooling::AbstractXMLObject.

◆ setDocument()

virtual void xmltooling::XMLObject::setDocument ( xercesc::DOMDocument *  doc) const
pure virtual

Assigns ownership of a DOM document to the XMLObject.

This binds the lifetime of the document to the lifetime of the object.

Parameters
docDOM document bound to this object

Implemented in xmltooling::AbstractDOMCachingXMLObject.

◆ setDOM()

virtual void xmltooling::XMLObject::setDOM ( xercesc::DOMElement *  dom,
bool  bindDocument = false 
) const
pure virtual

Sets the DOM representation of this XMLObject.

Parameters
domDOM representation of this XMLObject
bindDocumenttrue if the object should take ownership of the associated Document

Implemented in xmltooling::AbstractDOMCachingXMLObject.

◆ setNil()

void xmltooling::XMLObject::setNil ( const XMLCh *  value)

Sets the xsi:nil property using a string constant.

Parameters
valuevalue to set

◆ setParent()

virtual void xmltooling::XMLObject::setParent ( XMLObject parent)
pure virtual

Sets the parent of this element.

Parameters
parentthe parent of this element

Implemented in xmltooling::AbstractXMLObject.

◆ setTextContent()

virtual void xmltooling::XMLObject::setTextContent ( const XMLCh *  value,
unsigned int  position = 0 
)
pure virtual

Sets (or clears) text content relative to a child element's position.

Parameters
valuevalue to set, or nullptr to clear
positionposition relative to child element

Implemented in xmltooling::AbstractComplexElement, and xmltooling::AbstractSimpleElement.

◆ unmarshall()

virtual XMLObject* xmltooling::XMLObject::unmarshall ( xercesc::DOMElement *  element,
bool  bindDocument = false 
)
pure virtual

Unmarshalls the given W3C DOM element into the XMLObject.

The root of a given XML construct should be unmarshalled with the bindDocument parameter set to true.

Parameters
elementthe DOM element to unmarshall
bindDocumenttrue iff the resulting XMLObject should take ownership of the DOM's Document
Returns
the unmarshalled XMLObject
Exceptions
UnmarshallingExceptionthrown if an error occurs unmarshalling the DOM element into the XMLObject

Implemented in xmltooling::AbstractXMLObjectUnmarshaller.


The documentation for this class was generated from the following file: