Класс QAbstractXmlNodeModel

Класс QAbstractXmlNodeModel — это абстрактный базовый класс для моделирования не-XML данных, чтобы они выглядели как XML для QXmlQuery. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются безопасными для многопоточного доступа.

Открытые типы

Открытые функции

Защищённые функции

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

Класс QAbstractXmlNodeModel — это абстрактный базовый класс для моделирования не-XML данных, чтобы они выглядели как XML для QXmlQuery.

Класс QAbstractXmlNodeModel определяет интерфейс, который должна реализовывать модель узла, чтобы эта модель узла была доступна для движка запросов для обработки запросов XQuery. Модель узла представляет данные как структуру, которую можно запросить так, как будто данные являются XML.

Модель узла, представленная подклассом QAbstractXmlNodeModel, предназначена для доступа к ней движком запросов Qt XML Patterns. Если API кажется немного странным в некоторых местах, это потому, что функции-члены вызываются движком запросов, когда он вычисляет запрос XQuery. Они не предназначены для программирования.

Использование

QAbstractXmlNodeModel связывает произвольную структуру не-XML данных, которые будут запрошены, с хорошо определённой структурой XML-данных, понятных QXmlQuery.

Представьте себе приложение химии, которое считывает файл chemistryData, содержащий не-XML данные, представляющие химическую структуру, состоящую из молекул и атомов. Приложение будет запрашивать эти данные химии с помощью запроса XQuery, считанного из файла queryFile. Мы напишем пользовательский подкласс QAbstractXmlNodeModel (ChemistryNodeModel) , который считывает chemistryData и создает структуру данных, возможно, состоящую из объектов собственных классов molecule и atom. Очевидно, что эта структура данных не является XML. Наш пользовательский подкласс будет знать, как обойти эту не-XML структуру и представить её через интерфейс XPath Data Model.

QFile queryFile(argv[1]);
QFile chemistryData(argv[2]);
QString moleculeName = argv[3];

QXmlQuery query;
query.setQuery(&queryFile, QUrl::fromLocalFile(queryFile.fileName()));

ChemistryNodeModel myNodeModel(query.namePool(), chemistryData);
QXmlNodeModelIndex startNode = myNodeModel.nodeFor(moleculeName);
query.bindVariable("queryRoot", startNode);

QFile out;
out.open(stdout, QIODevice::WriteOnly);

QXmlSerializer serializer(query, &out);
query.evaluateTo(&serializer);

Приложение сначала создаёт экземпляр QXmlQuery и вызывает setQuery(), чтобы прочитать queryFile содержащий XQuery, который мы хотим запустить. Затем оно создаёт экземпляр нашего пользовательского класса модели узла, ChemistryNodeModel, который является подклассом QAbstractXmlNodeModel. Его конструктор вызывается с пулом имён, полученным от нашего QXmlQuery, и с chemistryFile содержащим структуру молекул и атомов, которые будут запрошены. Пул имён необходим, потому что наш пользовательский класс модели узла имеет функцию-член name(), которая возвращает имя любого узла в модели. Запрос и пользовательская модель узла должны использовать один и тот же пул имён для построения этих имён. Конструктор затем считал бы chemistryFile и построил бы структуру пользовательской модели узла.

Чтобы связать query с пользовательской моделью узла, мы должны привязать имя переменной, используемой в запросе, к узлу в модели. Затем переменная может быть использована в запросе в качестве узла начального узла. Сначала индекс индекс для желаемого начального узла извлекается путём вызова QAbstractXmlNodeModel::createIndex(). Затем индекс связывается с именем переменной, в данном случае queryRoot, путём передачи имени и индекса в QXmlQuery::bindVariable(). Запрос затем может использовать ссылку на переменную $queryRoot для ссылки на начальный узел. Обратите внимание, что если запрос использует несколько ссылок на переменные, вызов QXmlQuery::bindVariable() необходим для привязки каждого имени переменной к узлу в модели.

Запрос выполняется, когда приложение вызывает одну из функций вычисления QXmlQuery. Приложение использует QXmlQuery::evaluateTo(QAbstractXmlReceiver *), потому что оно затем использует сериализатор, чтобы вывести результат запроса в виде XML в stdout. Мы могли бы использовать QXmlQuery::evaluateTo(QXmlResultItems *) для получения списка элементов результатов или QXmlQuery::evaluateTo(QStringList *) , если запрос оценивался в последовательности xs:string значений.

Во время выполнения запроса движок итерирует по модели узлов, используя nextFromSimpleAxis(), чтобы получить индекс следующего узла для посещения. Движок может получить имя узла, вызвав name() с индексом узла. Также вызываются stringValue(), baseUri(), documentUri() и kind() при необходимости с индексом узла.

Пример демонстрирует стандартный шаблон использования подкласса QAbstractXmlNodeModel в сочетании с QXmlQuery для выполнения запроса XQuery.

1. Создайте QXmlQuery и передайте ему XQuery, который нужно запустить;
2. Создайте подкласс QAbstractXmlNodeModel или QSimpleXmlNodeModel;
3. Получите QXmlNodeModelIndex для узла в модели, с которого QXmlQuery должен начать запрос;
4. Используйте QXmlQuery::bindVariable(), чтобы связать QXmlNodeModelIndex с $variable name;
5. Вызовите одну из функций оценки QXmlQuery для выполнения запроса.

Наследование

Поскольку интерфейс модели данных XPath, представленный QAbstractXmlNodeModel, позволяет QXmlQuery работать с данными, не являющимися XML, как если бы они были XML, реализация подклассов QAbstractXmlNodeModel может потребовать значительных усилий. Класс QSimpleXmlNodeModel предназначен для упрощения реализации во многих распространенных случаях.

Безопасность потоков

Поскольку к модели узлов могут одновременно обращаться потоки в модуле Qt XML Patterns, подклассы QAbstractXmlNodeModel должны быть написаны с учётом безопасности потоков. Классы, которые упрощают реализацию безопасности потоков, включают QReadLocker и QWriteLocker.

Смотрите пример Пример файловой системы для демонстрации.

Документация типов членов

typedef QAbstractXmlNodeModel::List

A список указателей на экземпляры QAbstractXmlNodeModel.

См. также QExplicitlySharedDataPointer.

typedef QAbstractXmlNodeModel::Ptr

A указатель на экземпляр QAbstractXmlNodeModel.

См. также QExplicitlySharedDataPointer.

enum QAbstractXmlNodeModel::SimpleAxis

Четыре оси, каждая из которых содержит только один узел.

Документация функций-членов

QAbstractXmlNodeModel::QAbstractXmlNodeModel()

Конструктор по умолчанию.

[virtual] QAbstractXmlNodeModel::~QAbstractXmlNodeModel()

Деструктор.

[pure virtual protected] QVector<QXmlNodeModelIndex> QAbstractXmlNodeModel::attributes(const QXmlNodeModelIndex &element) const

Возвращает атрибуты element. Вызывающий гарантирует, что element — это элемент в этой модели узлов.

[pure virtual] QUrl QAbstractXmlNodeModel::baseUri(const QXmlNodeModelIndex &n) const

Возвращает базовый URI для узла с индексом n. Вызывающий гарантирует, что n не null и что он принадлежит узлу в этой модели узлов.

Базовый URI узла можно извлечь, используя функцию fn:base-uri(). Базовый URI обычно используется для разрешения относительных URI, которые появляются в узле или его потомках. Он соответствует возврату только URI документа, хотя это может неточно отражать основополагающие данные.

Эта функция соответствует аксессору dm:base-uri, который возвращает базовый URI в соответствии со следующим:

• Для узлов документов базовый URI и URI документа совпадают.
• Для элементов базовый URI — это URI, указанный в атрибуте xml:base элемента, если он присутствует, или он разрешается до базового URI родительского элемента.
• Узлы пространства имён не имеют базового URI.
• Базовый URI для инструкции обработки, комментария, атрибута или текстового узла — это базовый URI родительского элемента узла.

Реализация гарантирует возврат допустимого QUrl или QUrl по умолчанию. Если у узла нет базового URI, например, в случае, когда у комментария нет родителя, возвращается QUrl по умолчанию.

См. также XQuery 1.0 и XPath 2.0 Data Model (XDM), 5.2 аксессор base-uri.

[pure virtual] QXmlNodeModelIndex::DocumentOrder QAbstractXmlNodeModel::compareOrder(const QXmlNodeModelIndex &ni1, const QXmlNodeModelIndex &ni2) const

Эта функция возвращает относительный порядок документа для узлов, индексированных ni1 и ni2. Она используется для оператора Is и для сортировки узлов в порядке документа.

Вызывающий гарантирует, что ni1 и ni2 не null и что оба идентифицируют узлы в этой модели узлов.

Если ni1 идентично ni2, возвращается QXmlNodeModelIndex::Is. Если ni1 предшествует ni2 в порядке документа, возвращается QXmlNodeModelIndex::Precedes. Если ni1 следует за ni2 в порядке документа, возвращается QXmlNodeModelIndex::Follows.

См. также XQuery 1.0 и XPath 2.0 Data Model (XDM), 2.4 Порядок документа.

[protected] QXmlNodeModelIndex QAbstractXmlNodeModel::createIndex(qint64 data) const

Создаёт индекс узла с data в качестве внутренних данных. data не ограничено.

[protected] QXmlNodeModelIndex QAbstractXmlNodeModel::createIndex(void *pointer, qint64 additionalData = 0) const

Создаёт индекс узла с pointer и additionalData в качестве внутренних данных.

Что представляет собой pointer и additionalData, не ограничено.

[protected] QXmlNodeModelIndex QAbstractXmlNodeModel::createIndex(qint64 data, qint64 additionalData) const

Это перегруженная функция.

Создаёт QXmlNodeModelIndex, содержащий data и additionalData.

[pure virtual] QUrl QAbstractXmlNodeModel::documentUri(const QXmlNodeModelIndex &n) const

Возвращает URI документа для n. URI документа идентифицирует ресурс, который является документом. Например, документ может быть обычным файлом, например, file:/, или это может быть http:// URL расположения файла. URI документа используется для разрешения URI и для простого определения местоположения документа.

Если модель узлов сопоставляет URI естественным образом, возвращается этот URI. В противном случае возвращается URI компании или продукта. URI документа может быть любым URI, если он корректен и абсолютен.

Вызывающий гарантирует, что n не null и что он принадлежит к QAbstractXmlNodeModel.

Эта функция соответствует аксессору dm:document-uri, который возвращает URI документа следующим образом:

• Если n — узел документа, возвращается абсолютный QUrl, содержащий URI документа, или QUrl по умолчанию. Последнее указывает, что для узла документа URI документа недоступен.
• Для всех остальных узлов возвращается QUrl по умолчанию.

См. также XQuery 1.0 и XPath 2.0 Data Model (XDM), 5.4 аксессор document-uri, QUrl::isValid() и QUrl::isRelative().

[pure virtual] QXmlNodeModelIndex QAbstractXmlNodeModel::elementById(const QXmlName &id) const

Возвращает индекс элемента, идентифицированного как id. Функция вызова id() из XQuery вызывает эту функцию.

Возвращаемый индекс узла будет соответствовать элементу, значение которого имеет тип ID и равно id, или элементу, у которого есть атрибут со значением типа ID и равным id. Если такого элемента нет, возвращается экземпляр QXmlNodeModelIndex по умолчанию. Реализатор гарантирует, что если возвращаемый индекс узла не равен null, он идентифицирует элемент.

Недостаточно, чтобы атрибут или элемент просто именовались id. Их тип значения также должен быть ID. Однако, зарезервированное имя xml:id достаточно.

В id namespace URI и prefix не определены, и local name — это ID, который должен быть найден.

См. также XQuery 1.0 and XPath 2.0 Functions and Operators, 15.5.2 fn:id.

[pure virtual] QXmlNodeModelIndex::NodeKind QAbstractXmlNodeModel::kind(const QXmlNodeModelIndex &ni) const

Возвращает значение, указывающее тип узла, идентифицированного ni. Вызывающий код гарантирует, что ni не равно null и что оно идентифицирует узел в этой модели узлов. Эта функция отображается на dm:node-kind() accessor.

См. также XQuery 1.0 and XPath 2.0 Data Model (XDM), 5.10 node-kind Accessor.

[pure virtual] QXmlName QAbstractXmlNodeModel::name(const QXmlNodeModelIndex &ni) const

Возвращает имя ni. Вызывающий код гарантирует, что ni не null и что оно принадлежит данной QAbstractXmlNodeModel.

Если у узла нет имени, например, у узлов комментариев, возвращается null-ссылка QXmlName. QXmlNames должны создаваться с экземпляром QXmlQuery, используемым для вычисления запросов с помощью данного QAbstractXmlNodeModel.

Эта функция отображается на dm:node-name() accessor.

Если ni — это инструкция обработки, возвращается QXmlName с локальным именем в качестве целевого имени, а URI пространства имён и префикс — оба пусты.

См. также XQuery 1.0 and XPath 2.0 Data Model (XDM), 5.11 node-name Accessor и QXmlName.

[pure virtual] QVector<QXmlName> QAbstractXmlNodeModel::namespaceBindings(const QXmlNodeModelIndex &n) const

Возвращает пространства имён, действующие в рамках n. Вызывающий код гарантирует, что n не null и что оно принадлежит данной QAbstractXmlNodeModel.

Возвращаемый вектор объявлений пространств имён включает пространства имён предков n.

Вызывающий код гарантирует, что n является элементом, принадлежащим данной QAbstractXmlNodeModel.

[pure virtual protected] QXmlNodeModelIndex QAbstractXmlNodeModel::nextFromSimpleAxis(SimpleAxis axis, const QXmlNodeModelIndex &origin) const

При оценке выражений путей Qt XML Patterns имитирует их путём комбинации вызовов со значениями QSimpleXmlNodeModel::SimpleAxis. Поэтому реализация этой функции должна возвращать узел, если таковой имеется, который появляется на оси axis, исходящей из origin.

Если такого узла нет, возвращается QXmlNodeModelIndex по умолчанию.

QSimpleXmlNodeModel исключает необходимость обработки избыточных особых случаев, гарантируя, что она никогда не запрашивает:

• Дочерние или соседние узлы для атрибутов.
• Дочерние узлы для комментариев, инструкций обработки и текстовых узлов.
• Соседние или родительские узлы для узлов документа.

Типичная реализация выполняет switch над значением axis:

QXmlNodeModelIndex MyTreeModel::nextFromSimpleAxis(SimpleAxis axis, const QXmlNodeModelIndex &origin) const
{
  // Convert the QXmlNodeModelIndex to a value that is specific to what we represent.
  const MyValue value = toMyValue(ni);

  switch(axis)
  {
      case Parent:
          return toNodeIndex(value.parent());
      case FirstChild:
      case PreviousSibling:
      case NextSibling:
          // and so on
  }
}

[pure virtual] QVector<QXmlNodeModelIndex> QAbstractXmlNodeModel::nodesByIdref(const QXmlName &idref) const

Возвращает элементы и/или атрибуты, имеющие значение IDREF равное idref. Функция вызова idref() из XQuery вызывает эту функцию.

Реализатор гарантирует, что узлы, идентифицированные возвращаемыми индексами, являются элементами или атрибутами.

Недостаточно, чтобы атрибут или элемент просто именовались idref. Он должен также быть типа IDREF. Элементы должны быть типизированы как xs:IDREF или xs:IDREFS, а в случае атрибутов — как IDREF или IDREFS в схеме.

В idref namespace URI и prefix не определены, и local name — это ID, который необходимо найти.

См. также XQuery 1.0 and XPath 2.0 Functions and Operators, 15.5.3 fn:idref.

[pure virtual] QXmlNodeModelIndex QAbstractXmlNodeModel::root(const QXmlNodeModelIndex &n) const

Возвращает корневой узел дерева, содержащего узел с индексом n. Вызывающий код гарантирует, что n не null и что оно идентифицирует узел в этой модели узлов.

Если n идентифицирует узел, являющийся прямым потомком корня, parent() вернёт тот же QXmlNodeModelIndex, что и эта функция.

QSourceLocation QAbstractXmlNodeModel::sourceLocation(const QXmlNodeModelIndex &index) const

Возвращает расположение источника для объекта с заданным index или QSourceLocation по умолчанию в случае отсутствия информации о расположении.

Эта функция была добавлена в Qt 4.6.

[pure virtual] QString QAbstractXmlNodeModel::stringValue(const QXmlNodeModelIndex &n) const

Возвращает строковое значение для узла n.

Вызывающий код гарантирует, что n не null и что оно принадлежит данному экземпляру QAbstractXmlNodeModel.

Эта функция отображается на dm:string-value() accessor, который полностью специфицирован в спецификации. Вот краткое изложение:

• Для инструкций обработки строковое значение — это раздел данных (исключая пробелы между именем и данными).
• Для текстовых узлов строковое значение равно содержимому текстового узла.
• Для комментариев — содержимое комментария.
• Для элементов — конкатенация всех текстовых узлов, являющихся потомками. Обратите внимание, это не только дочерние узлы, но и дочерние узлы дочерних узлов, и так далее.
• Для узлов документа — конкатенация всех текстовых узлов в документе.

См. также XQuery 1.0 and XPath 2.0 Data Model (XDM), 5.13 string-value Accessor.

[pure virtual] QVariant QAbstractXmlNodeModel::typedValue(const QXmlNodeModelIndex &node) const

Возвращает типизированное значение для узла node.

Типизированное значение — это атомное значение, содержащееся в элементе или атрибуте.

Вызывающий код гарантирует, что node является либо элементом, либо атрибутом. Реализатор гарантирует, что возвращаемое значение QVariant имеет значение, поддерживаемое в XQuery. Это не может быть произвольное значение QVariant. Реализатор также гарантирует, что stringValue() возвращает лексическое представление typedValue() (это гарантируется QSimpleXmlNodeModel::stringValue()).

Если возвращаемое значение QVariant является значением по умолчанию, это означает, что у node нет типизированного значения.