source: trunk/doc/src/examples/trafficinfo.qdoc@ 1168

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example xmlpatterns/trafficinfo
    \title TrafficInfo Example

    Shows how XQuery can be used extract information from WML documents provided by a WAP service.

    \section1 Overview

    The WAP service used in this example is \l{Trafikanten}{wap.trafikanten.no}
    that is run by the Norwegian governmental agency for public transport in
    Oslo. The service provides real time information about the departure of
    busses, trams and undergrounds for every station in the city area.

    This example application displays the departure information for a specific
    station and provides the feature to filter for a special bus or tram line.

    \image trafficinfo-example.png

    \section1 Retrieving the Data

    Without the knowledge of XQuery, one would use QNetworkAccessManager to
    query the WML document from the WAP service and then using the QDom
    classes or QXmlStreamReader classes to iterate over the document and
    extract the needed information.
    However this approach results in a lot of glue code and consumes valuable
    developer time, so we are looking for something that can access XML
    documents locally or over the network and extract data according to given
    filter rules. That's the point where XQuery enters the stage!

    If we want to know when the underground number 6 in direction
    \Aring\c{}sjordet is passing the underground station in Nydalen on November
    14th 2008 after 1pm, we use the following URL:

    \c{http://wap.trafikanten.no/F.asp?f=03012130&t=13&m=00&d=14.11.2008&start=1}

    The parameters have the following meanings:
    \list
        \o \e{f} The unique station ID of Nydalen.
        \o \e{t} The hour in 0-23 format.
        \o \e{m} The minute in 0-59 format.
        \o \e{d} The date in dd.mm.yyyy format.
        \o \e{start} Not interesting for our use but should be passed.
    \endlist

    As a result we get the following document:

    \quotefile examples/xmlpatterns/trafficinfo/time_example.wml

    So for every departure we have a \c <a> tag that contains the time as a
    text element, and the following text element contains the line number
    and direction.

    To encapsulate the XQuery code in the example application, we create a
    custom \c TimeQuery class. This provides the \c queryInternal() function
    that takes a station ID and date/time as input and returns the list of
    times and directions:

    \snippet examples/xmlpatterns/trafficinfo/timequery.cpp 1