src/kitemviews/private/nepomuk/resourcewatcher.h

   1 /*
   2     This file is part of the Nepomuk KDE project.
   3     Copyright (C) 2011  Vishesh Handa <handa.vish@gmail.com>
   4     Copyright (C) 2011 Sebastian Trueg <trueg@kde.org>
   5
   6     This library is free software; you can redistribute it and/or
   7     modify it under the terms of the GNU Lesser General Public
   8     License as published by the Free Software Foundation; either
   9     version 2.1 of the License, or (at your option) any later version.
  10
  11     This library is distributed in the hope that it will be useful,
  12     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14     Lesser General Public License for more details.
  15
  16     You should have received a copy of the GNU Lesser General Public
  17     License along with this library; if not, write to the Free Software
  18     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  19 */
  20
  21
  22 #ifndef RESOURCEWATCHER_H
  23 #define RESOURCEWATCHER_H
  24
  25 #include <Nepomuk/Types/Class>
  26 #include <Nepomuk/Types/Property>
  27 #include <Nepomuk/Resource>
  28
  29 #include <QtDBus/QDBusVariant>
  30 #include <QtCore/QVariant>
  31
  32 //#include "nepomukdatamanagement_export.h"
  33
  34 namespace Nepomuk {
  35
  36     /**
  37      * \class ResourceWatcher resourcewatcher.h
  38      *
  39      * \brief Selectively monitor the nepomuk repository for changes.
  40      *
  41      * Resources may be monitored on the basis of types, properties, and uris.
  42      *
  43      * Changes may be monitored in one of the following ways:
  44      * -# By resources -
  45      *    Specify the exact resources that should be watched. Any changes made to the specified resources
  46      *    (Excluding \ref nepomuk_dms_metadata) will be notified through the propertyAdded() and propertyRemoved()
  47      *    signals. Notifications will also be sent if any of the watched resources is deleted.
  48      * -# By resources and properties -
  49      *    Specify the exact resources and their properties. Any changes made to the specified resources
  50      *    which touch one of the specified properties will be notified through the propertyAdded() and propertyRemoved()
  51      *    signals.
  52      * -# By types -
  53      *    Specific types may be specified via add/setType. If types are set, then notifications will be
  54      *    sent for all new resources of that type. This includes property changes and resource creation and removal.
  55      *    TODO: add flags that allow to only watch for resource creation and removal.
  56      * -# By types and properties -
  57      *    Both the types and properties may be specified. Notifications will be sent for property changes
  58      *    in resource with the specified types.
  59      *
  60      * \section nepomuk_rw_examples Resource Watcher Usage Example
  61      *
  62      * The following code creates a new ResourceWatcher, configures it to listen to changes on the \c nmm:performer
  63      * property on one specific resource \c res.
  64      *
  65      * \code
  66      * Nepomuk::ResourceWatcher* watcher = new Nepomuk::ResourceWatcher(this);
  67      * watcher->addResource(res);
  68      * watcher->addProperty(NMM:performer());
  69      * connect(watcher, SIGNAL(propertyAdded(Nepomuk::Resource, Nepomuk::Types::Property, QVariant)),
  70      *         this, SLOT(slotPropertyChanged()));
  71      * connect(watcher, SIGNAL(propertyRemoved(Nepomuk::Resource, Nepomuk::Types::Property, QVariant)),
  72      *         this, SLOT(slotPropertyChanged()));
  73      * rwatcher->start();
  74      * \endcode
  75      *
  76      * \author Vishesh Handa <handa.vish@gmail.com>, Sebastian Trueg <trueg@kde.org>
  77      *
  78      * \ingroup nepomuk_datamanagement
  79      */
  80     class ResourceWatcher : public QObject
  81     {
  82         Q_OBJECT
  83
  84     public:
  85         /**
  86          * \brief Create a new %ResourceWatcher instance.
  87          *
  88          * This instance will not emit any signals before it has been configured
  89          * and started.
  90          */
  91         ResourceWatcher( QObject* parent = 0 );
  92
  93         /**
  94          * \brief Destructor.
  95          */
  96         virtual ~ResourceWatcher();
  97
  98     public Q_SLOTS:
  99         /**
 100          * \brief Add a type to be watched.
 101          *
 102          * Every resource of this type will be watched for changes.
 103          *
 104          * \sa setTypes()
 105          */
 106         void addType( const Types::Class & type );
 107
 108         /**
 109          * \brief Add a resource to be watched.
 110          *
 111          * Every change to this resource will be
 112          * signalled, depending on the configured properties().
 113          *
 114          * \sa setResources()
 115          */
 116         void addResource( const Nepomuk::Resource & res );
 117
 118         /**
 119          * \brief Add a property to be watched.
 120          *
 121          * Every change to a value of this property
 122          * will be signalled, depending on the configured resources() or types().
 123          *
 124          * \sa setProperties()
 125          */
 126         void addProperty( const Types::Property & property );
 127
 128         /**
 129          * \brief Remove a type to be watched.
 130          *
 131          * Every resource of this type will be watched for changes.
 132          *
 133          * \sa setTypes()
 134          */
 135         void removeType( const Types::Class & type );
 136
 137         /**
 138          * \brief Remove a resource to be watched.
 139          *
 140          * Every change to this resource will be
 141          * signalled, depending on the configured properties().
 142          *
 143          * \sa setResources()
 144          */
 145         void removeResource( const Nepomuk::Resource & res );
 146
 147         /**
 148          * \brief Remove a property to be watched.
 149          *
 150          * Every change to a value of this property
 151          * will be signalled, depending on the configured resources() or types().
 152          *
 153          * \sa setProperties()
 154          */
 155         void removeProperty( const Types::Property & property );
 156
 157         /**
 158          * \brief Set the types to be watched.
 159          *
 160          * Every resource having one of these types will be watched for changes.
 161          *
 162          * \sa addType()
 163          */
 164         void setTypes( const QList<Types::Class> & types_ );
 165
 166         /**
 167          * \brief Set the resources to be watched.
 168          *
 169          * Every change to one of these resources will be
 170          * signalled, depending on the configured properties().
 171          *
 172          * \sa addResource()
 173          */
 174         void setResources( const QList<Nepomuk::Resource> & resources_ );
 175
 176         /**
 177          * \brief Set the properties to be watched.
 178          *
 179          * Every change to a value of any of these properties
 180          * will be signalled, depending on the configured resources() or types().
 181          *
 182          * \sa addProperty()
 183          */
 184         void setProperties( const QList<Types::Property> & properties_ );
 185
 186         /**
 187          * \brief The types that have been configured via addType() and setTypes().
 188          *
 189          * Every resource having one of these types will be watched
 190          * for changes.
 191          */
 192         QList<Types::Class> types() const;
 193
 194         /**
 195          * \brief The resources that have been configured via addResource() and setResources().
 196          *
 197          * Every change to one of these resources will be
 198          * signalled, depending on the configured properties().
 199          */
 200         QList<Nepomuk::Resource> resources() const;
 201
 202         /**
 203          * \brief The properties that have been configured via addProperty() and setProperties().
 204          *
 205          * Every change to a value of any of these properties
 206          * will be signalled, depending on the configured resources() or types().
 207          */
 208         QList<Types::Property> properties() const;
 209
 210         /**
 211          * \brief Start the signalling of changes.
 212          *
 213          * Before calling this method no signal will be emitted. In
 214          * combination with stop() this allows to suspend the watching.
 215          * Calling start() multiple times has no effect.
 216          */
 217         bool start();
 218
 219         /**
 220          * \brief Stop the signalling of changes.
 221          *
 222          * Allows to stop the watcher which has been started
 223          * via start(). Calling stop() multiple times has no effect.
 224          */
 225         void stop();
 226
 227     Q_SIGNALS:
 228         /**
 229          * \brief This signal is emitted when a new resource is created.
 230          * \param resource The newly created resource.
 231          * \param types The types the new resource has. If types() have been configured this list will always
 232          * contain one of the configured types.
 233          */
 234         void resourceCreated( const Nepomuk::Resource & resource, const QList<QUrl>& types ); //FIXME: Use either Resource or uri, not a mix
 235
 236         /**
 237          * \brief This signal is emitted when a resource is deleted.
 238          * \param uri The resource URI of the removed resource.
 239          * \param types The types the removed resource had. If types() have been configured this list will always
 240          * contain one of the configured types.
 241          */
 242         void resourceRemoved( const QUrl & uri, const QList<QUrl>& types );
 243
 244         /**
 245          * \brief This signal is emitted when a type has been added to a resource. This does not include creation which
 246          * is signalled via resourceCreated(). It only applies to changes in a resource's types.
 247          * \param res The changed resource.
 248          * \param type The newly added type. If types() have been configured it will be one of them.
 249          */
 250         void resourceTypeAdded( const Nepomuk::Resource & res, const Nepomuk::Types::Class & type );
 251
 252         /**
 253          * \brief This signal is emitted when a type has been removed from a resource.
 254          *
 255          * This does not include removal of entire resources which is signalled via resourceRemoved().
 256          * It only applies to changes in a resource's types.
 257          * \param res The changed resource.
 258          * \param type The removed type. If types() have been configured it will be one of them.
 259          */
 260         void resourceTypeRemoved( const Nepomuk::Resource & res, const Nepomuk::Types::Class & type );
 261
 262         /**
 263          * \brief This signal is emitted when a property value is added.
 264          * \param resource The changed resource.
 265          * \param property The property which has a new value.
 266          * \param value The newly added property value.
 267          */
 268         void propertyAdded( const Nepomuk::Resource & resource,
 269                             const Nepomuk::Types::Property & property,
 270                             const QVariant & value );
 271
 272         /**
 273          * \brief This signal is emitted when a property value is removed.
 274          * \param resource The changed resource.
 275          * \param property The property which was changed.
 276          * \param value The removed property value.
 277          */
 278         void propertyRemoved( const Nepomuk::Resource & resource,
 279                               const Nepomuk::Types::Property & property,
 280                               const QVariant & value );
 281
 282         /**
 283          * \brief This signal is emitted when a property value is changed.
 284          *
 285          * This signal is essentially a combination of the propertyAdded and propertyRemoved signals.
 286          *
 287          * Be aware that removing and then adding a property will result in two separate
 288          * propertyChanged signals. They are never combined.
 289          *
 290          * Specially, since one could theoretically take forever between the removal and the
 291          * setting of the property.
 292          *
 293          * \param resource The changed resource.
 294          * \param property The property which was changed.
 295          * \param addedValues The values that have been added.
 296          * \param removedValues The values that have been removed.
 297          */
 298         void propertyChanged( const Nepomuk::Resource & resource,
 299                               const Nepomuk::Types::Property & property,
 300                               const QVariantList & addedValues,
 301                               const QVariantList & removedValues );
 302
 303     private Q_SLOTS:
 304         void slotResourceCreated(const QString& res, const QStringList& types);
 305         void slotResourceRemoved(const QString& res, const QStringList& types);
 306         void slotResourceTypesAdded(const QString& res, const QStringList& types);
 307         void slotResourceTypesRemoved(const QString& res, const QStringList& types);
 308         void slotPropertyAdded(const QString& res, const QString& prop, const QVariantList& objects);
 309         void slotPropertyRemoved(const QString& res, const QString& prop, const QVariantList& objects);
 310         void slotPropertyChanged(const QString& res, const QString& prop,
 311                                  const QVariantList & oldObjs,
 312                                  const QVariantList & newObjs);
 313     private:
 314         class Private;
 315         Private * d;
 316     };
 317 }
 318
 319 #endif // RESOURCEWATCHER_H