1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
|
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.1, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page xmlprocessing.html
\title Using XML Technologies
\previouspage Working with the DOM Tree
\contentspage XML Processing
\keyword Patternist
\brief An overview of Qt's support for using XML technologies in
Qt programs.
\tableofcontents
\section1 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 \e{element selection} part
of XQuery.
The QtXmlPatterns module supports using
\l{http://www.w3.org/TR/xquery} {XQuery 1.0} and
\l{http://www.w3.org/TR/xpath20} {XPath 2.0} in Qt applications,
for querying XML data \e{and} for querying
\l{QAbstractXmlNodeModel} {non-XML data that can be modeled to
look like XML}. The QtXmlPatterns module is included in the \l{Qt
Full Framework Edition}, and the \l{Open Source Versions of Qt}.
Readers who are not familiar with the XQuery/XPath language can read
\l {A Short Path to XQuery} for a brief introduction.
\section1 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:
\target qtxmlpatterns_example_query
\quotefile snippets/patternist/introductionExample.xq
First, the query opens a \c{<bibliography>} element in the
output. The
\l{xquery-introduction.html#using-path-expressions-to-match-select-items}
{embedded path expression} then loads the XML document describing
the contents of the library (\c{library.xml}) and begins the
search. For each \c{<book>} element it finds, where the publisher
was Addison-Wesley and the publication year was after 1991, it
creates a new \c{<book>} element in the output as a child of the
open \c{<bibliography>} element. Each new \c{<book>} element gets
the book's title as its contents and the book's publication year
as an attribute. Finally, the \c{<bibliography>} element is
closed.
The advantages of using QtXmlPatterns and XQuery in your Qt
programs are summarized as follows:
\list
\o \bold{Ease of development}: All the C++ programming required to
perform data query tasks can be replaced by a simple XQuery
like the example above.
\o \bold{Comprehensive functionality}: The
\l{http://www.w3.org/TR/xquery/#id-expressions} {expression
syntax} and rich set of
\l{http://www.w3.org/TR/xpath-functions} {functions and
operators} provided by XQuery are sufficient for performing any
data searching, selecting, and sorting tasks.
\o \bold{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.
\o \bold{Maximal flexibility} The QtXmlPatterns module can be used
to query XML data \e{and} non-XML data that can be
\l{QAbstractXmlNodeModel} {modeled to look like XML}.
\endlist
\section1 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 \c{xmlpatterns} command line utility.
\section2 Running the query engine from your Qt application
If we save the example XQuery shown above in a text file (e.g.
\c{myquery.xq}), we can run it from a Qt application using a
standard QtXmlPatterns code sequence:
\snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 3
First construct a QFile for the text file containing the XQuery
(\c{myquery.xq}). Then create an instance of QXmlQuery and call
its \l{QXmlQuery::}{setQuery()} function to load and parse the
XQuery file. Then create an \l{QXmlSerializer} {XML serializer} to
output the query's result set as unformatted XML. Finally, call
the \l{QXmlQuery::}{evaluateTo()} function to evaluate the query
and serialize the results as XML.
\note If you compile Qt yourself, the QtXmlPatterns module will
\e{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.
\section2 Running the query engine from the command line utility
\e xmlpatterns is a command line utility for running XQueries. It
expects the name of a file containing the XQuery text.
\snippet doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc 2
The XQuery in \c{myQuery.xq} will be evaluated and its output
written to \c stdout. Pass the \c -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.
\target QtXDM
\section1 The XQuery Data Model
XQuery represents data items as \e{atomic values} or \e{nodes}. An
atomic value is a value in the domain of one of the
\l{http://www.w3.org/TR/xmlschema-2/#built-in-datatypes} {built-in
datatypes} defined in \l{http://www.w3.org/TR/xmlschema-2} {Part
2} of the W3C XML Schema. A node is normally an XML element or
attribute, but when non-XML data is \l{QAbstractXmlNodeModel}
{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.
\section2 Binding program variables to XQuery variables
When you want to run a parameterized XQuery from your Qt
application, you will need to \l{QXmlQuery::bindVariable()} {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 (\c{$file}), the publisher name
(\c{$publisher}), and the year of publication (\c{$year}):
\target qtxmlpatterns_example_query2
\quotefile snippets/patternist/introExample2.xq
Modify the QtXmlPatterns code to use one of the \l{QXmlQuery::}
{bindVariable()} functions to bind a program variable to each
XQuery $variable:
\snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 4
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:
\table
\header
\o QVariant type
\o XQuery $variable type
\row
\o QVariant::LongLong
\o \c xs:integer
\row
\o QVariant::Int
\o \c xs:integer
\row
\o QVariant::UInt
\o \c xs:nonNegativeInteger
\row
\o QVariant::ULongLong
\o \c xs:unsignedLong
\row
\o QVariant::String
\o \c xs:string
\row
\o QVariant::Double
\o \c xs:double
\row
\o QVariant::Bool
\o \c xs:boolean
\row
\o QVariant::Double
\o \c xs:decimal
\row
\o QVariant::ByteArray
\o \c xs:base64Binary
\row
\o QVariant::StringList
\o \c xs:string*
\row
\o QVariant::Url
\o \c xs:string
\row
\o QVariant::Date
\o \c xs:date.
\row
\o QVariant::DateTime
\o \c xs:dateTime
\row
\o QVariant::Time.
\o \c xs:time. (see \l{Binding To Time}{Binding To
QVariant::Time} below)
\row
\o QVariantList
\o (see \l{Binding To QVariantList}{Binding To QVariantList}
below)
\endtable
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.
\target Binding To Time
\section3 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 \c 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 \c xs:dateTime.
\target Binding To QVariantList
\section3 Binding To QVariantList
A QVariantList can be bound to an XQuery $variable. All the
\l{QVariant}s 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.
\section2 Interpreting XQuery results
When the results of an XQuery are returned in a sequence of \l
{QXmlResultItems} {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 \l {QXmlResultItems} {result items} with
the XQuery results:
\snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 5
Iterate through the \l {QXmlResultItems} {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 \l {QXmlItem::}
{toAtomicValue()} and switch on its \l {QVariant::type()} {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):
\table
\header
\o XQuery result item type
\o QVariant type returned
\row
\o \c xs:QName
\o QXmlName (see \l{Handling QXmlNames}{Handling QXmlNames}
below)
\row
\o \c xs:integer
\o QVariant::LongLong
\row
\o \c xs:string
\o QVariant::String
\row
\o \c xs:string*
\o QVariant::StringList
\row
\o \c xs:double
\o QVariant::Double
\row
\o \c xs:float
\o QVariant::Double
\row
\o \c xs:boolean
\o QVariant::Bool
\row
\o \c xs:decimal
\o QVariant::Double
\row
\o \c xs:hexBinary
\o QVariant::ByteArray
\row
\o \c xs:base64Binary
\o QVariant::ByteArray
\row
\o \c xs:gYear
\o QVariant::DateTime
\row
\o \c xs:gYearMonth
\o QVariant::DateTime
\row
\o \c xs:gMonthDay
\o QVariant::DateTime
\row
\o \c xs:gDay
\o QVariant::DateTime
\row
\o \c xs:gMonth
\o QVariant::DateTime
\row
\o \c xs:anyURI
\o QVariant::Url
\row
\o \c xs:untypedAtomic
\o QVariant::String
\row
\o \c xs:ENTITY
\o QVariant::String
\row
\o \c xs:date
\o QVariant::DateTime
\row
\o \c xs:dateTime
\o QVariant::DateTime
\row
\o \c xs:time
\o (see \l{xstime-not-mapped}{No mapping for xs:time} below)
\endtable
\target Handling QXmlNames
\section3 Handling QXmlNames
If your XQuery can return atomic value items of type \c{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 \l{QMetaType} {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>()):
\snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 6
To access the strings in a QXmlName returned by an
\l{QXmlQuery::evaluateTo()} {XQuery evaluation}, the QXmlName must
be accessed with the \l{QXmlNamePool} {name pool} from the
instance of QXmlQuery that was used for the evaluation.
\target xstime-not-mapped
\section3 No mapping for xs:time
An instance of \c xs:time can't be represented correctly as an
instance of QVariant::Time, unless the \c 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 \c 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 \c xs:dateTime with an arbitrary date, or to an \c xs:string.
\section1 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 \e myOrders.xml
to find all the skin care product orders and output them ordered
by shipping date.
\quotefile snippets/patternist/introAcneRemover.xq
QtXmlPatterns can be used out of the box to perform this
query, provided \e 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:
\quotefile snippets/patternist/introFileHierarchy.xml
The \l{File System Example}{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.
\quotefromfile snippets/patternist/introNavigateFS.xq
\skipto <html>
\printuntil
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:
\list
\o The internal representation for word processor documents
\o The set of dependencies for a software build system
\o The hierarchy (or graph) that links a set of HTML documents
from a web crawler
\o The images and meta-data in an image collection
\o The set of D-Bus interfaces available in a system
\o A QObject hierarchy, as seen in the \l{QObject XML Model
Example} {QObject XML Model example}.
\endlist
See the QAbstractXmlNodeModel documentation for information about
how to implement custom XML node models.
\section1 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.
\image patternist-wordProcessor.png
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.
\section1 Security Considerations
\section2 Code Injection
XQuery is vulnerable to
\l{http://en.wikipedia.org/wiki/Code_injection} {code injection
attacks} in the same way as the SQL language. If an XQuery is
constructed by concatenating strings, and the strings come from
user input, the constructed XQuery could be 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
\l{http://www.ibm.com/developerworks/xml/library/x-xpathinjection.html}
{Avoid the dangers of XPath injection}, by Robi Sen and
\l{http://www.packetstormsecurity.org/papers/bypass/Blind_XPath_Injection_20040518.pdf}
{Blind XPath Injection}, by Amit Klein, discuss the XQuery code
injection problem in more detail.
\section2 Denial of Service Attacks
Applications using QtXmlPatterns are subject to the same
limitations of software as other systems. 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 try to transfer too much
data. A query could also do too much recursion, which could crash
the system. XQueries can do these things accidentally, but they
can also be done as deliberate denial of service attacks.
\section1 Features and Conformance
\section2 XQuery 1.0
QtXmlPatterns aims at being a
\l{http://www.w3.org/TR/xquery/#id-xquery-conformance} {conformant
XQuery processor}. It adheres to
\l{http://www.w3.org/TR/xquery/#id-minimal-conformance} {Minimal
Conformance} and supports the
\l{http://www.w3.org/TR/xquery/#id-serialization-feature}
{Serialization Feature} and the
\l{http://www.w3.org/TR/xquery/#id-full-axis-feature} {Full Axis
Feature}. QtXmlPatterns currently passes 97% of the tests in the
\l{http://www.w3.org/XML/Query/test-suite} {XML Query Test Suite}.
Areas where conformance may be questionable and where behavior may
be changed in future releases include:
\list
\o Some corner cases involving namespaces and element constructors
are incorrect.
\o XPath is a subset of XQuery and the implementation of
QtXmlPatterns uses XPath 2.0 with XQuery 1.0.
\endlist
The specifications discusses conformance further:
\l{http://www.w3.org/TR/xquery/}{XQuery 1.0: An XML Query
Language}. W3C's XQuery testing effort can be of interest as
well, \l{http://www.w3.org/XML/Query/test-suite/}{XML Query Test
Suite}.
Currently \c fn:collection() does not access any data set, and
there is no API for providing data through the collection. As a
result, evaluating \c fn:collection() returns the empty
sequence. We intend to provide functionality for this in a future
release of Qt.
Only queries encoded in UTF-8 are supported.
\section2 XSLT 2.0
Partial support for XSLT was introduced in Qt 4.5. Future
releases of QtXmlPatterns will aim to support these XSLT
features:
\list
\o Basic XSLT 2.0 processor
\o Serialization feature
\o Backwards Compatibility feature
\endlist
For details, see \l{http://www.w3.org/TR/xslt20/#conformance}{XSL
Transformations (XSLT) Version 2.0, 21 Conformance}.
\note In this release, XSLT support is considered experimental.
Unsupported or partially supported XSLT features are documented
in the following table. The implementation of XSLT in Qt 4.5 can
be seen as XSLT 1.0 but with the data model of XPath 2.0 and
XSLT 2.0, and using the using the functionality of XPath 2.0 and
its accompanying function library. When QtXmlPatterns encounters
an unsupported or partially support feature, it will either report
a syntax error or silently continue, unless otherwise noted in the
table.
The implementation currently passes 42% of W3C's XSLT test suite,
which focus on features introduced in XSLT 2.0.
\table
\header
\o XSL Feature
\o Support Status
\row
\o \c xsl:key and \c fn:key()
\o not supported
\row
\o \c xsl:include
\o not supported
\row
\o \c xsl:import
\o not supported
\row
\o \c xsl:copy
\o The \c copy-namespaces and \c inherit-namespaces attributes
have no effect. For copied comments, attributes and
processing instructions, the copy has the same node
identity as the original.
\row
\o \c xsl:copy-of
\o The \c copy-namespaces attribute has no effect.
\row
\o \c fn:format-number()
\o not supported
\row
\o \c xsl:message
\o not supported
\row
\o \c xsl:use-when
\o not supported
\row
\o \c Tunnel Parameters
\o not supported
\row
\o \c xsl:attribute-set
\o not supported
\row
\o \c xsl:decimal-format
\o not supported
\row
\o \c xsl:fallback
\o not supported
\row
\o \c xsl:apply-imports
\o not supported
\row
\o \c xsl:character-map
\o not supported
\row
\o \c xsl:number
\o not supported
\row
\o \c xsl:namespace-alias
\o not supported
\row
\o \c xsl:output
\o not supported
\row
\o \c xsl:output-character
\o not supported
\row
\o \c xsl:preserve-space
\o not supported
\row
\o \c xsl:result-document
\o not supported
\row
\o Patterns
\o Complex patterns or patterns with predicates have issues.
\row
\o \c 2.0 Compatibility Mode
\o Stylesheets are interpreted as XSLT 2.0 stylesheets, even
if the \c version attribute is in the XSLT source is
1.0. In other words, the version attribute is ignored.
\row
\o Grouping
\o \c fn:current-group(), \c fn:grouping-key() and \c
xsl:for-each-group.
\row
\o Regexp elements
\o \c xsl:analyze-string, \c xsl:matching-substring,
\c xsl:non-matching-substring, and \c fn:regex-group()
\row
\o Date & Time formatting
\o \c fn:format-dateTime(), \c fn:format-date() and fn:format-time().
\row
\o XPath Conformance
\o Since XPath is a subset of XSLT, its issues are in affect too.
\endtable
The QtXmlPatterns implementation of the XPath Data Model does not
include entities (due to QXmlStreamReader not reporting them).
This means that functions \c unparsed-entity-uri() and \c
unparsed-entity-public-id() always return negatively.
\section2 XPath 2.0
Since XPath 2.0 is a subset of XQuery 1.0, XPath 2.0 is
supported. Areas where conformance may be questionable and,
consequently, where behavior may be changed in future releases
include:
\list
\o Regular expression support is currently not conformant
but follows Qt's QRegExp standard syntax.
\o Operators for \c xs:time, \c xs:date, and \c xs:dateTime
are incomplete.
\o Formatting of very large or very small \c xs:double, \c
xs:float, and \c xs:decimal values may be incorrect.
\endlist
\section2 xml:id
Processing of XML files supports \c xml:id. This allows elements
that have an attribute named \c xml:id to be looked up efficiently
with the \c fn:id() function. See
\l{http://www.w3.org/TR/xml-id/}{xml:id Version 1.0} for details.
\section2 XML Schema 1.0
There are two ways QtXmlPatterns can be used to validate schemas:
You can use the C++ API in your Qt application using the classes
QXmlSchema and QXmlSchemaValidator, or you can use the command line
utility named xmlpatternsvalidator (located in the "bin" directory
of your Qt build).
The QtXmlPatterns implementation of XML Schema validation supports
the schema specification version 1.0 in large parts. Known problems
of the implementation and areas where conformancy may be questionable
are:
\list
\o Large \c minOccurs or \c maxOccurs values or deeply nested ones
require huge amount of memory which might cause the system to freeze.
Such a schema should be rewritten to use \c unbounded as value instead
of large numbers. This restriction will hopefully be fixed in a later release.
\o Comparison of really small or large floating point values might lead to
wrong results in some cases. However such numbers should not be relevant
for day-to-day usage.
\o Regular expression support is currently not conformant but follows
Qt's QRegExp standard syntax.
\o Identity constraint checks can not use the values of default or fixed
attribute definitions.
\endlist
\section2 Resource Loading
When QtXmlPatterns loads an XML resource, e.g., using the
\c fn:doc() function, the following schemes are supported:
\table
\header
\o Scheme Name
\o Description
\row
\o \c file
\o Local files.
\row
\o \c data
\o The bytes are encoded in the URI itself. e.g., \c
data:application/xml,%3Ce%2F%3E is \c <e/>.
\row
\o \c ftp
\o Resources retrieved via FTP.
\row
\o \c http
\o Resources retrieved via HTTP.
\row
\o \c https
\o Resources retrieved via HTTPS. This will succeed if no SSL
errors are encountered.
\row
\o \c qrc
\o Qt Resource files. Expressing it as an empty scheme, :/...,
is not supported.
\endtable
\section2 XML
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.
URIs are first passed to QAbstractUriResolver. Check
QXmlQuery::setUriResolver() for possible rewrites.
*/
/*!
\namespace QPatternist
\brief The QPatternist namespace contains classes and functions required by the QtXmlPatterns module.
\internal
*/
|