Класс QXmlQuery

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

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

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

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

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

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

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

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

Использование QXmlQuery для запроса XML-данных, как в приведенном ниже фрагменте, является простым, поскольку он может использовать встроенную модель данных XML в качестве своего делегата для базового движка запросов для обхода данных. Встроенная модель данных указана в XQuery 1.0 and 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() для привязки имени переменной к узлу начала в пользовательской модели. Ссылка $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, содержимое которого — 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 уже является строкой Unicode, определение его кодировки не требуется.

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.