classIBXMLCALL DocumentHandler

Interface for document event handling

Inheritance:

DocumentHandler


Public

[more] Constructors and destructor.
[more] The document event handler interface.


Documentation

Interface for document event handling.

This is the main interface is typically implemented by client code. If an applications implements this interface and registers it with the parser instance using the setDocumentHandler() method of the parser object, the parser will report all basic document-related events like the start of the document and occurrence of tags using this interface.

The order of the events matches the order of the information in the actual XML document.

Any given instance of this interface may be registered with only one parser at a time to parse XML content. Using a single DocumentHandler with multiple parsers will result in errors.

Application writer who do not want to implement all of the interface may use a default implementation provided by the class HandlerBase.

o Constructors and destructor.

o DocumentHandler()
Default constructor.

ovirtual ~DocumentHandler()
Destructor.

o The document event handler interface.

ovoid startDocument()
Callback notification of a start of document event.

The parser will invoke this method once before any other callback in the DocumentHandler (except an invocation of setDocumentLocator). This event notifies the client that the parsing of an XML document has commenced.

The client may signal an error by throwing an SAXException, the parser will either stop or continue parsing after the exception.

Throws:
SAXException

ovoid endDocument()
Callback notification of an end of document event.

The parser will invoke this method once as the last event of a parse. This event notifies the client that the parser has encountered the end of the XML document.

The parser will not invoke this method until it has either terminated the parse or reached the end of the input data.

The client may signal an error by throwing an SAXException, the parser will either stop or continue parsing after the exception.

Throws:
SAXException

ovoid ignorableWhitespace(const ibxmlchar* ch, unsigned int start, unsigned int length)
Callback notification of a text fragment of whitespace.

Validating parsers use this method to notify the client that a contiguous block of ignorable whitespace characters has been encountered. Non-validating parsers may use this method if capable of parsing and using content models.

As the underlying parser implementation does not do document validation and is incapable of using content models, this method will never be called, but it should be implemented by all applications in case of future implementation changes and for compability with other SAX parsers.

A conforming parser may return all contiguous whitespace data as one block or as multiple blocks. All whitespace in one block should originate in the same external entity, so that a Locator may provide valid positioning information.

The client must not read from the character array outside the range specified. Doing so results in unpredictable behaviour.

The client may signal an error by throwing an SAXException, the parser will either stop or continue parsing after the exception.

Throws:
SAXException
Parameters:
ch - A pointer to an array of characters containing the fragment of character text parsed.
start - The index into the array of characters at which the whitespace text fragment parsed begins.
length - The number of whitespace characters passed in the character array which are the subject of this notification. characters at which the whitespace text fragment parsed begins.
See Also:
characters

ovoid startElement(const ibxmlchar* name, const AttributeList& atts)
Callback notification of a start tag event.

The parser invokes this method once each time a new element start tag is encountered in th XML input source.

The client may signal an error by throwing an SAXException, the parser will either stop or continue parsing after the exception.

Throws:
SAXException
Parameters:
name - A pointer to a string containing the name of the element. If the element has an explicit namespace prefix, the prefix is part of the name.
atts - A reference to an object of the class AttributeList containing a list of all attributes declared by the element (if any). If no attributes are declared, the getLength() method of the AttributeList object will return 0.
See Also:
endElement
AttributeList

ovoid endElement(const ibxmlchar* name)
Callback notification of an end tag event.

The parser invokes this method once each time a closing element end tag is encountered in th XML input source.

The client may signal an error by throwing an SAXException, the parser will either stop or continue parsing after the exception.

Throws:
SAXException
Parameters:
name - A pointer to a string containing the name of the element. If the element has an explicit namespace prefix, the prefix is part of the name.
See Also:
startElement

ovoid characters(const ibxmlchar* ch, unsigned int start, unsigned int length)
Callback notification of a character chunk event.

The parser invokes this method to notify the client that a sequence of character text has been encountered in the XML document.

A conforming parser may return all contiguous character data as one block or as multiple blocks. All whitespace in one block should originate in the same external entity, so that a Locator may provide valid positioning information.

Non-validating parsers may report whitespace either using this method or the ignorableWhitespace() method. A validating parser must use the ignorableWhitespace() method.

As the underlying parser implementation does not do any validation, all whitespace notifications will be handled by this method.

The client must not read from the character array outside the range specified. Doing so results in unpredictable behaviour.

The client may signal an error by throwing an SAXException, the parser will either stop or continue parsing after the exception.

Throws:
SAXException
Parameters:
ch - A pointer to an array of characters containing the fragment of character text parsed.
start - The index into the array of characters at which the whitespace text fragment parsed begins.
length - The number of whitespace characters passed in the character array which are the subject of this notification. characters at which the whitespace text fragment parsed begins.
See Also:
ignorableWhitespace

ovoid processingInstruction(const ibxmlchar* target, const ibxmlchar* data)
Callback notification of a processing instruction event.

The parser invokes this method once each time it encounters a processing instruction in the XML document. Note that processing instructions may appear both before and after the root document element.

The client may signal an error by throwing an SAXException, the parser will either stop or continue parsing after the exception.

Throws:
SAXException
Parameters:
target - A pointer to a string containing the processing instruction target.
data - A pointer to a string containing the data supplied with the processing instruction, or null if no data was supplied.

ovoid setDocumentLocator(const Locator* locator)
Receive a Locator object for locating the origin of elements in the XML document being parsed.

The parser calls this method before any other DocumentHandler method. The client may use the Locator object passed from any of the callback methods in the DocumentHandler class to determine the end position of any document related event. Use of the Locator object outside of the DocumentHandler callback methods above will result in unpredictable behaviour.

Parameters:
locator - A pointer to the Locator object of the current parse.


Direct child classes:
HandlerBase
See Also:
setDocumentHandler
setDocumentHandler
setDocumentHandler

Alphabetic index Hierarchy of classes



This page was generated with the help of DOC++.