xmltooling/io/AbstractXMLObjectMarshaller.h

   1 /**
   2  * Licensed to the University Corporation for Advanced Internet
   3  * Development, Inc. (UCAID) under one or more contributor license
   4  * agreements. See the NOTICE file distributed with this work for
   5  * additional information regarding copyright ownership.
   6  *
   7  * UCAID licenses this file to you under the Apache License,
   8  * Version 2.0 (the "License"); you may not use this file except
   9  * in compliance with the License. You may obtain a copy of the
  10  * License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing,
  15  * software distributed under the License is distributed on an
  16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
  17  * either express or implied. See the License for the specific
  18  * language governing permissions and limitations under the License.
  19  */
  20
  21 /**
  22  * @file xmltooling/io/AbstractXMLObjectMarshaller.h
  23  *
  24  * A mix-in to implement object marshalling with DOM reuse.
  25  */
  26
  27 #ifndef __xmltooling_xmlmarshaller_h__
  28 #define __xmltooling_xmlmarshaller_h__
  29
  30 #include <xmltooling/AbstractDOMCachingXMLObject.h>
  31
  32 #if defined (_MSC_VER)
  33     #pragma warning( push )
  34     #pragma warning( disable : 4250 4251 )
  35 #endif
  36
  37 namespace xmltooling {
  38
  39     /**
  40      * A mix-in to implement object marshalling with DOM reuse.
  41      */
  42     class XMLTOOL_API AbstractXMLObjectMarshaller : public virtual AbstractXMLObject
  43     {
  44     public:
  45         virtual ~AbstractXMLObjectMarshaller();
  46
  47         xercesc::DOMElement* marshall(
  48             xercesc::DOMDocument* document=nullptr
  49 #ifndef XMLTOOLING_NO_XMLSEC
  50             ,const std::vector<xmlsignature::Signature*>* sigs=nullptr
  51             ,const Credential* credential=nullptr
  52 #endif
  53             ) const;
  54
  55         xercesc::DOMElement* marshall(
  56             xercesc::DOMElement* parentElement
  57 #ifndef XMLTOOLING_NO_XMLSEC
  58             ,const std::vector<xmlsignature::Signature*>* sigs=nullptr
  59             ,const Credential* credential=nullptr
  60 #endif
  61             ) const;
  62
  63     protected:
  64         AbstractXMLObjectMarshaller();
  65
  66         /**
  67          * Sets the given element as the Document Element of the given Document.
  68          * If the document already has a Document Element it is replaced by the given element.
  69          *
  70          * @param document the document
  71          * @param element the Element that will serve as the Document Element
  72          */
  73         void setDocumentElement(xercesc::DOMDocument* document, xercesc::DOMElement* element) const;
  74
  75 #ifndef XMLTOOLING_NO_XMLSEC
  76         /**
  77          * Marshalls the XMLObject into the given DOM Element.
  78          * The DOM Element must be within a DOM tree rooted in the owning Document.
  79          *
  80          * @param targetElement the Element into which the XMLObject is marshalled into
  81          * @param sigs          optional array of signatures to create after marshalling
  82          * @param credential    optional credential to supply signing key and related info
  83          *
  84          * @throws MarshallingException thrown if there is a problem marshalling the object
  85          * @throws SignatureException thrown if a problem occurs during signature creation
  86          */
  87         void marshallInto(
  88             xercesc::DOMElement* targetElement, const std::vector<xmlsignature::Signature*>* sigs, const Credential* credential=nullptr
  89             ) const;
  90 #else
  91         /**
  92          * Marshalls the XMLObject into the given DOM Element.
  93          * The DOM Element must be within a DOM tree rooted in the owning Document.
  94          *
  95          * @param targetElement the Element into which the XMLObject is marshalled into
  96          *
  97          * @throws MarshallingException thrown if there is a problem marshalling the object
  98          */
  99         void marshallInto(xercesc::DOMElement* targetElement) const;
 100 #endif
 101
 102         /**
 103          * Creates an xsi:type attribute, corresponding to the given type of the XMLObject, on the DOM element.
 104          *
 105          * @param domElement the DOM element
 106          *
 107          * @throws MarshallingException thrown if the type on the XMLObject is doesn't contain
 108          * a local name, prefix, and namespace URI
 109          */
 110         void marshallElementType(xercesc::DOMElement* domElement) const;
 111
 112         /**
 113          * Creates the xmlns attributes for any namespaces set on the XMLObject.
 114          *
 115          * @param domElement the DOM element the namespaces will be added to
 116          */
 117         void marshallNamespaces(xercesc::DOMElement* domElement) const;
 118
 119 #ifndef XMLTOOLING_NO_XMLSEC
 120         /**
 121          * Marshalls the text content and/or child elements of the XMLObject.
 122          *
 123          * @param domElement the DOM element that will recieved the marshalled children
 124          * @param credential    optional credential to supply signing key and related info
 125          *
 126          * @throws MarshallingException thrown if there is a problem marshalling a child element
 127          */
 128         void marshallContent(xercesc::DOMElement* domElement, const Credential* credential) const;
 129 #else
 130         /**
 131          * Marshalls the text content and/or child elements of the XMLObject.
 132          *
 133          * @param domElement the DOM element that will recieved the marshalled children
 134          *
 135          * @throws MarshallingException thrown if there is a problem marshalling a child element
 136          */
 137         void marshallContent(xercesc::DOMElement* domElement) const;
 138 #endif
 139
 140         /**
 141          * Marshalls the attributes from the XMLObject into the given DOM element.
 142          *
 143          * @param domElement the DOM Element into which attributes will be marshalled
 144          *
 145          * @throws MarshallingException thrown if there is a problem marshalling an attribute
 146          */
 147         virtual void marshallAttributes(xercesc::DOMElement* domElement) const;
 148
 149         /**
 150          * Called before marshalling in the event that a new DOM is being generated.
 151          * <p>Allows objects to adjust internal state prior to the marshalling step.
 152          */
 153         virtual void prepareForMarshalling() const;
 154     };
 155
 156 };
 157
 158 #if defined (_MSC_VER)
 159     #pragma warning( pop )
 160 #endif
 161
 162 #endif /* __xmltooling_xmlmarshaller_h__ */