[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