1 /****************************************************************************
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** GNU Lesser General Public License Usage
11 ** This file may be used under the terms of the GNU Lesser General Public
12 ** License version 2.1 as published by the Free Software Foundation and
13 ** appearing in the file LICENSE.LGPL included in the packaging of this
14 ** file. Please review the following information to ensure the GNU Lesser
15 ** General Public License version 2.1 requirements will be met:
16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
18 ** In addition, as a special exception, Nokia gives you certain additional
19 ** rights. These rights are described in the Nokia Qt LGPL Exception
20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
22 ** GNU General Public License Usage
23 ** Alternatively, this file may be used under the terms of the GNU General
24 ** Public License version 3.0 as published by the Free Software Foundation
25 ** and appearing in the file LICENSE.GPL included in the packaging of this
26 ** file. Please review the following information to ensure the GNU General
27 ** Public License version 3.0 requirements will be met:
28 ** http://www.gnu.org/copyleft/gpl.html.
31 ** Alternatively, this file may be used in accordance with the terms and
32 ** 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.
67 The QXmlQuery class compiles and executes queries written in the
68 \l {http://www.w3.org/TR/xquery/}{XQuery language}. QXmlQuery is
69 typically used to query XML data, but it can also query non-XML
70 data that has been modeled to look like XML.
72 Using QXmlQuery to query XML data, as in the snippet below, is
73 simple because it can use the built-in \l {QAbstractXmlNodeModel}
74 {XML data model} as its delegate to the underlying query engine for
75 traversing the data. The built-in data model is specified in \l
76 {http://www.w3.org/TR/xpath-datamodel/} {XQuery 1.0 and XPath 2.0
79 \snippet doc/src/snippets/code/src_xmlpatterns_api_qabstractxmlreceiver.cpp 0
81 The example uses QXmlQuery to match the first paragraph of an XML
82 document and then \l {QXmlSerializer} {output the result} to a
85 Using QXmlQuery to query \e {non-XML} data requires writing a
86 subclass of QAbstractXmlNodeModel to use as a replacement for the
87 built-in XML data model. The custom data model will be able to
88 traverse the non-XML data as required by the QAbstractXmlNodeModel
89 interface. An instance of this custom data model then becomes the
90 delegate used by the query engine to traverse the non-XML data. For
91 an example of how to use QXmlQuery to query non-XML data, see the
92 documentation for QAbstractXmlNodeModel.
94 \section1 Running XQueries
96 To run a query set up with QXmlQuery, call one of the evaluation
101 \o evaluateTo(QAbstractXmlReceiver *) is called with a pointer to an
102 XML \l {QAbstractXmlReceiver} {receiver}, which receives the query
103 results as a sequence of callbacks. The receiver callback class is
104 like the callback class used for translating the output of a SAX
105 parser. QXmlSerializer, for example, is a receiver callback class
106 for translating the sequence of callbacks for output as unformatted
113 \o evaluateTo(QXmlResultItems *) is called with a pointer to an
114 iterator for an empty sequence of query \l {QXmlResultItems} {result
115 items}. The Java-like iterator allows the query results to be
116 accessed sequentially.
122 \o evaluateTo(QStringList *) is like evaluateTo(QXmlResultItems *),
123 but the query must evaluate to a sequence of strings.
127 \section1 Running XPath Expressions
129 The XPath language is a subset of the XQuery language, so
130 running an XPath expression is the same as running an XQuery
131 query. Pass the XPath expression to QXmlQuery using setQuery().
133 \section1 Running XSLT stylesheets
135 Running an XSLT stylesheet is like running an XQuery, except that
136 when you construct your QXmlQuery, you must pass QXmlQuery::XSLT20
137 to tell QXmlQuery to interpret whatever it gets from setQuery() as
138 an XSLT stylesheet instead of as an XQuery. You must also set the
139 input document by calling setFocus().
141 \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 7
143 \note Currently, setFocus() must be called \e before setQuery() when
146 Another way to run an XSLT stylesheet is to use the \c xmlpatterns
147 command line utility.
150 xmlpatterns myStylesheet.xsl myInput.xml
153 \note For the current release, XSLT support should be considered
154 experimental. See section \l{XQuery#XSLT 2.0} {XSLT conformance} for
157 Stylesheet parameters are bound using bindVariable().
159 \section1 Binding A Query To A Starting Node
161 When a query is run on XML data, as in the snippet above, the
162 \c{doc()} function returns the node in the built-in data model where
163 the query evaluation will begin. But when a query is run on a custom
164 node model containing non-XML data, one of the bindVariable()
165 functions must be called to bind a variable name to a starting node
166 in the custom model. A $variable reference is used in the XQuery
167 text to access the starting node in the custom model. It is not
168 necessary to declare the variable name external in the query. See
169 the example in the documentation for QAbstractXmlNodeModel.
171 \section1 Reentrancy and Thread-Safety
173 QXmlQuery is reentrant but not thread-safe. It is safe to use the
174 QxmlQuery copy constructor to create a copy of a query and run the
175 same query multiple times. Behind the scenes, QXmlQuery will reuse
176 resources such as opened files and compiled queries to the extent
177 possible. But it is not safe to use the same instance of QXmlQuery
180 \section1 Error Handling
182 Errors can occur during query evaluation. Examples include type
183 errors and file loading errors. When an error occurs:
187 \o The error message is sent to the messageHandler().
189 \o QXmlResultItems::hasError() will return \c{true}, or
190 evaluateTo() will return \c{false};
192 \o The results of the evaluation are undefined.
196 \section1 Resource Management
198 When a query runs, it parses documents, allocating internal data
199 structures to hold them, and it may load other resources over the
200 network. It reuses these allocated resources when possible, to
201 avoid having to reload and reparse them.
203 When setQuery() is called, the query text is compiled into an
204 internal data structure and optimized. The optimized form can
205 then be reused for multiple evaluations of the query. Since the
206 compile-and-optimize process can be expensive, repeating it for
207 the same query should be avoided by using a separate instance of
208 QXmlQuery for each query text.
210 Once a document has been parsed, its internal representation is
211 maintained in the QXmlQuery instance and shared among multiple
214 An instance of QCoreApplication must exist before QXmlQuery can be
217 \section1 Event Handling
219 When QXmlQuery accesses resources (e.g., calling \c fn:doc() to load a file,
220 or accessing a device via a bound variable), the event loop is used, which
221 means events will be processed. To avoid processing events when QXmlQuery
222 accesses resources, create your QXmlQuery instance in a separate thread.
226 \enum QXmlQuery::QueryLanguage
229 Specifies whether you want QXmlQuery to interpret the input to
230 setQuery() as an XQuery or as an XSLT stylesheet.
232 \value XQuery10 XQuery 1.0.
233 \value XSLT20 XSLT 2.0
234 \omitvalue XmlSchema11IdentityConstraintSelector The selector, the restricted
235 XPath pattern found in W3C XML Schema 1.1 for uniqueness
236 contraints. Apart from restricting the syntax, the type check stage
237 for the expression assumes a sequence of nodes to be the focus.
238 \omitvalue XmlSchema11IdentityConstraintField The field, the restricted
239 XPath pattern found in W3C XML Schema 1.1 for uniqueness
240 contraints. Apart from restricting the syntax, the type check stage
241 for the expression assumes a sequence of nodes to be the focus.
242 \omitvalue XPath20 Signifies XPath 2.0. Has no effect in the public API, it's
243 used internally. As With XmlSchema11IdentityConstraintSelector and
244 XmlSchema11IdentityConstraintField, the type check stage
245 for the expression assumes a sequence of nodes to be the focus.
250 // ### Qt5: Merge constructor overloads
252 Constructs an invalid, empty query that cannot be used until
253 setQuery() is called.
255 \note This constructor must not be used if you intend to use
256 this QXmlQuery to process XSL-T stylesheets. The other constructor
257 must be used in that case.
259 QXmlQuery::QXmlQuery() : d(new QXmlQueryPrivate())
264 Constructs a QXmlQuery that is a copy of \a other. The new
265 instance will share resources with the existing query
266 to the extent possible.
268 QXmlQuery::QXmlQuery(const QXmlQuery &other) : d(new QXmlQueryPrivate(*other.d))
270 /* First we have invoked QXmlQueryPrivate's synthesized copy constructor.
271 * Keep this section in sync with QXmlQuery::operator=(). */
276 Constructs a query that will use \a np as its name pool. The query
277 cannot be evaluated until setQuery() has been called.
279 QXmlQuery::QXmlQuery(const QXmlNamePool &np) : d(new QXmlQueryPrivate(np))
285 Constructs a query that will be used to run Xqueries or XSL-T
286 stylesheets, depending on the value of \a queryLanguage. It will use
287 \a np as its name pool.
289 \note If your QXmlQuery will process XSL-T stylesheets, this
290 constructor must be used. The default constructor can only
291 create instances of QXmlQuery for running XQueries.
293 \note The XSL-T support in this release is considered experimental.
294 See the \l{XQuery#XSLT 2.0} {XSLT conformance} for details.
299 QXmlQuery::QXmlQuery(QueryLanguage queryLanguage,
300 const QXmlNamePool &np) : d(new QXmlQueryPrivate(np))
302 d->queryLanguage = queryLanguage;
306 Destroys this QXmlQuery.
308 QXmlQuery::~QXmlQuery()
314 Assigns \a other to this QXmlQuery instance.
316 QXmlQuery &QXmlQuery::operator=(const QXmlQuery &other)
318 /* Keep this section in sync with QXmlQuery::QXmlQuery(const QXmlQuery &).
330 Changes the \l {QAbstractMessageHandler}{message handler} for this
331 QXmlQuery to \a aMessageHandler. The query sends all compile and
332 runtime messages to this message handler. QXmlQuery does not take
333 ownership of \a aMessageHandler.
335 Normally, the default message handler is sufficient. It writes
336 compile and runtime messages to \e stderr. The default message
337 handler includes color codes if \e stderr can render colors.
339 Note that changing the message handler after the query has been
340 compiled has no effect, i.e. the query uses the same message handler
341 at runtime that it uses at compile time.
343 When QXmlQuery calls QAbstractMessageHandler::message(),
344 the arguments are as follows:
348 \o message() argument
352 \o Only QtWarningMsg and QtFatalMsg are used. The former
353 identifies a compile or runtime warning, while the
354 latter identifies a dynamic or static error.
356 \o const QString & description
357 \o An XHTML document which is the actual message. It is translated
358 into the current language.
360 \o const QUrl &identifier
361 \o Identifies the error with a URI, where the fragment is
362 the error code, and the rest of the URI is the error namespace.
364 \o const QSourceLocation & sourceLocation
365 \o Identifies where the error occurred.
369 void QXmlQuery::setMessageHandler(QAbstractMessageHandler *aMessageHandler)
371 d->messageHandler = aMessageHandler;
375 Returns the message handler that handles compile and runtime
376 messages for this QXmlQuery.
378 QAbstractMessageHandler *QXmlQuery::messageHandler() const
380 return d->messageHandler;
384 Sets this QXmlQuery to an XQuery read from the \a sourceCode
385 device. The device must have been opened with at least
388 \a documentURI represents the query obtained from the \a sourceCode
389 device. It is the base URI of the static context, as defined in the
390 \l {http://www.w3.org/TR/xquery/}{XQuery language}. It is used
391 internally to resolve relative URIs that appear in the query, and
392 for message reporting. \a documentURI can be empty. If it is empty,
393 the \l{QCoreApplication::applicationFilePath()} {application file
394 path} is used. If it is not empty, it may be either relative or
395 absolute. If it is relative, it is resolved itself against the
396 \l {QCoreApplication::applicationFilePath()} {application file
397 path} before it is used. If \a documentURI is neither a valid URI
398 nor empty, the result is undefined.
400 If the query contains a static error (e.g. syntax error), an error
401 message is sent to the messageHandler(), and isValid() will return
404 Variables must be bound before setQuery() is called.
406 The encoding of the XQuery in \a sourceCode is detected internally
407 using the rules for setting and detecting encoding of XQuery files,
408 which are explained in the \l {http://www.w3.org/TR/xquery/}
411 If \a sourceCode is \c null or not readable, or if \a documentURI is not
412 a valid URI, behavior is undefined.
415 void QXmlQuery::setQuery(QIODevice *sourceCode, const QUrl &documentURI)
419 qWarning("A null QIODevice pointer cannot be passed.");
423 if(!sourceCode->isReadable())
425 qWarning("The device must be readable.");
429 d->queryURI = QPatternist::XPathHelper::normalizeQueryURI(documentURI);
430 d->expression(sourceCode);
435 The behavior and requirements of this function are the same as for
436 setQuery(QIODevice*, const QUrl&), after the XQuery has been read
437 from the IO device into a string. Because \a sourceCode is already
438 a Unicode string, detection of its encoding is unnecessary.
440 void QXmlQuery::setQuery(const QString &sourceCode, const QUrl &documentURI)
442 Q_ASSERT_X(documentURI.isEmpty() || documentURI.isValid(), Q_FUNC_INFO,
443 "The document URI must be valid.");
445 QByteArray query(sourceCode.toUtf8());
446 QBuffer buffer(&query);
447 buffer.open(QIODevice::ReadOnly);
449 setQuery(&buffer, documentURI);
453 Sets this QXmlQuery to the XQuery read from the \a queryURI. Use
454 isValid() after calling this function. If an error occurred reading
455 \a queryURI, e.g., the query does not exist, cannot be read, or is
456 invalid, isValid() will return \e false.
458 The supported URI schemes are the same as those in the XQuery
459 function \c{fn:doc}, except that queryURI can be the object of
462 \a baseURI is the Base URI of the static context, as defined in the
463 \l {http://www.w3.org/TR/xquery/}{XQuery language}. It is used
464 internally to resolve relative URIs that appear in the query, and
465 for message reporting. If \a baseURI is empty, \a queryURI is used.
466 Otherwise, \a baseURI is used, and it is resolved against the \l
467 {QCoreApplication::applicationFilePath()} {application file path} if
470 If \a queryURI is empty or invalid, or if \a baseURI is invalid,
471 the behavior of this function is undefined.
473 void QXmlQuery::setQuery(const QUrl &queryURI, const QUrl &baseURI)
475 Q_ASSERT_X(queryURI.isValid(), Q_FUNC_INFO, "The passed URI must be valid.");
477 const QUrl canonicalURI(QPatternist::XPathHelper::normalizeQueryURI(queryURI));
478 Q_ASSERT(canonicalURI.isValid());
479 Q_ASSERT(!canonicalURI.isRelative());
480 Q_ASSERT(baseURI.isValid() || baseURI.isEmpty());
482 d->queryURI = QPatternist::XPathHelper::normalizeQueryURI(baseURI.isEmpty() ? queryURI : baseURI);
484 QPatternist::AutoPtr<QIODevice> result;
488 result.reset(QPatternist::AccelTreeResourceLoader::load(canonicalURI, d->m_networkAccessDelegator,
489 d->staticContext()));
491 catch(const QPatternist::Exception)
493 /* We do nothing, result will be 0. */
498 setQuery(result.data(), d->queryURI);
502 d->recompileRequired();
506 Binds the variable \a name to the \a value so that $\a name can be
507 used from within the query to refer to the \a value.
509 \a name must not be \e null. \a {name}.isNull() must return false.
510 If \a name has already been bound by a previous bindVariable() call,
511 its previous binding will be overridden.
513 If \a {value} is null so that \a {value}.isNull() returns true, and
514 \a {name} already has a binding, the effect is to remove the
515 existing binding for \a {name}.
517 To bind a value of type QString or QUrl, wrap the value in a
518 QVariant such that QXmlItem's QVariant constructor is called.
520 All strings processed by the query must be valid XQuery strings,
521 which means they must contain only XML 1.0 characters. However,
522 this requirement is not checked. If the query processes an invalid
523 string, the behavior is undefined.
525 \sa QVariant::isValid(), {QtXDM}{How QVariant maps to XQuery's Data Model},
528 void QXmlQuery::bindVariable(const QXmlName &name, const QXmlItem &value)
532 qWarning("The variable name cannot be null.");
536 const QPatternist::VariableLoader::Ptr vl(d->variableLoader());
537 const QVariant variant(QVariant::fromValue(value));
539 /* If the type of the variable changed(as opposed to only the value),
540 * we will have to recompile. */
541 if(vl->invalidationRequired(name, variant) || value.isNull())
542 d->recompileRequired();
544 vl->addBinding(name, variant);
550 This function constructs a QXmlName from \a localName using the
551 query's \l {QXmlNamePool} {namespace}. The function then behaves as
552 the overloaded function. It is equivalent to the following snippet.
554 \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 0
556 void QXmlQuery::bindVariable(const QString &localName, const QXmlItem &value)
558 bindVariable(QXmlName(d->namePool, localName), value);
562 Binds the variable \a name to the \a device so that $\a name can be
563 used from within the query to refer to the \a device. The QIODevice
564 \a device is exposed to the query as a URI of type \c{xs:anyURI},
565 which can be passed to the \c{fn:doc()} function to be read. E.g.,
566 this function can be used to pass an XML document in memory to
569 \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 1
571 The caller must ensure that \a device has been opened with at least
572 QIODevice::ReadOnly prior to this binding. Otherwise, behavior is
575 If the query will access an XML document contained in a QString, use
576 a QBuffer as shown in the following snippet. Suppose \e myQString
577 contains \c{<document>content</document>}
579 \snippet doc/src/snippets/qxmlquery/bindingExample.cpp 0
581 \a name must not be \e null. \a {name}.isNull() must return false.
582 If \a name has already been bound, its previous binding will be
583 overridden. The URI that \a name evaluates to is arbitrary and may
586 If the type of the variable binding changes (e.g., if a previous
587 binding by the same name was a QVariant, or if there was no previous
588 binding), isValid() will return \c{false}, and recompilation of the
589 query text is required. To recompile the query, call setQuery(). For
590 this reason, bindVariable() should be called before setQuery(), if
593 \note \a device must not be deleted while this QXmlQuery exists.
595 void QXmlQuery::bindVariable(const QXmlName &name, QIODevice *device)
597 if(device && !device->isReadable())
599 qWarning("A null, or readable QIODevice must be passed.");
605 qWarning("The variable name cannot be null.");
609 const QPatternist::VariableLoader::Ptr vl(d->variableLoader());
613 const QVariant variant(QVariant::fromValue(device));
615 if(vl->invalidationRequired(name, variant))
616 d->recompileRequired();
618 vl->addBinding(name, variant);
620 /* We need to tell the resource loader to discard its document, because
621 * the underlying QIODevice has changed, but the variable name is the
622 * same which means that the URI is the same, and hence the resource
623 * loader will return the document for the old QIODevice.
625 d->resourceLoader()->clear(QUrl(QLatin1String("tag:trolltech.com,2007:QtXmlPatterns:QIODeviceVariable:") + d->namePool.d->stringForLocalName(name.localName())));
629 vl->removeBinding(name);
630 d->recompileRequired();
637 If \a localName is a valid \l {QXmlName::isNCName()} {NCName}, this
638 function is equivalent to the following snippet.
640 \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 2
642 A QXmlName is constructed from \a localName, and is passed
643 to the appropriate overload along with \a device.
645 \sa QXmlName::isNCName()
647 void QXmlQuery::bindVariable(const QString &localName, QIODevice *device)
649 bindVariable(QXmlName(d->namePool, localName), device);
653 Evaluates this query and sends the result as a sequence of callbacks
654 to the \l {QAbstractXmlReceiver} {receiver} \a callback. QXmlQuery
655 does not take ownership of \a callback.
657 If an error occurs during the evaluation, error messages are sent to
658 messageHandler() and \c false is returned.
660 If this query \l {isValid()} {is invalid}, \c{false} is returned
661 and the behavior is undefined. If \a callback is null,
662 behavior is undefined.
664 \sa QAbstractXmlReceiver, isValid()
666 bool QXmlQuery::evaluateTo(QAbstractXmlReceiver *callback) const
670 qWarning("A non-null callback must be passed.");
679 * This order is significant. expression() might cause
680 * query recompilation, and as part of that it recreates
681 * the static context. However, if we create the dynamic
682 * context before the query recompilation has been
683 * triggered, it will use the old static context, and
684 * hence old source locations.
686 const QPatternist::Expression::Ptr expr(d->expression());
687 const QPatternist::DynamicContext::Ptr dynContext(d->dynamicContext(callback));
688 callback->startOfSequence();
689 expr->evaluateToSequenceReceiver(dynContext);
690 callback->endOfSequence();
693 catch(const QPatternist::Exception)
703 Attempts to evaluate the query and returns the results in the
704 \a target \l {QStringList} {string list}.
706 If the query \l {isValid()} {is valid} and the evaluation succeeds,
707 true is returned. Otherwise, false is returned and the contents of
708 \a target are undefined.
710 The query must evaluate to a sequence of \c{xs:string} values. If
711 the query does not evaluate to a sequence of strings, the values can
712 often be converted by adding a call to \c{string()} at the end of
715 If \a target is null, the behavior is undefined.
717 bool QXmlQuery::evaluateTo(QStringList *target) const
721 qWarning("A non-null callback must be passed.");
730 * This order is significant. expression() might cause
731 * query recompilation, and as part of that it recreates
732 * the static context. However, if we create the dynamic
733 * context before the query recompilation has been
734 * triggered, it will use the old static context, and
735 * hence old source locations.
737 const QPatternist::Expression::Ptr expr(d->expression());
741 QPatternist::DynamicContext::Ptr dynContext(d->dynamicContext());
743 if(!QPatternist::BuiltinTypes::xsString->xdtTypeMatches(expr->staticType()->itemType()))
746 const QPatternist::Item::Iterator::Ptr it(expr->evaluateSequence(dynContext));
747 QPatternist::Item next(it->next());
749 while(!next.isNull())
751 target->append(next.stringValue());
757 catch(const QPatternist::Exception)
767 Evaluates the query or stylesheet, and writes the output to \a target.
769 QXmlSerializer is used to write the output to \a target. In a future
770 release, it is expected that this function will be changed to
771 respect serialization options set in the stylesheet.
773 If an error occurs during the evaluation, error messages are sent to
774 messageHandler() and \c false is returned.
776 If \a target is \c null, or is not opened in at least
777 QIODevice::WriteOnly mode, the behavior is undefined. QXmlQuery
778 does not take ownership of \a target.
783 bool QXmlQuery::evaluateTo(QIODevice *target) const
787 qWarning("The pointer to the device cannot be null.");
791 if(!target->isWritable())
793 qWarning("The device must be writable.");
797 QXmlSerializer serializer(*this, target);
798 return evaluateTo(&serializer);
802 Starts the evaluation and makes it available in \a result. If \a
803 result is null, the behavior is undefined. The evaluation takes
804 place incrementally (lazy evaluation), as the caller uses
805 QXmlResultItems::next() to get the next result.
807 \sa QXmlResultItems::next()
809 void QXmlQuery::evaluateTo(QXmlResultItems *result) const
813 qWarning("A null pointer cannot be passed.");
822 * We don't have the d->expression() calls and
823 * d->dynamicContext() calls in the same order as seen in
824 * QXmlQuery::evaluateTo(), and the reason to why
825 * that isn't a problem, is that we call isValid().
827 const QPatternist::DynamicContext::Ptr dynContext(d->dynamicContext());
828 result->d_ptr->setDynamicContext(dynContext);
829 result->d_ptr->iterator = d->expression()->evaluateSequence(dynContext);
831 catch(const QPatternist::Exception)
833 result->d_ptr->iterator = QPatternist::CommonValues::emptyIterator;
834 result->d_ptr->hasError = true;
839 result->d_ptr->iterator= QPatternist::CommonValues::emptyIterator;
840 result->d_ptr->hasError = true;
845 Evaluates the query, and serializes the output as XML to \a output.
847 If an error occurs during the evaluation, error messages are sent to
848 messageHandler(), the content of \a output is undefined and \c false is
849 returned, otherwise \c true is returned.
851 If \a output is \c null behavior is undefined. QXmlQuery
852 does not take ownership of \a output.
854 Internally, the class QXmlFormatter is used for this.
857 bool QXmlQuery::evaluateTo(QString *output) const
859 Q_ASSERT_X(output, Q_FUNC_INFO,
860 "The input cannot be null");
862 QBuffer outputDevice;
863 outputDevice.open(QIODevice::ReadWrite);
865 QXmlFormatter formatter(*this, &outputDevice);
866 const bool success = evaluateTo(&formatter);
868 outputDevice.close();
869 *output = QString::fromUtf8(outputDevice.data().constData());
875 Returns true if this query is valid. Examples of invalid queries
876 are ones that contain syntax errors or that have not had setQuery()
879 bool QXmlQuery::isValid() const
885 Sets the URI resolver to \a resolver. QXmlQuery does not take
886 ownership of \a resolver.
890 void QXmlQuery::setUriResolver(const QAbstractUriResolver *resolver)
892 d->uriResolver = resolver;
896 Returns the query's URI resolver. If no URI resolver has been set,
897 QtXmlPatterns will use the URIs in queries as they are.
899 The URI resolver provides a level of abstraction, or \e{polymorphic
900 URIs}. A resolver can rewrite \e{logical} URIs to physical ones, or
901 it can translate obsolete or invalid URIs to valid ones.
903 QtXmlPatterns calls the URI resolver for all URIs it encounters,
904 except for namespaces. Specifically, all builtin functions that deal
905 with URIs (\c{fn:doc()}, and \c{fn:doc-available()}).
907 In the case of \c{fn:doc()}, the absolute URI is the base URI in the
908 static context (which most likely is the location of the query).
909 Rather than use the URI the user specified, the return value of
910 QAbstractUriResolver::resolve() will be used.
912 When QtXmlPatterns calls QAbstractUriResolver::resolve() the
913 absolute URI is the URI mandated by the XQuery language, and the
914 relative URI is the URI specified by the user.
918 const QAbstractUriResolver *QXmlQuery::uriResolver() const
920 return d->uriResolver;
924 Returns the name pool used by this QXmlQuery for constructing \l
925 {QXmlName} {names}. There is no setter for the name pool, because
926 mixing name pools causes errors due to name confusion.
928 QXmlNamePool QXmlQuery::namePool() const
934 Sets the focus to \a item. The focus is the set of items that the
935 context item expression and path expressions navigate from. For
936 example, in the expression \e p/span, the element that \e p
937 evaluates to is the focus for the following expression, \e span.
939 The focus can be accessed using the context item expression, i.e.,
942 By default, the focus is not set and is undefined. It will
943 therefore result in a dynamic error, \c XPDY0002, if the focus
944 is attempted to be accessed. The focus must be set before the
945 query is set with setQuery().
947 There is no behavior defined for setting an item which is null.
950 void QXmlQuery::setFocus(const QXmlItem &item)
952 d->contextItem = item;
956 * This function should be a private member function of QXmlQuery,
957 * but we don't dare that due to our weird compilers.
961 template<typename TInputType>
962 bool setFocusHelper(QXmlQuery *const queryInstance,
963 const TInputType &focusValue)
965 /* We call resourceLoader(), so we have ensured that we have a resourceLoader
966 * that we will share in our copy. */
967 queryInstance->d->resourceLoader();
969 QXmlQuery focusQuery(*queryInstance);
971 /* Now we use the same, so we own the loaded document. */
972 focusQuery.d->m_resourceLoader = queryInstance->d->m_resourceLoader;
974 /* The copy constructor doesn't allow us to copy an existing QXmlQuery and
975 * changing the language at the same time so we need to use private API. */
976 focusQuery.d->queryLanguage = QXmlQuery::XQuery10;
978 Q_ASSERT(focusQuery.queryLanguage() == QXmlQuery::XQuery10);
979 focusQuery.bindVariable(QChar::fromLatin1('u'), focusValue);
980 focusQuery.setQuery(QLatin1String("doc($u)"));
981 Q_ASSERT(focusQuery.isValid());
983 QXmlResultItems focusResult;
985 queryInstance->d->m_resourceLoader = focusQuery.d->m_resourceLoader;
987 focusQuery.evaluateTo(&focusResult);
988 const QXmlItem focusItem(focusResult.next());
990 if(focusItem.isNull() || focusResult.hasError())
994 queryInstance->setFocus(focusItem);
1003 Sets the focus to be the document located at \a documentURI and
1004 returns true. If \a documentURI cannot be loaded, false is returned.
1005 It is undefined at what time the document may be loaded. When
1006 loading the document, the message handler and URI resolver set on
1007 this QXmlQuery are used.
1009 If \a documentURI is empty or is not a valid URI, the behavior of
1010 this function is undefined.
1012 bool QXmlQuery::setFocus(const QUrl &documentURI)
1014 Q_ASSERT_X(documentURI.isValid() && !documentURI.isEmpty(),
1016 "The URI passed must be valid.");
1018 return setFocusHelper(this, QVariant(documentURI));
1023 Sets the focus to be the \a document read from the QIODevice and
1024 returns true. If \a document cannot be loaded, false is returned.
1026 QXmlQuery does not take ownership of \a document. The user
1027 guarantees that a document is available from the \a document device
1028 and that the document is not empty. The device must be opened in at
1029 least read-only mode. \a document must stay in scope as long as the
1030 current query is active.
1035 bool QXmlQuery::setFocus(QIODevice *document)
1039 qWarning("A null QIODevice pointer cannot be passed.");
1043 if(!document->isReadable())
1045 qWarning("The device must be readable.");
1049 return setFocusHelper(this, document);
1053 This function behaves identically to calling the setFocus() overload with a
1054 QIODevice whose content is \a focus encoded as UTF-8. That is, \a focus is
1055 treated as if it contained an XML document.
1057 Returns the same result as the overload.
1062 bool QXmlQuery::setFocus(const QString &focus)
1065 device.setData(focus.toUtf8());
1066 device.open(QIODevice::ReadOnly);
1068 return setFocusHelper(this, &device);
1072 Returns a value indicating what this QXmlQuery is being used for.
1073 The default is QXmlQuery::XQuery10, which means the QXmlQuery is
1074 being used for running XQuery and XPath queries. QXmlQuery::XSLT20
1075 can also be returned, which indicates the QXmlQuery is for running
1080 QXmlQuery::QueryLanguage QXmlQuery::queryLanguage() const
1082 return d->queryLanguage;
1086 Sets the \a name of the initial template. The initial template is
1087 the one the processor calls first, instead of attempting to match a
1088 template to the context node (if any). If an initial template is not
1089 set, the standard order of template invocation will be used.
1091 This function only applies when using QXmlQuery to process XSL-T
1092 stylesheets. The name becomes part of the compiled stylesheet.
1093 Therefore, this function must be called before calling setQuery().
1095 If the stylesheet has no template named \a name, the processor will
1096 use the standard order of template invocation.
1099 \sa initialTemplateName()
1101 void QXmlQuery::setInitialTemplateName(const QXmlName &name)
1103 d->initialTemplateName = name;
1109 Sets the name of the initial template to \a localName, which must be
1110 a valid \l{QXmlName::localName()} {local name}. The initial template
1111 is the one the processor calls first, instead of attempting to match
1112 a template to the context node (if any). If an initial template is
1113 not set, the standard order of template invocation will be used.
1115 This function only applies when using QXmlQuery to process XSL-T
1116 stylesheets. The name becomes part of the compiled stylesheet.
1117 Therefore, this function must be called before calling setQuery().
1119 If \a localName is not a valid \l{QXmlName::localName()} {local
1120 name}, the effect is undefined. If the stylesheet has no template
1121 named \a localName, the processor will use the standard order of
1122 template invocation.
1125 \sa initialTemplateName()
1127 void QXmlQuery::setInitialTemplateName(const QString &localName)
1129 Q_ASSERT_X(QXmlName::isNCName(localName),
1131 "The name passed must be a valid NCName.");
1132 setInitialTemplateName(QXmlName(d->namePool, localName));
1136 Returns the name of the XSL-T stylesheet template that the processor
1137 will call first when running an XSL-T stylesheet. This function only
1138 applies when using QXmlQuery to process XSL-T stylesheets. By
1139 default, no initial template is set. In that case, a default
1140 constructed QXmlName is returned.
1144 QXmlName QXmlQuery::initialTemplateName() const
1146 return d->initialTemplateName;
1150 Sets the network manager to \a newManager.
1151 QXmlQuery does not take ownership of \a newManager.
1153 \sa networkAccessManager()
1156 void QXmlQuery::setNetworkAccessManager(QNetworkAccessManager *newManager)
1158 d->m_networkAccessDelegator->m_genericManager = newManager;
1162 Returns the network manager, or 0 if it has not been set.
1164 \sa setNetworkAccessManager()
1167 QNetworkAccessManager *QXmlQuery::networkAccessManager() const
1169 return d->m_networkAccessDelegator->m_genericManager;
1173 Binds the result of the query \a query, to a variable by name \a name.
1175 Evaluation of \a query will be commenced when this function is called.
1177 If \a query is invalid, behavior is undefined. \a query will be copied.
1182 void QXmlQuery::bindVariable(const QXmlName &name, const QXmlQuery &query)
1184 Q_ASSERT_X(query.isValid(), Q_FUNC_INFO, "The query being bound must be valid.");
1186 const QPatternist::VariableLoader::Ptr vl(d->variableLoader());
1187 const QVariant variant(QVariant::fromValue(query));
1189 if(vl->invalidationRequired(name, variant))
1190 d->recompileRequired();
1192 vl->addBinding(name, variant);
1198 Has the same behavior and effects as the function being overloaded, but takes
1199 the variable name \a localName as a QString. \a query is used as in the
1200 overloaded function.
1204 void QXmlQuery::bindVariable(const QString &localName, const QXmlQuery &query)
1206 return bindVariable(QXmlName(d->namePool, localName), query);