src/xalanc/XercesParserLiaison/XercesParserLiaison.hpp

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements. See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the  "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
#if !defined(XercesPARSERLIAISON_HEADER_GUARD_1357924680)
#define XercesPARSERLIAISON_HEADER_GUARD_1357924680


// Base include file.  Must be first.
#include <xalanc/XercesParserLiaison/XercesParserLiaisonDefinitions.hpp>



// Standard Library header files.
#include <xalanc/Include/XalanMap.hpp>



// Xerces DOM header files
#include <xercesc/sax/ErrorHandler.hpp>



// Base class header file.
#include <xalanc/XMLSupport/XMLParserLiaison.hpp>



#if defined(XALAN_BUILD_DEPRECATED_DOM_BRIDGE)
#include <xalanc/XercesParserLiaison/Deprecated/XercesBridgeTypes.hpp>
#endif
#include <xalanc/XercesParserLiaison/XercesWrapperTypes.hpp>



namespace XERCES_CPP_NAMESPACE
{
#if XERCES_VERSION_MAJOR >= 2
    class XercesDOMParser;
#else
    class DOMParser;
#endif
    class SAXParser;
}


namespace XALAN_CPP_NAMESPACE {



class XercesDOMSupport;
#if defined(XALAN_BUILD_DEPRECATED_DOM_BRIDGE)
class XercesDocumentBridge;
#endif
class XercesDocumentWrapper;


typedef xercesc::SAXParseException    SAXParseExceptionType;


class XALAN_XERCESPARSERLIAISON_EXPORT XercesParserLiaison :
    public XMLParserLiaison,
    public ErrorHandler
{
    
public:

    typedef xercesc::SAXParser            SAXParserType;

    /**
     * Construct a XercesParserLiaison instance.
     *
     * @param theSupport instance of DOMSupport object
     *
     * @deprecated This constructor is deprecated.  Use the next constructor instead.
     */
    XercesParserLiaison(
        XercesDOMSupport&   theSupport,
        MemoryManager&      theManager XALAN_DEFAULT_MEMMGR);

    /**
     * Construct a XercesParserLiaison instance.
     */
    XercesParserLiaison(MemoryManager&  theManager XALAN_DEFAULT_MEMMGR);

    virtual
    ~XercesParserLiaison();



    // These interfaces are inherited from XMLParserLiaison...
    MemoryManager&
    getMemoryManager()
    {
        return m_externalSchemaLocation.getMemoryManager();
    }

    virtual void
    reset();

    virtual ExecutionContext*
    getExecutionContext() const;

    virtual void
    setExecutionContext(ExecutionContext&   theContext);

    virtual XalanDocument*
    parseXMLStream(
            const InputSource&      reader,
            const XalanDOMString&   identifier = XalanDOMString(XalanMemMgrs::getDummyMemMgr()));

    virtual void
    parseXMLStream(
            const InputSource&      urlInputSource,
            DocumentHandler&        handler,
            const XalanDOMString&   identifier = XalanDOMString(XalanMemMgrs::getDummyMemMgr()));

    virtual void
    destroyDocument(XalanDocument*  theDocument);

    virtual int
    getIndent() const;

    virtual void
    setIndent(int   i);

    virtual bool
    getUseValidation() const;

    virtual void
    setUseValidation(bool   b);

    virtual const XalanDOMString&
    getParserDescription(XalanDOMString&    theResult) const;

    virtual EntityResolver*
    getEntityResolver() const;

    virtual void
    setEntityResolver(EntityResolver*   resolver);

    virtual XMLEntityResolver*
    getXMLEntityResolver() const;

    virtual void
    setXMLEntityResolver(XMLEntityResolver*     resolver);

    virtual ErrorHandler*
    getErrorHandler() const;

    virtual void
    setErrorHandler(ErrorHandler*   handler);

    // These interfaces are new to XercesParserLiaison...

    /**
      * Create an instance of the Xerces default document that
      * is suitable as a raw document.  The new document instance
      * is owned by this instance and will be destroyed when this
      * instance goes out of scope, or by an explicit call to
      * destroyDocument()
      *
      * @return a pointer to the new instance
      */
    virtual DOMDocument_Type*
    createDOMFactory();

    /**
      * Destroy an instance created by a call to createDOMFactory().
      *
      * @theDocument a pointer to the instance to be destroyed
      */
    virtual void
    destroyDocument(DOMDocument_Type*   theDocument);

    /** Get the 'include ignorable whitespace' flag.
      *
      * This method returns the state of the parser's include ignorable
      * whitespace flag.
      *
      * @return 'true' if the include ignorable whitespace flag is set on
      *         the parser, 'false' otherwise.
      *
      * @see #setIncludeIgnorableWhitespace
      */
    virtual bool
    getIncludeIgnorableWhitespace() const;

    /** Set the 'include ignorable whitespace' flag
      *
      * This method allows the user to specify whether a validating parser
      * should include ignorable whitespaces as text nodes.  It has no effect
      * on non-validating parsers which always include non-markup text.
      * <p>When set to true (also the default), ignorable whitespaces will be
      * added to the DOM tree as text nodes.  The method
      * <code>DOMText::isWhitespace</code> will return true for those text
      * nodes only.
      * <p>When set to false, all ignorable whitespace will be discarded and
      * no text node is added to the DOM tree.  Note: applications intended
      * to process the "xml:space" attribute should not set this flag to false.
      *
      * @param include The new state of the include ignorable whitespace
      *                flag.
      *
      * @see #getIncludeIgnorableWhitespace
      */
    virtual void
    setIncludeIgnorableWhitespace(bool  include);

    /**
      * This method returns the state of the parser's namespace
      * handling capability.
      *
      * @return true, if the parser is currently configured to
      *         understand namespaces, false otherwise.
      *
      * @see #setDoNamespaces
      */
    virtual bool
    getDoNamespaces() const;

    /**
      * This method allows users to enable or disable the parser's
      * namespace processing. When set to true, parser starts enforcing
      * all the constraints / rules specified by the NameSpace
      * specification.
      *
      * <p>The parser's default state is: false.</p>
      *
      * <p>This flag is ignored by the underlying scanner if the installed
      * validator indicates that namespace constraints should be
      * enforced.</p>
      *
      * @param newState The value specifying whether NameSpace rules should
      *                 be enforced or not.
      *
      * @see #getDoNamespaces
      */
    virtual void
    setDoNamespaces(bool    newState);

    /**
      * This method returns the state of the parser's
      * exit-on-First-Fatal-Error flag.
      *
      * @return true, if the parser is currently configured to
      *         exit on the first fatal error, false otherwise.
      *
      * @see #setExitOnFirstFatalError
      */
    virtual bool
    getExitOnFirstFatalError() const;

    /**
      * This method allows users to set the parser's behaviour when it
      * encounters the first fatal error. If set to true, the parser
      * will exit at the first fatal error. If false, then it will
      * report the error and continue processing.
      *
      * <p>The default value is 'true' and the parser exits on the
      * first fatal error.</p>
      *
      * @param newState The value specifying whether the parser should
      *                 continue or exit when it encounters the first
      *                 fatal error.
      *
      * @see #getExitOnFirstFatalError
      */
    virtual void
    setExitOnFirstFatalError(bool   newState);

    /**
      * This method returns the location for an external schema document
      * for parsing.
      *
      * @return A string representing the location of the external schema document
      */
    virtual const XalanDOMChar*
    getExternalSchemaLocation() const;

    /**
      * This method sets the location for an external schema document
      * for parsing.
      *
      * @param location A string representing the location of the external schema document
      */
    virtual void
    setExternalSchemaLocation(const XalanDOMChar*   location);

    /**
      * This method returns the location for an external schema document
      * for parsing.
      *
      * @return A string representing the location of the external schema document
      */
    virtual const XalanDOMChar*
    getExternalNoNamespaceSchemaLocation() const;

    /**
      * This method sets the location for an external schema document
      * for parsing.
      *
      * @param location A string representing the location of the external schema document
      */
    virtual void
    setExternalNoNamespaceSchemaLocation(const XalanDOMChar*    location);

#if defined(XALAN_BUILD_DEPRECATED_DOM_BRIDGE)
    /**
     * This API is deprecated.
     *
     * Create a XalanDocument proxy for an existing Xerces document.
     * The parser liaison owns the instance, and you must not delete
     * it.  The liaison will delete it when reset() is called, or the
     * liaison is destroyed.
     *
     * @deprecated The Xerces DOM bridge is deprecated.
     * @param theXercesDocument The Xerces document.
     * @return a pointer to a new XalanDocument-derived instance.
     */
    XalanDocument*
    createDocument(const DOM_Document_Type&     theXercesDocument)
    {
        return createDocument(theXercesDocument, m_threadSafe, m_buildBridge);
    }

    /**
     * This API is deprecated.
     *
     * Create a XalanDocument proxy for an existing Xerces document.
     * The parser liaison owns the instance, and you must not delete
     * it.  The liaison will delete it when reset() is called, or the
     * liaison is destroyed.
     *
     * @deprecated The Xerces DOM bridge is deprecated.
     * @param theXercesDocument The Xerces document.
     * @param threadSafe If true, read access to the tree will be thread-safe (implies buildBridge == true).
     * @param buildBridge If true, the entire bridge structure is built.
     * @return a pointer to a new XalanDocument-derived instance.
     */
    XalanDocument*
    createDocument(
            const DOM_Document_Type&    theXercesDocument,
            bool                        threadSafe,
            bool                        buildBridge);
#endif

    /**
     * Create a XalanDocument proxy for an existing Xerces document.
     * The parser liaison owns the instance, and you must not delete
     * it.  The liaison will delete it when reset() is called, or the
     * liaison is destroyed.
     *
     * @param theXercesDocument The Xerces document.
     * @return a pointer to a new XalanDocument-derived instance.
     */
    XalanDocument*
    createDocument(const DOMDocument_Type*  theXercesDocument)
    {
        return createDocument(theXercesDocument, m_threadSafe, m_buildWrapper, m_buildMaps);
    }

    /**
     * Create a XalanDocument proxy for an existing Xerces document.
     * The parser liaison owns the instance, and you must not delete
     * it.  The liaison will delete it when reset() is called, or the
     * liaison is destroyed.
     *
     * @param theXercesDocument The Xerces document.
     * @param threadSafe If true, read access to the tree will be thread-safe (implies buildWrapper == true).
     * @param buildWrapper If true, the entire wrapper structure is built.
     * @param buildMaps If true, the map of Xerces to Xalan nodes is always built.
     * @return a pointer to a new XalanDocument-derived instance.
     */
    XalanDocument*
    createDocument(
            const DOMDocument_Type*     theXercesDocument,
            bool                        threadSafe,
            bool                        buildWrapper,
            bool                        buildMaps = false);

#if defined(XALAN_BUILD_DEPRECATED_DOM_BRIDGE)
    /**
     * This API is deprecated.
     *
     * Map a pointer to a XalanDocument instance to its implementation
     * class pointer.  Normally, you should have no reason for doing
     * this.  The liaison will return a null pointer if it did not
     * create the instance passed.
     *
     * @deprecated The Xerces DOM bridge has been deprecated.
     * @param theDocument A pointer to a XalanDocument instance.
     * @return A pointer to the XercesDocumentBridge instance.
     */
    XercesDocumentBridge*
    mapDocument(const XalanDocument*    theDocument) const;
#endif

    /**
     * Map a pointer to a XalanDocument instance to its implementation
     * class pointer.  Normally, you should have no reason for doing
     * this.  The liaison will return a null pointer if it did not
     * create the instance passed.
     *
     * @param theDocument A pointer to a XalanDocument instance.
     * @return A pointer to the XercesDocumentWrapper instance.
     */
    XercesDocumentWrapper*
    mapDocumentToWrapper(const XalanDocument*   theDocument) const;

#if defined(XALAN_BUILD_DEPRECATED_DOM_BRIDGE)
    /** 
     * This API is deprecated.
     *
     * Map a pointer to a XalanDocument instance to its corresponding
     * class pointer.  Normally, you should have no reason for doing
     * this.  The liaison will return a null pointer if it did not
     * create the instance passed.
     *
     * @deprecated The Xerces DOM bridge has been deprecated.
     * @param theDocument A pointer to a XalanDocument instance.
     * @return A pointer to the XercesDocumentBridge instance.
     */
    DOM_Document_Type
    mapXercesDocument(const XalanDocument*  theDocument) const;
#endif

    /** 
     * Map a pointer to a XalanDocument instance to its corresponding
     * class pointer.  Normally, you should have no reason for doing
     * this.  The liaison will return a null pointer if it did not
     * create the instance passed.
     *
     * @param theDocument A pointer to a XalanDocument instance.
     * @return A pointer to the XercesDocumentBridge instance.
     */
    const DOMDocument_Type*
    mapToXercesDocument(const XalanDocument*    theDocument) const;

    // Implementations for SAX ErrorHandler

    virtual void
    warning(const SAXParseExceptionType&    exception);

    virtual void
    error(const SAXParseExceptionType&  exception);
   
    virtual void
    fatalError(const SAXParseExceptionType&     exception);

    virtual void
    resetErrors();

    struct DocumentEntry
    {
#if defined(XALAN_BUILD_DEPRECATED_DOM_BRIDGE)
        bool    m_isDeprecated;

        bool
        isDeprecated() const
        {
            return m_isDeprecated;
        }
#else
        bool
        isDeprecated() const
        {
            return false;
        }
#endif

        bool    m_isOwned;

        bool
        isOwned() const
        {
            return m_isOwned;
        }

#if defined(XALAN_BUILD_DEPRECATED_DOM_BRIDGE)
        union
        {
            XercesDocumentBridge*   m_bridge;
            XercesDocumentWrapper*  m_wrapper;
        };

        DocumentEntry&
        operator=(XercesDocumentBridge*     theBridge)
        {
            m_isDeprecated = true;

            m_bridge = theBridge;

            m_isOwned = true;

            return *this;
        }

        DocumentEntry&
        operator=(XercesDocumentWrapper*    theWrapper)
        {
            m_isDeprecated = false;

            m_wrapper = theWrapper;

            m_isOwned = true;

            return *this;
        }
#else
        XercesDocumentWrapper*  m_wrapper;

        DocumentEntry&
        operator=(XercesDocumentWrapper*    theWrapper)
        {
            m_wrapper = theWrapper;

            m_isOwned = true;

            return *this;
        }
#endif
    };

    typedef XalanMap<const XalanDocument*, DocumentEntry>   DocumentMapType;

    /**
     * This API is deprecated.
     * 
     * This functions returns the state of the liaison's build-bridge-nodes flag.
     *
     * @deprecated The Xerces DOM bridge is deprecated.
     * @return true, if the bridge nodes are automatically built, false otherwise.
     */
    bool
    getBuildBridgeNodes() const
    
    {
        return m_buildBridge;
    }

    /**
     * This API is deprecated.
     *
     * This functions sets the state of the liaison's build-bridge-nodes flag.
     * This flag must be set for the document to be thread safe.  It can also be
     * set to true to increase performance.  If this flag is set to false, then
     * the thread-safe flag will also be set to false.
     *
     * @deprecated The Xerces DOM bridge is deprecated.
     * @param newState The new state for the flag.
     *
     */
    void
    setBuildBridgeNodes(bool    newState)
    {
        m_buildBridge = newState;

        if (newState == false)
        {
            m_threadSafe = false;
        }
    }

    /**
     * This functions returns the state of the liaison's build-wrapper-nodes flag.
     *
     * @return true, if the wrapper nodes are automatically built, false otherwise.
     */
    bool
    getBuildWrapperNodes() const
    
    {
        return m_buildWrapper;
    }

    /**
     * This functions sets the state of the liaison's build-wrapper-nodes flag.
     * This flag must be set for the document to be thread safe.  It can also be
     * set to true to increase performance.  If this flag is set to false, then
     * the thread-safe flag will also be set to false.
     *
     * @param newState The new state for the flag.
     *
     */
    void
    setBuildWrapperNodes(bool   newState)
    {
        m_buildWrapper = newState;

        if (newState == false)
        {
            m_threadSafe = false;
        }
    }

    /**
     * This functions returns the state of the liaison's thread-safe flag.
     * If true, documents created will be safe when data is read.  By default,
     * documents are _not_ thread-safe.
     *
     * Note -- modifications are _never_ synchronized.
     *
     * @return true, if the new documents will be thread safe, false otherwise.
     */
    bool
    getThreadSafe() const
    
    {
        return m_threadSafe;
    }

    /**
     * This functions sets the state of the liaison's thread-safe flag.
     * This flag must be set for the document to be thread safe.  If this
     * flag is set to true, then the build-bridge-nodes flag will also be
     * set to true.
     *
     * @param newState The new state for the flag.
     *
     */
    void
    setThreadSafe(bool  newState)
    {
        m_threadSafe = newState;

        if (m_threadSafe == true)
        {
            m_buildWrapper = true;
            m_buildBridge = true;
        }
    }

    /**
     * This functions returns the state of the liaison's buildMaps flag.
     * If true, maps will be created to allow mapping of Xalan<->Xerces mapping
     * in both directions for XercesWrapper classes.
     *
     * @return true, if the new documents will be built with Maps
     */
    bool
    getBuildMaps() const
    
    {
        return m_buildMaps;
    }
 
    /**
     * This functions sets the state of the liaison's buildMaps flag.
     * When this flag is true, maps will be built providing Xerces<->Xalan
     * mapping in Wrapper classes.
     *
     * @note The maps created use a large amount of memory.  If only
     * Xalan->Xerces node mapping is required, do not set this to true.
     *
     * @param newState The new state for the flag.
     *
     */
    void
    setBuildMaps(bool   newState)
    {
        m_buildMaps = newState;
    }

    typedef xercesc::XercesDOMParser  DOMParserType;

protected:

    static void
    formatErrorMessage(
            const SAXParseExceptionType&    e,
            XalanDOMString&                 theMessage);

#if defined(XALAN_BUILD_DEPRECATED_DOM_BRIDGE)
    /**
     * Create a XalanDocument proxy for an existing Xerces document.
     *
     * This API is deprecated.
     *
     * @param theXercesDocument The Xerces document.
     * @param threadSafe If true, read access to the tree will be thread-safe (implies buildBridge == true).
     * @param buildBridge If true, the entire bridge structure is built.
     * @return a pointer to a new XercesDocumentBridge instance.
     */
    XercesDocumentBridge*
    doCreateDocument(
            const DOM_Document_Type&    theXercesDocument,
            bool                        threadSafe,
            bool                        buildBridge);
#endif

    /**
     * Create a XalanDocument proxy for an existing Xerces document.
     *
     * @param theXercesDocument The Xerces document.
     * @param threadSafe If true, read access to the tree will be thread-safe (implies buildBridge == true).
     * @param buildWrapper If true, the entire bridge structure is built.
     * @param buildMaps If true, the map of Xerces to Xalan nodes is always built.
     * @return a pointer to a new XercesDocumentWrapper instance.
     */
    XercesDocumentWrapper*
    doCreateDocument(
            const DOMDocument_Type*     theXercesDocument,
            bool                        threadSafe,
            bool                        buildWrapper,
            bool                        buildMaps,
            bool                        isOwned);

private:

    void
    ensureDOMParser();

    DOMParserType*
    createDOMParser();

    SAXParserType*
    createSAXParser();



    // Data members...
    int                 m_indent;

    bool                m_useValidation;

    bool                m_includeIgnorableWhitespace;

    bool                m_doNamespaces;

    bool                m_exitOnFirstFatalError;

    EntityResolver*     m_entityResolver;

    XMLEntityResolver*  m_xmlEntityResolver;

    ErrorHandler*       m_errorHandler;

    XalanDOMString      m_externalSchemaLocation;

    XalanDOMString      m_externalNoNamespaceSchemaLocation;

    DocumentMapType     m_documentMap;

    bool                m_buildWrapper;

    bool                m_buildBridge;

    bool                m_threadSafe;

    bool                m_buildMaps;

    ExecutionContext*   m_executionContext;

    DOMParserType*      m_domParser;
};



}



#endif  // XercesPARSERLIAISON_HEADER_GUARD_1357924680