[prev in list] [next in list] [prev in thread] [next in thread]
List: kde-commits
Subject: [publictransport] engine: GIT_SILENT: Update/add documentation, cleanup (silent)
From: Friedrich_Karl_Tilman_Pülz <fpuelz () gmx ! de>
Date: 2012-11-30 20:36:57
Message-ID: 20121130203657.47801A60C8 () git ! kde ! org
[Download RAW message or body]
Git commit 9ce9bf895e60ac9ba0b2641ad15de0803b6ca433 by Friedrich Karl Tilman Pülz.
Committed on 26/11/2012 at 22:09.
Pushed by fkpulz into branch 'master'.
GIT_SILENT: Update/add documentation, cleanup
Remove old comments, simplify some things, remove unused code
M +44 -40 engine/publictransportdataengine.cpp
M +80 -41 engine/publictransportdataengine.h
http://commits.kde.org/publictransport/9ce9bf895e60ac9ba0b2641ad15de0803b6ca433
diff --git a/engine/publictransportdataengine.cpp \
b/engine/publictransportdataengine.cpp index 63b6e8b..e2348b5 100644
--- a/engine/publictransportdataengine.cpp
+++ b/engine/publictransportdataengine.cpp
@@ -53,6 +53,7 @@ const int PublicTransportEngine::DEFAULT_TIME_OFFSET = 0;
Plasma::Service* PublicTransportEngine::serviceForSource( const QString &name )
{
#ifdef BUILD_PROVIDER_TYPE_GTFS
+ // Return the GTFS service for "GTFS" or "gtfs" names
if ( name.toLower() == QLatin1String("gtfs") ) {
GtfsService *service = new GtfsService( name, this );
service->setDestination( name );
@@ -62,6 +63,7 @@ Plasma::Service* PublicTransportEngine::serviceForSource( const \
QString &name ) }
#endif
+ // If the name of a data requesting source is given, return the timetable \
service const SourceType type = sourceTypeFromName( name );
if ( isDataRequestingSourceType(type) ) {
TimetableService *service = new TimetableService( name, this );
@@ -69,6 +71,7 @@ Plasma::Service* PublicTransportEngine::serviceForSource( const \
QString &name ) return service;
}
+ // No service for the given name found
return 0;
}
@@ -291,26 +294,27 @@ void PublicTransportEngine::networkStateChanged( uint state )
}
}
-bool PublicTransportEngine::isProviderUsed( const QString &serviceProviderId )
+bool PublicTransportEngine::isProviderUsed( const QString &providerId )
{
- for ( QStringList::ConstIterator it = m_runningSources.constBegin();
- it != m_runningSources.constEnd(); ++it )
- {
- if ( it->contains(serviceProviderId) ) {
+ // Check if a request is currently running for the provider
+ foreach ( const QString &runningSource, m_runningSources ) {
+ if ( runningSource.contains(providerId) ) {
return true;
}
}
+ // Check if a data source is connected that uses the provider
for ( QHash< QString, DataSource* >::ConstIterator it = \
m_dataSources.constBegin(); it != m_dataSources.constEnd(); ++it )
{
Q_ASSERT( *it );
TimetableDataSource *dataSource = dynamic_cast< TimetableDataSource* >( *it \
);
- if ( dataSource && dataSource->providerId() == serviceProviderId ) {
+ if ( dataSource && dataSource->providerId() == providerId ) {
return true;
}
}
+ // The provider is not used any longer by the engine
return false;
}
@@ -318,6 +322,8 @@ void PublicTransportEngine::slotSourceRemoved( const QString \
&sourceName ) {
const QString nonAmbiguousName = disambiguateSourceName( sourceName );
if ( m_dataSources.contains(nonAmbiguousName) ) {
+ // If this is a timetable data source, which might be associated with \
multiple + // ambiguous source names, check if this data source is still \
connected under other names TimetableDataSource *timetableDataSource =
dynamic_cast< TimetableDataSource* >( \
m_dataSources[nonAmbiguousName] ); if ( timetableDataSource ) {
@@ -328,19 +334,20 @@ void PublicTransportEngine::slotSourceRemoved( const QString \
&sourceName ) }
}
+ // If a provider was used by the source,
+ // remove the provider if it is not used by another source
const DataSource *dataSource = m_dataSources.take( nonAmbiguousName );
Q_ASSERT( dataSource );
-// kDebug() << "Source" << sourceName << "removed, still cached data sources" \
<< m_dataSources.count();
-
- // If a provider was used by the source, remove the provider if it is not \
used in another source if ( dataSource->data().contains("serviceProvider") ) {
const QString providerId = \
dataSource->value("serviceProvider").toString(); if ( !providerId.isEmpty() && \
!isProviderUsed(providerId) ) { + // Remove provider from the list,
+ // if no other ProviderPointer to that provider exists, this deletes \
the provider m_providers.remove( providerId );
}
}
- // Data source is no longer used
+ // The data source is no longer used, delete it
delete dataSource;
}
}
@@ -579,18 +586,22 @@ bool \
PublicTransportEngine::updateServiceProviderForCountrySource( const SourceR \
providerId = defaultProvider; }
+ // Test if the provider is valid
QVariantHash providerData;
QString errorMessage;
if ( testServiceProvider(providerId, &providerData, &errorMessage) ) {
+ // The provider is valid, update it's state
QVariantHash stateData;
const QString state = updateProviderState( providerId, &stateData,
providerData["type"].toString() \
);
+ // Publish all provider information and add "state", "stateData" and "error"
setData( data.name, providerData );
setData( data.name, "state", state );
setData( data.name, "stateData", stateData );
setData( data.name, "error", false );
} else {
+ // The provider is erroneous, only return "id", "error" and "errorMessage"
setData( data.name, "id", providerId );
setData( data.name, "error", true );
setData( data.name, "errorMessage", errorMessage );
@@ -1053,12 +1064,6 @@ void PublicTransportEngine::requestAdditionalData( const \
QString &sourceName, in routeDataUrl) );
}
-void PublicTransportEngine::forceUpdate()
-{
- kDebug() << "FORCE UPDATE \
-------------------------------------------------------------------";
- forceImmediateUpdateOfAllVisualizations();
-}
-
QString PublicTransportEngine::fixProviderId( const QString &providerId )
{
if ( !providerId.isEmpty() ) {
@@ -1089,7 +1094,7 @@ QString PublicTransportEngine::disambiguateSourceName( const \
QString &sourceName
// Round time parameter values to 15 minutes precision
QRegExp rx( "(time=[^\\|]+|datetime=[^\\|]+)" );
- if ( rx.indexIn( ret ) != -1 ) {
+ if ( rx.indexIn(ret) != -1 ) {
// Get the time value
const QString timeParameter = rx.cap( 1 );
QDateTime time;
@@ -1371,13 +1376,13 @@ PublicTransportEngine::SourceRequestData::SourceRequestData( \
const QString &name
} else if ( parameterName == QLatin1String("targetstop") ) {
JourneyRequest *journeyRequest = dynamic_cast< JourneyRequest* \
>( request ); if ( !journeyRequest ) {
- kWarning() << "The \"targetStop\" parameter is only used for \
journey requests"; + kWarning() << "The 'targetstop' parameter \
is only used for journey requests"; }
journeyRequest->setTargetStop( parameterValue );
} else if ( parameterName == QLatin1String("originstop") ) {
JourneyRequest *journeyRequest = dynamic_cast< JourneyRequest* \
>( request ); if ( !journeyRequest ) {
- kWarning() << "The \"originStop\" parameter is only used for \
journey requests"; + kWarning() << "The 'originstop' parameter \
is only used for journey requests"; }
journeyRequest->setStop( parameterValue );
} else if ( parameterName == QLatin1String("timeoffset") ) {
@@ -1395,7 +1400,7 @@ PublicTransportEngine::SourceRequestData::SourceRequestData( \
const QString &name bool ok;
request->setMaxCount( parameterValue.toInt(&ok) );
if ( !ok ) {
- kWarning() << "Bad value for 'maxCount' in source name:" << \
parameterValue; + kWarning() << "Bad value for 'maxcount' in \
source name:" << parameterValue; request->setMaxCount( 20 );
}
} else if ( dynamic_cast<StopsByGeoPositionRequest*>(request) ) {
@@ -1487,7 +1492,8 @@ bool PublicTransportEngine::SourceRequestData::isValid() const
if ( !journeyRequest || journeyRequest->stop().isEmpty() ||
journeyRequest->targetStop().isEmpty() )
{
- kWarning() << "Origin and/or target stop names are missing in data \
source name" << name; + kWarning() << "Origin and/or target stop names \
are missing in data source name" + << name;
return false;
}
}
@@ -1498,22 +1504,24 @@ bool PublicTransportEngine::SourceRequestData::isValid() \
const
bool PublicTransportEngine::sourceRequestEvent( const QString &name )
{
- if ( isDataRequestingSourceType(sourceTypeFromName(name)) ) {
- setData( name, DataEngine::Data() ); // Create source, TODO: check if [name] \
is valid + // If name is associated with a data source that runs asynchronously,
+ // create the source first with empty data, gets updated once the request has \
finished + SourceRequestData data( name );
+ if ( data.isValid() && isDataRequestingSourceType(data.type) ) {
+ setData( name, DataEngine::Data() );
}
-// TODO call forceImmediateUpdateOfAllVisualizations() after the data is \
available
- return requestOrUpdateSourceEvent( name );
+ return requestOrUpdateSourceEvent( data );
}
bool PublicTransportEngine::updateSourceEvent( const QString &name )
{
- return requestOrUpdateSourceEvent( name, true );
+ return requestOrUpdateSourceEvent( SourceRequestData(name), true );
}
-bool PublicTransportEngine::requestOrUpdateSourceEvent( const QString &name, bool \
update ) +bool PublicTransportEngine::requestOrUpdateSourceEvent( const \
SourceRequestData &sourceData, + \
bool update ) {
- SourceRequestData sourceData( name );
if ( !sourceData.isValid() ) {
return false;
}
@@ -1545,7 +1553,7 @@ bool PublicTransportEngine::requestOrUpdateSourceEvent( const \
QString &name, boo
case InvalidSourceName:
default:
- kDebug() << "Source name incorrect" << name;
+ kDebug() << "Source name incorrect" << sourceData.name;
return false;
}
}
@@ -1672,18 +1680,14 @@ void PublicTransportEngine::updateTimeout()
{
// Find the timetable data source to which the timer belongs which timeout() \
signal was emitted QTimer *timer = qobject_cast< QTimer* >( sender() );
- for ( QHash<QString,DataSource*>::ConstIterator it = m_dataSources.constBegin();
- it != m_dataSources.constEnd(); ++it )
- {
- TimetableDataSource *dataSource = dynamic_cast< TimetableDataSource* >( *it \
);
- if ( dataSource && dataSource->updateTimer() == timer ) {
- // Found the timetable data source of the timer,
- // requests updates for all connected sources (possibly multiple \
combined stops)
- foreach ( const QString &sourceName, dataSource->usingDataSources() ) {
- updateTimetableDataSource( SourceRequestData(sourceName) );
- }
- return;
+ TimetableDataSource *dataSource = dataSourceFromAdditionDataTimer( timer );
+ if ( dataSource ) {
+ // Found the timetable data source of the timer,
+ // requests updates for all connected sources (possibly multiple combined \
stops) + foreach ( const QString &sourceName, dataSource->usingDataSources() ) \
{ + updateTimetableDataSource( SourceRequestData(sourceName) );
}
+ return;
}
// No data source found that started the timer,
diff --git a/engine/publictransportdataengine.h b/engine/publictransportdataengine.h
index 9d9eb4b..aae8ecc 100644
--- a/engine/publictransportdataengine.h
+++ b/engine/publictransportdataengine.h
@@ -63,23 +63,27 @@ class PublicTransportEngine : public Plasma::DataEngine {
Q_OBJECT
public:
+ /** @brief A shared pointer to a ServiceProvider. */
typedef QSharedPointer< ServiceProvider > ProviderPointer;
/**
* @brief The available types of sources of this data engine.
*
- * Source names can be associated with these types by the first word using \
souceTypeFromName.
- * @see sourceTypeKeyword
- * @see sourceTypeFromName
+ * Source names can be associated with these types by their first words using
+ * souceTypeFromName().
+ * @see sourceTypeKeyword()
+ * @see sourceTypeFromName()
**/
enum SourceType {
InvalidSourceName = 0, /**< Returned by @ref sourceTypeFromName,
* if the source name is invalid. */
// Data sources providing information about the engine, available providers
- ServiceProviderSource = 1, /**< The source contains information about \
available
- * service providers for a given country. See also @ref \
usage_serviceproviders_sec. */
- ServiceProvidersSource = 2, /**< The source contains information about \
available + ServiceProviderSource = 1, /**< The source contains information \
about a specific + * service provider, identified by it's ID or a \
country code. If a country code + * is given, the default provider for \
that country gets used, if any. + * See also @ref \
usage_serviceproviders_sec. */ + ServiceProvidersSource = 2, /**< The source \
contains information about all available
* service providers. See also @ref usage_serviceproviders_sec. */
ErroneousServiceProvidersSource = 3, /**< The source contains a list of \
erroneous
* service providers. */
@@ -88,8 +92,8 @@ public:
VehicleTypesSource = 5, /**< The source contains information about all \
available
* vehicle types. They are stored by integer keys, matching the \
values of
* the Enums::VehicleType (engine) and PublicTransport::VehicleType
- * (libpublictransporthelper) enumerations. The information stored \
stored in
- * this data source can also be retrieved from \
PublicTransport::VehicleType + * (libpublictransporthelper) \
enumerations. The information stored in this + * data source can also \
be retrieved from PublicTransport::VehicleType
* using libpublictransporthelper. See also @ref \
usage_vehicletypes_sec. */
// Data sources providing timetable data
@@ -108,7 +112,7 @@ public:
};
/** @brief Every data engine needs a constructor with these arguments. */
- PublicTransportEngine( QObject* parent, const QVariantList& args );
+ PublicTransportEngine( QObject *parent, const QVariantList &args );
/** @brief Destructor. */
~PublicTransportEngine();
@@ -157,6 +161,17 @@ public:
virtual QStringList sources() const;
/**
+ * @brief Gets the service for the data source with the given @p name.
+ *
+ * The returned service can be used to start operations on the timetable data \
source. + * For example it has an operation to import GTFS feeds into a local \
database or to update + * or delete that database.
+ * @return A pointer to the created Plasma::Service or 0 if no service is \
available for @p name. + * @see PublicTransportService
+ **/
+ virtual Plasma::Service* serviceForSource( const QString &name );
+
+ /**
* @brief Get the number of seconds until the next automatic update of @p \
sourceName.
*
* Timetable data sources update their data periodically, based on the needs of \
the data source @@ -238,12 +253,12 @@ signals:
/**
* @brief Emitted when a request for additional data has been finished.
*
- * This signal gets used by the "timetable" service to get notified when a job \
has finsihed + * This signal gets used by the timetable service to get notified \
when a job has finsihed
* and whether it was successful or not.
- *
* @param newData The new contents (including additional data) in the data \
source for the item.
* @param success Whether or not the additional data job was successful.
* @param errorMessage Contains an error message if @p success is @c false.
+ * @see usage_service_sec
**/
void additionalDataRequestFinished( const QVariantHash &newData, bool success = \
true,
const QString &errorMessage = QString() );
@@ -253,10 +268,24 @@ public slots:
void requestAdditionalData( const QString &sourceName, int updateItem );
protected slots:
+ /**
+ * @brief Free resources for the data source with the given @p name where \
possible. + *
+ * Destroys the DataSource object associated with the data source, if the source \
is not also + * connected under other ambiguous names (for timetable data \
sources). If a ServiceProvider + * was used for the data source but not for any \
other source, it gets destroyed, too. + **/
void slotSourceRemoved( const QString &name );
+
+ /**
+ * @brief The network state has changed, eg. was connected or disconnected.
+ *
+ * This slot is connected with the @c networkstatus module of @c kded through \
DBus. + * @p state The new network state.
+ **/
void networkStateChanged( uint state );
- void forceUpdate();
+ /** @brief The update timeout for a timetable data source was reached. */
void updateTimeout();
#ifdef BUILD_PROVIDER_TYPE_GTFS
@@ -266,7 +295,7 @@ protected slots:
/** @brief Received a message from a @p job of the GTFS service. */
void gtfsImportJobInfoMessage( KJob *job, const QString &plain, const QString \
&rich );
- /** @brief A @p job of the GTFS service notifies it's progress. */
+ /** @brief A @p job of the GTFS service notifies it's progress in @p percent. */
void gtfsImportJobPercent( KJob *job, ulong percent );
#endif // BUILD_PROVIDER_TYPE_GTFS
@@ -275,7 +304,7 @@ protected slots:
*
* @param provider The provider that was used to get the departures.
* @param requestUrl The url used to request the information.
- * @param departures A list of departures that were received.
+ * @param departures The departures that were received.
* @param globalInfo Global information that affects all departures.
* @param request Information about the request for the here received @p \
departures.
*
@@ -292,7 +321,7 @@ protected slots:
*
* @param provider The provider that was used to get the arrivals.
* @param requestUrl The url used to request the information.
- * @param arrivals A list of arrivals that were received.
+ * @param arrivals The arrivals that were received.
* @param globalInfo Global information that affects all arrivals.
* @param request Information about the request for the here received @p \
arrivals.
*
@@ -309,7 +338,7 @@ protected slots:
*
* @param provider The provider that was used to get the journeys.
* @param requestUrl The url used to request the information.
- * @param journeys A list of journeys that were received.
+ * @param journeys The journeys that were received.
* @param globalInfo Global information that affects all journeys.
* @param request Information about the request for the here received @p \
journeys.
*
@@ -326,7 +355,7 @@ protected slots:
*
* @param provider The service provider that was used to get the stops.
* @param requestUrl The url used to request the information.
- * @param stops A list of stops that were received.
+ * @param stops The stops that were received.
* @param request Information about the request for the here received @p stops.
*
* @see ServiceProvider::useSeparateCityValue()
@@ -427,7 +456,14 @@ protected:
**/
bool updateSourceEvent( const QString &name );
- bool requestOrUpdateSourceEvent( const QString &name, bool update = false );
+ /**
+ * @brief Implementation of sourceRequestEvent() and updateSourceEvent() (@p \
update @c true). + *
+ * Requesting and updating a source is done in (almost) the same way.
+ * @param data A SourceRequestData for the data source to be requested/updated.
+ * @param update @c True, if the data source should be updated. @c False, \
otherwise. + **/
+ bool requestOrUpdateSourceEvent( const SourceRequestData &data, bool update = \
false );
/**
* @brief Updates the ServiceProviders data source.
@@ -509,17 +545,6 @@ protected:
UpdateFlags updateFlags = DefaultUpdateFlags );
/**
- * @brief Gets the service for the data source with the given @p name.
- *
- * The returned service can be used to start operations on the timetable data \
source.
- * For example it has an operation to import GTFS feeds into a local database or \
to update
- * or delete that database.
- * @return A pointer to the created Plasma::Service or 0 if no service is \
available for @p name.
- * @see PublicTransportService
- **/
- virtual Plasma::Service* serviceForSource( const QString &name );
-
- /**
* @brief Test @p providerId for errors.
*
* @param providerId The ID of the provider to test.
@@ -535,16 +560,24 @@ protected:
QString *errorMessage,
const QSharedPointer<KConfig> &cache = \
QSharedPointer<KConfig>() );
+ /**
+ * @brief Request timetable data after checking the provider and the request.
+ *
+ * The request fails, if the requested provider is invalid, if an unsupported \
feature + * is needed to run the request or if a @c city parameter is missing but \
needed by the + * provider.
+ * @param data A SourceRequestData object for the data source name that \
triggered the request. + * @return @c True, if the request could be started \
successfully, @c false otherwise. + * @see ServiceProvider::request()
+ **/
bool request( const SourceRequestData &data );
- inline bool request( const QString &sourceName ) {
- return request( SourceRequestData(sourceName) );
- };
private:
+ /** @brief Get the date and time for the next update of @p dataSource. */
QDateTime sourceUpdateTime( TimetableDataSource *dataSource,
UpdateFlags updateFlags = DefaultUpdateFlags );
- /** Handler for departuresReceived() (@p isDepartureData @c true) and \
arrivalsReceived() */ + /** @brief Handler for departuresReceived() (@p \
isDepartureData @c true) and arrivalsReceived() */ void timetableDataReceived( \
ServiceProvider *provider, const QUrl &requestUrl, const DepartureInfoList &items,
const GlobalTimetableInfo &globalInfo,
@@ -565,6 +598,7 @@ private:
QVariantHash serviceProviderData( const ServiceProviderData &data,
const ServiceProvider *provider = 0 );
+ /** @brief Overload, use if @p provider is @em not 0. */
QVariantHash serviceProviderData( const ServiceProvider *provider );
/**
@@ -599,8 +633,8 @@ private:
**/
ProvidersDataSource *providersDataSource() const;
- /** @brief Checks if the provider with the given ID is used by a connected \
source. */
- bool isProviderUsed( const QString &serviceProviderId );
+ /** @brief Checks if the provider with the given @p providerId is used by a \
connected source. */ + bool isProviderUsed( const QString &providerId );
/**
* @brief Get an error code for the given @p stateId.
@@ -620,14 +654,17 @@ private:
static bool isStateDataCached( const QString &stateDataKey );
/**
- * @brief Remove all ambiguous parts from @p sourceName and make it lower case.
+ * @brief Disambiguates the given @p sourceName.
*
- * TODO
+ * Date and time parameters get replaced by a @c datetime parameter, with the \
time rounded to + * 15 minutes to use one data source object for all sources that \
are less than 15 minutes apart + * from each other.
+ * Parameters get reordered to a standard order, so that data source names with \
only a + * different parameter order point to the same DataSource object. \
Parameter values get + * converted to lower case (eg. stop names).
*
- * Ambiguous parts are date and time parameters. Timetable items should be \
shared between
- * data sources for the same stop, also if their date and/or time values differ.
- * Without removing these parameters eg. departure data sources with a little \
different time
- * values will not share it's departures and download them twice (at least the \
overlapping ones). + * Without doing this eg. departure data sources with only \
little different time values + * will @em not share their departures and download \
them twice.
**/
static QString disambiguateSourceName( const QString &sourceName );
@@ -676,7 +713,9 @@ private:
static ServiceProvider *createProviderForData( const ServiceProviderData *data,
QObject *parent = 0, const QSharedPointer<KConfig> &cache = \
QSharedPointer<KConfig>(0) );
+ /** @brief Get the timetable data source that uses the given @p timer. */
TimetableDataSource *dataSourceFromAdditionDataTimer( QTimer *timer ) const;
+
bool enoughDataAvailable( DataSource *dataSource, const SourceRequestData \
&sourceData ) const;
QHash< QString, ProviderPointer > m_providers; // Already loaded service \
providers by ID
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic