Класс 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, и со структурой молекул и атомов, подлежащих запросу. Пул имён имен требуется, потому что наш пользовательский класс модели узлов имеет функцию-член 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 и 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:/, или это может быть URI http:// местоположения файла. 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. Функции XQuery id() вызывают эту функцию.

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

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

В id, namespace URI и prefix не определены, а local name — это идентификатор, который следует найти.

См. также Функции и операторы 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 Accessor.

[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 Accessor и 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 — это идентификатор, который следует найти.

См. также Функции и операторы 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() - accessor, спецификация полностью определяет его. Вот краткое описание:

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

См. также Модель данных XQuery 1.0 и XPath 2.0 (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 не имеет типизированного значения.