xercesc/xinclude/XIncludeUtils.hpp

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one or more
0003  * contributor license agreements.  See the NOTICE file distributed with
0004  * this work for additional information regarding copyright ownership.
0005  * The ASF licenses this file to You under the Apache License, Version 2.0
0006  * (the "License"); you may not use this file except in compliance with
0007  * the License.  You may obtain a copy of the License at
0008  *
0009  *      http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  */
0017
0018 /*
0019  * $Id$
0020  */
0021
0022 #if !defined(XERCESC_INCLUDE_GUARD_XINCLUDEUTILS_HPP)
0023 #define XERCESC_INCLUDE_GUARD_XINCLUDEUTILS_HPP
0024
0025 #include <xercesc/util/XercesDefs.hpp>
0026 #include <xercesc/util/XMLException.hpp>
0027 #include <xercesc/dom/DOMNode.hpp>
0028 #include <xercesc/dom/DOMDocument.hpp>
0029 #include <xercesc/dom/DOMErrorHandler.hpp>
0030 #include <xercesc/framework/XMLElementDecl.hpp>
0031 #include <xercesc/xinclude/XIncludeLocation.hpp>
0032 #include <xercesc/framework/XMLErrorCodes.hpp>
0033
0034 XERCES_CPP_NAMESPACE_BEGIN
0035
0036 class XMLEntityHandler;
0037
0038 typedef struct XIncludeHistoryNode{
0039     XMLCh *URI;
0040     struct XIncludeHistoryNode *next;
0041 }XIncludeHistoryNode;
0042
0043 /**
0044   * Class implementing all the utility functions required by an XInclude parser.
0045   *
0046   * This class is designed primarily for internal use. This class implements
0047   * utility methods to be called by an XInclude parser. It is intended to encapsulate
0048   * the actual processing and recognition of XInclude components.
0049   */
0050 class XINCLUDE_EXPORT XIncludeUtils
0051 {
0052 private:
0053
0054     /** Constructor
0055      *
0056      */
0057     XIncludeUtils(XMLErrorReporter *errorReporter);
0058
0059     /** Destructor
0060      *
0061      */
0062     ~XIncludeUtils();
0063
0064      /** Parse the supplied XInclude element performing relevant XInclude functionality
0065       *
0066       * @param xincludeNode The XInclude node to parse and action
0067       * @param parsedDocument The DOMDocument to which the results of the XInclude are to be added
0068       *
0069       * @return true if the XInclude processing was successful, false if not. Note that an
0070       * XInclude that fails resulting in a successful fallback action would return true.
0071       */
0072     bool doDOMNodeXInclude(DOMNode *xincludeNode, DOMDocument *parsedDocument, XMLEntityHandler* entityResolver);
0073
0074      /** Parse an XInclude xml file into a DOMDocument node.
0075       *
0076       * @param href the location of the document to include
0077       * @param relativeHref
0078       * @param parsedDocument
0079       *
0080       * @return a newly created DOMDocument containing the parsed and actioned
0081       * href, or NULL if the document could not be loaded.
0082       */
0083     DOMDocument *doXIncludeXMLFileDOM(const XMLCh *href,
0084         const XMLCh *relativeHref,
0085         DOMNode *xincludeNode,
0086         DOMDocument *parsedDocument,
0087         XMLEntityHandler* entityResolver);
0088
0089      /** Parse an XInclude text file into a DOMText node.
0090       *
0091       * @param href the location of the document to include
0092       * @param relativeHref
0093       * @param encoding
0094       * @param parsedDocument
0095       *
0096       * @return a newly created DOMText containing the parsed and actioned
0097       * href, or NULL if the document could not be loaded.
0098       */
0099     DOMText *doXIncludeTEXTFileDOM(const XMLCh *href,
0100         const XMLCh *relativeHref,
0101         const XMLCh *encoding,
0102         DOMNode *xincludeNode,
0103         DOMDocument *parsedDocument,
0104         XMLEntityHandler* entityResolver);
0105
0106      /** Detect whether the supplied details are correct for an xi:include element
0107       *
0108       * @param name the element name
0109       * @param namespaceURI the element namespace
0110       *
0111       * @return true if details are valid for an xi:include element, false
0112       * if not.
0113       */
0114     static bool isXIIncludeElement(const XMLCh *name, const XMLCh *namespaceURI);
0115
0116      /** Detect whether the supplied details are correct for an xi:fallback element
0117       *
0118       * @param name the element name
0119       * @param namespaceURI the element namespace
0120       *
0121       * @return true if details are valid for an xi:fallback element, false
0122       * if not.
0123       */
0124     static bool isXIFallbackElement(const XMLCh *name, const XMLCh *namespaceURI);
0125
0126      /** Detect whether the supplied DOMNode is an xi:include element
0127       *
0128       * @param node The node to check
0129       *
0130       * @return true if node is an xi:include element, false
0131       * if not.
0132       */
0133     static bool isXIIncludeDOMNode(DOMNode *node);
0134
0135      /** Detect whether the supplied DOMNode is an xi:fallback element
0136       *
0137       * @param node The DOMNode to check
0138       *
0139       * @return true if node is an xi:fallback element, false
0140       * if not.
0141       */
0142     static bool isXIFallbackDOMNode(DOMNode *node);
0143
0144      /** Walk the content of the supplied source node, performing any xinclude actions
0145       * that are encountered.
0146       *
0147       * @param source A DOMNode to parse, this node may be modified by the method
0148       * @param parsedDocument the DOMDocument to which the parsed results are to be copied.
0149       *
0150       * @return true if XInclude behaviour was successfully performed on source, false if not.
0151       */
0152     bool parseDOMNodeDoingXInclude(DOMNode *source, DOMDocument *parsedDocument, XMLEntityHandler* entityResolver);
0153
0154      /** Parse the supplied URI and escape all characters as specified by
0155       * the XINclusions specification.
0156       *
0157       * @param hrefAttrValue the href to parse and escape.
0158       * @param needsDeallocating set to true if the return value needs deallocating
0159       * by the caller after use, false if the value returned is the same as the
0160       * hrefAttrValue passed in.
0161       *
0162       * @return an escaped version of hrefAttrValue or hrefAttrValue itself if
0163       * hrefAttrValue contains only valid characters.
0164       */
0165     /* 4.1.1 */
0166     const XMLCh *getEscapedHRefAttrValue(const XMLCh *hrefAttrValue, bool &needsDeallocating);
0167
0168      /** Set the accept and accept-lang parameters on HTTP requests generated while
0169       * XIncluding.
0170       *
0171       * @param acceptAttrValue
0172       * @param acceptLangAttrValue
0173       *
0174       * @return true if the values were successfully added to the HTTP request, false
0175       * if not.
0176       */
0177     /* 4.1.2 */
0178     bool setContentNegotiation(const XMLCh *acceptAttrValue, const XMLCh *acceptLangAttrValue);
0179
0180      /** Check the characters passed in are all valid characters for XInclusion
0181       * as specified at http://www.w3.org/TR/xinclude/#text-included-items
0182       *
0183       * @param includeChars the characters to parse for validity
0184       *
0185       * @return true if the includeChars parameter contains only valid characters
0186       * for inclusion, false if there are invalid characters in includeChars.
0187       */
0188     bool checkTextIsValidForInclude(XMLCh *includeChars);
0189
0190      /** Add the supplied parameter to the InclusionHistoryStack
0191       *
0192       * @param URItoAdd the URI to add to the InclusionHistoryStack/
0193       *
0194       * @return true if the URI was added, false if a problem prevented
0195       * the URI being added.
0196       */
0197     bool addDocumentURIToCurrentInclusionHistoryStack(const XMLCh *URItoAdd);
0198
0199      /** Check the XInclude InclusionHistoryStack to see if the supplied URI
0200       * has already been included. This is used to ensure that circular inclusion
0201       * chains are detected and that the inclusion mechanism does not get stuck in
0202       * a loop.
0203       *
0204       * @param toFind the URI to look up.
0205       *
0206       * @return true if the toFind parameter is found in the InclusionHistortStack,
0207       * false if the parameter is not in the stack or the stack is empty.
0208       */
0209     bool isInCurrentInclusionHistoryStack(const XMLCh *toFind);
0210
0211      /** Pop (i.e. remove and return) the top value from the InclusionHistoryStack
0212       *
0213       * @param toPop the value that is expected to be at the top of the stack, or
0214       * NULL if no checking is required.
0215       *
0216       * @return the element at the top of the stack
0217       */
0218     XIncludeHistoryNode * popFromCurrentInclusionHistoryStack(const XMLCh *toPop);
0219
0220      /** Free the internal inclusion history list.
0221       *
0222       * @return nothing
0223       */
0224     void freeInclusionHistory();
0225
0226      /** Construct and pass on an error description
0227       *
0228       * @param errorNode The DOMNode that was being parsed when the error occurred
0229       * @param errorType The severity of the error
0230       * @param errorMsg An optional message to include in the error report
0231       * @param href The URI of the document being parsed.
0232       *
0233       * @return true if the errorHandler requests continuation of parsing despite error
0234       * false if the errorHandler requests parsing end on encountering error, or it
0235       * there is no error handler.
0236       */
0237     bool reportError(const DOMNode* const errorNode
0238                      , XMLErrs::Codes errorType
0239                      , const XMLCh* const errorMsg
0240                      , const XMLCh*    const href);
0241
0242 public:
0243     /* temporarily public to facilitate helper func getBaseAttrValue */
0244     static const XMLCh fgXIBaseAttrName[];
0245 private:
0246     XIncludeHistoryNode *fIncludeHistoryHead;
0247     XMLSize_t fErrorCount;
0248     XMLErrorReporter *fErrorReporter;
0249     static const XMLCh fgXIIncludeQName[];
0250     static const XMLCh fgXIFallbackQName[];
0251     static const XMLCh fgXIIncludeHREFAttrName[];
0252     static const XMLCh fgXIIncludeParseAttrName[];
0253     static const XMLCh fgXIIncludeParseAttrXMLValue[];
0254     static const XMLCh fgXIIncludeParseAttrTextValue[];
0255     static const XMLCh fgXIIncludeXPointerAttrName[];
0256     static const XMLCh fgXIIncludeEncodingAttrName[];
0257     static const XMLCh fgXIIncludeAcceptAttrName[];
0258     static const XMLCh fgXIIncludeAcceptLanguageAttrName[];
0259     static const XMLCh fgXIIIncludeNamespaceURI[];
0260
0261     friend class XIncludeDOMDocumentProcessor;
0262     friend class AbstractDOMParser;
0263 };
0264
0265 XERCES_CPP_NAMESPACE_END
0266
0267 #endif