axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From susan...@apache.org
Subject cvs commit: ws-axis/c/include/axis/server XMLParser.h
Date Mon, 14 Jun 2004 13:59:17 GMT
susantha    2004/06/14 06:59:17

  Modified:    c/include/axis/server XMLParser.h
  Log:
  Added doxygen comments to generate API documentation
  
  Revision  Changes    Path
  1.14      +64 -37    ws-axis/c/include/axis/server/XMLParser.h
  
  Index: XMLParser.h
  ===================================================================
  RCS file: /home/cvs/ws-axis/c/include/axis/server/XMLParser.h,v
  retrieving revision 1.13
  retrieving revision 1.14
  diff -u -r1.13 -r1.14
  --- XMLParser.h	24 May 2004 05:54:55 -0000	1.13
  +++ XMLParser.h	14 Jun 2004 13:59:17 -0000	1.14
  @@ -23,54 +23,81 @@
   
   /**
    * @class XMLParser
  - * @brief Interface that any parser wrapper should implement in order to be use 
  - *        in Axis as a XML PULL parser. Its the responsibility of the implementation
  - *        class to free any memory allocated inside the class. The class should not 
  - *		  deallocate either the given input stream or any memory buffers that it gets
  - *		  from the stream.
  + * @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:
       virtual ~XMLParser(){};
  -	/**
  -	 * Sets the input stream. Here the parser object should also be initialized
  -	 * to its initial state. Axis will call this function first for each input 
  -	 * stream to be parsed.
  -	 *
  -	 * @param pInputStream Input stream from which the data to be parsed taken
  -	 *		  by calling its getBytes function. Function should not deallocate
  -	 *        either pInputStream or any memory buffers that it gets.
  -	 */
  +    /**
  +     * 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;
  -	/**
  -	 * Used to get the corresponding namespace string for a given prefix.
  -	 *
  -	 * @param pcPrefix Prefix for which the namespace string is requested 
  -	 */
  +    /**
  +     * 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;
  -	/**
  -	 * Used to get the parser status. Should return AXIS_SUCCESS if nothing
  -	 * has gone wrong.
  -	 */
  +    /**
  +     * @brief  Used to get the parser status.
  +     * @return Returns AXIS_SUCCESS if nothing has gone wrong. AXIS_FAIL
  +     *         otherwise.
  +     */
       virtual int getStatus()=0;
  -	/**
  -	 * Used to get the next XML 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 considered
  -	 * valid. If the implementation of this interface is wrapping up a SAX 
  -	 * parser it should follow the above rules.
  -	 *
  -	 * @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.
  -	 */
  +    /**
  +     * Used to get the next XML 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 considered
  +     * valid. 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 @link AnyElement.h for the
  +     *         structure of AnyElement.
  +     */
       virtual const AnyElement* next(bool bIsCharData=false)=0;
   protected:
  -	AxisIOStream* m_pInputStream;
  +    AxisIOStream* m_pInputStream;
   
   };
   
  
  
  

Mime
View raw message