Класс QXmlQuery

Класс QXmlQuery выполняет XQuery-запросы к данным XML или к данным, не являющимся XML, но смоделированным как XML. Подробнее...

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

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

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

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

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

Класс QXmlQuery выполняет XQuery-запросы к данным XML или к данным, не являющимся XML, но смоделированным как XML.

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

Использование QXmlQuery для запроса данных XML, как показано в примере ниже, простое, поскольку он может использовать встроенную модель данных XML в качестве делегата для движка запросов для обхода данных. Встроенная модель данных специфицируется в XQuery 1.0 и XPath 2.0 Data Model.

QXmlQuery query;
query.setQuery("doc('index.html')/html/body/p[1]");

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

В примере используется QXmlQuery для сопоставления первого абзаца документа XML, а затем результат выводится на устройство в формате XML.

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

Выполнение XQuery-запросов

Для выполнения запроса, заданного с помощью QXmlQuery, вызовите одну из функций вычисления.

• evaluateTo(QAbstractXmlReceiver *) вызывается с указателем на приемник XML, который получает результаты запроса как последовательность обратных вызовов. Класс обратного вызова приемника похож на класс обратного вызова, используемый для преобразования вывода парсера SAX. QXmlSerializer, например, является классом обратного вызова приемника для преобразования последовательности обратных вызовов в вывод в виде неформатированного текста XML.

• evaluateTo(QXmlResultItems *) вызывается с указателем на итератор для пустой последовательности элементов результатов запроса. Итератор по образцу Java позволяет получать результаты запроса последовательно.

• evaluateTo(QStringList *) похож на evaluateTo(QXmlResultItems *), но запрос должен быть оценен как последовательность строк.

Выполнение XPath-выражений

Язык XPath является подмножеством языка XQuery, поэтому выполнение XPath-выражения аналогично выполнению XQuery-запроса. Передайте XPath-выражение в QXmlQuery с помощью setQuery().

Выполнение XSLT-стилей

Выполнение XSLT-стиля похоже на выполнение XQuery, за исключением того, что при создании объекта QXmlQuery необходимо передать QXmlQuery::XSLT20, чтобы указать QXmlQuery интерпретировать полученное из setQuery() значение как XSLT-стиль, а не как XQuery. Также необходимо установить входной документ, вызвав setFocus().

    QXmlQuery query(QXmlQuery::XSLT20);
    query.setFocus(QUrl("myInput.xml"));
    query.setQuery(QUrl("myStylesheet.xsl"));
    query.evaluateTo(out);

Примечание: В настоящее время, для использования XSLT необходимо вызвать setFocus() перед setQuery().

Другой способ выполнения XSLT-стиля — использование утилиты командной строки xmlpatterns.

xmlpatterns myStylesheet.xsl myInput.xml

Примечание: Поддержка XSLT в текущей версии считается экспериментальной. Подробности см. в разделе Соответствие XSLT.

Параметры стиля связываются с помощью bindVariable().

Связывание запроса с начальным узлом

При выполнении запроса на XML-данных, как в приведённом выше фрагменте, функция doc() возвращает узел во встроенной модели данных, с которого начнется вычисление запроса. Но при выполнении запроса на пользовательской модели узлов, содержащей данные, отличные от XML, необходимо вызвать одну из функций bindVariable(), чтобы связать имя переменной с начальным узлом в пользовательской модели. Ссылка $variable используется в тексте XQuery для доступа к начальному узлу в пользовательской модели. Не нужно объявлять имя переменной внешне в запросе. См. пример в документации для QAbstractXmlNodeModel.

Взаимодействие с потоками и безопасность

QXmlQuery поддерживает взаимное исключение (реентерабелен), но не является потокобезопасным. Можно безопасно использовать конструктор копирования QXmlQuery, чтобы создать копию запроса и выполнить его несколько раз. Внутренне QXmlQuery будет повторно использовать ресурсы, такие как открытые файлы и скомпилированные запросы, насколько это возможно. Но использование одного экземпляра QXmlQuery в нескольких потоках небезопасно.

Обработка ошибок

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

• Сообщение об ошибке отправляется в messageHandler().
• QXmlResultItems::hasError() вернёт true, или evaluateTo() вернёт false;
• Результаты вычисления не определены.

Управление ресурсами

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

Когда вызывается setQuery(), текст запроса компилируется во внутреннюю структуру данных и оптимизируется. Оптимизированная форма может затем использоваться для многократного выполнения запроса. Поскольку процесс компиляции и оптимизации может быть дорогостоящим, его следует избегать, используя отдельный экземпляр QXmlQuery для каждого текста запроса.

После того, как документ был проанализирован, его внутреннее представление сохраняется в экземпляре QXmlQuery и делится между несколькими экземплярами QXmlQuery.

Перед использованием QXmlQuery должен существовать экземпляр QCoreApplication.

Обработка событий

Когда QXmlQuery получает доступ к ресурсам (например, вызывая fn:doc() для загрузки файла или доступа к устройству через связанную переменную), используется цикл событий, что означает, что события будут обрабатываться. Чтобы избежать обработки событий при доступе QXmlQuery к ресурсам, создайте свой экземпляр QXmlQuery в отдельном потоке.

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

enum QXmlQuery::QueryLanguage

Определяет, будет ли QXmlQuery интерпретировать входные данные для setQuery() как XQuery или как XSLT-стиль.

Этот перечисление был введён или изменён в Qt 4.5.

См. также setQuery().

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

QXmlQuery::QXmlQuery()

Создаёт невалидный, пустой запрос, который нельзя использовать до тех пор, пока не будет вызван setQuery().

Примечание: Этот конструктор не следует использовать, если вы намереваетесь использовать этот QXmlQuery для обработки XSL-T стилей. В этом случае должен использоваться другой конструктор.

QXmlQuery::QXmlQuery(const QXmlQuery &other)

Создаёт QXmlQuery, который является копией other. Новый экземпляр будет совместно использовать ресурсы с существующим запросом по возможности.

QXmlQuery::QXmlQuery(const QXmlNamePool &np)

Создаёт запрос, который будет использовать np в качестве своего имени пула. Запрос не может быть вычислен, пока не будет вызван setQuery().

QXmlQuery::QXmlQuery(QXmlQuery::QueryLanguage queryLanguage, const QXmlNamePool &np = QXmlNamePool())

Создаёт запрос, который будет использоваться для выполнения XQueries или XSL-T стилей, в зависимости от значения queryLanguage. Он будет использовать np в качестве своего пула имён.

Примечание: Если ваш QXmlQuery будет обрабатывать XSL-T стили, этот конструктор должен быть использован. Конструктор по умолчанию может создавать только экземпляры QXmlQuery для выполнения XQueries.

Примечание: Поддержка XSL-T в этой версии считается экспериментальной. Подробности см. в разделе Соответствие XSLT.

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

См. также queryLanguage().

QXmlQuery::~QXmlQuery()

Удаляет этот QXmlQuery.

void QXmlQuery::bindVariable(const QXmlName &name, const QXmlItem &value)

Связывает переменную name со значением value, чтобы $name можно было использовать в запросе для ссылки на value.

name не может быть null. name.isNull() должно возвращать false. Если name уже была связана предыдущим вызовом bindVariable(), её предыдущая связь будет переопределена.

Если value равна null, так что value.isNull() возвращает true, и name уже имеет привязку, то эффект заключается в удалении существующей привязки для name.

Для привязки значения типа QString или QUrl, оберните значение в QVariant так, чтобы вызывался конструктор QVariant объекта QXmlItem.

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

См. также QVariant::isValid(), Как QVariant сопоставляется с моделью данных XQuery, и QXmlItem::isNull().

void QXmlQuery::bindVariable(const QString &localName, const QXmlItem &value)

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

Эта функция строит QXmlName из localName, используя пространство имён запроса. Затем функция ведет себя как перегруженная функция. Она эквивалентна следующему фрагменту кода.

    QXmlNamePool namePool(query.namePool());
    query.bindVariable(QXmlName(namePool, localName), value);

void QXmlQuery::bindVariable(const QXmlName &name, QIODevice *device)

Связывает переменную name с device, так что $name можно использовать в запросе для ссылки на device. QIODevice device отображается для запроса как URI типа xs:anyURI, который можно передать функции fn:doc() для чтения. Например, эта функция может быть использована для передачи XML-документа в памяти в fn:doc.

    QByteArray myDocument;
    QBuffer buffer(&myDocument); // This is a QIODevice.
    buffer.open(QIODevice::ReadOnly);
    QXmlQuery query;
    query.bindVariable("myDocument", &buffer);
    query.setQuery("doc($myDocument)");

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

Если запрос будет обращаться к XML-документу, содержащемуся в QString, используйте QBuffer, как показано в следующем фрагменте. Предположим, что myQString содержит <document>content</document>

    QBuffer device;
    device.setData(myQString.toUtf8());
    device.open(QIODevice::ReadOnly);

    QXmlQuery query;
    query.setQuery("doc($inputDocument)/query[theDocument]");
    query.bindVariable("inputDocument", &device);

name не может быть null. name.isNull() должно возвращать false. Если name уже привязана, её предыдущая привязка будет переопределена. URI, к которому обращается name, произволен и может меняться.

Если тип привязки переменной изменяется (например, если предыдущая привязка с тем же именем была QVariant, или если предыдущей привязки не было), isValid() вернёт false, и требуется повторная компиляция текста запроса. Для повторной компиляции запроса вызовите setQuery(). По этой причине bindVariable() следует вызывать перед setQuery(), если это возможно.

Примечание: device не должен удаляться, пока существует этот QXmlQuery.

void QXmlQuery::bindVariable(const QString &localName, QIODevice *device)

Это перегруженный метод.

Если localName является допустимым NCName, этот метод эквивалентен следующему фрагменту.

    QXmlNamePool namePool(query.namePool());
    query.bindVariable(QXmlName(namePool, localName), device);

Из localName создаётся QXmlName, и она передаётся соответствующей перегрузке вместе с device.

См. также QXmlName::isNCName().

void QXmlQuery::bindVariable(const QXmlName &name, const QXmlQuery &query)

Привязывает результат запроса query к переменной с именем name.

Вычисление query начнется при вызове этого метода.

Если query недействителен, поведение не определено. query будет скопирован.

Этот метод был добавлен в Qt 4.5.

См. также isValid().

void QXmlQuery::bindVariable(const QString &localName, const QXmlQuery &query)

Это перегруженный метод.

Имеет такое же поведение и эффекты, как перегруженный метод, но принимает имя переменной localName как QString. query используется как в перегруженном методе.

Этот метод был добавлен в Qt 4.5.

void QXmlQuery::evaluateTo(QXmlResultItems *result) const

Запускает вычисление и делает его доступным в result. Если result равен null, поведение не определено. Вычисление происходит по частям (ленивая оценка), так как вызывающий код использует QXmlResultItems::next() для получения следующего результата.

См. также QXmlResultItems::next().

bool QXmlQuery::evaluateTo(QAbstractXmlReceiver *callback) const

Вычисляет этот запрос и отправляет результат как последовательность обратных вызовов получателю callback. QXmlQuery не берет на себя ответственность за callback.

Если при вычислении произошла ошибка, сообщения об ошибках отправляются в messageHandler() и возвращается false.

Если этот запрос недействителен, возвращается false, и поведение не определено. Если callback равен null, поведение не определено.

См. также QAbstractXmlReceiver и isValid().

bool QXmlQuery::evaluateTo(QStringList *target) const

Пытается вычислить запрос и возвращает результаты в списке строк target.

Если запрос действителен и вычисление прошло успешно, возвращается true. В противном случае возвращается false, и содержимое target не определено.

Запрос должен вычисляться в последовательность xs:string значений. Если запрос не вычисляется в последовательность строк, значения часто можно преобразовать, добавив вызов string() в конце XQuery.

Если target равен null, поведение не определено.

bool QXmlQuery::evaluateTo(QIODevice *target) const

Вычисляет запрос или таблицу стилей и записывает вывод в target.

QXmlSerializer используется для записи вывода в target. В будущей версии ожидается, что этот метод будет учитывать параметры сериализации, установленные в таблице стилей.

Если при вычислении произошла ошибка, сообщения об ошибках отправляются в messageHandler(), и возвращается false.

Если target null, или не открыт как минимум в режиме QIODevice::WriteOnly, поведение не определено. QXmlQuery не берет на себя ответственность за target.

Это перегруженный метод.

Этот метод был добавлен в Qt 4.5.

bool QXmlQuery::evaluateTo(QString *output) const

Вычисляет запрос и сериализует вывод как XML в output.

Если при вычислении произошла ошибка, сообщения об ошибках отправляются в messageHandler(), содержимое output не определено, и возвращается false, в противном случае возвращается true.

Если output null, поведение не определено. QXmlQuery не берет на себя ответственность за output.

Внутренне для этого используется класс QXmlFormatter.

Этот метод был добавлен в Qt 4.5.

QXmlName QXmlQuery::initialTemplateName() const

Возвращает имя шаблона XSL-T таблицы стилей, который процессор вызовет в первую очередь при выполнении таблицы стилей XSL-T. Этот метод применим только при использовании QXmlQuery для обработки таблиц стилей XSL-T. По умолчанию начальный шаблон не установлен. В этом случае возвращается QXmlName по умолчанию.

Этот метод был добавлен в Qt 4.5.

См. также setInitialTemplateName().

bool QXmlQuery::isValid() const

Возвращает true, если этот запрос действителен. Примерами недействительных запросов являются запросы, содержащие синтаксические ошибки, или запросы, для которых ещё не был вызван setQuery().

QAbstractMessageHandler *QXmlQuery::messageHandler() const

Возвращает обработчик сообщений, который обрабатывает сообщения компиляции и выполнения для этого QXmlQuery.

См. также setMessageHandler().

QXmlNamePool QXmlQuery::namePool() const

Возвращает пул имён, используемый этим QXmlQuery для создания имён. Для пула имён нет метода установки, потому что смешивание пулов имён приводит к ошибкам из-за конфликтов имён.

QNetworkAccessManager *QXmlQuery::networkAccessManager() const

Возвращает менеджер сети или 0, если он не был установлен.

Этот метод был добавлен в Qt 4.5.

См. также setNetworkAccessManager().

QXmlQuery::QueryLanguage QXmlQuery::queryLanguage() const

Возвращает значение, указывающее, для чего используется этот QXmlQuery. По умолчанию это QXmlQuery::XQuery10, что означает, что QXmlQuery используется для запуска запросов XQuery и XPath. Также может возвращаться QXmlQuery::XSLT20, что указывает на использование QXmlQuery для работы с XSL-T таблицами стилей.

Этот метод был добавлен в Qt 4.5.

void QXmlQuery::setFocus(const QXmlItem &item)

Устанавливает фокус на item. Фокус — это набор элементов, от которых начинаются навигация выражений контекста элемента и выражений путей. Например, в выражении p/span элемент, к которому относится p, является фокусом для последующего выражения span.

К фокусу можно получить доступ, используя выражение контекстного элемента, т.е. точку (".").

По умолчанию фокус не установлен и не определён. Поэтому попытка доступа к фокусу приведёт к динамической ошибке XPDY0002. Фокус должен быть установлен перед установкой запроса с помощью setQuery().

Поведение для установки элемента, равного null, не определено.

bool QXmlQuery::setFocus(const QUrl &documentURI)

Это перегруженный метод.

Устанавливает фокус на документ, расположенный по адресу documentURI, и возвращает true. Если documentURI не может быть загружен, возвращается false. Время загрузки документа не определено. При загрузке документа используются обработчик сообщений и разрешитель URI, установленные в этом QXmlQuery.

Если documentURI пуста или не является допустимым URI, поведение этого метода не определено.

Этот метод был добавлен в Qt 4.5.

bool QXmlQuery::setFocus(QIODevice *document)

Устанавливает фокус на document, считываемый из QIODevice, и возвращает true. Если document не может быть загружен, возвращается false.

QXmlQuery не берет на себя ответственность за document. Пользователь гарантирует, что документ доступен из устройства document, и что документ не пуст. Устройство должно быть открыто как минимум в режиме чтения. document должен оставаться в области видимости, пока активен текущий запрос.

Это перегруженный метод.

Этот метод был добавлен в Qt 4.5.

bool QXmlQuery::setFocus(const QString &focus)

Эта функция ведет себя идентично вызову перегрузки setFocus() с QIODevice, содержимое которого закодировано в UTF-8 как focus. То есть, focus обрабатывается так, как если бы он содержал XML-документ.

Возвращает тот же результат, что и перегрузка.

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

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

void QXmlQuery::setInitialTemplateName(const QXmlName &name)

Устанавливает имя начальной шаблона. Начальный шаблон — это тот, который процессор вызывает первым, вместо попытки сопоставить шаблон с узлом контекста (если таковой имеется). Если начальный шаблон не задан, используется стандартный порядок вызова шаблонов.

Эта функция применяется только при использовании QXmlQuery для обработки XSL-T стилей. Имя становится частью скомпилированного стиля. Поэтому эту функцию необходимо вызвать перед вызовом setQuery().

Если в стиле нет шаблона с именем name, процессор использует стандартный порядок вызова шаблонов.

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

См. также initialTemplateName().

void QXmlQuery::setInitialTemplateName(const QString &localName)

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

Устанавливает имя начального шаблона на localName, которое должно быть допустимым локальным именем. Начальный шаблон — это тот, который процессор вызывает первым, вместо попытки сопоставить шаблон с узлом контекста (если таковой имеется). Если начальный шаблон не задан, используется стандартный порядок вызова шаблонов.

Если localName не является допустимым локальным именем, результат неопределён. Если в стиле нет шаблона с именем localName, процессор использует стандартный порядок вызова шаблонов.

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

См. также initialTemplateName().

void QXmlQuery::setMessageHandler(QAbstractMessageHandler *aMessageHandler)

Изменяет обработчик сообщений для этого QXmlQuery на aMessageHandler. Запрос отправляет все сообщения о компиляции и выполнении этому обработчику. QXmlQuery не принимает владение aMessageHandler.

Обычно, стандартный обработчик сообщений достаточен. Он записывает сообщения о компиляции и выполнении в stderr. Стандартный обработчик сообщений включает цветовые коды, если stderr может отображать цвета.

Обратите внимание, что изменение обработчика сообщений после компиляции запроса не оказывает влияния, т. е. запрос использует тот же обработчик сообщений во время выполнения, что и во время компиляции.

Когда QXmlQuery вызывает QAbstractMessageHandler::message(), аргументы следующие:

См. также messageHandler().

void QXmlQuery::setNetworkAccessManager(QNetworkAccessManager *newManager)

Устанавливает менеджер сети на newManager. QXmlQuery не принимает владение newManager.

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

См. также networkAccessManager().

void QXmlQuery::setQuery(QIODevice *sourceCode, const QUrl &documentURI = QUrl())

Устанавливает для этого QXmlQuery XQuery, считанный из устройства sourceCode. Устройство должно быть открыто как минимум с QIODevice::ReadOnly.

documentURI представляет запрос, полученный из устройства sourceCode. Это базовый URI статического контекста, как определено в языке XQuery. Он используется внутри для разрешения относительных URI, которые появляются в запросе, и для отчётности о сообщениях. documentURI может быть пустым. Если он пустой, используется путь к файлу приложения. Если он не пустой, он может быть относительным или абсолютным. Если он относительный, он разрешается относительно пути к файлу приложения, прежде чем используется. Если documentURI не является допустимым URI или пустым, результат неопределён.

Если запрос содержит статическую ошибку (например, синтаксическую ошибку), сообщение об ошибке отправляется в messageHandler(), и isValid() вернёт false.

Переменные должны быть связаны перед вызовом setQuery().

Кодировка XQuery в sourceCode определяется внутренне с использованием правил для установки и определения кодировки файлов XQuery, которые описаны в языке XQuery.

Если sourceCode — null или не может быть прочитан, или если documentURI не является допустимым URI, поведение неопределённо.

См. также isValid().

void QXmlQuery::setQuery(const QString &sourceCode, const QUrl &documentURI = QUrl())

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

Поведение и требования этой функции такие же, как для setQuery(QIODevice*, const QUrl&), после того, как XQuery был прочитан из устройства ввода-вывода в строку. Так как sourceCode уже представляет собой строку Юникод, определение его кодировки не требуется.

void QXmlQuery::setQuery(const QUrl &queryURI, const QUrl &baseURI = QUrl())

Устанавливает для этого QXmlQuery XQuery, прочитанный из queryURI. Используйте isValid() после вызова этой функции. Если произошла ошибка при чтении queryURI, например, запрос не существует, не может быть прочитан или недействителен, isValid() вернёт false.

Поддерживаемые схемы URI такие же, как и в функции XQuery fn:doc, за исключением того, что queryURI может быть объектом привязки переменной.

baseURI — это базовый URI статического контекста, как определено в языке XQuery. Он используется внутри для разрешения относительных URI, которые появляются в запросе, и для отчётности о сообщениях. Если baseURI пусто, используется queryURI. В противном случае, используется baseURI, и он разрешается относительно пути к файлу приложения, если он относительный.

Если queryURI пусто или недействительно, или если baseURI недействительно, поведение этой функции неопределённо.

void QXmlQuery::setUriResolver(const QAbstractUriResolver *resolver)

Устанавливает разрешитель URI на resolver. QXmlQuery не принимает владение resolver.

См. также uriResolver().

const QAbstractUriResolver *QXmlQuery::uriResolver() const

Возвращает разрешитель URI запроса. Если разрешитель URI не задан, Qt XML Patterns будет использовать URI в запросах как есть.

Разрешитель URI предоставляет уровень абстракции или полиморфные URI. Разрешитель может переписывать логические URI в физические или переводить устаревшие или недействительные URI в допустимые.

Qt XML Patterns вызывает разрешитель URI для всех URI, которые встречаются, за исключением пространств имён. В частности, для всех встроенных функций, которые имеют дело с URI (fn:doc(), и fn:doc-available()).

В случае fn:doc(), абсолютный URI является базовым URI в статическом контексте (вероятно, это расположение запроса). Вместо использования указанного пользователем URI, будет использоваться возвращаемое значение QAbstractUriResolver::resolve().

Когда Qt XML Patterns вызывает QAbstractUriResolver::resolve(), абсолютный URI — это URI, предписанный языком XQuery, а относительный URI — это URI, указанный пользователем.

См. также setUriResolver().

QXmlQuery &QXmlQuery::operator=(const QXmlQuery &other)

Присваивает other экземпляру QXmlQuery.