Класс QXmlQuery

Класс QXmlQuery выполняет XQuery-запросы к данным 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.

Выполнение 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() для связывания имени переменной с начальным узлом в пользовательской модели. Ссылка $переменная используется в тексте XQuery для доступа к начальному узлу в пользовательской модели. Не нужно объявлять имя переменной во внешнем коде запроса. См. пример в документации для QAbstractXmlNodeModel.

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

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

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

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

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

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

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

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

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

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

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

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

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

enum QXmlQuery::QueryLanguage

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

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

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

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

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

Конструирует запрос, который будет использоваться для выполнения XQuery или XSLT-стилей в зависимости от значения queryLanguage. Он будет использовать np в качестве пула имён.

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

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

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

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

QXmlQuery::QXmlQuery(const QXmlNamePool &np)

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

QXmlQuery::QXmlQuery(const QXmlQuery &other)

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

QXmlQuery::QXmlQuery()

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

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

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

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

Эта функция применяется только при использовании 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().