xmltooling/XMLObject.h

   1 /*
   2  *  Copyright 2001-2007 Internet2
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file XMLObject.h
  19  *
  20  * Abstract interface to objects that can be manipulated in and out of XML form.
  21  */
  22
  23 #ifndef __xmltooling_xmlobj_h__
  24 #define __xmltooling_xmlobj_h__
  25
  26 #include <xmltooling/QName.h>
  27 #include <xmltooling/Namespace.h>
  28
  29 #include <set>
  30 #include <list>
  31 #include <vector>
  32 #include <xercesc/dom/DOM.hpp>
  33
  34 using namespace xercesc;
  35
  36 #ifndef XMLTOOLING_NO_XMLSEC
  37 namespace xmlsignature {
  38     class XMLTOOL_API Signature;
  39 };
  40 #endif
  41
  42 #if defined (_MSC_VER)
  43     #pragma warning( push )
  44     #pragma warning( disable : 4250 4251 )
  45 #endif
  46
  47 namespace xmltooling {
  48
  49 #ifndef XMLTOOLING_NO_XMLSEC
  50     class XMLTOOL_API Credential;
  51 #endif
  52
  53     /**
  54      * Object that represents an XML Element that has been unmarshalled into this C++ object.
  55      */
  56     class XMLTOOL_API XMLObject
  57     {
  58     public:
  59         virtual ~XMLObject() {}
  60
  61         /**
  62          * Creates a copy of the object, along with all of its children.
  63          *
  64          * The new object tree will be completely distinct and independent of
  65          * the original in all respects.
  66          */
  67         virtual XMLObject* clone() const=0;
  68
  69         /**
  70          * Specialized function for detaching a child object from its parent
  71          * <strong>while disposing of the parent</strong>.
  72          *
  73          * This is not a generic way of detaching any child object, but only of
  74          * pruning a single child from the root of an XMLObject tree. If the
  75          * detached XMLObject's parent is itself a child, an exception will be
  76          * thrown. It's mainly useful for turning a child into the new root of
  77          * the tree without having to clone the child.
  78          */
  79         virtual void detach()=0;
  80
  81         /**
  82          * Gets the QName for this element.  This QName <strong>MUST</strong>
  83          * contain the namespace URI, namespace prefix, and local element name.
  84          *
  85          * @return constant reference to the QName for this object
  86          */
  87         virtual const QName& getElementQName() const=0;
  88
  89         /**
  90          * Gets the namespaces that are scoped to this element.
  91          *
  92          * The caller MUST NOT modify the set returned, but may use any
  93          * non-modifying operations or algorithms on it. Iterators will
  94          * remain valid unless the set member referenced is removed using
  95          * the removeNamespace method.
  96          *
  97          * @return the namespaces that are scoped to this element
  98          */
  99         virtual const std::set<Namespace>& getNamespaces() const=0;
 100
 101         /**
 102          * Adds a namespace to the ones already scoped to this element
 103          *
 104          * @param ns the namespace to add
 105          */
 106         virtual void addNamespace(const Namespace& ns) const=0;
 107
 108         /**
 109          * Removes a namespace from this element
 110          *
 111          * @param ns the namespace to remove
 112          */
 113         virtual void removeNamespace(const Namespace& ns)=0;
 114
 115         /**
 116          * Gets the XML schema type of this element.  This translates to contents the xsi:type
 117          * attribute for the element.
 118          *
 119          * @return XML schema type of this element
 120          */
 121         virtual const QName* getSchemaType() const=0;
 122
 123         /**
 124          * Gets the value of the ID attribute set on this object, if any.
 125          *
 126          * @return an ID value or NULL
 127          */
 128         virtual const XMLCh* getXMLID() const=0;
 129
 130         /**
 131          * Checks to see if this object has a parent.
 132          *
 133          * @return true if the object has a parent, false if not
 134          */
 135         virtual bool hasParent() const=0;
 136
 137         /**
 138          * Gets the parent of this element or null if there is no parent.
 139          *
 140          * @return the parent of this element or null
 141          */
 142         virtual XMLObject* getParent() const=0;
 143
 144         /**
 145          * Sets the parent of this element.
 146          *
 147          * @param parent the parent of this element
 148          */
 149         virtual void setParent(XMLObject* parent)=0;
 150
 151         /**
 152          * Checks if this XMLObject has children.
 153          *
 154          * @return true if this XMLObject has children, false if not
 155          */
 156         virtual bool hasChildren() const=0;
 157
 158         /**
 159          * Returns an unmodifiable list of child objects in the order that they
 160          * should appear in the serialized representation.
 161          *
 162          * The validity of the returned list is not maintained if any non-const
 163          * operations are performed on the parent object.
 164          *
 165          * @return the list of children
 166          */
 167         virtual const std::list<XMLObject*>& getOrderedChildren() const=0;
 168
 169         /**
 170          * Used by a child's detach method to isolate the child from
 171          * this parent object in preparation for destroying the parent
 172          * (this object).
 173          *
 174          * @param child the child object to remove
 175          */
 176         virtual void removeChild(XMLObject* child)=0;
 177
 178         /**
 179          * Returns the text content at the specified position relative to
 180          * any child elements. A zero represents leading text, 1 comes after
 181          * the first child, and so forth.
 182          *
 183          * @param position  the relative child element position of the text
 184          * @return the designated text value
 185          */
 186         virtual const XMLCh* getTextContent(unsigned int position=0) const=0;
 187
 188         /**
 189          * Sets (or clears) text content relative to a child element's position.
 190          *
 191          * @param value         value to set, or NULL to clear
 192          * @param position      position relative to child element
 193          */
 194         virtual void setTextContent(const XMLCh* value, unsigned int position=0)=0;
 195
 196         /**
 197          * Gets the DOM representation of this XMLObject, if one exists.
 198          *
 199          * @return the DOM representation of this XMLObject
 200          */
 201         virtual DOMElement* getDOM() const=0;
 202
 203         /**
 204          * Sets the DOM representation of this XMLObject.
 205          *
 206          * @param dom       DOM representation of this XMLObject
 207          * @param bindDocument  true if the object should take ownership of the associated Document
 208          */
 209         virtual void setDOM(DOMElement* dom, bool bindDocument=false) const=0;
 210
 211         /**
 212          * Assigns ownership of a DOM document to the XMLObject.
 213          * This binds the lifetime of the document to the lifetime of the object.
 214          *
 215          * @param doc DOM document bound to this object
 216          */
 217         virtual void setDocument(DOMDocument* doc) const=0;
 218
 219         /**
 220          * Releases the DOM representation of this XMLObject, if there is one.
 221          */
 222         virtual void releaseDOM() const=0;
 223
 224         /**
 225          * Releases the DOM representation of this XMLObject's parent.
 226          *
 227          * @param propagateRelease true if all ancestors of this element should release their DOM
 228          */
 229         virtual void releaseParentDOM(bool propagateRelease=true) const=0;
 230
 231         /**
 232          * Releases the DOM representation of this XMLObject's children.
 233          *
 234          * @param propagateRelease true if all descendants of this element should release their DOM
 235          */
 236         virtual void releaseChildrenDOM(bool propagateRelease=true) const=0;
 237
 238         /**
 239          * A convenience method that is equal to calling releaseDOM() then releaseParentDOM(true).
 240          */
 241         void releaseThisandParentDOM() const {
 242             if (getDOM()) {
 243                 releaseDOM();
 244                 releaseParentDOM(true);
 245             }
 246         }
 247
 248         /**
 249          * A convenience method that is equal to calling releaseChildrenDOM(true) then releaseDOM().
 250          */
 251         void releaseThisAndChildrenDOM() const {
 252             if (getDOM()) {
 253                 releaseChildrenDOM(true);
 254                 releaseDOM();
 255             }
 256         }
 257
 258         /**
 259          * Marshalls the XMLObject, and its children, into a DOM element.
 260          * If a document is supplied, then it will be used to create the resulting elements.
 261          * If the document does not have a Document Element set, then the resulting
 262          * element will be set as the Document Element. If no document is supplied, then
 263          * a new document will be created and bound to the lifetime of the root object being
 264          * marshalled, unless an existing DOM can be reused without creating a new document.
 265          *
 266          * @param document  the DOM document the marshalled element will be placed in, or NULL
 267          * @param sigs      ordered array of signatures to create after marshalling is complete
 268          * @param credential    optional credential to supply signing key and related info
 269          * @return the DOM element representing this XMLObject
 270          *
 271          * @throws MarshallingException thrown if there is a problem marshalling the given object
 272          * @throws SignatureException thrown if a problem occurs during signature creation
 273          */
 274         virtual DOMElement* marshall(
 275             DOMDocument* document=NULL
 276 #ifndef XMLTOOLING_NO_XMLSEC
 277             ,const std::vector<xmlsignature::Signature*>* sigs=NULL
 278             ,const Credential* credential=NULL
 279 #endif
 280             ) const=0;
 281
 282         /**
 283          * Marshalls the XMLObject and appends it as a child of the given parent element.
 284          *
 285          * <strong>NOTE:</strong> The given Element must be within a DOM tree rooted in
 286          * the Document owning the given Element.
 287          *
 288          * @param parentElement the parent element to append the resulting DOM tree
 289          * @param sigs          ordered array of signatures to create after marshalling is complete
 290          * @param credential    optional credential to supply signing key and related info
 291          * @return the marshalled element tree
 292
 293          * @throws MarshallingException thrown if the given XMLObject can not be marshalled.
 294          * @throws SignatureException thrown if a problem occurs during signature creation
 295          */
 296         virtual DOMElement* marshall(
 297             DOMElement* parentElement
 298 #ifndef XMLTOOLING_NO_XMLSEC
 299             ,const std::vector<xmlsignature::Signature*>* sigs=NULL
 300             ,const Credential* credential=NULL
 301 #endif
 302             ) const=0;
 303
 304         /**
 305          * Unmarshalls the given W3C DOM element into the XMLObject.
 306          * The root of a given XML construct should be unmarshalled with the bindDocument parameter
 307          * set to true.
 308          *
 309          * @param element       the DOM element to unmarshall
 310          * @param bindDocument  true iff the resulting XMLObject should take ownership of the DOM's Document
 311          *
 312          * @return the unmarshalled XMLObject
 313          *
 314          * @throws UnmarshallingException thrown if an error occurs unmarshalling the DOM element into the XMLObject
 315          */
 316         virtual XMLObject* unmarshall(DOMElement* element, bool bindDocument=false)=0;
 317
 318     protected:
 319         XMLObject() {}
 320     private:
 321         XMLObject& operator=(const XMLObject& src);
 322     };
 323
 324 };
 325
 326 #if defined (_MSC_VER)
 327     #pragma warning( pop )
 328 #endif
 329
 330 #endif /* __xmltooling_xmlobj_h__ */