src/xml/XMLParser.h

/*
 *   Copyright 2003-2004 The Apache Software Foundation.
 *
 *   Licensed 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.
 */

/**
 * @file XMLParser.h
 *
 * This file contains the API that any XML parser library for Axis should
 * implement.
 *
 * @author Susantha Kumara (susantha@opensource.lk, skumara@virtusa.com)
 */
 
#if !defined(__XMLPARSER_H_OF_AXIS_INCLUDED__)
#define __XMLPARSER_H_OF_AXIS_INCLUDED__

#include "AnyElement.h"
#include "../transport/SOAPTransport.h"

#include <axis/GDefine.hpp>
#include <iostream>
#include <string>

AXIS_CPP_NAMESPACE_USE

using namespace std;

/**
 * @class XMLParser
 * @brief Interface that any parser wrapper should implement in order to be
 *        use in Axis as a XML PULL parser. This interface basically describes
 *        XML pull parsing behavior. Any SAX or DOM parser can be wrapped to
 *        expose XML pull behavior by implementing this interface. But the
 *        efficiency of the overall component depends on the particular
 *        implementaion.
 *        Its the responsibility of the implementation class to free any
 *        memory allocated inside the class. The class should not deallocate
 *        the given input stream.
 * @author Susantha Kumara (susantha@opensource.lk, skumara@virtusa.com)
 */
class XMLParser
{
public:
    /**
     * Constructor
     */
    XMLParser() 
    {
        m_pInputStream = NULL;
        m_bCanParseMore = false;
        m_iStatus = AXIS_SUCCESS;
        m_sErrorString = "";        
    }
    
    /**
     * Destructor - no-op
     */
    virtual ~XMLParser(){}
    
    /**
     * Sets the input stream. Here the parser should be prepared to start
     * parsing a new stream and hence should be initialized to its initial
     * state. Axis will call this function first for each input stream to
     * be parsed.
     *
     * @brief  Sets the input stream.
     * @pre    The stream passed MUST be an already opened stream (established
     *         connection.
     * @param  pInputStream Input stream from which the data to be parsed are
     *         read by calling its getBytes function. Function should not
     *         deallocate either pInputStream
     * @return AXIS_SUCCESS if successfull. AXIS_FAIL otherwise.
     */
    virtual int setInputStream(AxisIOStream* pInputStream)=0;
    
    /**
     * Gets the corresponding namespace string for a given prefix. The
     * Parser should store the prefix/namespace pairs that it finds and
     * valid at the current cursor position of the stream. This method
     * provides a way to get the corresponding namespace for any valid
     * prefix at the current cursor position of the pull parser.
     *
     * @brief  Gets the corresponding namespace string for a given prefix.
     * @param  pcPrefix Prefix for which the namespace string is requested
     * @return The namespace if a match is found. NULL otherwise. 
     */
    virtual const XML_Ch* getNS4Prefix(const XML_Ch* pcPrefix)=0;
    
    /**
     * @brief  Used to get the parser status.
     * @return Returns AXIS_SUCCESS if nothing has gone wrong. AXIS_FAIL
     *         otherwise.
     */
    virtual int getStatus() { return m_iStatus; }

    /**
     * @brief  Used to get the error string if status is AXIS_FAIL.
     * @return Returns error string if AXIS_FAIL, NULL otherwise.
     */
    virtual const char *getErrorString()
    {
        return (m_iStatus == AXIS_SUCCESS) ? NULL : m_sErrorString.c_str(); 
    } 

    /**
     * @brief  Used to get the parser exception code corresponding to error if 
     * status is AXIS_FAIL. See AxisException.hpp for parser error codes.
     * @return Returns exception code if AXIS_FAIL, -1 otherwise.
     */
    virtual int getErrorCode() { return (m_iStatus == AXIS_SUCCESS) ? -1 : m_iErrorCode; }     
    
    /**
     * Used to get the next XML data event. The valid events are start element, 
     * end element and character data. If we think of SAX events the processing 
     * instruction events, namespace prefix mapping events are not returned by
     * this method. If the implementation of this interface is wrapping up a 
     * SAX parser it should follow the above rules.
     *
     * As the function signature suggests the returned AnyElement is const and
     * the caller should not deallocate any member of it. Its the sole
     * responsibility of the Parser wrapper implementation to manage any memory
     * allocated by it.
     *
     * @brief  Used to get the next XML event.
     * @param  bIsCharData Indicates whether Axis is expecting a character data 
     *         event or not. If Axis is NOT expecting a character data event 
     *         (bIsCharData is false) the parser should NOT return a character 
     *         data event. Instead it should skip all character data events 
     *         until it finds a non-character data event and return it. This
     *         behaviour is needed to ignore unexpected white space of the
     *         stream.
     * @return Returns a filled AnyElement structure that contains all the data
     *         of the current XML element. See AnyElement.h for the
     *         structure of AnyElement.
     */
    virtual const AnyElement* next(bool bIsCharData=false)=0; 
    
    /**
     * Used to get the any next XML event. The valid events are start element,
     * end element, character data and prefix mappings. If we think of SAX  
     * events only processing instruction events are not returned by this
     * method. If the implementation of this interface is wrapping up a SAX 
     * parser it should follow the above rules.
     *
     * As the function signature suggests the returned AnyElement is const and
     * the caller should not deallocate any member of it. Its the sole
     * responsibility of the Parser wrapper implementation to manage any memory
     * allocated by it.
     *
     * @brief  Used to get the next XML event.
     * @return Returns a filled AnyElement structure that contains all the data
     *         of the current XML element. See AnyElement.h for the structure
     *         of AnyElement.
     */
    virtual const AnyElement* anyNext()=0;
    
    /**
     * @brief  Peek a head and get the next elemnt. Should return NULL string
     *         if last element processed was a start/end element.
     * @return Return the name of the next element. 
     */
    virtual const char* peek()=0;      

    /**
     * Gets the corresponding prefix string for a given namespace. The
     * Parser should store the prefix/namespace pairs that it finds and
     * valid at the current cursor position of the stream. This method
     * provides a way to get the corresponding prefix for any valid
     * namespace at the current cursor position of the pull parser.
     *
     * @brief  Gets the corresponding namespace string for a given prefix.
     * @param  pcNS Namespace for which the prefix string is requested
     * @return The prefix if a match is found. NULL otherwise. 
     */
    virtual const XML_Ch* getPrefix4NS(const XML_Ch* pcNS)=0;

    /**
     * @brief  Whether there is more data to parse.
     * @return true if more data to parse; false otherwise. 
     */
    virtual bool canParseMore() { return m_bCanParseMore; }
    
    /**
      * Enable trace.
      *  @param logFilePath  path to log file. 
      *  @param filters      log filters.  See common/AxisTrace.h.
      */
      virtual void enableTrace(const char* logFilePath, const char *filters) { }

protected:
    AxisIOStream* m_pInputStream;
    bool m_bCanParseMore;
    int m_iStatus;
    int m_iErrorCode;
    std::string m_sErrorString;
};

#endif