1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include <QtCore/QBuffer>
43 #include <QtCore/QStringList>
44 #include <QtXmlPatterns/QXmlFormatter>
46 #include "qacceltreeresourceloader_p.h"
47 #include "qcommonvalues_p.h"
48 #include "qxmlresultitems.h"
49 #include "qxmlresultitems_p.h"
50 #include "qxmlserializer.h"
51 #include "qxpathhelper_p.h"
53 #include "qxmlquery.h"
54 #include "qxmlquery_p.h"
61 \brief The QXmlQuery class performs XQueries on XML data, or on non-XML data modeled to look like XML.
66 \inmodule QtXmlPatterns
68 The QXmlQuery class compiles and executes queries written in the
69 \l {http://www.w3.org/TR/xquery/}{XQuery language}. QXmlQuery is
70 typically used to query XML data, but it can also query non-XML
71 data that has been modeled to look like XML.
73 Using QXmlQuery to query XML data, as in the snippet below, is
74 simple because it can use the built-in \l {QAbstractXmlNodeModel}
75 {XML data model} as its delegate to the underlying query engine for
76 traversing the data. The built-in data model is specified in \l
77 {http://www.w3.org/TR/xpath-datamodel/} {XQuery 1.0 and XPath 2.0
80 \snippet doc/src/snippets/code/src_xmlpatterns_api_qabstractxmlreceiver.cpp 0
82 The example uses QXmlQuery to match the first paragraph of an XML
83 document and then \l {QXmlSerializer} {output the result} to a
86 Using QXmlQuery to query \e {non-XML} data requires writing a
87 subclass of QAbstractXmlNodeModel to use as a replacement for the
88 built-in XML data model. The custom data model will be able to
89 traverse the non-XML data as required by the QAbstractXmlNodeModel
90 interface. An instance of this custom data model then becomes the
91 delegate used by the query engine to traverse the non-XML data. For
92 an example of how to use QXmlQuery to query non-XML data, see the
93 documentation for QAbstractXmlNodeModel.
95 \section1 Running XQueries
97 To run a query set up with QXmlQuery, call one of the evaluation
102 \li evaluateTo(QAbstractXmlReceiver *) is called with a pointer to an
103 XML \l {QAbstractXmlReceiver} {receiver}, which receives the query
104 results as a sequence of callbacks. The receiver callback class is
105 like the callback class used for translating the output of a SAX
106 parser. QXmlSerializer, for example, is a receiver callback class
107 for translating the sequence of callbacks for output as unformatted
114 \li evaluateTo(QXmlResultItems *) is called with a pointer to an
115 iterator for an empty sequence of query \l {QXmlResultItems} {result
116 items}. The Java-like iterator allows the query results to be
117 accessed sequentially.
123 \li evaluateTo(QStringList *) is like evaluateTo(QXmlResultItems *),
124 but the query must evaluate to a sequence of strings.
128 \section1 Running XPath Expressions
130 The XPath language is a subset of the XQuery language, so
131 running an XPath expression is the same as running an XQuery
132 query. Pass the XPath expression to QXmlQuery using setQuery().
134 \section1 Running XSLT stylesheets
136 Running an XSLT stylesheet is like running an XQuery, except that
137 when you construct your QXmlQuery, you must pass QXmlQuery::XSLT20
138 to tell QXmlQuery to interpret whatever it gets from setQuery() as
139 an XSLT stylesheet instead of as an XQuery. You must also set the
140 input document by calling setFocus().
142 \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 7
144 \note Currently, setFocus() must be called \e before setQuery() when
147 Another way to run an XSLT stylesheet is to use the \c xmlpatterns
148 command line utility.
151 xmlpatterns myStylesheet.xsl myInput.xml
154 \note For the current release, XSLT support should be considered
155 experimental. See section \l{XQuery#XSLT 2.0} {XSLT conformance} for
158 Stylesheet parameters are bound using bindVariable().
160 \section1 Binding A Query To A Starting Node
162 When a query is run on XML data, as in the snippet above, the
163 \c{doc()} function returns the node in the built-in data model where
164 the query evaluation will begin. But when a query is run on a custom
165 node model containing non-XML data, one of the bindVariable()
166 functions must be called to bind a variable name to a starting node
167 in the custom model. A $variable reference is used in the XQuery
168 text to access the starting node in the custom model. It is not
169 necessary to declare the variable name external in the query. See
170 the example in the documentation for QAbstractXmlNodeModel.
172 \section1 Reentrancy and Thread-Safety
174 QXmlQuery is reentrant but not thread-safe. It is safe to use the
175 QxmlQuery copy constructor to create a copy of a query and run the
176 same query multiple times. Behind the scenes, QXmlQuery will reuse
177 resources such as opened files and compiled queries to the extent
178 possible. But it is not safe to use the same instance of QXmlQuery
181 \section1 Error Handling
183 Errors can occur during query evaluation. Examples include type
184 errors and file loading errors. When an error occurs:
188 \li The error message is sent to the messageHandler().
190 \li QXmlResultItems::hasError() will return \c{true}, or
191 evaluateTo() will return \c{false};
193 \li The results of the evaluation are undefined.
197 \section1 Resource Management
199 When a query runs, it parses documents, allocating internal data
200 structures to hold them, and it may load other resources over the
201 network. It reuses these allocated resources when possible, to
202 avoid having to reload and reparse them.
204 When setQuery() is called, the query text is compiled into an
205 internal data structure and optimized. The optimized form can
206 then be reused for multiple evaluations of the query. Since the
207 compile-and-optimize process can be expensive, repeating it for
208 the same query should be avoided by using a separate instance of
209 QXmlQuery for each query text.
211 Once a document has been parsed, its internal representation is
212 maintained in the QXmlQuery instance and shared among multiple
215 An instance of QCoreApplication must exist before QXmlQuery can be
218 \section1 Event Handling
220 When QXmlQuery accesses resources (e.g., calling \c fn:doc() to load a file,
221 or accessing a device via a bound variable), the event loop is used, which
222 means events will be processed. To avoid processing events when QXmlQuery
223 accesses resources, create your QXmlQuery instance in a separate thread.
227 \enum QXmlQuery::QueryLanguage
230 Specifies whether you want QXmlQuery to interpret the input to
231 setQuery() as an XQuery or as an XSLT stylesheet.
233 \value XQuery10 XQuery 1.0.
234 \value XSLT20 XSLT 2.0
235 \omitvalue XmlSchema11IdentityConstraintSelector The selector, the restricted
236 XPath pattern found in W3C XML Schema 1.1 for uniqueness
237 contraints. Apart from restricting the syntax, the type check stage
238 for the expression assumes a sequence of nodes to be the focus.
239 \omitvalue XmlSchema11IdentityConstraintField The field, the restricted
240 XPath pattern found in W3C XML Schema 1.1 for uniqueness
241 contraints. Apart from restricting the syntax, the type check stage
242 for the expression assumes a sequence of nodes to be the focus.
243 \omitvalue XPath20 Signifies XPath 2.0. Has no effect in the public API, it's
244 used internally. As With XmlSchema11IdentityConstraintSelector and
245 XmlSchema11IdentityConstraintField, the type check stage
246 for the expression assumes a sequence of nodes to be the focus.
251 // ### Qt5: Merge constructor overloads
253 Constructs an invalid, empty query that cannot be used until
254 setQuery() is called.
256 \note This constructor must not be used if you intend to use
257 this QXmlQuery to process XSL-T stylesheets. The other constructor
258 must be used in that case.
260 QXmlQuery::QXmlQuery() : d(new QXmlQueryPrivate())
265 Constructs a QXmlQuery that is a copy of \a other. The new
266 instance will share resources with the existing query
267 to the extent possible.
269 QXmlQuery::QXmlQuery(const QXmlQuery &other) : d(new QXmlQueryPrivate(*other.d))
271 /* First we have invoked QXmlQueryPrivate's synthesized copy constructor.
272 * Keep this section in sync with QXmlQuery::operator=(). */
277 Constructs a query that will use \a np as its name pool. The query
278 cannot be evaluated until setQuery() has been called.
280 QXmlQuery::QXmlQuery(const QXmlNamePool &np) : d(new QXmlQueryPrivate(np))
286 Constructs a query that will be used to run Xqueries or XSL-T
287 stylesheets, depending on the value of \a queryLanguage. It will use
288 \a np as its name pool.
290 \note If your QXmlQuery will process XSL-T stylesheets, this
291 constructor must be used. The default constructor can only
292 create instances of QXmlQuery for running XQueries.
294 \note The XSL-T support in this release is considered experimental.
295 See the \l{XQuery#XSLT 2.0} {XSLT conformance} for details.
300 QXmlQuery::QXmlQuery(QueryLanguage queryLanguage,
301 const QXmlNamePool &np) : d(new QXmlQueryPrivate(np))
303 d->queryLanguage = queryLanguage;
307 Destroys this QXmlQuery.
309 QXmlQuery::~QXmlQuery()
315 Assigns \a other to this QXmlQuery instance.
317 QXmlQuery &QXmlQuery::operator=(const QXmlQuery &other)
319 /* Keep this section in sync with QXmlQuery::QXmlQuery(const QXmlQuery &).
331 Changes the \l {QAbstractMessageHandler}{message handler} for this
332 QXmlQuery to \a aMessageHandler. The query sends all compile and
333 runtime messages to this message handler. QXmlQuery does not take
334 ownership of \a aMessageHandler.
336 Normally, the default message handler is sufficient. It writes
337 compile and runtime messages to \e stderr. The default message
338 handler includes color codes if \e stderr can render colors.
340 Note that changing the message handler after the query has been
341 compiled has no effect, i.e. the query uses the same message handler
342 at runtime that it uses at compile time.
344 When QXmlQuery calls QAbstractMessageHandler::message(),
345 the arguments are as follows:
349 \li message() argument
353 \li Only QtWarningMsg and QtFatalMsg are used. The former
354 identifies a compile or runtime warning, while the
355 latter identifies a dynamic or static error.
357 \li const QString & description
358 \li An XHTML document which is the actual message. It is translated
359 into the current language.
361 \li const QUrl &identifier
362 \li Identifies the error with a URI, where the fragment is
363 the error code, and the rest of the URI is the error namespace.
365 \li const QSourceLocation & sourceLocation
366 \li Identifies where the error occurred.
370 void QXmlQuery::setMessageHandler(QAbstractMessageHandler *aMessageHandler)
372 d->messageHandler = aMessageHandler;
376 Returns the message handler that handles compile and runtime
377 messages for this QXmlQuery.
379 QAbstractMessageHandler *QXmlQuery::messageHandler() const
381 return d->messageHandler;
385 Sets this QXmlQuery to an XQuery read from the \a sourceCode
386 device. The device must have been opened with at least
389 \a documentURI represents the query obtained from the \a sourceCode
390 device. It is the base URI of the static context, as defined in the
391 \l {http://www.w3.org/TR/xquery/}{XQuery language}. It is used
392 internally to resolve relative URIs that appear in the query, and
393 for message reporting. \a documentURI can be empty. If it is empty,
394 the \l{QCoreApplication::applicationFilePath()} {application file
395 path} is used. If it is not empty, it may be either relative or
396 absolute. If it is relative, it is resolved itself against the
397 \l {QCoreApplication::applicationFilePath()} {application file
398 path} before it is used. If \a documentURI is neither a valid URI
399 nor empty, the result is undefined.
401 If the query contains a static error (e.g. syntax error), an error
402 message is sent to the messageHandler(), and isValid() will return
405 Variables must be bound before setQuery() is called.
407 The encoding of the XQuery in \a sourceCode is detected internally
408 using the rules for setting and detecting encoding of XQuery files,
409 which are explained in the \l {http://www.w3.org/TR/xquery/}
412 If \a sourceCode is \c null or not readable, or if \a documentURI is not
413 a valid URI, behavior is undefined.
416 void QXmlQuery::setQuery(QIODevice *sourceCode, const QUrl &documentURI)
420 qWarning("A null QIODevice pointer cannot be passed.");
424 if(!sourceCode->isReadable())
426 qWarning("The device must be readable.");
430 d->queryURI = QPatternist::XPathHelper::normalizeQueryURI(documentURI);
431 d->expression(sourceCode);
436 The behavior and requirements of this function are the same as for
437 setQuery(QIODevice*, const QUrl&), after the XQuery has been read
438 from the IO device into a string. Because \a sourceCode is already
439 a Unicode string, detection of its encoding is unnecessary.
441 void QXmlQuery::setQuery(const QString &sourceCode, const QUrl &documentURI)
443 Q_ASSERT_X(documentURI.isEmpty() || documentURI.isValid(), Q_FUNC_INFO,
444 "The document URI must be valid.");
446 QByteArray query(sourceCode.toUtf8());
447 QBuffer buffer(&query);
448 buffer.open(QIODevice::ReadOnly);
450 setQuery(&buffer, documentURI);
454 Sets this QXmlQuery to the XQuery read from the \a queryURI. Use
455 isValid() after calling this function. If an error occurred reading
456 \a queryURI, e.g., the query does not exist, cannot be read, or is
457 invalid, isValid() will return \e false.
459 The supported URI schemes are the same as those in the XQuery
460 function \c{fn:doc}, except that queryURI can be the object of
463 \a baseURI is the Base URI of the static context, as defined in the
464 \l {http://www.w3.org/TR/xquery/}{XQuery language}. It is used
465 internally to resolve relative URIs that appear in the query, and
466 for message reporting. If \a baseURI is empty, \a queryURI is used.
467 Otherwise, \a baseURI is used, and it is resolved against the \l
468 {QCoreApplication::applicationFilePath()} {application file path} if
471 If \a queryURI is empty or invalid, or if \a baseURI is invalid,
472 the behavior of this function is undefined.
474 void QXmlQuery::setQuery(const QUrl &queryURI, const QUrl &baseURI)
476 Q_ASSERT_X(queryURI.isValid(), Q_FUNC_INFO, "The passed URI must be valid.");
478 const QUrl canonicalURI(QPatternist::XPathHelper::normalizeQueryURI(queryURI));
479 Q_ASSERT(canonicalURI.isValid());
480 Q_ASSERT(!canonicalURI.isRelative());
481 Q_ASSERT(baseURI.isValid() || baseURI.isEmpty());
483 d->queryURI = QPatternist::XPathHelper::normalizeQueryURI(baseURI.isEmpty() ? queryURI : baseURI);
485 QPatternist::AutoPtr<QIODevice> result;
489 result.reset(QPatternist::AccelTreeResourceLoader::load(canonicalURI, d->m_networkAccessDelegator,
490 d->staticContext()));
492 catch(const QPatternist::Exception)
494 /* We do nothing, result will be 0. */
499 setQuery(result.data(), d->queryURI);
503 d->recompileRequired();
507 Binds the variable \a name to the \a value so that $\a name can be
508 used from within the query to refer to the \a value.
510 \a name must not be \e null. \a {name}.isNull() must return false.
511 If \a name has already been bound by a previous bindVariable() call,
512 its previous binding will be overridden.
514 If \a {value} is null so that \a {value}.isNull() returns true, and
515 \a {name} already has a binding, the effect is to remove the
516 existing binding for \a {name}.
518 To bind a value of type QString or QUrl, wrap the value in a
519 QVariant such that QXmlItem's QVariant constructor is called.
521 All strings processed by the query must be valid XQuery strings,
522 which means they must contain only XML 1.0 characters. However,
523 this requirement is not checked. If the query processes an invalid
524 string, the behavior is undefined.
526 \sa QVariant::isValid(), {QtXDM}{How QVariant maps to XQuery's Data Model},
529 void QXmlQuery::bindVariable(const QXmlName &name, const QXmlItem &value)
533 qWarning("The variable name cannot be null.");
537 const QPatternist::VariableLoader::Ptr vl(d->variableLoader());
538 const QVariant variant(QVariant::fromValue(value));
540 /* If the type of the variable changed(as opposed to only the value),
541 * we will have to recompile. */
542 if(vl->invalidationRequired(name, variant) || value.isNull())
543 d->recompileRequired();
545 vl->addBinding(name, variant);
551 This function constructs a QXmlName from \a localName using the
552 query's \l {QXmlNamePool} {namespace}. The function then behaves as
553 the overloaded function. It is equivalent to the following snippet.
555 \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 0
557 void QXmlQuery::bindVariable(const QString &localName, const QXmlItem &value)
559 bindVariable(QXmlName(d->namePool, localName), value);
563 Binds the variable \a name to the \a device so that $\a name can be
564 used from within the query to refer to the \a device. The QIODevice
565 \a device is exposed to the query as a URI of type \c{xs:anyURI},
566 which can be passed to the \c{fn:doc()} function to be read. E.g.,
567 this function can be used to pass an XML document in memory to
570 \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 1
572 The caller must ensure that \a device has been opened with at least
573 QIODevice::ReadOnly prior to this binding. Otherwise, behavior is
576 If the query will access an XML document contained in a QString, use
577 a QBuffer as shown in the following snippet. Suppose \e myQString
578 contains \c{<document>content</document>}
580 \snippet doc/src/snippets/qxmlquery/bindingExample.cpp 0
582 \a name must not be \e null. \a {name}.isNull() must return false.
583 If \a name has already been bound, its previous binding will be
584 overridden. The URI that \a name evaluates to is arbitrary and may
587 If the type of the variable binding changes (e.g., if a previous
588 binding by the same name was a QVariant, or if there was no previous
589 binding), isValid() will return \c{false}, and recompilation of the
590 query text is required. To recompile the query, call setQuery(). For
591 this reason, bindVariable() should be called before setQuery(), if
594 \note \a device must not be deleted while this QXmlQuery exists.
596 void QXmlQuery::bindVariable(const QXmlName &name, QIODevice *device)
598 if(device && !device->isReadable())
600 qWarning("A null, or readable QIODevice must be passed.");
606 qWarning("The variable name cannot be null.");
610 const QPatternist::VariableLoader::Ptr vl(d->variableLoader());
614 const QVariant variant(QVariant::fromValue(device));
616 if(vl->invalidationRequired(name, variant))
617 d->recompileRequired();
619 vl->addBinding(name, variant);
621 /* We need to tell the resource loader to discard its document, because
622 * the underlying QIODevice has changed, but the variable name is the
623 * same which means that the URI is the same, and hence the resource
624 * loader will return the document for the old QIODevice.
626 d->resourceLoader()->clear(QUrl(QLatin1String("tag:trolltech.com,2007:QtXmlPatterns:QIODeviceVariable:") + d->namePool.d->stringForLocalName(name.localName())));
630 vl->removeBinding(name);
631 d->recompileRequired();
638 If \a localName is a valid \l {QXmlName::isNCName()} {NCName}, this
639 function is equivalent to the following snippet.
641 \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 2
643 A QXmlName is constructed from \a localName, and is passed
644 to the appropriate overload along with \a device.
646 \sa QXmlName::isNCName()
648 void QXmlQuery::bindVariable(const QString &localName, QIODevice *device)
650 bindVariable(QXmlName(d->namePool, localName), device);
654 Evaluates this query and sends the result as a sequence of callbacks
655 to the \l {QAbstractXmlReceiver} {receiver} \a callback. QXmlQuery
656 does not take ownership of \a callback.
658 If an error occurs during the evaluation, error messages are sent to
659 messageHandler() and \c false is returned.
661 If this query \l {isValid()} {is invalid}, \c{false} is returned
662 and the behavior is undefined. If \a callback is null,
663 behavior is undefined.
665 \sa QAbstractXmlReceiver, isValid()
667 bool QXmlQuery::evaluateTo(QAbstractXmlReceiver *callback) const
671 qWarning("A non-null callback must be passed.");
680 * This order is significant. expression() might cause
681 * query recompilation, and as part of that it recreates
682 * the static context. However, if we create the dynamic
683 * context before the query recompilation has been
684 * triggered, it will use the old static context, and
685 * hence old source locations.
687 const QPatternist::Expression::Ptr expr(d->expression());
688 const QPatternist::DynamicContext::Ptr dynContext(d->dynamicContext(callback));
689 callback->startOfSequence();
690 expr->evaluateToSequenceReceiver(dynContext);
691 callback->endOfSequence();
694 catch(const QPatternist::Exception)
704 Attempts to evaluate the query and returns the results in the
705 \a target \l {QStringList} {string list}.
707 If the query \l {isValid()} {is valid} and the evaluation succeeds,
708 true is returned. Otherwise, false is returned and the contents of
709 \a target are undefined.
711 The query must evaluate to a sequence of \c{xs:string} values. If
712 the query does not evaluate to a sequence of strings, the values can
713 often be converted by adding a call to \c{string()} at the end of
716 If \a target is null, the behavior is undefined.
718 bool QXmlQuery::evaluateTo(QStringList *target) const
722 qWarning("A non-null callback must be passed.");
731 * This order is significant. expression() might cause
732 * query recompilation, and as part of that it recreates
733 * the static context. However, if we create the dynamic
734 * context before the query recompilation has been
735 * triggered, it will use the old static context, and
736 * hence old source locations.
738 const QPatternist::Expression::Ptr expr(d->expression());
742 QPatternist::DynamicContext::Ptr dynContext(d->dynamicContext());
744 if(!QPatternist::BuiltinTypes::xsString->xdtTypeMatches(expr->staticType()->itemType()))
747 const QPatternist::Item::Iterator::Ptr it(expr->evaluateSequence(dynContext));
748 QPatternist::Item next(it->next());
750 while(!next.isNull())
752 target->append(next.stringValue());
758 catch(const QPatternist::Exception)
768 Evaluates the query or stylesheet, and writes the output to \a target.
770 QXmlSerializer is used to write the output to \a target. In a future
771 release, it is expected that this function will be changed to
772 respect serialization options set in the stylesheet.
774 If an error occurs during the evaluation, error messages are sent to
775 messageHandler() and \c false is returned.
777 If \a target is \c null, or is not opened in at least
778 QIODevice::WriteOnly mode, the behavior is undefined. QXmlQuery
779 does not take ownership of \a target.
784 bool QXmlQuery::evaluateTo(QIODevice *target) const
788 qWarning("The pointer to the device cannot be null.");
792 if(!target->isWritable())
794 qWarning("The device must be writable.");
798 QXmlSerializer serializer(*this, target);
799 return evaluateTo(&serializer);
803 Starts the evaluation and makes it available in \a result. If \a
804 result is null, the behavior is undefined. The evaluation takes
805 place incrementally (lazy evaluation), as the caller uses
806 QXmlResultItems::next() to get the next result.
808 \sa QXmlResultItems::next()
810 void QXmlQuery::evaluateTo(QXmlResultItems *result) const
814 qWarning("A null pointer cannot be passed.");
823 * We don't have the d->expression() calls and
824 * d->dynamicContext() calls in the same order as seen in
825 * QXmlQuery::evaluateTo(), and the reason to why
826 * that isn't a problem, is that we call isValid().
828 const QPatternist::DynamicContext::Ptr dynContext(d->dynamicContext());
829 result->d_ptr->setDynamicContext(dynContext);
830 result->d_ptr->iterator = d->expression()->evaluateSequence(dynContext);
832 catch(const QPatternist::Exception)
834 result->d_ptr->iterator = QPatternist::CommonValues::emptyIterator;
835 result->d_ptr->hasError = true;
840 result->d_ptr->iterator= QPatternist::CommonValues::emptyIterator;
841 result->d_ptr->hasError = true;
846 Evaluates the query, and serializes the output as XML to \a output.
848 If an error occurs during the evaluation, error messages are sent to
849 messageHandler(), the content of \a output is undefined and \c false is
850 returned, otherwise \c true is returned.
852 If \a output is \c null behavior is undefined. QXmlQuery
853 does not take ownership of \a output.
855 Internally, the class QXmlFormatter is used for this.
858 bool QXmlQuery::evaluateTo(QString *output) const
860 Q_ASSERT_X(output, Q_FUNC_INFO,
861 "The input cannot be null");
863 QBuffer outputDevice;
864 outputDevice.open(QIODevice::ReadWrite);
866 QXmlFormatter formatter(*this, &outputDevice);
867 const bool success = evaluateTo(&formatter);
869 outputDevice.close();
870 *output = QString::fromUtf8(outputDevice.data().constData());
876 Returns true if this query is valid. Examples of invalid queries
877 are ones that contain syntax errors or that have not had setQuery()
880 bool QXmlQuery::isValid() const
886 Sets the URI resolver to \a resolver. QXmlQuery does not take
887 ownership of \a resolver.
891 void QXmlQuery::setUriResolver(const QAbstractUriResolver *resolver)
893 d->uriResolver = resolver;
897 Returns the query's URI resolver. If no URI resolver has been set,
898 QtXmlPatterns will use the URIs in queries as they are.
900 The URI resolver provides a level of abstraction, or \e{polymorphic
901 URIs}. A resolver can rewrite \e{logical} URIs to physical ones, or
902 it can translate obsolete or invalid URIs to valid ones.
904 QtXmlPatterns calls the URI resolver for all URIs it encounters,
905 except for namespaces. Specifically, all builtin functions that deal
906 with URIs (\c{fn:doc()}, and \c{fn:doc-available()}).
908 In the case of \c{fn:doc()}, the absolute URI is the base URI in the
909 static context (which most likely is the location of the query).
910 Rather than use the URI the user specified, the return value of
911 QAbstractUriResolver::resolve() will be used.
913 When QtXmlPatterns calls QAbstractUriResolver::resolve() the
914 absolute URI is the URI mandated by the XQuery language, and the
915 relative URI is the URI specified by the user.
919 const QAbstractUriResolver *QXmlQuery::uriResolver() const
921 return d->uriResolver;
925 Returns the name pool used by this QXmlQuery for constructing \l
926 {QXmlName} {names}. There is no setter for the name pool, because
927 mixing name pools causes errors due to name confusion.
929 QXmlNamePool QXmlQuery::namePool() const
935 Sets the focus to \a item. The focus is the set of items that the
936 context item expression and path expressions navigate from. For
937 example, in the expression \e p/span, the element that \e p
938 evaluates to is the focus for the following expression, \e span.
940 The focus can be accessed using the context item expression, i.e.,
943 By default, the focus is not set and is undefined. It will
944 therefore result in a dynamic error, \c XPDY0002, if the focus
945 is attempted to be accessed. The focus must be set before the
946 query is set with setQuery().
948 There is no behavior defined for setting an item which is null.
951 void QXmlQuery::setFocus(const QXmlItem &item)
953 d->contextItem = item;
957 * This function should be a private member function of QXmlQuery,
958 * but we don't dare that due to our weird compilers.
962 template<typename TInputType>
963 bool setFocusHelper(QXmlQuery *const queryInstance,
964 const TInputType &focusValue)
966 /* We call resourceLoader(), so we have ensured that we have a resourceLoader
967 * that we will share in our copy. */
968 queryInstance->d->resourceLoader();
970 QXmlQuery focusQuery(*queryInstance);
972 /* Now we use the same, so we own the loaded document. */
973 focusQuery.d->m_resourceLoader = queryInstance->d->m_resourceLoader;
975 /* The copy constructor doesn't allow us to copy an existing QXmlQuery and
976 * changing the language at the same time so we need to use private API. */
977 focusQuery.d->queryLanguage = QXmlQuery::XQuery10;
979 Q_ASSERT(focusQuery.queryLanguage() == QXmlQuery::XQuery10);
980 focusQuery.bindVariable(QChar::fromLatin1('u'), focusValue);
981 focusQuery.setQuery(QLatin1String("doc($u)"));
982 Q_ASSERT(focusQuery.isValid());
984 QXmlResultItems focusResult;
986 queryInstance->d->m_resourceLoader = focusQuery.d->m_resourceLoader;
988 focusQuery.evaluateTo(&focusResult);
989 const QXmlItem focusItem(focusResult.next());
991 if(focusItem.isNull() || focusResult.hasError())
995 queryInstance->setFocus(focusItem);
1004 Sets the focus to be the document located at \a documentURI and
1005 returns true. If \a documentURI cannot be loaded, false is returned.
1006 It is undefined at what time the document may be loaded. When
1007 loading the document, the message handler and URI resolver set on
1008 this QXmlQuery are used.
1010 If \a documentURI is empty or is not a valid URI, the behavior of
1011 this function is undefined.
1013 bool QXmlQuery::setFocus(const QUrl &documentURI)
1015 Q_ASSERT_X(documentURI.isValid() && !documentURI.isEmpty(),
1017 "The URI passed must be valid.");
1019 return setFocusHelper(this, QVariant(documentURI));
1024 Sets the focus to be the \a document read from the QIODevice and
1025 returns true. If \a document cannot be loaded, false is returned.
1027 QXmlQuery does not take ownership of \a document. The user
1028 guarantees that a document is available from the \a document device
1029 and that the document is not empty. The device must be opened in at
1030 least read-only mode. \a document must stay in scope as long as the
1031 current query is active.
1036 bool QXmlQuery::setFocus(QIODevice *document)
1040 qWarning("A null QIODevice pointer cannot be passed.");
1044 if(!document->isReadable())
1046 qWarning("The device must be readable.");
1050 return setFocusHelper(this, document);
1054 This function behaves identically to calling the setFocus() overload with a
1055 QIODevice whose content is \a focus encoded as UTF-8. That is, \a focus is
1056 treated as if it contained an XML document.
1058 Returns the same result as the overload.
1063 bool QXmlQuery::setFocus(const QString &focus)
1066 device.setData(focus.toUtf8());
1067 device.open(QIODevice::ReadOnly);
1069 return setFocusHelper(this, &device);
1073 Returns a value indicating what this QXmlQuery is being used for.
1074 The default is QXmlQuery::XQuery10, which means the QXmlQuery is
1075 being used for running XQuery and XPath queries. QXmlQuery::XSLT20
1076 can also be returned, which indicates the QXmlQuery is for running
1081 QXmlQuery::QueryLanguage QXmlQuery::queryLanguage() const
1083 return d->queryLanguage;
1087 Sets the \a name of the initial template. The initial template is
1088 the one the processor calls first, instead of attempting to match a
1089 template to the context node (if any). If an initial template is not
1090 set, the standard order of template invocation will be used.
1092 This function only applies when using QXmlQuery to process XSL-T
1093 stylesheets. The name becomes part of the compiled stylesheet.
1094 Therefore, this function must be called before calling setQuery().
1096 If the stylesheet has no template named \a name, the processor will
1097 use the standard order of template invocation.
1100 \sa initialTemplateName()
1102 void QXmlQuery::setInitialTemplateName(const QXmlName &name)
1104 d->initialTemplateName = name;
1110 Sets the name of the initial template to \a localName, which must be
1111 a valid \l{QXmlName::localName()} {local name}. The initial template
1112 is the one the processor calls first, instead of attempting to match
1113 a template to the context node (if any). If an initial template is
1114 not set, the standard order of template invocation will be used.
1116 This function only applies when using QXmlQuery to process XSL-T
1117 stylesheets. The name becomes part of the compiled stylesheet.
1118 Therefore, this function must be called before calling setQuery().
1120 If \a localName is not a valid \l{QXmlName::localName()} {local
1121 name}, the effect is undefined. If the stylesheet has no template
1122 named \a localName, the processor will use the standard order of
1123 template invocation.
1126 \sa initialTemplateName()
1128 void QXmlQuery::setInitialTemplateName(const QString &localName)
1130 Q_ASSERT_X(QXmlName::isNCName(localName),
1132 "The name passed must be a valid NCName.");
1133 setInitialTemplateName(QXmlName(d->namePool, localName));
1137 Returns the name of the XSL-T stylesheet template that the processor
1138 will call first when running an XSL-T stylesheet. This function only
1139 applies when using QXmlQuery to process XSL-T stylesheets. By
1140 default, no initial template is set. In that case, a default
1141 constructed QXmlName is returned.
1145 QXmlName QXmlQuery::initialTemplateName() const
1147 return d->initialTemplateName;
1151 Sets the network manager to \a newManager.
1152 QXmlQuery does not take ownership of \a newManager.
1154 \sa networkAccessManager()
1157 void QXmlQuery::setNetworkAccessManager(QNetworkAccessManager *newManager)
1159 d->m_networkAccessDelegator->m_genericManager = newManager;
1163 Returns the network manager, or 0 if it has not been set.
1165 \sa setNetworkAccessManager()
1168 QNetworkAccessManager *QXmlQuery::networkAccessManager() const
1170 return d->m_networkAccessDelegator->m_genericManager;
1174 Binds the result of the query \a query, to a variable by name \a name.
1176 Evaluation of \a query will be commenced when this function is called.
1178 If \a query is invalid, behavior is undefined. \a query will be copied.
1183 void QXmlQuery::bindVariable(const QXmlName &name, const QXmlQuery &query)
1185 Q_ASSERT_X(query.isValid(), Q_FUNC_INFO, "The query being bound must be valid.");
1187 const QPatternist::VariableLoader::Ptr vl(d->variableLoader());
1188 const QVariant variant(QVariant::fromValue(query));
1190 if(vl->invalidationRequired(name, variant))
1191 d->recompileRequired();
1193 vl->addBinding(name, variant);
1199 Has the same behavior and effects as the function being overloaded, but takes
1200 the variable name \a localName as a QString. \a query is used as in the
1201 overloaded function.
1205 void QXmlQuery::bindVariable(const QString &localName, const QXmlQuery &query)
1207 return bindVariable(QXmlName(d->namePool, localName), query);