You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by su...@apache.org on 2004/06/14 15:59:17 UTC
cvs commit: ws-axis/c/include/axis/server XMLParser.h
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;
};