| <?xml version="1.0" standalone="no"?> |
| <!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd"> |
| |
| <s1 title="SAX2 Programming Guide"> |
| |
| <anchor name="UsingSAX2API"/> |
| <s2 title="Using the SAX2 API"> |
| <p>The SAX2 API for XML parsers was originally developed for |
| Java. Please be aware that there is no standard SAX2 API for |
| C++, and that use of the &XercesCName; SAX2 API does not |
| guarantee client code compatibility with other C++ XML |
| parsers.</p> |
| |
| <p>The SAX2 API presents a callback based API to the parser. An |
| application that uses SAX2 provides an instance of a handler |
| class to the parser. When the parser detects XML constructs, |
| it calls the methods of the handler class, passing them |
| information about the construct that was detected. The most |
| commonly used handler classes are ContentHandler which is |
| called when XML constructs are recognized, and ErrorHandler |
| which is called when an error occurs. The header files for the |
| various SAX2 handler classes are in |
| '<&XercesCInstallDir;>/include/xercesc/sax2'</p> |
| |
| <p>As a convenience, &XercesCName; provides the class |
| DefaultHandler, which is a single class which is publicly derived |
| from all the Handler classes. DefaultHandler's default |
| implementation of the handler callback methods is to do |
| nothing. A convenient way to get started with &XercesCName; is |
| to derive your own handler class from DefaultHandler and override |
| just those methods in HandlerBase which you are interested in |
| customizing. This simple example shows how to create a handler |
| which will print element names, and print fatal error |
| messages. The source code for the sample applications show |
| additional examples of how to write handler classes.</p> |
| |
| <p>This is the header file MySAX2Handler.hpp:</p> |
| <source>#include <xercesc/sax2/DefaultHandler.hpp> |
| |
| class MySAX2Handler : public DefaultHandler { |
| public: |
| void startElement( |
| const XMLCh* const uri, |
| const XMLCh* const localname, |
| const XMLCh* const qname, |
| const Attributes& attrs |
| ); |
| void fatalError(const SAXParseException&); |
| };</source> |
| |
| <p>This is the implementation file MySAX2Handler.cpp:</p> |
| |
| <source>#include "MySAX2Handler.hpp" |
| #include <iostream.h> |
| |
| MySAX2Handler::MySAX2Handler() |
| { |
| } |
| |
| MySAX2Handler::startElement(const XMLCh* const uri, |
| const XMLCh* const localname, |
| const XMLCh* const qname, |
| const Attributes& attrs) |
| { |
| char* message = XMLString::transcode(name); |
| cout << "I saw element: "<< message << endl; |
| delete [] message; |
| } |
| |
| MySAX2Handler::fatalError(const SAXParseException& exception) |
| { |
| char* message = XMLString::transcode(exception.getMessage()); |
| cout << "Fatal Error: " << message |
| << " at line: " << exception.getLineNumber() |
| << endl; |
| }</source> |
| |
| <p>The XMLCh and Attributes types are supplied by |
| &XercesCName; and are documented in the include |
| files. Examples of their usage appear in the source code to |
| the sample applications.</p> |
| </s2> |
| |
| <anchor name="SAX2XMLReader"/> |
| <s2 title="SAX2XMLReader"> |
| <anchor name="ConstructParser2"/> |
| <s3 title="Constructing an XML Reader"> |
| <p>In order to use &XercesCName; to parse XML files, you will |
| need to create an instance of the SAX2XMLReader class. The example |
| below shows the code you need in order to create an instance |
| of SAX2XMLReader. The ContentHandler and ErrorHandler instances |
| required by the SAX API are provided using the DefaultHandler |
| class supplied with &XercesCName;.</p> |
| |
| <source> |
| #include <xercesc/sax2/SAX2XMLReader.hpp> |
| #include <xercesc/sax2/XMLReaderFactory.hpp> |
| #include <xercesc/sax2/DefaultHandler.hpp> |
| #include <xercesc/util/XMLString.hpp> |
| |
| int main (int argc, char* args[]) { |
| |
| try { |
| XMLPlatformUtils::Initialize(); |
| } |
| catch (const XMLException& toCatch) { |
| char* message = XMLString::transcode(toCatch.getMessage()); |
| cout << "Error during initialization! :\n" |
| cout << "Exception message is: \n" |
| << message << "\n"; |
| delete [] message; |
| return 1; |
| } |
| |
| char* xmlFile = "x1.xml"; |
| SAX2XMLReader* parser = XMLReaderFactory::createXMLReader(); |
| parser->setFeature(XMLUni::fgSAX2CoreValidation, true) // optional |
| parser->setFeature(XMLUni::fgSAX2CoreNameSpaces, true) // optional |
| |
| DefaultHandler* defaultHandler = new DefaultHandler(); |
| parser->setContentHandler(defaultHandler); |
| parser->setErrorHandler(defaultHandler); |
| |
| try { |
| parser->parse(xmlFile); |
| } |
| catch (const XMLException& toCatch) { |
| char* message = XMLString::transcode(toCatch.getMessage()); |
| cout << "Exception message is: \n" |
| << message << "\n"; |
| delete [] message; |
| return -1; |
| } |
| catch (const SAXParseException& toCatch) { |
| char* message = XMLString::transcode(toCatch.getMessage()); |
| cout << "Exception message is: \n" |
| << message << "\n"; |
| delete [] message; |
| return -1; |
| } |
| catch (...) { |
| cout << "Unexpected Exception \n" ; |
| return -1; |
| } |
| |
| delete parser; |
| delete defaultHandler; |
| return 0; |
| }</source> |
| </s3> |
| |
| <anchor name="SAX2Features"/> |
| <s3 title="Supported Features in SAX2XMLReader"> |
| |
| <p>The behavior of the SAX2XMLReader is dependant on the values of the following features. |
| All of the features below can be set using the function <code>SAX2XMLReader::setFeature(cons XMLCh* const, const bool)</code>. |
| And can be queried using the function <code>bool SAX2XMLReader::getFeature(const XMLCh* const)</code>. |
| </p> |
| <p>None of these features can be modified in the middle of a parse, or an exception will be thrown.</p> |
| |
| <s4 title="SAX2 Features"> |
| <anchor name="namespaces"/> |
| <table> |
| <tr><th colspan="2"><em>http://xml.org/sax/features/namespaces</em></th></tr> |
| <tr><th><em>true:</em></th><td> Perform Namespace processing. </td></tr> |
| <tr><th><em>false:</em></th><td> Do not perform Namespace processing. </td></tr> |
| <tr><th><em>default:</em></th><td> true </td></tr> |
| <tr><th><em>note:</em></th><td> If the validation feature is set to true, then the |
| document must contain a grammar that supports the use of namespaces. </td></tr> |
| <tr><th><em>see:</em></th><td> |
| <link anchor="namespace-prefixes">http://xml.org/sax/features/namespace-prefixes </link> |
| </td></tr> |
| <tr><th><em>see:</em></th><td> |
| <link anchor="validation">http://xml.org/sax/features/validation</link> |
| </td></tr> |
| </table> |
| <p/> |
| |
| <anchor name="namespace-prefixes"/> |
| <table> |
| <tr><th colspan="2"><em>http://xml.org/sax/features/namespace-prefixes</em></th></tr> |
| <tr><th><em>true:</em></th><td> Report the original prefixed names and attributes used for Namespace declarations. </td></tr> |
| <tr><th><em>false:</em></th><td> Do not report attributes used for Namespace declarations, and optionally do not report original prefixed names. </td></tr> |
| <tr><th><em>default:</em></th><td> false </td></tr> |
| </table> |
| |
| <p/> |
| |
| <anchor name="validation"/> |
| <table> |
| <tr><th colspan="2"><em>http://xml.org/sax/features/validation</em></th></tr> |
| <tr><th><em>true:</em></th><td> Report all validation errors. </td></tr> |
| <tr><th><em>false:</em></th><td> Do not report validation errors. </td></tr> |
| <tr><th><em>default:</em></th><td> true </td></tr> |
| <tr><th><em>note:</em></th><td> If this feature is set to true, the document must |
| specify a grammar. If this feature is set to false and document specifies a grammar, |
| that grammar might be parsed but no validation of the document contents will be |
| performed. </td></tr> |
| <tr><th><em>see:</em></th><td> |
| <link anchor="validation-dynamic">http://apache.org/xml/features/validation/dynamic</link> |
| </td></tr> |
| <tr><th><em>see:</em></th><td> |
| <link anchor="load-external-dtd">http://apache.org/xml/features/nonvalidating/load-external-dtd</link> |
| </td></tr> |
| </table> |
| |
| </s4> |
| |
| <s4 title="Xerces Features"> |
| <anchor name="validation-dynamic"/> |
| <table> |
| <tr><th colspan="2"><em>http://apache.org/xml/features/validation/dynamic</em></th></tr> |
| <tr><th><em>true:</em></th><td> The parser will validate the document only if a grammar is specified. (http://xml.org/sax/features/validation must be true). </td></tr> |
| <tr><th><em>false:</em></th><td> Validation is determined by the state of the http://xml.org/sax/features/validation feature. </td></tr> |
| <tr><th><em>default:</em></th><td> false </td></tr> |
| <tr><th><em>see:</em></th><td> |
| <link anchor="validation">http://xml.org/sax/features/validation</link> |
| </td></tr> |
| </table> |
| |
| <p/> |
| |
| <anchor name="schema"/> |
| <table> |
| <tr><th colspan="2"><em>http://apache.org/xml/features/validation/schema</em></th></tr> |
| <tr><th><em>true:</em></th><td> Enable the parser's schema support. </td></tr> |
| <tr><th><em>false:</em></th><td> Disable the parser's schema support. </td></tr> |
| <tr><th><em>default:</em></th><td> true </td></tr> |
| <tr><th><em>note</em></th><td> If set to true, namespace processing must also be turned on. </td></tr> |
| <tr><th><em>see:</em></th><td> |
| <link anchor="namespaces">http://xml.org/sax/features/namespaces</link> |
| </td></tr> |
| </table> |
| |
| <p/> |
| |
| <table> |
| <tr><th colspan="2"><em>http://apache.org/xml/features/validation/schema-full-checking</em></th></tr> |
| <tr><th><em>true:</em></th><td> Enable full schema constraint checking, including checking |
| which may be time-consuming or memory intensive. Currently, particle unique |
| attribution constraint checking and particle derivation restriction checking |
| are controlled by this option. </td></tr> |
| <tr><th><em>false:</em></th><td> Disable full schema constraint checking. </td></tr> |
| <tr><th><em>default:</em></th><td> false </td></tr> |
| <tr><th><em>note:</em></th><td> This feature checks the Schema grammar itself for |
| additional errors that are time-consuming or memory intensive. It does <em>not</em> affect the |
| level of checking performed on document instances that use Schema grammars. </td></tr> |
| <tr><th><em>see:</em></th><td> |
| <link anchor="schema">http://apache.org/xml/features/validation/schema</link> |
| </td></tr> |
| </table> |
| |
| <p/> |
| |
| <anchor name="load-external-dtd"/> |
| <table> |
| <tr><th colspan="2"><em>http://apache.org/xml/features/nonvalidating/load-external-dtd</em></th></tr> |
| <tr><th><em>true:</em></th><td> Load the External DTD. </td></tr> |
| <tr><th><em>false:</em></th><td> Ignore the external DTD completely. </td></tr> |
| <tr><th><em>default:</em></th><td> true </td></tr> |
| <tr><th><em>note</em></th><td> This feature is ignored and DTD is always loaded when validation is on. </td></tr> |
| <tr><th><em>see:</em></th><td> |
| <link anchor="validation">http://xml.org/sax/features/validation</link> |
| </td></tr> |
| </table> |
| |
| <p/> |
| |
| <anchor name="continue-after-fatal"/> |
| <table> |
| <tr><th colspan="2"><em>http://apache.org/xml/features/continue-after-fatal-error</em></th></tr> |
| <tr><th><em>true:</em></th><td> Attempt to continue parsing after a fatal error. </td></tr> |
| <tr><th><em>false:</em></th><td> Stops parse on first fatal error. </td></tr> |
| <tr><th><em>default:</em></th><td> false </td></tr> |
| <tr><th><em>note:</em></th><td> The behavior of the parser when this feature is set to |
| true is <em>undetermined</em>! Therefore use this feature with extreme caution because |
| the parser may get stuck in an infinite loop or worse. </td></tr> |
| </table> |
| |
| <p/> |
| |
| <table> |
| <tr><th colspan="2"><em>http://apache.org/xml/features/validation-error-as-fatal</em></th></tr> |
| <tr><th><em>true:</em></th><td> The parser will treat validation error as fatal and will |
| exit depends on the state of |
| <link anchor="continue-after-fatal">http://apache.org/xml/features/continue-after-fatal-error</link>. |
| </td></tr> |
| <tr><th><em>false:</em></th><td> The parser will report the error and continue processing. </td></tr> |
| <tr><th><em>default:</em></th><td> false </td></tr> |
| <tr><th><em>note:</em></th><td> Setting this true does not mean the validation error will |
| be printed with the word "Fatal Error". It is still printed as "Error", but the parser |
| will exit if |
| <link anchor="continue-after-fatal">http://apache.org/xml/features/continue-after-fatal-error</link> |
| is set to false. </td></tr> |
| <tr><th><em>see:</em></th><td> |
| <link anchor="continue-after-fatal">http://apache.org/xml/features/continue-after-fatal-error</link> |
| </td></tr> |
| </table> |
| |
| <p/> |
| |
| <anchor name="use-cached"/> |
| <table> |
| <tr><th colspan="2"><em>http://apache.org/xml/features/validation/use-cachedGrammarInParse</em></th></tr> |
| <tr><th><em>true:</em></th><td>Use cached grammar if it exists in the pool.</td></tr> |
| <tr><th><em>false:</em></th><td>Parse the schema grammar.</td></tr> |
| <tr><th><em>default:</em></th><td> false </td></tr> |
| <tr><th><em>note:</em></th><td>If http://apache.org/xml/features/validation/cache-grammarFromParse is enabled, |
| this feature is set to true automatically. Any setting to this feature by the users is a no-op.</td></tr> |
| <tr><th><em>see:</em></th><td> |
| <link anchor="cache-grammar">http://apache.org/xml/features/validation/cache-grammarFromParse</link> |
| </td></tr> |
| </table> |
| |
| <p/> |
| |
| <anchor name="cache-grammar"/> |
| <table> |
| <tr><th colspan="2"><em>http://apache.org/xml/features/validation/cache-grammarFromParse</em></th></tr> |
| <tr><th><em>true:</em></th><td>Cache the grammar in the pool for re-use in subsequent parses.</td></tr> |
| <tr><th><em>false:</em></th><td>Do not cache the grammar in the pool</td></tr> |
| <tr><th><em>default:</em></th><td> false </td></tr> |
| <tr><th><em>note:</em></th><td> If set to true, the http://apache.org/xml/features/validation/use-cachedGrammarInParse |
| is also set to true automatically.</td></tr> |
| <tr><th><em>see:</em></th><td> |
| <link anchor="use-cached">http://apache.org/xml/features/validation/use-cachedGrammarInParse</link> |
| </td></tr> |
| </table> |
| |
| <p/> |
| |
| </s4> |
| </s3> |
| |
| <anchor name="SAX2Properties"/> |
| <s3 title="Supported Properties in SAX2XMLReader"> |
| |
| <p>The behavior of the SAX2XMLReader is dependant on the values of the following properties. |
| All of the properties below can be set using the function <code>SAX2XMLReader::setProperty(const XMLCh* const, void*)</code>. |
| It takes a void pointer as the property value. Application is required to initialize this void |
| pointer to a correct type. Please check the column "Value Type" below |
| to learn exactly what type of property value each property expects for processing. |
| Passing a void pointer that was initialized with a wrong type will lead to unexpected result. |
| If the same property is set more than once, the last one takes effect.</p> |
| |
| <p>Property values can be queried using the function <code>void* SAX2XMLReader::getFeature(const XMLCh* const)</code>. |
| The parser owns the returned pointer, and the memory allocated for the returned pointer will |
| be destroyed when the parser is deleted. To ensure accessibility of the returned information after |
| the parser is deleted, callers need to copy and store the returned information somewhere else. |
| Since the returned pointer is a generic void pointer, check the column "Value Type" below to learn |
| exactly what type of object each property returns for replication.</p> |
| |
| <p>None of these properties can be modified in the middle of a parse, or an exception will be thrown.</p> |
| |
| <s4 title="Xerces Properties"> |
| <table> |
| <tr><th colspan="2"><em>http://apache.org/xml/properties/schema/external-schemaLocation</em></th></tr> |
| <tr><th><em>Description</em></th><td> The XML Schema Recommendation explicitly states that |
| the inclusion of schemaLocation/ noNamespaceSchemaLocation attributes in the |
| instance document is only a hint; it does not mandate that these attributes |
| must be used to locate schemas. Similar situation happens to <import> |
| element in schema documents. This property allows the user to specify a list |
| of schemas to use. If the targetNamespace of a schema specified using this |
| method matches the targetNamespace of a schema occurring in the instance |
| document in schemaLocation attribute, or |
| if the targetNamespace matches the namespace attribute of <import> |
| element, the schema specified by the user using this property will |
| be used (i.e., the schemaLocation attribute in the instance document |
| or on the <import> element will be effectively ignored). </td></tr> |
| <tr><th><em>Value</em></th><td> The syntax is the same as for schemaLocation attributes |
| in instance documents: e.g, "http://www.example.com file_name.xsd". |
| The user can specify more than one XML Schema in the list. </td></tr> |
| <tr><th><em>Value Type</em></th><td> XMLCh* </td></tr> |
| </table> |
| |
| <p/> |
| <table> |
| <tr><th colspan="2"><em>http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation</em></th></tr> |
| <tr><th><em>Description</em></th><td> The XML Schema Recommendation explicitly states that |
| the inclusion of schemaLocation/ noNamespaceSchemaLocation attributes in the |
| instance document is only a hint; it does not mandate that these attributes |
| must be used to locate schemas. This property allows the user to specify the |
| no target namespace XML Schema Location externally. If specified, the instance |
| document's noNamespaceSchemaLocation attribute will be effectively ignored. </td></tr> |
| <tr><th><em>Value</em></th><td> The syntax is the same as for the noNamespaceSchemaLocation |
| attribute that may occur in an instance document: e.g."file_name.xsd". </td></tr> |
| <tr><th><em>Value Type</em></th><td> XMLCh* </td></tr> |
| </table> |
| </s4> |
| </s3> |
| </s2> |
| |
| </s1> |