Viadeo Twitter Google Bookmarks ! Facebook Digg del.icio.us MySpace Yahoo MyWeb Blinklist Netvouz Reddit Simpy StumbleUpon Bookmarks Windows Live Favorites 
Logo Documentation Qt ·  Page d'accueil  ·  Tous les espaces de nom  ·  Toutes les classes  ·  Classes principales  ·  Annotées  ·  Classes groupées  ·  Modules  ·  Fonctions  · 

QtXmlPatterns Module

An overview of Qt's support for using XQuery and XPath in Qt programs. More...

Classes

QAbstractMessageHandlerCallback interface for handling messages
QAbstractUriResolverCallback interface for resolving Uniform Resource Identifiers
QAbstractXmlNodeModelAbstract base class for modeling non-XML data to look like XML for QXmlQuery
QAbstractXmlReceiverCallback interface for transforming the output of a QXmlQuery
QSimpleXmlNodeModelImplementation of QAbstractXmlNodeModel sufficient for many common cases
QSourceLocationIdentifies a location in a resource by URI, line, and column
QXmlFormatterImplementation of QXmlSerializer for transforming XQuery output into formatted XML
QXmlItemContains either an XML node or an atomic value
QXmlNameRepresents the name of an XML node, in an efficient, namespace-aware way
QXmlNamePoolTable of shared strings referenced by instances of QXmlName
QXmlNodeModelIndexIdentifies a node in an XML node model subclassed from QAbstractXmlNodeModel
QXmlQueryPerforms XQueries on XML data, or on non-XML data modeled to look like XML
QXmlResultItemsIterates through the results of evaluating an XQuery in QXmlQuery
QXmlSerializerImplementation of QAbstractXmlReceiver for transforming XQuery output into unformatted XML

Detailed Description

Introduction

XQuery is a language for traversing XML documents to select and aggregate items of interest and to transform them for output as XML or some other format. XPath is the element selection part of XQuery.

The QtXmlPatterns module supports using XQuery 1.0 and XPath 2.0 in Qt applications, for querying XML data and for querying non-XML data that can be modeled to look like XML. The QtXmlPatterns module is included in the Qt Full Framework Edition, and the Qt Open Source Edition. Readers who are not familiar with the XQuery/XPath language can read A Short Path to XQuery for a brief introduction.

Advantages of using QtXmlPatterns and XQuery

The XQuery/XPath language simplifies data searching and transformation tasks by eliminating the need for doing a lot of C++ or Java procedural programming for each new query task. Here is an XQuery that constructs a bibliography of the contents of a library:

 <bibliography>
 {doc("library.xml")/bib/book[publisher="Addison-Wesley" and @year>1991]/<book year="{@year}">{title}</book>}
 </bibliography>

First, the query opens a <bibliography> element in the output. The embedded path expression then loads the XML document describing the contents of the library (library.xml) and begins the search. For each <book> element it finds, where the publisher was Addison-Wesley and the publication year was after 1991, it creates a new <book> element in the output as a child of the open <bibliography> element. Each new <book> element gets the book's title as its contents and the book's publication year as an attribute. Finally, the <bibliography> element is closed.

The advantages of using QtXmlPatterns and XQuery in your Qt programs are summarized as follows:

  • Ease of development: All the C++ programming required to perform data query tasks can be replaced by a simple XQuery like the example above.
  • Comprehensive functionality: The expression syntax and rich set of functions and operators provided by XQuery are sufficient for performing any data searching, selecting, and sorting tasks.
  • Conformance to standards: Conformance to all applicable XML and XQuery standards ensures that QtXmlPatterns can always process XML documents generated by other conformant applications, and that XML documents created with QtXmlPatterns can be processed by other conformant applications.
  • Maximal flexibility The QtXmlPatterns module can be used to query XML data and non-XML data that can be modeled to look like XML.

Using the QtXmlPatterns module

There are two ways QtXmlPatterns can be used to evaluate queries. You can run the query engine in your Qt application using the QtXmlPatterns C++ API, or you can run the query engine from the command line using Qt's xmlpatterns command line utility.

Running the query engine from your Qt application

To access the QtXmlPatterns C++ API from your Qt application, include the QtXmlPatterns classes at compile time:

 #include <QtXmlPatterns>

Link the compiled application with the QtXmlPatterns module by adding the following line to the QT line in your qmake .pro file:

 QT += xmlpatterns

If we save the example XQuery shown above in a text file (e.g. myquery.xq), we can run it from a Qt application using a standard QtXmlPatterns code sequence:

     QFile xq("myquery.xq");

     QXmlQuery query;
     query.setQuery(&xq, QUrl::fromLocalFile(xq.fileName()));

     QXmlSerializer serializer(query, myOutputDevice);
     query.evaluateTo(&serializer);

First construct a QFile for the text file containing the XQuery (myquery.xq). Then create an instance of QXmlQuery and call its setQuery() function to load and parse the XQuery file. Then create an XML serializer to output the query's result set as unformatted XML. Finally, call the evaluateTo() function to evaluate the query and serialize the results as XML.

Note: If you compile Qt yourself, the QtXmlPatterns module will not be built if exceptions are disabled, or if you compile Qt with a compiler that doesn't support member templates, e.g., MSVC 6.

See the QXmlQuery documentation for more information about the QtXmlPatterns C++ API.

Running the query engine from the command line utility

xmlpatterns is a command line utility for running XQueries. It expects the name of a file containing the XQuery text.

 xmlpatterns myQuery.xq

The XQuery in myQuery.xq will be evaluated and its output written to stdout. Pass the -help switch to get the list of input flags and their meanings.

xmlpatterns can be used in scripting. However, the descriptions and messages it outputs were not meant to be parsed and may be changed in future releases of Qt.

The XQuery Data Model

XQuery represents data items as atomic values or nodes. An atomic value is a value in the domain of one of the built-in datatypes defined in Part 2 of the W3C XML Schema. A node is normally an XML element or attribute, but when non-XML data is modeled to look like XML, a node can also represent a non-XML data items.

When you run an XQuery using the C++ API in a Qt application, you will often want to bind program variables to $variables in the XQuery. After the query is evaluated, you will want to interpret the sequence of data items in the result set.

Binding program variables to XQuery variables

When you want to run a parameterized XQuery from your Qt application, you will need to bind variables in your program to $name variables in your XQuery.

Suppose you want to parameterize the bibliography XQuery in the example above. You could define variables for the catalog that contains the library ($file), the publisher name ($publisher), and the year of publication ($year):

 <bibliography>
 {
     doc($file)/bib/book[publisher = $publisher and @year > $year]/<book year="{@year}">{title}</book>
 }
 </bibliography>

Modify the QtXmlPatterns code to use one of the bindVariable() functions to bind a program variable to each XQuery $variable:

     QFile xq("myquery.xq");
     QString fileName("the filename");
     QString publisherName("the publisher");
     qlonglong year = 1234;

     QXmlQuery query;
     query.setQuery(&xq, QUrl::fromLocalFile(xq.fileName()));

     query.bindVariable("file", QVariant(fileName));
     query.bindVariable("publisher", QVariant(publisherName));
     query.bindVariable("year", QVariant(year));

     QXmlSerializer serializer(query, myOutputDevice);
     query.evaluateTo(&serializer);

Each program variable is passed to QtXmlPatterns as a QVariant of the type of the C++ variable or constant from which it is constructed. Note that QtXmlPatterns assumes that the type of the QVariant in the bindVariable() call is the correct type, so the $variable it is bound to must be used in the XQuery accordingly. The following table shows how QVariant types are mapped to XQuery $variable types:

QVariant typeXQuery $variable type
QVariant::LongLongxs:integer
QVariant::Intxs:integer
QVariant::UIntxs:nonNegativeInteger
QVariant::ULongLongxs:unsignedLong
QVariant::Stringxs:string
QVariant::Doublexs:double
QVariant::Boolxs:boolean
QVariant::Doublexs:decimal
QVariant::ByteArrayxs:base64Binary
QVariant::StringListxs:string*
QVariant::Urlxs:string
QVariant::Datexs:date.
QVariant::DateTimexs:dateTime
QVariant::Time.xs:time. (see Binding To QVariant::Time below)
QVariantList(see Binding To QVariantList below)

A type not shown in the table is not supported and will cause undefined XQuery behavior or a $variable binding error, depending on the context in the XQuery where the variable is used.

Binding To QVariant::Time

Because the instance of QTime used in QVariant::Time does not include a zone offset, an instance of QVariant::Time should not be bound to an XQuery variable of type xs:time, unless the QTime is UTC. When binding a non-UTC QTime to an XQuery variable, it should first be passed as a string, or converted to a QDateTime with an arbitrary date, and then bound to an XQuery variable of type xs:dateTime.

Binding To QVariantList

A QVariantList can be bound to an XQuery $variable. All the QVariants in the list must be of the same atomic type, and the $variable the variant list is bound to must be of that same atomic type. If the QVariants in the list are not all of the same atomic type, the XQuery behavior is undefined.

Interpreting XQuery results

When the results of an XQuery are returned in a sequence of result items, atomic values in the sequence are treated as instances of QVariant. Suppose that instead of serializing the results of the XQuery as XML, we process the results programatically. Modify the standard QtXmlPatterns code sequence to call the overload of QXmlQuery::evaluateTo() that populates a sequence of result items with the XQuery results:

     QFile xq("myquery.xq");
     QString fileName("the filename");
     QString publisherName("the publisher");
     qlonglong year = 1234;

     QXmlQuery query;
     query.setQuery(&xq, QUrl::fromLocalFile(xq.fileName()));

     query.bindVariable("file", QVariant(fileName));
     query.bindVariable("publisher", QVariant(publisherName));
     query.bindVariable("year", QVariant(year));

     QXmlResultItems result;
     query.evaluateTo(&result);
     QXmlItem item(result.next());
     while (!item.isNull()) {
         if (item.isAtomicValue()) {
             QVariant v = item.toAtomicValue();
             switch (v.type()) {
                 case QVariant::LongLong:
                     // xs:integer
                     break;
                 case QVariant::String:
                     // xs:string
                     break;
                 default:
                     // error
                     break;
             }
         }
         else if (item.isNode()) {
             QXmlNodeModelIndex i = item.toNodeModelIndex();
             // process node
         }
         item = result.next();
     }

Iterate through the result items and test each QXmlItem to see if it is an atomic value or a node. If it is an atomic value, convert it to a QVariant with toAtomicValue() and switch on its variant type to handle all the atomic values your XQuery might return. The following table shows the QVariant type to expect for each atomic value type (or QXmlName):

XQuery result item typeQVariant type returned
xs:QNameQXmlName (see Handling QXmlNames below)
xs:integerQVariant::LongLong
xs:stringQVariant::String
xs:string*QVariant::StringList
xs:doubleQVariant::Double
xs:floatQVariant::Double
xs:booleanQVariant::Bool
xs:decimalQVariant::Double
xs:hexBinaryQVariant::ByteArray
xs:base64BinaryQVariant::ByteArray
xs:gYearQVariant::DateTime
xs:gYearMonthQVariant::DateTime
xs:gMonthDayQVariant::DateTime
xs:gDayQVariant::DateTime
xs:gMonthQVariant::DateTime
xs:anyURIQVariant::Url
xs:untypedAtomicQVariant::String
xs:ENTITYQVariant::String
xs:dateQVariant::DateTime
xs:dateTimeQVariant::DateTime
xs:time(see No mapping for xs:time below)

Handling QXmlNames

If your XQuery can return atomic value items of type xs:QName, they will appear in your QXmlResultItems as instances of QXmlName. Since the QVariant class does not support the QXmlName class directly, extracting them from QXmlResultItems requires a bit of slight-of-hand using the Qt metatype system. We must modify our example to use a couple of template functions, a friend of QMetaType (qMetaTypeId<T>()) and a friend of QVariant (qVariantValue<T>()):

     QFile xq("myquery.xq");

     QXmlQuery query;
     query.setQuery(&xq, QUrl::fromLocalFile(xq.fileName()));

     QXmlResultItems result;
     query.evaluateTo(&result);
     QXmlItem item(result.next());
     while (!item.isNull()) {
         if (item.isAtomicValue()) {
             QVariant v = item.toAtomicValue();
             switch (v.type()) {
                 case QVariant::LongLong:
                     // xs:integer
                     break;
                 case QVariant::String:
                     // xs:string
                     break;
                 default:
                     if (v.userType() == qMetaTypeId<QXmlName>()) {
                         QXmlName n = qVariantValue<QXmlName>(v);
                         // process QXmlName n...
                     }
                     else {
                         // error
                     }
                     break;
             }
         }
         else if (item.isNode()) {
             QXmlNodeModelIndex i = item.toNodeModelIndex();
             // process node
         }
         item = result.next();
     }

To access the strings in a QXmlName returned by an XQuery evaluation, the QXmlName must be accessed with the name pool from the instance of QXmlQuery that was used for the evaluation.

No mapping for xs:time

An instance of xs:time can't be represented correctly as an instance of QVariant::Time, unless the xs:time is a UTC time. This is because xs:time has a zone offset (0 for UTC) in addition to the time value, which the QTime in QVariant::Time does not have. This means that if an XQuery tries to return an atomic value of type xs:time, an invalid QVariant will be returned. A query can return an atomic value of type xs:time by either converting it to an xs:dateTime with an arbitrary date, or to an xs:string.

Using XQuery with Non-XML Data

Although the XQuery language was designed for querying XML, with QtXmlPatterns one can use XQuery for querying any data that can be modeled to look like XML. Non-XML data is modeled to look like XML by loading it into a custom subclass of QAbstractXmlNodeModel, where it is then presented to the QtXmlPatterns XQuery engine via the same API the XQuery engine uses for querying XML.

When QtXmlPatterns loads and queries XML files and produces XML output, it can always load the XML data into its default XML node model, where it can be traversed efficiently. The XQuery below traverses the product orders found in the XML file myOrders.xml to find all the skin care product orders and output them ordered by shipping date.

 <result>
     <para>The following skin care products have shipped, ordered by shipping date(oldest first):</para>
     {
         for $i in doc("myOrders.xml")/orders/order[@product = "Acme Skin Care"]
         order by xs:date($i/@shippingDate) descending
         return $i
     }
 </result>

QtXmlPatterns can be used out of the box to perform this query, provided myOrders.xml actually contains well-formed XML. It can be loaded directly into the default XML node model and traversed. But suppose we want QtXmlPatterns to perform queries on the hierarchical structure of the local file system. The default XML node model in QtXmlPatterns is not suitable for navigating the file system, because there is no XML file to load that contains a description of it. Such an XML file, if it existed, might look something like this:

 <?xml version="1.0" encoding="UTF-8"?>
 <directory name="home">

     <file name="myNote.txt" mimetype="text/plain" size="8" extension="txt" uri="file:///home/frans/myNote.txt">
         <content asBase64Binary="TXkgTm90ZSE=" asStringFromUTF-8="My Note!"/>
     </file>

     <directory name="src">
         ...
     </directory>

     ...

 </directory>

The File System Example does exactly this.

There is no such file to load into the default XML node model, but one can write a subclass of QAbstractXmlNodeModel to represent the file system. This custom XML node model, once populated with all the directory and file descriptors obtained directly from the system, presents the complete file system hierarchy to the query engine via the same API used by the default XML node model to present the contents of an XML file. In other words, once the custom XML node model is populated, it presents the file system to the query engine as if a description of it had been loaded into the default XML node model from an XML file like the one shown above.

Now we can write an XQuery to find all the XML files and parse them to find the ones that don't contain well-formed XML.

 <html>
     <body>
         {
             $myRoot//file[@mimetype = 'text/xml' or @mimetype = 'application/xml']
             /
             (if(doc-available(@uri))
              then ()
              else <p>Failed to parse file {@uri}.</p>)
         }
     </body>
 </html>

Without QtXmlPatterns, there is no simple way to solve this kind of problem. You might do it by writing a C++ program to traverse the file system, sniff out all the XML files, and submit each one to an XML parser to test that it contains valid XML. The C++ code required to write that program will probably be more complex than the C++ code required to subclass QAbstractXmlNodeModel, but even if the two are comparable, your custom C++ program can be used only for that one task, while your custom XML node model can be used by any XQuery that must navigate the file system.

The general approach to using XQuery to perform queries on non-XML data has been a three step process. In the first step, the data is loaded into a non-XML data model. In the second step, the non-XML data model is serialized as XML and output to XML (text) files. In the final step, an XML tool loads the XML files into a second, XML data model, where the XQueries can be performed. The development cost of implementing this process is often high, and the three step system that results is inefficient because the two data models must be built and maintained separately.

With QtXmlPatterns, subclassing QAbstractXmlNodeModel eliminates the transformation required to convert the non-XML data model to the XML data model, because there is only ever one data model required. The non-XML data model presents the non-XML data to the query engine via the XML data model API. Also, since the query engine uses the API to access the QAbstractXmlNodeModel, the data model subclass can construct the elements, attributes and other data on demand, responding to the query's specific requests. This can greatly improve efficiency, because it means the entire model might not have to be built. For example, in the file system model above, it is not necessary to build an instance for a whole XML file representing the whole file system. Instead nodes are created on demand, which also likely is a small subset of the file system.

Examples of other places where XQuery could be used in QtXmlPatterns to query non-XML data:

  • The internal representation for word processor documents
  • The set of dependencies for a software build system
  • The hierarchy (or graph) that links a set of HTML documents from a web crawler
  • The images and meta-data in an image collection
  • The set of D-Bus interfaces available in a system
  • A QObject hierarchy, as seen in the QObject XML Model example.

See the QAbstractXmlNodeModel documentation for information about how to implement custom XML node models.

More on using QtXmlPatterns with non-XML Data

Subclassing QAbstractXmlNodeModel to let the query engine access non-XML data by the same API it uses for XML is the feature that enables QtXmlPatterns to query non-XML data with XQuery. It allows XQuery to be used as a mapping layer between different non-XML node models or between a non-XML node model and the built-in XML node model. Once the subclass(es) of QAbstractXmlNodeModel have been written, XQuery can be used to select a set of elements from one node model, transform the selected elements, and then write them out, either as XML using QXmlQuery::evaluateTo() and QXmlSerializer, or as some other format using a subclass of QAbstractXmlReceiver.

Consider a word processor application that must import and export data in several different formats. Rather than writing a lot of C++ code to convert each input format to an intermediate form, and more C++ code to convert the intermediate form back to each output format, one can implement a solution based on QtXmlPatterns that uses simple XQueries to transform each XML or non-XML format (e.g. MathFormula.xml below) to the intermediate form (e.g. the DocumentRepresentation node model class below), and more simple XQueries to transform the intermediate form back to each XML or non-XML format.

Because CSV files are not XML, a subclass of QAbstractXmlNodeModel is used to present the CSV data to the XQuery engine as if it were XML. What are not shown are the subclasses of QAbstractXmlReceiver that would then send the selected elements into the DocumentRepresentation node model, and the subclasses of QAbstractXmlNodeModel that would ultimately write the output files in each format.

Security Considerations

Code Injection

Like SQL, XQuery is vulnerable to code injection attacks. If an XQuery is constructed by concatenation, where concatenated strings can come from user input, the final XQuery can become malevolent. The best way to prevent code injection attacks is to not construct XQueries from user-written strings, but only accept user data input using QVariant and variable bindings. See QXmlQuery::bindVariable()

The articles Avoid the dangers of XPath injection, Robi Sen and Blind XPath Injection, Amit Klein discuss the XQuery code injection problem in more detail.

Denial of Service Attacks

Applications using QtXmlPatterns are subject to the same software limits as any other system. Generally, these can not be checked. This means QtXmlPatterns does not prevent rogue queries from consuming too many resources. For example, a query could take too much time to execute, or could attempt to transfer too much data. Or a query could cause an unreasonable amount of recursion, which could crash the system. XQueries can do these things accidentally, but they can also be meant as deliberate, denial of service attacks.

Features and Conformance

Conformance

QtXmlPatterns aims at being a conformant XQuery processor. Apart from adhering to {http://www.w3.org/TR/xquery/#id-minimal-conformance} {Minimal Conformance}, QtXmlPatterns supports the Serialization Feature and the Full Axis Feature. QtXmlPatterns passes 97% of the tests in the XML Query Test Suite, and it is expected this will improve over time. Areas where conformance may be questionable and where behavior may be changed in future releases are:

  • Regular expression support is currently not conformant but follows Qt's QRegExp standard syntax.
  • Operators for xs:time, xs:date, and xs:dateTime are incomplete.
  • Formatting of very large or very small xs:double, xs:float, and xs:decimal values may be incorrect.
  • Some corner cases involving namespaces and element constructors are incorrect.

XML 1.0 and XML Namespaces 1.0 are supported, as opposed to the 1.1 versions. When a strings is passed to a query as a QString, the characters must be XML 1.0 characters. Otherwise, the behavior is undefined. This is not checked.

Since XPath 2.0 is a subset of XQuery 1.0, it is supported.

The specifications discusses conformance further: XQuery 1.0: An XML Query Language. W3C's XQuery testing effort can be of interest as well, XML Query Test Suite.

Currently fn:collection() does not access any data set, and there is no API for providing data through the collection. As a result, evaluating fn:collection() returns the empty sequence. We intend to provide functionality for this in a future release of Qt.

Processing of XML files supports xml:id. In practice, this allows elements that have an attribute named xml:id to be looked up efficiently with the fn:id() function. See xml:id Version 1.0 for details.

Only queries encoded in UTF-8 are supported.

Resource Loading

When QtXmlPatterns loads an XML resource, e.g., using fn:doc() function, the following schemes are supported:

Scheme NameDescription
fileLocal files.
dataThe bytes are encoded in the URI itself. For instance, data:application/xml,%3Ce%2F%3E is <e/>.
ftpResources retrieved via FTP.
httpResources retrieved via HTTP.
httpsResources retrieved via HTTPS. This will succeed if no SSL errors are encountered.
qrcQt Resource files. Expressing it as an empty scheme, :/..., is not supported.

URIs are first passed to QAbstractUriResolver. Check QXmlQuery::setUriResolver() for possible rewrites.

[Previous: QtXml Module] [Qt's Modules] [Next: Phonon Module]

Publicité

Best Of

Actualités les plus lues

Semaine
Mois
Année
  1. « Quelque chose ne va vraiment pas avec les développeurs "modernes" », un développeur à "l'ancienne" critique la multiplication des bibliothèques 59
  2. Apercevoir la troisième dimension ou l'utilisation multithreadée d'OpenGL dans Qt, un article des Qt Quarterly traduit par Guillaume Belz 0
  3. Les développeurs ignorent-ils trop les failles découvertes dans leur code ? Prenez-vous en compte les remarques des autres ? 17
  4. BlackBerry 10 : premières images du prochain OS de RIM qui devrait intégrer des widgets et des tuiles inspirées de Windows Phone 0
  5. Quelles nouveautés de C++11 Visual C++ doit-il rapidement intégrer ? Donnez-nous votre avis 10
  6. Adieu qmake, bienvenue qbs : Qt Building Suite, un outil déclaratif et extensible pour la compilation de projets Qt 17
  7. La rubrique Qt a besoin de vous ! 1
Page suivante

Le Qt Labs au hasard

Logo

Construire l'avenir : (ré-)introduction aux composants de Qt Quick

Les Qt Labs sont les laboratoires des développeurs de Qt, où ils peuvent partager des impressions sur le framework, son utilisation, ce que pourrait être son futur. Lire l'article.

Communauté

Ressources

Liens utiles

Contact

  • Vous souhaitez rejoindre la rédaction ou proposer un tutoriel, une traduction, une question... ? Postez dans le forum Contribuez ou contactez-nous par MP ou par email (voir en bas de page).

Qt dans le magazine
Cette page est une traduction d'une page de la documentation de Qt, écrite par Nokia Corporation and/or its subsidiary(-ies). Les éventuels problèmes résultant d'une mauvaise traduction ne sont pas imputables à Nokia. Qt 4.4
Copyright © 2012 Developpez LLC. Tous droits réservés Developpez LLC. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents et images sans l'autorisation expresse de Developpez LLC. Sinon, vous encourez selon la loi jusqu'à 3 ans de prison et jusqu'à 300 000 E de dommages et intérêts. Cette page est déposée à la SACD.
Vous avez déniché une erreur ? Un bug ? Une redirection cassée ? Ou tout autre problème, quel qu'il soit ? Ou bien vous désirez participer à ce projet de traduction ? N'hésitez pas à nous contacter ou par MP !
 
 
Developpez.com

Nous contacter

Participez

Informations légales

 
Services

Forum Qt

Blogs

Hébergement

 
Partenaires

Hébergement Web