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

Примечание: В настоящее время метод 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 в отдельном потоке.

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

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

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

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

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

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

QXmlQuery::QXmlQuery()

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

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

QXmlQuery::QXmlQuery(const QXmlQuery &other)

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

QXmlQuery::QXmlQuery(const QXmlNamePool &np)

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

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

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

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

Примечание: Поддержка XSLT в этой версии считается экспериментальной. Подробности см. в разделе Соответствие 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 таким образом, чтобы вызывался конструктор QXmlItem от QVariant.

Все строки, обрабатываемые запросом, должны быть допустимыми строками 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);

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

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

Примечание: устройство не должно быть удалено, пока существует этот 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().

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.