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>
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.
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.
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
22
#ifndef RESOURCEWATCHER_H
23
#define RESOURCEWATCHER_H
25
#include <Nepomuk/Types/Class>
26
#include <Nepomuk/Types/Property>
27
#include <Nepomuk/Resource>
29
#include <QtDBus/QDBusVariant>
30
#include <QtCore/QVariant>
32
//#include "nepomukdatamanagement_export.h"
37
* \class ResourceWatcher resourcewatcher.h
39
* \brief Selectively monitor the nepomuk repository for changes.
41
* Resources may be monitored on the basis of types, properties, and uris.
43
* Changes may be monitored in one of the following ways:
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()
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.
60
* \section nepomuk_rw_examples Resource Watcher Usage Example
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.
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()));
76
* \author Vishesh Handa <handa.vish@gmail.com>, Sebastian Trueg <trueg@kde.org>
78
* \ingroup nepomuk_datamanagement
80
class ResourceWatcher : public QObject
86
* \brief Create a new %ResourceWatcher instance.
88
* This instance will not emit any signals before it has been configured
91
ResourceWatcher( QObject* parent = 0 );
96
virtual ~ResourceWatcher();
100
* \brief Add a type to be watched.
102
* Every resource of this type will be watched for changes.
106
void addType( const Types::Class & type );
109
* \brief Add a resource to be watched.
111
* Every change to this resource will be
112
* signalled, depending on the configured properties().
116
void addResource( const Nepomuk::Resource & res );
119
* \brief Add a property to be watched.
121
* Every change to a value of this property
122
* will be signalled, depending on the configured resources() or types().
124
* \sa setProperties()
126
void addProperty( const Types::Property & property );
129
* \brief Remove a type to be watched.
131
* Every resource of this type will be watched for changes.
135
void removeType( const Types::Class & type );
138
* \brief Remove a resource to be watched.
140
* Every change to this resource will be
141
* signalled, depending on the configured properties().
145
void removeResource( const Nepomuk::Resource & res );
148
* \brief Remove a property to be watched.
150
* Every change to a value of this property
151
* will be signalled, depending on the configured resources() or types().
153
* \sa setProperties()
155
void removeProperty( const Types::Property & property );
158
* \brief Set the types to be watched.
160
* Every resource having one of these types will be watched for changes.
164
void setTypes( const QList<Types::Class> & types_ );
167
* \brief Set the resources to be watched.
169
* Every change to one of these resources will be
170
* signalled, depending on the configured properties().
174
void setResources( const QList<Nepomuk::Resource> & resources_ );
177
* \brief Set the properties to be watched.
179
* Every change to a value of any of these properties
180
* will be signalled, depending on the configured resources() or types().
184
void setProperties( const QList<Types::Property> & properties_ );
187
* \brief The types that have been configured via addType() and setTypes().
189
* Every resource having one of these types will be watched
192
QList<Types::Class> types() const;
195
* \brief The resources that have been configured via addResource() and setResources().
197
* Every change to one of these resources will be
198
* signalled, depending on the configured properties().
200
QList<Nepomuk::Resource> resources() const;
203
* \brief The properties that have been configured via addProperty() and setProperties().
205
* Every change to a value of any of these properties
206
* will be signalled, depending on the configured resources() or types().
208
QList<Types::Property> properties() const;
211
* \brief Start the signalling of changes.
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.
220
* \brief Stop the signalling of changes.
222
* Allows to stop the watcher which has been started
223
* via start(). Calling stop() multiple times has no effect.
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.
234
void resourceCreated( const Nepomuk::Resource & resource, const QList<QUrl>& types ); //FIXME: Use either Resource or uri, not a mix
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.
242
void resourceRemoved( const QUrl & uri, const QList<QUrl>& types );
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.
250
void resourceTypeAdded( const Nepomuk::Resource & res, const Nepomuk::Types::Class & type );
253
* \brief This signal is emitted when a type has been removed from a resource.
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.
260
void resourceTypeRemoved( const Nepomuk::Resource & res, const Nepomuk::Types::Class & type );
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.
268
void propertyAdded( const Nepomuk::Resource & resource,
269
const Nepomuk::Types::Property & property,
270
const QVariant & value );
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.
278
void propertyRemoved( const Nepomuk::Resource & resource,
279
const Nepomuk::Types::Property & property,
280
const QVariant & value );
283
* \brief This signal is emitted when a property value is changed.
285
* This signal is essentially a combination of the propertyAdded and propertyRemoved signals.
287
* Be aware that removing and then adding a property will result in two separate
288
* propertyChanged signals. They are never combined.
290
* Specially, since one could theoretically take forever between the removal and the
291
* setting of the property.
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.
298
void propertyChanged( const Nepomuk::Resource & resource,
299
const Nepomuk::Types::Property & property,
300
const QVariantList & addedValues,
301
const QVariantList & removedValues );
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);
319
#endif // RESOURCEWATCHER_H
added
removed
messagelist/private/nepomuk/resourcewatcher.h
