Doc: Remove deprecated API from XML processing overview
Pick-to: 5.15 Fixes: QTBUG-83873 Change-Id: I7fce8de11a9fb09a158f7ad5e32c0fcc323dbdf1 Reviewed-by: Sona Kurazyan <sona.kurazyan@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>bb10
Kai Koehne
parent
ae4a5b9067
commit
38fafdafc9
|
|
@ -1,6 +1,6 @@
|
|||
/****************************************************************************
|
||||
**
|
||||
** Copyright (C) 2016 The Qt Company Ltd.
|
||||
** Copyright (C) 2020 The Qt Company Ltd.
|
||||
** Contact: https://www.qt.io/licensing/
|
||||
**
|
||||
** This file is part of the documentation of the Qt Toolkit.
|
||||
|
|
@ -29,7 +29,7 @@
|
|||
\group xml-tools
|
||||
\title XML Classes
|
||||
|
||||
\brief Classes that support XML, via, for example DOM and SAX.
|
||||
\brief Classes that support XML.
|
||||
|
||||
These classes are relevant to XML users.
|
||||
|
||||
|
|
@ -42,10 +42,13 @@
|
|||
|
||||
\brief An Overview of the XML processing facilities in Qt.
|
||||
|
||||
In addition to core XML support, classes for higher level querying
|
||||
and manipulation of XML data are provided by the Qt XML Patterns
|
||||
module. In the Qt SVG module, the QSvgRenderer and QSvgGenerator
|
||||
classes can read and write a subset of SVG, an XML-based file
|
||||
Qt provides two general-purpose sets of APIs to read and write well-formed
|
||||
XML: \l{XML Streaming}{stream based} and
|
||||
\l{Working with the DOM Tree}{DOM based}.
|
||||
|
||||
Qt also provides specific support for some XML dialects. For instance, the
|
||||
Qt SVG module provides the QSvgRenderer and QSvgGenerator classes to read
|
||||
and write a subset of SVG, an XML-based file
|
||||
format. Qt also provides helper functions that may be useful to
|
||||
those working with XML and XHTML: see Qt::escape() and
|
||||
Qt::convertFromPlainText().
|
||||
|
|
@ -56,7 +59,6 @@
|
|||
\li \l {Classes for XML Processing}
|
||||
\li \l {An Introduction to Namespaces}
|
||||
\li \l {XML Streaming}
|
||||
\li \l {The SAX Interface}
|
||||
\li \l {Working with the DOM Tree}
|
||||
\endlist
|
||||
|
||||
|
|
@ -202,7 +204,7 @@
|
|||
namespace prefix. In this case the local part and the qualified name
|
||||
are identical (i.e. \e chapter).
|
||||
|
||||
\sa {DOM Bookmarks Example}, {SAX Bookmarks Example}
|
||||
\sa {DOM Bookmarks Example}
|
||||
*/
|
||||
|
||||
/*!
|
||||
|
|
@ -210,13 +212,12 @@
|
|||
\title XML Streaming
|
||||
|
||||
\previouspage An Introduction to Namespaces
|
||||
\nextpage The SAX Interface
|
||||
\nextpage Working with the DOM Tree
|
||||
|
||||
Since version 4.3, Qt provides two new classes for reading and
|
||||
writing XML: QXmlStreamReader and QXmlStreamWriter.
|
||||
Qt provides two classes for reading and writing XML through a simple streaming
|
||||
API: QXmlStreamReader and QXmlStreamWriter.
|
||||
|
||||
The QXmlStreamReader and QXmlStreamWriter are two new classes provided
|
||||
in Qt 4.3 and later. A stream reader reports an XML document as a stream
|
||||
A stream reader reports an XML document as a stream
|
||||
of tokens. This differs from SAX as SAX applications provide handlers to
|
||||
receive XML events from the parser whereas the QXmlStreamReader drives the
|
||||
loop, pulling tokens from the reader when they are needed.
|
||||
|
|
@ -283,240 +284,12 @@
|
|||
\snippet streambookmarks/xbelwriter.cpp 1
|
||||
*/
|
||||
|
||||
/*!
|
||||
\page xml-sax.html
|
||||
\title The SAX interface
|
||||
|
||||
\previouspage XML Streaming
|
||||
\nextpage Working with the DOM Tree
|
||||
|
||||
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 \l{http://www.saxproject.org}.
|
||||
|
||||
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.
|
||||
|
||||
\section1 Introduction to SAX2
|
||||
|
||||
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.
|
||||
|
||||
To make it less abstract consider the following example:
|
||||
\snippet code/doc_src_qtxml.qdoc 3
|
||||
|
||||
Whilst reading (a SAX2 parser is usually referred to as "reader")
|
||||
the above document three events would be triggered:
|
||||
\list 1
|
||||
\li A start tag occurs (\c{<quote>}).
|
||||
\li Character data (i.e. text) is found, "A quotation.".
|
||||
\li An end tag is parsed (\c{</quote>}).
|
||||
\endlist
|
||||
|
||||
Each time such an event occurs the parser reports it; you can set up
|
||||
event handlers to respond to these events.
|
||||
|
||||
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 \l{Working with the DOM Tree}{DOM interface}
|
||||
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.
|
||||
|
||||
The Qt XML module provides an abstract class, \l QXmlReader, that
|
||||
defines the interface for potential SAX2 readers. Qt includes a reader
|
||||
implementation, \l QXmlSimpleReader, that is easy to adapt through
|
||||
subclassing.
|
||||
|
||||
The reader reports parsing events through special handler classes:
|
||||
\table
|
||||
\header \li Handler class \li Description
|
||||
\row \li \l QXmlContentHandler
|
||||
\li Reports events related to the content of a document (e.g. the start tag
|
||||
or characters).
|
||||
\row \li \l QXmlDTDHandler
|
||||
\li Reports events related to the DTD (e.g. notation declarations).
|
||||
\row \li \l QXmlErrorHandler
|
||||
\li Reports errors or warnings that occurred during parsing.
|
||||
\row \li \l QXmlEntityResolver
|
||||
\li Reports external entities during parsing and allows users to resolve
|
||||
external entities themselves instead of leaving it to the reader.
|
||||
\row \li \l QXmlDeclHandler
|
||||
\li Reports further DTD related events (e.g. attribute declarations).
|
||||
\row \li \l QXmlLexicalHandler
|
||||
\li Reports events related to the lexical structure of the
|
||||
document (the beginning of the DTD, comments etc.).
|
||||
\endtable
|
||||
|
||||
These classes are abstract classes describing the interface. The \l
|
||||
QXmlDefaultHandler class provides a "do nothing" default
|
||||
implementation for all of them. Therefore users only need to overload
|
||||
the QXmlDefaultHandler functions they are interested in.
|
||||
|
||||
To read input XML data a special class \l QXmlInputSource is used.
|
||||
|
||||
Apart from those already mentioned, the following SAX2 support classes
|
||||
provide additional useful functionality:
|
||||
\table
|
||||
\header \li Class \li Description
|
||||
\row \li \l QXmlAttributes
|
||||
\li Used to pass attributes in a start element event.
|
||||
\row \li \l QXmlLocator
|
||||
\li Used to obtain the actual parsing position of an event.
|
||||
\row \li \l QXmlNamespaceSupport
|
||||
\li Used to implement namespace support for a reader. Note that
|
||||
namespaces do not change the parsing behavior. They are only
|
||||
reported through the handler.
|
||||
\endtable
|
||||
|
||||
The \l{SAX Bookmarks Example} illustrates how to subclass
|
||||
QXmlDefaultHandler to read an XML bookmark file (XBEL) and
|
||||
how to generate XML by hand.
|
||||
|
||||
\section1 SAX2 Features
|
||||
|
||||
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
|
||||
\e http://xml.org/sax/features/namespace-prefixes.
|
||||
|
||||
The Qt SAX2 implementation can report whether the reader has
|
||||
particular functionality using the QXmlReader::hasFeature()
|
||||
function. Available features can be tested with QXmlReader::feature(),
|
||||
and switched on or off using QXmlReader::setFeature().
|
||||
|
||||
Consider the example
|
||||
\snippet code/doc_src_qtxml.qdoc 4
|
||||
A reader that does not support the \e
|
||||
http://xml.org/sax/features/namespace-prefixes feature would report
|
||||
the element name \e document but not its attributes \e xmlns:book and
|
||||
\e xmlns with their values. A reader with the feature \e
|
||||
http://xml.org/sax/features/namespace-prefixes reports the namespace
|
||||
attributes if the \l{QXmlReader::feature()}{feature} is
|
||||
switched on.
|
||||
|
||||
Other features include \e http://xml.org/sax/features/namespace
|
||||
(namespace processing, implies \e
|
||||
http://xml.org/sax/features/namespace-prefixes) and \e
|
||||
http://xml.org/sax/features/validation (the ability to report
|
||||
validation errors).
|
||||
|
||||
Whilst SAX2 leaves it to the user to define and implement whatever
|
||||
features are required, support for \e
|
||||
http://xml.org/sax/features/namespace (and thus \e
|
||||
http://xml.org/sax/features/namespace-prefixes) is mandantory.
|
||||
The \l QXmlSimpleReader implementation of \l QXmlReader,
|
||||
supports them, and can do namespace processing.
|
||||
|
||||
\l QXmlSimpleReader is not validating, so it
|
||||
does not support \e http://xml.org/sax/features/validation.
|
||||
|
||||
\section1 Namespace Support via Features
|
||||
|
||||
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
|
||||
\e http://xml.org/sax/features/namespaces and
|
||||
\e http://xml.org/sax/features/namespace-prefixes features.
|
||||
|
||||
They influence the reporting behavior in the following way:
|
||||
\list 1
|
||||
\li Namespace prefixes and local parts of elements and attributes can
|
||||
be reported.
|
||||
\li The qualified names of elements and attributes are reported.
|
||||
\li \l QXmlContentHandler::startPrefixMapping() and \l
|
||||
QXmlContentHandler::endPrefixMapping() are called by the reader.
|
||||
\li Attributes that declare namespaces (i.e. the attribute \e xmlns and
|
||||
attributes starting with \e{xmlns:}) are reported.
|
||||
\endlist
|
||||
|
||||
Consider the following element:
|
||||
\snippet code/doc_src_qtxml.qdoc 5
|
||||
With \e http://xml.org/sax/features/namespace-prefixes set to true
|
||||
the reader will report four attributes; but with the \e
|
||||
namespace-prefixes feature set to false only three, with the \e
|
||||
xmlns:fnord attribute defining a namespace being "invisible" to the
|
||||
reader.
|
||||
|
||||
The \e http://xml.org/sax/features/namespaces feature is responsible
|
||||
for reporting local names, namespace prefixes and URIs. With \e
|
||||
http://xml.org/sax/features/namespaces set to true the parser will
|
||||
report \e title as the local name of the \e fnord:title attribute, \e
|
||||
fnord being the namespace prefix and \e http://example.com/fnord/ as
|
||||
the namespace URI. When \e http://xml.org/sax/features/namespaces is
|
||||
false none of them are reported.
|
||||
|
||||
In the current implementation the Qt XML classes follow the definition
|
||||
that the prefix \e xmlns itself isn't associated with any namespace at all
|
||||
(see \l{http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-using}).
|
||||
Therefore even with \e http://xml.org/sax/features/namespaces and
|
||||
\e http://xml.org/sax/features/namespace-prefixes both set to true
|
||||
the reader won't return either a local name, a namespace prefix or
|
||||
a namespace URI for \e xmlns:fnord.
|
||||
|
||||
This might be changed in the future following the W3C suggestion
|
||||
\l{http://www.w3.org/2000/xmlns/}
|
||||
to associate \e xmlns with the namespace \e http://www.w3.org/2000/xmlns.
|
||||
|
||||
As the SAX2 standard suggests, \l QXmlSimpleReader defaults to having
|
||||
\e http://xml.org/sax/features/namespaces set to true and
|
||||
\e http://xml.org/sax/features/namespace-prefixes set to false.
|
||||
When changing this behavior using \l QXmlSimpleReader::setFeature()
|
||||
note that the combination of both features set to
|
||||
false is illegal.
|
||||
|
||||
\section2 Summary
|
||||
|
||||
\l QXmlSimpleReader implements the following behavior:
|
||||
|
||||
\table
|
||||
\header \li (namespaces, namespace-prefixes)
|
||||
\li Namespace prefix and local part
|
||||
\li Qualified names
|
||||
\li Prefix mapping
|
||||
\li xmlns attributes
|
||||
\row \li (true, false) \li Yes \li Yes* \li Yes \li No
|
||||
\row \li (true, true) \li Yes \li Yes \li Yes \li Yes
|
||||
\row \li (false, true) \li No* \li Yes \li No* \li Yes
|
||||
\row \li (false, false) \li {4,1} Illegal
|
||||
\endtable
|
||||
|
||||
The behavior of the entries marked with an asterisk (*) is not specified by SAX.
|
||||
|
||||
\section1 Properties
|
||||
|
||||
Properties are a more general concept. They have a unique name,
|
||||
represented as an URI, but their value is \c void*. 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.
|
||||
|
||||
The URIs used for features and properties often look like URLs, e.g.
|
||||
\c http://xml.org/sax/features/namespace. This does not mean that the
|
||||
data required is at this address. It is simply a way of defining
|
||||
unique names.
|
||||
|
||||
Anyone can define and use new SAX2 properties for their readers.
|
||||
Property support is not mandatory.
|
||||
|
||||
To set or query properties the following functions are provided: \l
|
||||
QXmlReader::setProperty(), \l QXmlReader::property() and \l
|
||||
QXmlReader::hasProperty().
|
||||
*/
|
||||
|
||||
/*!
|
||||
\page xml-dom.tml
|
||||
\title Working with the DOM Tree
|
||||
\target dom
|
||||
|
||||
\previouspage The SAX Interface
|
||||
\previouspage XML Streaming
|
||||
|
||||
DOM Level 2 is a W3C Recommendation for XML interfaces that maps the
|
||||
constituents of an XML document to a tree structure. The specification
|
||||
|
|
@ -527,7 +300,8 @@
|
|||
|
||||
DOM provides an interface to access and change the content and
|
||||
structure of an XML file. It makes a hierarchical view of the document
|
||||
(a tree view). Thus -- in contrast to the SAX2 interface -- an object
|
||||
(a tree view). Thus -- in contrast to the streaming API provided
|
||||
by QXmlStreamReader -- an object
|
||||
model of the document is resident in memory after parsing which makes
|
||||
manipulation easy.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue