Класс QAbstractXmlNodeModel

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

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

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

Типы Public

Функции Public

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

Дополнительные унаследованные члены

• 1 общедоступная переменная, унаследованная от QSharedData

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

Класс 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. Его конструктор вызывается с пулом имён name pool, полученным из нашего QXmlQuery, и со структурой молекул и атомов, которые должны быть запрошены. Пул имён name pool требуется, потому что наш пользовательский класс модели узла имеет член-функцию name(), которая возвращает имя имя любого узла в модели. Запрос и пользовательская модель узла должны использовать один и тот же пул имён name pool для построения этих имён. Конструктор затем прочитает chemistryFile и построит структуру пользовательской модели узла.

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

Запрос выполняется, когда приложение вызывает одну из функций оценки QXmlQuery. Приложение использует QXmlQuery::evaluateTo(QAbstractXmlReceiver *), потому что затем оно использует сериализатор serializer, чтобы вывести результат запроса в виде 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.

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 базовый 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 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 и 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.

Эта функция соответствует аксессору dm:namespace-nodes.

Возвращаемый вектор объявлений пространств имён включает пространства имён предков 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 нет типизированного значения.