1 /****************************************************************************
3 ** Copyright (C) 2012 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 documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:FDL$
10 ** GNU Free Documentation License
11 ** Alternatively, this file may be used under the terms of the GNU Free
12 ** Documentation License version 1.3 as published by the Free Software
13 ** Foundation and appearing in the file included in the packaging of
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \example xmlpatterns/trafficinfo
30 \title TrafficInfo Example
32 Shows how XQuery can be used extract information from WML documents provided by a WAP service.
36 The WAP service used in this example is \l{Trafikanten}{wap.trafikanten.no}
37 that is run by the Norwegian governmental agency for public transport in
38 Oslo. The service provides real time information about the departure of
39 busses, trams and undergrounds for every station in the city area.
41 This example application displays the departure information for a specific
42 station and provides the feature to filter for a special bus or tram line.
44 \image trafficinfo-example.png
46 \section1 Retrieving the Data
48 Without the knowledge of XQuery, one would use QNetworkAccessManager to
49 query the WML document from the WAP service and then using the QDom
50 classes or QXmlStreamReader classes to iterate over the document and
51 extract the needed information.
52 However this approach results in a lot of glue code and consumes valuable
53 developer time, so we are looking for something that can access XML
54 documents locally or over the network and extract data according to given
55 filter rules. That's the point where XQuery enters the stage!
57 If we want to know when the underground number 6 in direction
58 \Aring\c{}sjordet is passing the underground station in Nydalen on November
59 14th 2008 after 1pm, we use the following URL:
61 \c{http://wap.trafikanten.no/F.asp?f=03012130&t=13&m=00&d=14.11.2008&start=1}
63 The parameters have the following meanings:
65 \o \e{f} The unique station ID of Nydalen.
66 \o \e{t} The hour in 0-23 format.
67 \o \e{m} The minute in 0-59 format.
68 \o \e{d} The date in dd.mm.yyyy format.
69 \o \e{start} Not interesting for our use but should be passed.
72 As a result we get the following document:
74 \quotefile examples/xmlpatterns/trafficinfo/time_example.wml
76 So for every departure we have a \c <a> tag that contains the time as a
77 text element, and the following text element contains the line number
80 To encapsulate the XQuery code in the example application, we create a
81 custom \c TimeQuery class. This provides the \c queryInternal() function
82 that takes a station ID and date/time as input and returns the list of
85 \snippet examples/xmlpatterns/trafficinfo/timequery.cpp 1
87 The first lines of this function synthesize the XQuery strings that fetch
88 the document and extract the data.
89 For better readability, two separated queries are used here: the first one
90 fetches the times and the second fetches the line numbers and directions.
92 The \c doc() XQuery method opens a local or remote XML document and returns
93 it, so the \c{/wml/card/p/small/} statement behind it selects all XML nodes
94 that can be reached by the path, \c wml \rarrow \c card \rarrow \c p \rarrow
96 Now we are on the node that contains all the XML nodes we are interested in.
98 In the first query we select all \c a nodes that have a \c href attribute
99 starting with the string "Rute" and return the text of these nodes.
101 In the second query we select all text nodes that are children of the
102 \c small node which start with a number.
103 These two queries are passed to the QXmlQuery instance and are evaluated
104 to string lists. After some sanity checking, we have collected all the
107 In the section above we have seen that an unique station ID must be passed
108 as an argument to the URL for retrieving the time, so how to find out which
109 is the right station ID to use? The WAP service provides a page for that
112 \c{http://wap.trafikanten.no/FromLink1.asp?fra=Nydalen}
114 will return the following document:
116 \snippet examples/xmlpatterns/trafficinfo/station_example.wml 0
118 The names of the available stations are listed as separate text elements
119 and the station ID is part of the \c href attribute of the parent \c a
120 (anchor) element. In our example, the \c StationQuery class encapsulates
121 the action of querying the stations that match the given name pattern with
124 \snippet examples/xmlpatterns/trafficinfo/stationquery.cpp 0
126 Just as in the \c TimeQuery implementation, the first step is to
127 synthesize the XQuery strings for selecting the station names and the
128 station IDs. As the station name that we pass in the URL will be input
129 from the user, we should protect the XQuery from code injection by using
130 the QXmlQuery::bindVariable() method to do proper quoting of the variable
131 content for us instead of concatenating the two strings manually.
133 So, we define a XQuery \c $station variable that is bound to the user
134 input. This variable is concatenated inside the XQuery code with the
135 \c concat method. To extract the station IDs, we select all \c a elements
136 that have an \c title attribute with the content "Velg", and from these
137 elements we take the substring of the \c href attribute that starts at the
140 The station name can be extracted a bit more easily by just taking the
141 text elements of the selected \a elements.
143 After some sanity checks we have all the station IDs and the corresponding
146 The rest of the code in this example is just for representing the time and
147 station information to the user, and uses techniques described in the