Класс QXmlQuery

Класс QXmlQuery выполняет XQueries над данными XML или над не-XML данными, смоделированными так, чтобы выглядеть как XML. Подробнее...

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

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

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

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

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

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

Класс 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.

Выполнение XQueries

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

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

• evaluateTo(QXmlResultItems *) вызывается с указателем на итератор для пустой последовательности элементов результата запроса result items. Итератор, похожий на 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);

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

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

xmlpatterns myStylesheet.xsl myInput.xml

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

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

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

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

Реентерабельность и потоковая безопасность

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

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

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

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

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

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

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

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

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

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

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

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

перечисление QXmlQuery::QueryLanguage

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

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

См. также 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(const QXmlNamePool &np)

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

QXmlQuery::QXmlQuery(const QXmlQuery &other)

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

QXmlQuery::QXmlQuery()

Конструирует недействительный, пустой запрос, который не может быть использован, пока не будет вызван setQuery().

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

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

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

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 таким образом, чтобы вызывался конструктор QXmlItem для QVariant.

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

См. также QVariant::isValid(), Как QVariant отображается в XQuery Data Model и 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)

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

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

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

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

bool QXmlQuery::setFocus(const QString &focus)

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

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

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

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

void QXmlQuery::setInitialTemplateName(const QXmlName &name)

Устанавливает 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().