Cross-Platform C++

ot::sax
class XMLReader  (abstract)

#include "ot/sax/XMLReader.h"

ot::ManagedObject Interface for reading an XML document using callbacks.

Note: despite its name, this interface does not extend the io.Reader interface, because reading XML is a fundamentally different activity than reading character data.

XMLReader is the interface that an XML parser's SAX2 driver must implement. This interface allows an application to set and query features and properties of the parser, to register event handlers for document processing, and to initiate a document parse.

All SAX interfaces are assumed to be synchronous: the parse methods must not return until parsing is complete, and readers must wait for an event-handler callback to return before reporting the next event.

Typical usage is something like this:

    RefPtr<XMLReader> rpReader = XMLReaderFactory::CreateXMLReader();
    
    // try to activate validation
    try {
        rpReader->setFeature(OT_T"("http://xml.org/sax/features/validation", true));
    }
    catch(SAXException& e) {
        Console::Err()->println(OT_T("Cannot activate validation.")); 
    }
    
    // register event handlers
    rpReader->setContentHandler(new MyContentHandler());
    rpReader->setErrorHandler(new MyErrorHandler());
    
    // parse the first document
    try {
        rpReader->parse(OT_T("http://www.foo.com/mydoc.xml"));
    }
    catch (IOException& e) {
      Console::Err()->println(OT_T("I/O exception reading XML document"));
    }
    catch (SAXException& e) {
        Console::Err()->println(OT_T("XML exception reading document"));
    }

See also:
XMLReaderFactory



Method Summary
 virtual RefPtr< ContentHandler > getContentHandler() const=0
         Return the current content handler.
 virtual RefPtr< DeclHandler > getDeclHandler() const=0
         Return the current DTD declaration event handler.
 virtual RefPtr< DTDHandler > getDTDHandler() const=0
         Return the current DTD handler.
 virtual RefPtr< EntityResolver > getEntityResolver() const=0
         Return the current entity resolver.
 virtual RefPtr< ErrorHandler > getErrorHandler() const=0
         Return the current error handler.
 virtual bool getFeature(const String& name) const=0
         Look up the value of a feature.
 virtual RefPtr< LexicalHandler > getLexicalHandler() const=0
         Return the current lexical event handler.
 virtual void parse(InputSource* pInputSource)=0
         Parse an XML document.
 virtual void parse(const String& systemId)=0
         Parse an XML document from a system identifier (URI).
 virtual void setContentHandler(ContentHandler* pHandler)=0
         Allow an application to register a content event handler.
 virtual void setDeclHandler(DeclHandler* pHandler)=0
         Allow an application to register a DTD declaration event handler.
 virtual void setDTDHandler(DTDHandler* pHandler)=0
         Allow an application to register a DTD event handler.
 virtual void setEntityResolver(EntityResolver* pResolver)=0
         Allow an application to register an entity resolver.
 virtual void setErrorHandler(ErrorHandler* pHandler)=0
         Allow an application to register an error event handler.
 virtual void setFeature(const String& name, bool bSet)=0
         Set the state of a feature.
 virtual void setLexicalHandler(LexicalHandler* pHandler)=0
         Allow an application to register a lexical event handler.

Methods inherited from class ot::ManagedObject
addRef, getRefCount, onFinalRelease, operator=, release

Method Detail

getContentHandler

virtual RefPtr< ContentHandlergetContentHandler() const=0
Return the current content handler.

Returns:
The current content handler, or null if none has been registered.
See also:
setContentHandler() , ContentHandler

getDeclHandler

virtual RefPtr< DeclHandlergetDeclHandler() const=0
Return the current DTD declaration event handler.

Returns:
The current DTD declaration event handler, or null if none has been registered.
See also:
setDeclHandler() , DeclHandler

getDTDHandler

virtual RefPtr< DTDHandlergetDTDHandler() const=0
Return the current DTD handler.

Returns:
The current DTD handler, or null if none has been registered.
See also:
setDTDHandler() , DTDHandler

getEntityResolver

virtual RefPtr< EntityResolvergetEntityResolver() const=0
Return the current entity resolver.

Returns:
The current entity resolver, or null if none has been registered.
See also:
setEntityResolver() , EntityResolver

getErrorHandler

virtual RefPtr< ErrorHandlergetErrorHandler() const=0
Return the current error handler.

Returns:
The current error handler, or null if none has been registered.
See also:
setErrorHandler() , ErrorHandler

getFeature

virtual bool getFeature(const String& name) const=0
Look up the value of a feature.

The feature name is any fully-qualified URI. It is possible for an XMLReader to recognize a feature name but to be unable to return its value.

All XMLReaders are required to recognize the http://xml.org/sax/features/namespaces and the http://xml.org/sax/features/namespace-prefixes feature names.

Some feature values may be available only in specific contexts, such as before, during, or after a parse.

See SAXFeatures for a list of the features supported by the OpenTop XMLReader.

Parameters:
name - The feature name, which is a fully-qualified URI.
Returns:
The current state of the feature (true or false).
Exceptions:
SAXNotRecognizedException - When the XMLReader does not recognize the feature name.
SAXNotSupportedException - When the XMLReader recognizes the feature name but cannot determine its value at this time.
See also:
setFeature()

getLexicalHandler

virtual RefPtr< LexicalHandlergetLexicalHandler() const=0
Return the current lexical event handler.

Returns:
The current lexical event handler, or null if none has been registered.
See also:
setLexicalHandler() , LexicalHandler

parse

virtual void parse(InputSource* pInputSource)=0
Parse an XML document.

The application can use this method to instruct the XML reader to begin parsing an XML document from any valid input source (a character stream, a byte stream, or a URI).

Applications may not invoke this method while a parse is in progress (they should create a new XMLReader instead for each nested XML document). Once a parse is complete, an application may reuse the same XMLReader object, possibly with a different input source.

During the parse, the XMLReader will provide information about the XML document through the registered event handlers.

This method is synchronous: it will not return until parsing has ended. If a client application wants to terminate parsing early, it should throw an exception from one of the event handlers.

Parameters:
pInputSource - The input source for the XML document.
Exceptions:
SAXException - Any SAX exception, usually thrown from one of the registered event handlers.
io::IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
See also:
InputSource , parse(const String& systemId) , setEntityResolver() , setDTDHandler() , setContentHandler() , setErrorHandler()

parse

virtual void parse(const String& systemId)=0
Parse an XML document from a system identifier (URI).

This method is a shortcut for the common case of reading a document from a system identifier. It is the exact equivalent of the following:

    parse(new InputSource(systemId));

If the system identifier is a URL, it should be fully resolved by the application before it is passed to the parser. URLs for the file: scheme may be relative, in which case they will be resolved relative to the current working directory.

Parameters:
systemId - The system identifier (URI).
Exceptions:
SAXException - Any SAX exception.
io::IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
See also:
parse(InputSource*)

setContentHandler

virtual void setContentHandler(ContentHandler* pHandler)=0
Allow an application to register a content event handler.

If the application does not register a content handler, all content events reported by the SAX parser will be silently ignored.

Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately.

Parameters:
pHandler - a pointer to the content handler, or null to unregister any previously registered content handler.
See also:
getContentHandler() , ContentHandler

setDeclHandler

virtual void setDeclHandler(DeclHandler* pHandler)=0
Allow an application to register a DTD declaration event handler.

If the application does not register a DTD declaration event handler, all DTD declarations reported by the SAX parser will be silently ignored.

Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately.

Parameters:
pHandler - a pointer to the DTD declaration handler, or null to unregister any previously registered DTD declaration handler.
See also:
getDeclHandler() , DeclHandler

setDTDHandler

virtual void setDTDHandler(DTDHandler* pHandler)=0
Allow an application to register a DTD event handler.

If the application does not register a DTD handler, all DTD events reported by the SAX parser will be silently ignored.

Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately.

Parameters:
pHandler - a pointer to the DTD handler, or null to unregister any previously registered DTD handler.
See also:
getDTDHandler() , DTDHandler

setEntityResolver

virtual void setEntityResolver(EntityResolver* pResolver)=0
Allow an application to register an entity resolver.

If the application does not register an entity resolver, the XMLReader will perform its own default resolution.

Applications may register a new or different resolver in the middle of a parse, and the SAX parser must begin using the new resolver immediately.

Parameters:
pHandler - a pointer to the entity resolver, or null to unregister any previously registered entity resolver.
See also:
getEntityResolver() , EntityResolver

setErrorHandler

virtual void setErrorHandler(ErrorHandler* pHandler)=0
Allow an application to register an error event handler.

If the application does not register an error handler, all non-fatal error events reported by the SAX parser will be silently ignored but fatal errors will be cause a SAXParseException to be thrown. It is highly recommended that all SAX applications implement an error handler to avoid unexpected bugs.

Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately.

Parameters:
pHandler - a pointer to the error handler or null to unregister a previously registered error handler
See also:
getErrorHandler() , ErrorHandler

setFeature

virtual void setFeature(const String& name,
                        bool bSet)=0
Set the state of a feature.

The feature name is any fully-qualified URI. It is possible for an XMLReader to recognize a feature name but to be unable to set its value.

All XMLReaders are required to support setting http://xml.org/sax/features/namespaces to true and http://xml.org/sax/features/namespace-prefixes to false.

Some feature values may be immutable or mutable only in specific contexts, such as before, during, or after a parse.

See SAXFeatures for a list of the features supported by the OpenTop XMLReader.

Parameters:
name - The feature name, which is a fully-qualified URI.
bSet - The requested state of the feature (true or false).
Exceptions:
SAXNotRecognizedException - When the XMLReader does not recognize the feature name.
SAXNotSupportedException - When the XMLReader recognizes the feature name but cannot set the requested value.
See also:
getFeature()

setLexicalHandler

virtual void setLexicalHandler(LexicalHandler* pHandler)=0
Allow an application to register a lexical event handler.

A common reason for registering a LexicalHandler is to receive notification of comments within an XML document. If the application does not register a lexical event handler, all lexical events reported by the SAX parser will be silently ignored.

Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately.

Parameters:
pHandler - a pointer to the lexical handler, or null to unregister any previously registered lexical handler.
See also:
getLexicalHandler() , LexicalHandler


Cross-Platform C++

Found a bug or missing feature? Please email us at support@elcel.com

Copyright © 2000-2003 ElCel Technology   Trademark Acknowledgements