Главная · Все пространства имен · Все классы · Основные классы · Классы по группам · Модули · Функции

[Предыдущая: Модуль QtSvg] [Модули Qt] [Следующая: Модуль QtXmlPatterns]

Модуль QtXml

Модуль QtXml обеспечивает работу с потоками чтения и записи XML документов и реализацию их в форме SAX и DOM. Далее...

Классы

Подробное описание

SAX - это стандартный, основанный на событиях интерфейс для анализаторов XML. В вопросе интерфейса Qt следует версии SAX2 реализации Java. Её схема именования была адаптирована в соответствии с требованиями Qt. Подробности о SAX2 можно узнать на http://www.saxproject.org.

Поддержка фильтров SAX2 и фабрики читателей находится в стадии разработки. Реализация Qt не включает классов совместимости с SAX1, представленных в интерфейсе Java. Для получения информации о SAX2 классах в Qt, смотрите SAX2 классы в Qt.

DOM Level 2 является рекомендованным W3C для XML интерфейсов, которые рассмотривают субъекты XML как древовидную структуру. Спецификации DOM Level 2 вы можете найти в http://www.w3.org/DOM/. Для более подробной информации о DOM классах в Qt, смотрите Классы DOM в Qt.

Начиная с 4.3, Qt вводит два новых класса для чтения и записи XML: QXmlStreamReader и QXmlStreamWriter.

В добавок к поддержке ядра XML, в модуле QtXmlPatterns содержатся классы высокоуровневой обработки XML данных и запросов. В модуле QtSvg классы QSvgRenderer и QSvgGenerator могут считывать и записывать файлы SVG формата, основанного на XML. Qt также обеспечивает вспомогательные функции, которые могут быть полезны при работе с XML и XHTML: смотрите Qt::escape() и Qt::convertFromPlainText().

Дальнейшая поддержка XML обеспечивается в группе Qt Solutions, которая содержит, например, классы работы с SOAP и MML при использовании Qt XML классов.

Этот модуль - часть Полной версии Qt и Версии Qt с открытым исходным кодом.

Темы:

• Конфигурирование процесса сборки
• Классы потоков QtXml
• КлассыQt SAX2
• Введение в SAX2
• Особенности SAX2
• Особенности поддержки пространств имен
• Резюме
• Свойства
• Классы Qt DOM
• Введение в DOM
• Введение в пространства имён
• Соглашения, используемые в Qt XML документации

Конфигурирование процесса сборки

Приложения, которые используют классы Qt XML, нуждаются в конфигурировании, чтобы при сборке был включён QtXml модуль. Следующая декларация в файле проекта qmake гарантирует, что приложение будет скомпилировано и связано с данным модулем:

Для включения определений классов этого модуля используйте следующую директиву:

 #include <QtXml>

Для линковки приложения с этим модулем, добавьте в ваш qmake файл проекта .pro:

 QT += xml

Эта строка необходима, так как по умолчанию только модули QtCore и QtGui используются в процессе сборки.

Классы потоков QtXml

QXmlStreamReader и QXmlStreamWriter - два новых класса, реализованных в Qt 4.3 и выше. Поток чтения представляет XML документ как поток меток (или символов - tokens). Это отличается от SAX как приложения SAX предоставляет обработчики для получения событий XML от парсера, тогда как QXmlStreamReader прогоняет цикл, извлекая элементы из читателя когда они необходимы. Это подход выталкивания позволяет создавать рекурсивные анализаторы, позволяющие обработку XML кода разбивать на различные методы и классы.

QXmlStreamReader является анализатором правильно сформированных XML 1.0 файлов, который не включает внешние обработанные сущности. Таким образом, данные, предоставленные потоком чтения, придерживаются W3C критериев для хорошо сформированных XML, до тех пор, пока не происходит ошибки. В противном случае такие функции, как atEnd(), error() и hasError() могут быть использованы для проверки и просмотра ошибок.

В качестве примера реализации QXmlStreamReader можно привести XbelReader в QXmlStream Bookmarks Example, который является подклассом QXmlStreamReader. Конструктор принимает treeWidget в качестве параметра, и класс будет иметь специфичные для Xbel функции:

     XbelReader(QTreeWidget *treeWidget);
     ...
     void readUnknownElement();
     void readXBEL();
     void readTitle(QTreeWidgetItem *item);
     void readSeparator(QTreeWidgetItem *item);
     void readFolder(QTreeWidgetItem *item);
     void readBookmark(QTreeWidgetItem *item);

     QTreeWidgetItem *createChildItem(QTreeWidgetItem *item);

     QTreeWidget *treeWidget;
     ...

Функция read() принимает QIODevice и устанавливает его с помощью setDevice(). Функция raiseError() используется для отображения пользовательских сообщений об ошибках, включая сообщения о том, что версия файла неверна.

 bool XbelReader::read(QIODevice *device)
 {
     setDevice(device);

     while (!atEnd()) {
         readNext();

         if (isStartElement()) {
             if (name() == "xbel" && attributes().value("version") == "1.0")
                 readXBEL();
             else
                 raiseError(QObject::tr("The file is not an XBEL version 1.0 file."));
         }
     }

     return !error();
 }

В связке с QXmlStreamReader работает класс QXmlStreamWriter, который обеспечивает запись XML с помощью простого потокового API. QXmlStreamWriter работает с QIODevice и имеет специальные функции для всех XML элементов или событий, которые могут быть использованы при записи, такие как writeDTD(), writeCharacters(), writeComment() и так далее.

Для записи XML документа с помощью QXmlStreamWriter вы начинаете документ с вызова функции writeStartDocument(), а заканчиваете вызовом writeEndDocument(), который закрывает все оставшиеся открытыми теги. Теги элементов открываются с помощью writeStartDocument() и последующим вызовом writeAttribute() или writeAttributes(), потом добавляется содержимое и вызывается writeEndDocument(). Также writeEmptyElement() может быть использована для создания пустых элементов.

Содержимое элемента включает в себя текстовые символы, ссылки на сущности или вложенные элементы. Содержимое может быть записано с помощью writeCharacters(), которая также берёт на себя заботу о всех запрещённых символах или их последовательностях, функции writeEntityReference() или последующих вызовов writeStartElement().

Класс XbelWriter из QXmlStream Bookmarks Example является подклассом QXmlStreamWriter. Его функция writeFile() демонстрирует функциональность ядра QXmlStreamWriter, упомянутую выше:

 bool XbelWriter::writeFile(QIODevice *device)
 {
     setDevice(device);

     writeStartDocument();
     writeDTD("<!DOCTYPE xbel>");
     writeStartElement("xbel");
     writeAttribute("version", "1.0");
     for (int i = 0; i < treeWidget->topLevelItemCount(); ++i)
         writeItem(treeWidget->topLevelItem(i));

     writeEndDocument();
     return true;
 }

КлассыQt SAX2

Введение в SAX2

Интерфейс SAX2 представляет собой событийно-ориентированный механизм для обеспечения пользователя информацией о документе. Под "событием" в этом контексте подразумевается какое-либо сообщение от анализатора, например, встретился начальный тег, или конечный и т.д.

Чтобы сделать объяснение менее абстрактным, рассмотрим следующий пример:

 <quote>A quotation.</quote>

В процессе чтения (в SAX2 анализатор обычно называют "читатель") этого документа произойдёт три события:

1. Начало тега (<quote>).
2. Найдены символьные данные (т.е. текст), "A quotation.".
3. Конец тега (</quote>).

Каждый раз, когда происходит это событие, анализатор сообщает об этом; вы можете установить свои обработчики этих событий.

Хотя этот способ чтения XML документов является быстрым и простым, манипулирование является сложным, потому что данные не сохраняются, а просто обрабатываются и отбрасываются порциями. Интерфейс DOM читает и сохраняет целый документ в виде древовидной структуры; это требует больших затрат памяти, но делает более простым процесс манипулирования структурой документа.

Модуль Qt XML обеспечивает абстрактный класс QXmlReader, который определяет интерфейс для потенциальных SAX2 читателей. Qt включает реализацию читателя QXmlSimpleReader, который легко адаптировать под себя с помощью наследования.

Читатель сообщает о событиях обработки через специальный класс управления:

Эти абстрактные классы описывают интерфейс Класс QXmlDefaultHandler обеспечивает реализацию по умолчанию для всех обработчиков, которая ничего не делает. Потому пользователям необходимо только перегрузить те функции QXmlDefaultHandler, которые им необходимы.

Для чтения входящих XML данных используется специальный класс QXmlInputSource.

В отличие от вышеупомянутых классов, данный класс поддержки SAX2 обеспечивает дополнительные удобные функции:

Пример SAX Bookmarks example показывает, как подкласс QXmlDefaultHandler используется для чтения XML файлов закладок (XBEL) и как создаётся XML вручную.

Особенности SAX2

Поведение XML читателя зависит от его поддержки некоторых дополнительных возможностей. Например, читатель может иметь функцию "сообщать об атрибутах, использующих декларации пространства имён и префиксов наряду с локальным именем тега". Как и любая другая функциональность, эта имеет свой уникальных идентификатор, представленный в виде URI: он выглядит так http://xml.org/sax/features/namespace-prefixes.

Реализация Qt SAX2 может сообщать, какая функциональность поддерживается читателем, с помощью функции QXmlReader::hasFeature(). Доступные функции могут быть проверены с помощью QXmlReader::feature() и выключены или включены посредством QXmlReader::setFeature().

Рассмотрим пример

 <document xmlns:book = 'http://trolltech.com/fnord/book/'
           xmlns      = 'http://trolltech.com/fnord/' >

Читатель, который не поддерживает функцию http://xml.org/sax/features/namespace-prefixes, сообщит об имени элемента document, но не сообщит про его атрибуты xmlns:book xmlns и их значения. Читатель с поддержкой http://xml.org/sax/features/namespace-prefixes сообщит об этих атрибутах, если функция включена.

Другие функции состоят в http://xml.org/sax/features/namespace (обработка пространств имён, включающая http://xml.org/sax/features/namespace-prefixes) и http://xml.org/sax/features/validation (способность сообщать об ошибках проверки).

Хотя SAX2 оставляет возможность пользователю определять и осуществлять любые функции, требуется, чтобы поддержка http://xml.org/sax/features/namespace (и http://xml.org/sax/features/namespace-prefixes) была важнее. Реализация QXmlSimpleReader QXmlReader, поддерживает их, потому может обрабатывать пространства имён.

QXmlSimpleReader не производит проверок, потому не поддерживает http://xml.org/sax/features/validation.

Особенности поддержки пространств имен

Как говорилось выше, мы можем настраивать поведение читателя при обработке пространств имён. Это происходит с помощью включения или отключения http://xml.org/sax/features/namespaces и http://xml.org/sax/features/namespace-prefixes функций.

В частности, они влияют на поведение обработчика следующим образом:

1. Может быть сообщено о префиксах пространств имён и локальных частях имён элементов и атрибутов.
2. Сообщается о полных именах элементов и атрибутов.
3. Читатель вызывает QXmlContentHandler::startPrefixMapping() и QXmlContentHandler::endPrefixMapping().
4. Сообщается о атрибутах, которые объявлены в пространстве имён (т.е. атрибуте xmlns и атрибутах, начинающиеся с xmlns:).

Рассмотрим следующий элемент:

 <author xmlns:fnord = 'http://trolltech.com/fnord/'
              title="Ms"
              fnord:title="Goddess"
              name="Eris Kallisti"/>

С http://xml.org/sax/features/namespace-prefixes, установленной в true, читатель сообщио о четырёх атрибутах; а с функцией namespace-prefixes, установленной в false, только о трёх, атрибут с пространством имён xmlns:fnord не будет замечен читателем.

Функция http://xml.org/sax/features/namespaces отвечает за сообщение о локальных именах, префиксах пространств имён и URI. С http://xml.org/sax/features/namespaces, установленной в true, анализатор будет сообщать о title, как о локальном имени атрибута fnord:title, о fnord, как о префиксе, и о http://trolltech.com/fnord/, как о URI пространства имён. Когда http://xml.org/sax/features/namespaces установлена в false, ни об одном из них не было бы сообщено.

В текущей реализации Qt XML классов соблюдается определение, что префикс xmlns сам по себе не ассоциирован с каким-либо пространством имён вовсе (смотрите http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-using). Потому когда http://xml.org/sax/features/namespaces и http://xml.org/sax/features/namespace-prefixes обе установлены в true, читатель не будет возвращать локальное имя, префикс и URI пространства имён для xmlns:fnord.

Это может быть изменено в будущем, в соответствии с советом W3C http://www.w3.org/2000/xmlns/ ассоциировать xmlns с пространством имён http://www.w3.org/2000/xmlns.

Как полагает стандарт SAX2, QXmlSimpleReader по умолчанию имеет http://xml.org/sax/features/namespaces, установленным в true, и http://xml.org/sax/features/namespace-prefixes, установленным в false. Когда вы изменяете это поведение, используя QXmlSimpleReader::setFeature(), помните, что установка комбинации обоих функций в false является неверной.

Резюме

QXmlSimpleReader включает следующее поведение:

Поведение помеченных звёздочкой (*) не определено в SAX.

Свойства

Свойства являются более общим понятием Они имеют уникальное имя, представленное как URI, но их значение - void*. Таким образом, почти всё можно использовать в качестве значения свойств. Эта концепция несколько опасна: нет средств обеспечения безопасности типа; пользователь должен сам заботиться о выборе правильного типа. Свойства наиболее полезны, если читатель поддерживает специальные классы обработки.

URI, используемые для свойств, обычно выглядят как URL, т.е. http://xml.org/sax/features/namespace. Это не означает, что данные должны быть доступны по данному адресу. Это просто способ задания уникального имени.

Кто угодно может определить и использовать новые свойства SAX2 в своих читателях. Но поддержка свойств не является обязательной.

Для реализации поддержки свойств необходимо определить следующие функции: QXmlReader::setProperty(), QXmlReader::property() и QXmlReader::hasProperty().

Классы Qt DOM

Введение в DOM

DOM обеспечивает интерфейс для доступа и изменения содержимого и структуры XML файла. Он создаёт иерархическое отображение документа (в виде дерева). Эта -- в отличие о интерфейса SAX2 -- объектная модель документа составляется в памяти после анализа документа, что делает её лёгкой для изменений.

Все узлы DOM в дереве документа являются подклассами QDomNode. Сам документ представляется объектом QDomDocument.

Здесь представлены доступные классы узлов и их возможные потомки:

• QDomDocument: возможные потомки
  • QDomElement (в основном, один)
  • QDomProcessingInstruction
  • QDomComment
  • QDomDocumentType
• QDomDocumentFragment: возможные потомки
  • QDomElement
  • QDomProcessingInstruction
  • QDomComment
  • QDomText
  • QDomCDATASection
  • QDomEntityReference
• QDomDocumentType: не имеет потомков
• QDomEntityReference: возможные потомки
  • QDomElement
  • QDomProcessingInstruction
  • QDomComment
  • QDomText
  • QDomCDATASection
  • QDomEntityReference
• QDomElement: возможные потомки
  • QDomElement
  • QDomText
  • QDomComment
  • QDomProcessingInstruction
  • QDomCDATASection
  • QDomEntityReference
• QDomAttr: возможные потомки
  • QDomText
  • QDomEntityReference
• QDomProcessingInstruction: нет потомков
• QDomComment: нет потомков
• QDomText: нет потомков
• QDomCDATASection: нет потомков
• QDomEntity: возможные потомки
  • QDomElement
  • QDomProcessingInstruction
  • QDomComment
  • QDomText
  • QDomCDATASection
  • QDomEntityReference
• QDomNotation: нет потомков

С помощью двух классов коллекций QDomNodeList и QDomNamedNodeMap обеспечивается: QDomNodeList как список узлов, а QDomNamedNodeMap используется для неупорядоченного списка узлов (обычно используется для атрибутов).

Класс QDomImplementation позволяет пользователю запрашивать особенности DOM реализации.

Для начала обратитесь к документации QDomDocument. Вы можете также захотеть посмотреть пример DOM Bookmarks, который показывает, как производить чтение и запись XML файлов закладок (XBEL) с помощью DOM.

Введение в пространства имён

Части документации модуля Qt XML предполагают, что вы знакомы с пространствами имён XML. Здесь мы представляем краткое введение; переходите к Соглашения, используемые в Qt XML документации, если вы уже знаете этот материал.

Пространства имён - концепция, введённая в XML для того, чтобы позволить создание более модульной структуры. С их помощью в процессе обработки данных программное обеспечение может легко разрешить конфликты имен в XML документах.

Рассмотрим следующий пример:

 <document>
 <book>
   <title>Practical XML</title>
   <author title="Ms" name="Eris Kallisti"/>
   <chapter>
     <title>A Namespace Called fnord</title>
   </chapter>
 </book>
 </document>

Здесь мы видим три различных использования имени title. Если вы хотите обработать этот элемент, вы столкнётесь с проблемами, потому как каждый из titles должен отображаться по-разному - не смотря на то, что они имеют одно название.

Решение заключается в том, чтобы отметить первый title как название кники, то есть использовать элемент title с пространством имён и отличить его от, например, названий главы и т.д.:

 <book:title>Practical XML</book:title>

book в этом случае является префиксом prefix, обозначающий пространство имён.

До того, как мы применим пространство имён к элементу или атрибуту, мы должны его объявить.

URI пространства имён выглядит следующим образом: http://trolltech.com/fnord/book/. Это не означает, что данные должны быть доступны по данному адресу; URI используется просто для обеспечения уникальности имени.

Мы объявляем пространство имён подобно атрибутам; строго говоря, они и являются являются атрибутами. Для того, чтобы сделать, например, http://trolltech.com/fnord/ пространством имён по умолчанию xmlns, мы пишем

 xmlns="http://trolltech.com/fnord/"

Для отличия пространства имён http://trolltech.com/fnord/book/ от пространства имён по умолчанию, мы должны просто указать его префикс:

 xmlns:book="http://trolltech.com/fnord/book/"

Подобным образом объявленное пространство имён может быть к именам элементов и атрибутов с помощью префикса и разделителя ":". Мы можем увидеть это в элементе book:title.

Элемент с именем без префикса относится к пространству имён по умолчанию. Это правило не применяется для атрибутов: атрибут без префикса не принадлежит ни к одному из объявленных пространств имён XML. Атрибуты всегда принадлежат к "традиционным" именем элемента, в котором они появляются. "Традиционное" пространство имён не является пространством имён XML, оно просто означает, что все имена атрибутов одного элемента должны быть различны. Позже мы увидим, как применить пространство имён к атрибуту.

Именно поэтому нет противоречий между атрибутом title (принадлежащий элементу author) и, например, элементом title в теге chapter.

Давайте поясним это на примере:

 <document xmlns:book = 'http://trolltech.com/fnord/book/'
           xmlns      = 'http://trolltech.com/fnord/' >
 <book>
   <book:title>Practical XML</book:title>
   <book:author xmlns:fnord = 'http://trolltech.com/fnord/'
                title="Ms"
                fnord:title="Goddess"
                name="Eris Kallisti"/>
   <chapter>
     <title>A Namespace Called fnord</title>
   </chapter>
 </book>
 </document>

В элементе document мы определили два пространства имён. Пространство имён по умолчанию http://trolltech.com/fnord/ применено к элементу book, элементу chapter, элементу title и, конечно, к самому document.

Элементы book:author и book:title принадлежат пространству имён с URI http://trolltech.com/fnord/book/.

Два атрибута book:author (title и name) не имеют присвоенных пространств имён XML. Они являются частью "традиционного" пространства имён элемента book:author, это означает, что, например, использование двух атрибутов title в book:author запрещено.

В приведенном выше примере мы обходим последнее правило добавлением атрибута title пространства имён http://trolltech.com/fnord/ в book:author: fnord:title принадлежит пространству имён с префиксом fnord, который объявлен в элементе book:author.

Очевидно, что пространство имён fnord имеет то же URI, что и пространство имён по умолчанию. Итак, почему мы просто не используем пространство имён по умолчанию, которое мы объявили? Ответ на этот вопрос довольно сложен:

• атрибуты без префикса не принадлежат ни одному из пространств имён, в том числе и пространству имён по умолчанию;
• кроме того, применение префикса приведёт к конфликту title-title;
• запись xmlns:title приведёт к объявлению нового пространства имён с префиксом title, вместо применения пространства имён по умолчанию xmlns.

Благодаря классам Qt XML элементы и атрибуты могут быть доступны двумя способами: с помощью ссылки по полному имени, содержащим префикс пространства имён и "реальное" имя (или локальное имя), или с помощью комбинации локального имени и URI пространства имён.

Больше информации о пространствах имён XML вы можете найти на http://www.w3.org/TR/REC-xml-names/.

Соглашения, используемые в Qt XML документации

Следующие утверждения используются для разделения частей имён в контексте пространств имён:

• Полное имя - имя в том виде, как оно появляется в документе. (В приведённом примере book:title - полное имя.)
• Префикс пространства имён - в полном имени часть, стоящая слева от ":". (book - префикс в book:title.)
• Локальная часть имени (также называемое локальным именем) располагается справа от ":". (В нашем примере title - локальное имя в book:title.)
• URI пространства имён ("Уникальный идентификатор ресурса") является уникальным идентификатором пространства имён. Он выглядит подобно URL (например, http://trolltech.com/fnord/ ), но не требует, чтобы данные были доступны с помощью какого-либо протокола по данному адресу.

Элементы без ":" (например, chapter в примере) не имеют префикса пространства имён. В этом случае локальное и полное имя совпадают (т.е. равны chapter).

Смотрите также Пример DOM Bookmarks и Пример SAX Bookmarks.

[Предыдущая: Модуль QtSvg] [Модули Qt] [Следующая: Модуль QtXmlPatterns]