<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- xml-processing.qdoc -->
<title>The SAX interface | Qt XML 5.12.6</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.12</td><td ><a href="qtxml-index.html">Qt XML</a></td><td >The SAX interface</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qtxml-index.html">Qt 5.12.6 Reference Documentation</a></td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<link rel="prev" href="xml-streaming.html" />
<link rel="next" href="xml-dom-tml.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="xml-streaming.html">XML Streaming</a>
<span class="naviSeparator"> ◦ </span>
<a class="nextPage" href="xml-dom-tml.html">Working with the DOM Tree</a>
</p><p/>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#introduction-to-sax2">Introduction to SAX2</a></li>
<li class="level1"><a href="#sax2-features">SAX2 Features</a></li>
<li class="level1"><a href="#namespace-support-via-features">Namespace Support via Features</a></li>
<li class="level2"><a href="#summary">Summary</a></li>
<li class="level1"><a href="#properties">Properties</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">The SAX interface</h1>
<span class="subtitle"></span>
<!-- $$$xml-sax.html-description -->
<div class="descr"> <a name="details"></a>
<p>SAX is an event-based standard interface for XML parsers. The Qt interface follows the design of the SAX2 Java implementation. Its naming scheme was adapted to fit the Qt naming conventions. Details on SAX2 can be found at <a href="http://www.saxproject.org">http://www.saxproject.org</a>.</p>
<p>Support for SAX2 filters and the reader factory are under development. The Qt implementation does not include the SAX1 compatibility classes present in the Java interface.</p>
<a name="introduction-to-sax2"></a>
<h2 id="introduction-to-sax2">Introduction to SAX2</h2>
<p>The SAX2 interface is an event-driven mechanism to provide the user with document information. An "event" in this context means something reported by the parser, for example, it has encountered a start tag, or an end tag, etc.</p>
<p>To make it less abstract consider the following example:</p>
<pre class="cpp">
<span class="operator"><</span>quote<span class="operator">></span>A quotation<span class="operator">.</span><span class="operator"><</span><span class="operator">/</span>quote<span class="operator">></span>
</pre>
<p>Whilst reading (a SAX2 parser is usually referred to as "reader") the above document three events would be triggered:</p>
<ol class="1" type="1"><li>A start tag occurs (<code><quote></code>).</li>
<li>Character data (i.e. text) is found, "A quotation.".</li>
<li>An end tag is parsed (<code></quote></code>).</li>
</ol>
<p>Each time such an event occurs the parser reports it; you can set up event handlers to respond to these events.</p>
<p>Whilst this is a fast and simple approach to read XML documents, manipulation is difficult because data is not stored, simply handled and discarded serially. The <a href="xml-dom-tml.html">DOM interface</a> reads in and stores the whole document in a tree structure; this takes more memory, but makes it easier to manipulate the document's structure.</p>
<p>The Qt XML module provides an abstract class, <a href="qxmlreader.html">QXmlReader</a>, that defines the interface for potential SAX2 readers. Qt includes a reader implementation, <a href="qxmlsimplereader.html">QXmlSimpleReader</a>, that is easy to adapt through subclassing.</p>
<p>The reader reports parsing events through special handler classes:</p>
<div class="table"><table class="generic">
<thead><tr class="qt-style"><th >Handler class</th><th >Description</th></tr></thead>
<tr valign="top" class="odd"><td ><a href="qxmlcontenthandler.html">QXmlContentHandler</a></td><td >Reports events related to the content of a document (e.g. the start tag or characters).</td></tr>
<tr valign="top" class="even"><td ><a href="qxmldtdhandler.html">QXmlDTDHandler</a></td><td >Reports events related to the DTD (e.g. notation declarations).</td></tr>
<tr valign="top" class="odd"><td ><a href="qxmlerrorhandler.html">QXmlErrorHandler</a></td><td >Reports errors or warnings that occurred during parsing.</td></tr>
<tr valign="top" class="even"><td ><a href="qxmlentityresolver.html">QXmlEntityResolver</a></td><td >Reports external entities during parsing and allows users to resolve external entities themselves instead of leaving it to the reader.</td></tr>
<tr valign="top" class="odd"><td ><a href="qxmldeclhandler.html">QXmlDeclHandler</a></td><td >Reports further DTD related events (e.g. attribute declarations).</td></tr>
<tr valign="top" class="even"><td ><a href="qxmllexicalhandler.html">QXmlLexicalHandler</a></td><td >Reports events related to the lexical structure of the document (the beginning of the DTD, comments etc.).</td></tr>
</table></div>
<p>These classes are abstract classes describing the interface. The <a href="qxmldefaulthandler.html">QXmlDefaultHandler</a> class provides a "do nothing" default implementation for all of them. Therefore users only need to overload the <a href="qxmldefaulthandler.html">QXmlDefaultHandler</a> functions they are interested in.</p>
<p>To read input XML data a special class <a href="qxmlinputsource.html">QXmlInputSource</a> is used.</p>
<p>Apart from those already mentioned, the following SAX2 support classes provide additional useful functionality:</p>
<div class="table"><table class="generic">
<thead><tr class="qt-style"><th >Class</th><th >Description</th></tr></thead>
<tr valign="top" class="odd"><td ><a href="qxmlattributes.html">QXmlAttributes</a></td><td >Used to pass attributes in a start element event.</td></tr>
<tr valign="top" class="even"><td ><a href="qxmllocator.html">QXmlLocator</a></td><td >Used to obtain the actual parsing position of an event.</td></tr>
<tr valign="top" class="odd"><td ><a href="qxmlnamespacesupport.html">QXmlNamespaceSupport</a></td><td >Used to implement namespace support for a reader. Note that namespaces do not change the parsing behavior. They are only reported through the handler.</td></tr>
</table></div>
<p>The <a href="qtxml-saxbookmarks-example.html">SAX Bookmarks Example</a> illustrates how to subclass <a href="qxmldefaulthandler.html">QXmlDefaultHandler</a> to read an XML bookmark file (XBEL) and how to generate XML by hand.</p>
<a name="sax2-features"></a>
<h2 id="sax2-features">SAX2 Features</h2>
<p>The behavior of an XML reader depends on its support for certain optional features. For example, a reader may have the feature "report attributes used for namespace declarations and prefixes along with the local name of a tag". Like every other feature this has a unique name represented by a URI: it is called <i>http://xml.org/sax/features/namespace-prefixes</i>.</p>
<p>The Qt SAX2 implementation can report whether the reader has particular functionality using the <a href="qxmlreader.html#hasFeature">QXmlReader::hasFeature</a>() function. Available features can be tested with <a href="qxmlreader.html#feature">QXmlReader::feature</a>(), and switched on or off using <a href="qxmlreader.html#setFeature">QXmlReader::setFeature</a>().</p>
<p>Consider the example</p>
<pre class="cpp">
<span class="operator"><</span>document xmlns:book <span class="operator">=</span> <span class="char">'http://example.com/fnord/book/'</span>
xmlns <span class="operator">=</span> <span class="char">'http://example.com/fnord/'</span> <span class="operator">></span>
</pre>
<p>A reader that does not support the <i>http://xml.org/sax/features/namespace-prefixes</i> feature would report the element name <i>document</i> but not its attributes <i>xmlns:book</i> and <i>xmlns</i> with their values. A reader with the feature <i>http://xml.org/sax/features/namespace-prefixes</i> reports the namespace attributes if the <a href="qxmlreader.html#feature">feature</a> is switched on.</p>
<p>Other features include <i>http://xml.org/sax/features/namespace</i> (namespace processing, implies <i>http://xml.org/sax/features/namespace-prefixes</i>) and <i>http://xml.org/sax/features/validation</i> (the ability to report validation errors).</p>
<p>Whilst SAX2 leaves it to the user to define and implement whatever features are required, support for <i>http://xml.org/sax/features/namespace</i> (and thus <i>http://xml.org/sax/features/namespace-prefixes</i>) is mandantory. The <a href="qxmlsimplereader.html">QXmlSimpleReader</a> implementation of <a href="qxmlreader.html">QXmlReader</a>, supports them, and can do namespace processing.</p>
<p><a href="qxmlsimplereader.html">QXmlSimpleReader</a> is not validating, so it does not support <i>http://xml.org/sax/features/validation</i>.</p>
<a name="namespace-support-via-features"></a>
<h2 id="namespace-support-via-features">Namespace Support via Features</h2>
<p>As we have seen in the previous section, we can configure the behavior of the reader when it comes to namespace processing. This is done by setting and unsetting the <i>http://xml.org/sax/features/namespaces</i> and <i>http://xml.org/sax/features/namespace-prefixes</i> features.</p>
<p>They influence the reporting behavior in the following way:</p>
<ol class="1" type="1"><li>Namespace prefixes and local parts of elements and attributes can be reported.</li>
<li>The qualified names of elements and attributes are reported.</li>
<li><a href="qxmlcontenthandler.html#startPrefixMapping">QXmlContentHandler::startPrefixMapping</a>() and <a href="qxmlcontenthandler.html#endPrefixMapping">QXmlContentHandler::endPrefixMapping</a>() are called by the reader.</li>
<li>Attributes that declare namespaces (i.e. the attribute <i>xmlns</i> and attributes starting with <i>xmlns:</i>) are reported.</li>
</ol>
<p>Consider the following element:</p>
<pre class="cpp">
<span class="operator"><</span>author xmlns:fnord <span class="operator">=</span> <span class="char">'http://example.com/fnord/'</span>
title<span class="operator">=</span><span class="string">"Ms"</span>
fnord:title<span class="operator">=</span><span class="string">"Goddess"</span>
name<span class="operator">=</span><span class="string">"Eris Kallisti"</span><span class="operator">/</span><span class="operator">></span>
</pre>
<p>With <i>http://xml.org/sax/features/namespace-prefixes</i> set to true the reader will report four attributes; but with the <i>namespace-prefixes</i> feature set to false only three, with the <i>xmlns:fnord</i> attribute defining a namespace being "invisible" to the reader.</p>
<p>The <i>http://xml.org/sax/features/namespaces</i> feature is responsible for reporting local names, namespace prefixes and URIs. With <i>http://xml.org/sax/features/namespaces</i> set to true the parser will report <i>title</i> as the local name of the <i>fnord:title</i> attribute, <i>fnord</i> being the namespace prefix and <i>http://example.com/fnord/</i> as the namespace URI. When <i>http://xml.org/sax/features/namespaces</i> is false none of them are reported.</p>
<p>In the current implementation the Qt XML classes follow the definition that the prefix <i>xmlns</i> itself isn't associated with any namespace at all (see <a href="http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-using">http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-using</a>). Therefore even with <i>http://xml.org/sax/features/namespaces</i> and <i>http://xml.org/sax/features/namespace-prefixes</i> both set to true the reader won't return either a local name, a namespace prefix or a namespace URI for <i>xmlns:fnord</i>.</p>
<p>This might be changed in the future following the W3C suggestion <a href="http://www.w3.org/2000/xmlns/">http://www.w3.org/2000/xmlns/</a> to associate <i>xmlns</i> with the namespace <i>http://www.w3.org/2000/xmlns</i>.</p>
<p>As the SAX2 standard suggests, <a href="qxmlsimplereader.html">QXmlSimpleReader</a> defaults to having <i>http://xml.org/sax/features/namespaces</i> set to true and <i>http://xml.org/sax/features/namespace-prefixes</i> set to false. When changing this behavior using <a href="qxmlsimplereader.html#setFeature">QXmlSimpleReader::setFeature</a>() note that the combination of both features set to false is illegal.</p>
<a name="summary"></a>
<h3 id="summary">Summary</h3>
<p><a href="qxmlsimplereader.html">QXmlSimpleReader</a> implements the following behavior:</p>
<div class="table"><table class="generic">
<thead><tr class="qt-style"><th >(namespaces, namespace-prefixes)</th><th >Namespace prefix and local part</th><th >Qualified names</th><th >Prefix mapping</th><th >xmlns attributes</th></tr></thead>
<tr valign="top" class="odd"><td >(true, false)</td><td >Yes</td><td >Yes*</td><td >Yes</td><td >No</td></tr>
<tr valign="top" class="even"><td >(true, true)</td><td >Yes</td><td >Yes</td><td >Yes</td><td >Yes</td></tr>
<tr valign="top" class="odd"><td >(false, true)</td><td >No*</td><td >Yes</td><td >No*</td><td >Yes</td></tr>
<tr valign="top" class="even"><td >(false, false)</td><td colspan="4">Illegal</td></tr>
</table></div>
<p>The behavior of the entries marked with an asterisk (*) is not specified by SAX.</p>
<a name="properties"></a>
<h2 id="properties">Properties</h2>
<p>Properties are a more general concept. They have a unique name, represented as an URI, but their value is <code>void*</code>. Thus nearly anything can be used as a property value. This concept involves some danger, though: there is no means of ensuring type-safety; the user must take care that they pass the right type. Properties are useful if a reader supports special handler classes.</p>
<p>The URIs used for features and properties often look like URLs, e.g. <code>http://xml.org/sax/features/namespace</code>. This does not mean that the data required is at this address. It is simply a way of defining unique names.</p>
<p>Anyone can define and use new SAX2 properties for their readers. Property support is not mandatory.</p>
<p>To set or query properties the following functions are provided: <a href="qxmlreader.html#setProperty">QXmlReader::setProperty</a>(), <a href="qxmlreader.html#property">QXmlReader::property</a>() and <a href="qxmlreader.html#hasProperty">QXmlReader::hasProperty</a>().</p>
</div>
<!-- @@@xml-sax.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="xml-streaming.html">XML Streaming</a>
<span class="naviSeparator"> ◦ </span>
<a class="nextPage" href="xml-dom-tml.html">Working with the DOM Tree</a>
</p>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2019 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br/> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br/> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
d5e62c01ae8d1e579463c6a871dd44bf
>
files
>
5370
