xmltooling/io/AbstractXMLObjectMarshaller.h

   1 /*
   2 *  Copyright 2001-2010 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 xmltooling/io/AbstractXMLObjectMarshaller.h
  19  *
  20  * A mix-in to implement object marshalling with DOM reuse.
  21  */
  22
  23 #ifndef __xmltooling_xmlmarshaller_h__
  24 #define __xmltooling_xmlmarshaller_h__
  25
  26 #include <xmltooling/AbstractDOMCachingXMLObject.h>
  27
  28 #if defined (_MSC_VER)
  29     #pragma warning( push )
  30     #pragma warning( disable : 4250 4251 )
  31 #endif
  32
  33 namespace xmltooling {
  34
  35     /**
  36      * A mix-in to implement object marshalling with DOM reuse.
  37      */
  38     class XMLTOOL_API AbstractXMLObjectMarshaller : public virtual AbstractXMLObject
  39     {
  40     public:
  41         virtual ~AbstractXMLObjectMarshaller();
  42
  43         xercesc::DOMElement* marshall(
  44             xercesc::DOMDocument* document=nullptr
  45 #ifndef XMLTOOLING_NO_XMLSEC
  46             ,const std::vector<xmlsignature::Signature*>* sigs=nullptr
  47             ,const Credential* credential=nullptr
  48 #endif
  49             ) const;
  50
  51         xercesc::DOMElement* marshall(
  52             xercesc::DOMElement* parentElement
  53 #ifndef XMLTOOLING_NO_XMLSEC
  54             ,const std::vector<xmlsignature::Signature*>* sigs=nullptr
  55             ,const Credential* credential=nullptr
  56 #endif
  57             ) const;
  58
  59     protected:
  60         AbstractXMLObjectMarshaller();
  61
  62         /**
  63          * Sets the given element as the Document Element of the given Document.
  64          * If the document already has a Document Element it is replaced by the given element.
  65          *
  66          * @param document the document
  67          * @param element the Element that will serve as the Document Element
  68          */
  69         void setDocumentElement(xercesc::DOMDocument* document, xercesc::DOMElement* element) const;
  70
  71 #ifndef XMLTOOLING_NO_XMLSEC
  72         /**
  73          * Marshalls the XMLObject into the given DOM Element.
  74          * The DOM Element must be within a DOM tree rooted in the owning Document.
  75          *
  76          * @param targetElement the Element into which the XMLObject is marshalled into
  77          * @param sigs          optional array of signatures to create after marshalling
  78          * @param credential    optional credential to supply signing key and related info
  79          *
  80          * @throws MarshallingException thrown if there is a problem marshalling the object
  81          * @throws SignatureException thrown if a problem occurs during signature creation
  82          */
  83         void marshallInto(
  84             xercesc::DOMElement* targetElement, const std::vector<xmlsignature::Signature*>* sigs, const Credential* credential=nullptr
  85             ) const;
  86 #else
  87         /**
  88          * Marshalls the XMLObject into the given DOM Element.
  89          * The DOM Element must be within a DOM tree rooted in the owning Document.
  90          *
  91          * @param targetElement the Element into which the XMLObject is marshalled into
  92          *
  93          * @throws MarshallingException thrown if there is a problem marshalling the object
  94          */
  95         void marshallInto(xercesc::DOMElement* targetElement) const;
  96 #endif
  97
  98         /**
  99          * Creates an xsi:type attribute, corresponding to the given type of the XMLObject, on the DOM element.
 100          *
 101          * @param domElement the DOM element
 102          *
 103          * @throws MarshallingException thrown if the type on the XMLObject is doesn't contain
 104          * a local name, prefix, and namespace URI
 105          */
 106         void marshallElementType(xercesc::DOMElement* domElement) const;
 107
 108         /**
 109          * Creates the xmlns attributes for any namespaces set on the XMLObject.
 110          *
 111          * @param domElement the DOM element the namespaces will be added to
 112          */
 113         void marshallNamespaces(xercesc::DOMElement* domElement) const;
 114
 115 #ifndef XMLTOOLING_NO_XMLSEC
 116         /**
 117          * Marshalls the text content and/or child elements of the XMLObject.
 118          *
 119          * @param domElement the DOM element that will recieved the marshalled children
 120          * @param credential    optional credential to supply signing key and related info
 121          *
 122          * @throws MarshallingException thrown if there is a problem marshalling a child element
 123          */
 124         void marshallContent(xercesc::DOMElement* domElement, const Credential* credential) const;
 125 #else
 126         /**
 127          * Marshalls the text content and/or child elements of the XMLObject.
 128          *
 129          * @param domElement the DOM element that will recieved the marshalled children
 130          *
 131          * @throws MarshallingException thrown if there is a problem marshalling a child element
 132          */
 133         void marshallContent(xercesc::DOMElement* domElement) const;
 134 #endif
 135
 136         /**
 137          * Marshalls the attributes from the XMLObject into the given DOM element.
 138          *
 139          * @param domElement the DOM Element into which attributes will be marshalled
 140          *
 141          * @throws MarshallingException thrown if there is a problem marshalling an attribute
 142          */
 143         virtual void marshallAttributes(xercesc::DOMElement* domElement) const;
 144
 145         /**
 146          * Called before marshalling in the event that a new DOM is being generated.
 147          * <p>Allows objects to adjust internal state prior to the marshalling step.
 148          */
 149         virtual void prepareForMarshalling() const;
 150     };
 151
 152 };
 153
 154 #if defined (_MSC_VER)
 155     #pragma warning( pop )
 156 #endif
 157
 158 #endif /* __xmltooling_xmlmarshaller_h__ */