|
OpenTop 1.3 | |||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | Cross-Platform C++ | ||||
SUMMARY: CONSTRUCTOR | METHOD | DETAIL: CONSTRUCTOR | METHOD |
#include "ot/sax/XMLReader.h"
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")); }
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 |
virtual RefPtr< ContentHandler > getContentHandler() const=0
virtual RefPtr< DeclHandler > getDeclHandler() const=0
virtual RefPtr< DTDHandler > getDTDHandler() const=0
virtual RefPtr< EntityResolver > getEntityResolver() const=0
virtual RefPtr< ErrorHandler > getErrorHandler() const=0
virtual bool getFeature(const String& name) const=0
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.
name
- SAXNotRecognizedException
- SAXNotSupportedException
- virtual RefPtr< LexicalHandler > getLexicalHandler() const=0
virtual void parse(InputSource* pInputSource)=0
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.
pInputSource
- SAXException
- io::IOException
- virtual void parse(const String& systemId)=0
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.
systemId
- SAXException
- io::IOException
- virtual void setContentHandler(ContentHandler* pHandler)=0
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.
pHandler
- virtual void setDeclHandler(DeclHandler* pHandler)=0
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.
pHandler
- virtual void setDTDHandler(DTDHandler* pHandler)=0
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.
pHandler
- virtual void setEntityResolver(EntityResolver* pResolver)=0
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.
pHandler
- virtual void setErrorHandler(ErrorHandler* pHandler)=0
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.
pHandler
- virtual void setFeature(const String& name, bool bSet)=0
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.
name
- bSet
- SAXNotRecognizedException
- SAXNotSupportedException
- virtual void setLexicalHandler(LexicalHandler* pHandler)=0
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.
pHandler
-
|
OpenTop 1.3 | |||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | Cross-Platform C++ | ||||
SUMMARY: CONSTRUCTOR | METHOD | DETAIL: CONSTRUCTOR | METHOD |