Класс QAbstractXmlNodeModel

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

Этот класс был представлен в Qt 4.4.

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

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

Общедоступные типы

Общедоступные функции

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

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

Класс 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 Data Model, представленный QAbstractXmlNodeModel, позволяет QXmlQuery работать с данными, отличными от XML, как если бы они были XML, реализация подклассов QAbstractXmlNodeModel может потребовать значительных усилий. Класс QSimpleXmlNodeModel предназначен для упрощения реализации для многих распространенных случаев использования.

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

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

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

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

typedef QAbstractXmlNodeModel::List

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

См. также QExplicitlySharedDataPointer.

typedef QAbstractXmlNodeModel::Ptr

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

См. также QExplicitlySharedDataPointer.

перечисление 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 and XPath 2.0 Data Model (XDM), 5.2 base-uri Accessor.

[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 and XPath 2.0 Data Model (XDM), 2.4 Document Order.

[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 and XPath 2.0 Data Model (XDM), 5.4 document-uri Accessor, 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 и XPath 2.0, 15.5.2 fn:id.

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

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

См. также Модель данных XQuery 1.0 и XPath 2.0 (XDM), 5.10 аксессор node-kind.

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

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

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

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

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

См. также Модель данных XQuery 1.0 и XPath 2.0 (XDM), 5.11 аксессор node-name и QXmlName.

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

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

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

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

[pure virtual protected] QXmlNodeModelIndex QAbstractXmlNodeModel::nextFromSimpleAxis(QAbstractXmlNodeModel::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 и XPath 2.0, 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(), который полностью определён в спецификации. Вот краткий обзор:

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

См. также Модель данных XQuery 1.0 и XPath 2.0 (XDM), 5.13 аксессор string-value.

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

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

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

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

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