1/*
2 This file is part of the kcal library.
3
4 Copyright (c) 2006 David Jarvie <djarvie@kde.org>
5 Copyright (c) 2003,2004 Cornelius Schumacher <schumacher@kde.org>
6
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Library General Public
9 License as published by the Free Software Foundation; either
10 version 2 of the License, or (at your option) any later version.
11
12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Library General Public License for more details.
16
17 You should have received a copy of the GNU Library General Public License
18 along with this library; see the file COPYING.LIB. If not, write to
19 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
20 Boston, MA 02110-1301, USA.
21*/
22#ifndef KCAL_RESOURCECACHED_H
23#define KCAL_RESOURCECACHED_H
24
25#include "resourcecalendar.h"
26#include "incidence.h"
27
28#include <kdatetime.h>
29
30#include <QtCore/QString>
31
32class KConfigGroup;
33namespace KRES { class IdMapper; }
34
35namespace KCal {
36
37class CalendarLocal;
38
39/**
40 This class provides a calendar resource using a local CalendarLocal object to
41 cache the calendar data.
42*/
43class KCAL_DEPRECATED_EXPORT ResourceCached : public ResourceCalendar,
44 public KCal::Calendar::CalendarObserver
45{
46 Q_OBJECT
47 public:
48 /**
49 Reload policy. Whether and when to automatically reload the resource.
50 @see setReloadPolicy(), reloadPolicy()
51 */
52 enum {
53 ReloadNever, /**< never reload the resource automatically */
54 ReloadOnStartup, /**< reload when the resource is opened */
55 ReloadInterval /**< reload at regular intervals set by setReloadInterval() */
56 };
57
58 /**
59 Save policy. Whether and when to automatically save the resource.
60 @see setSavePolicy(), savePolicy()
61 */
62 enum {
63 SaveNever, /**< never save the resource automatically */
64 SaveOnExit, /**< save when the resource is closed */
65 SaveInterval, /**< save at regular intervals set by setSaveInterval() */
66 SaveDelayed, /**< save after every change, after a 15 second delay */
67 SaveAlways /**< save after every change, after a 1 second delay */
68 };
69
70 /**
71 Whether to update the cache file when loading a resource, or whether to
72 upload the cache file after saving the resource.
73 Only applicable to genuinely cached resources.
74 */
75 enum CacheAction {
76 DefaultCache,/**< use the default action set by setReloadPolicy() or setSavePolicy() */
77 NoSyncCache, /**< perform a cache-only operation, without downloading or uploading */
78 SyncCache /**< update the cache file before loading, or upload cache after saving */
79 };
80
81 ResourceCached();
82 explicit ResourceCached( const KConfigGroup &group );
83 virtual ~ResourceCached();
84
85 void readConfig( const KConfigGroup &group );
86 void writeConfig( KConfigGroup &group );
87
88 /**
89 Set reload policy. This controls when the cache is refreshed.
90
91 ReloadNever never reload
92 ReloadOnStartup reload when resource is started
93 ReloadInterval reload regularly after given interval
94 */
95 void setReloadPolicy( int policy );
96 /**
97 Return reload policy.
98
99 @see setReloadPolicy()
100 */
101 int reloadPolicy() const;
102
103 /**
104 Set reload interval in minutes which is used when reload policy is
105 ReloadInterval.
106 */
107 void setReloadInterval( int minutes );
108
109 /**
110 Return reload interval in minutes.
111 */
112 int reloadInterval() const;
113
114 /**
115 Inhibit or allow cache reloads when using load(DefaultCache). If inhibited,
116 this overrides the policy set by setReloadPolicy(), preventing any non-explicit
117 reloads from being performed. If not inhibited, reloads take place according
118 to the policy set by setReloadPolicy().
119
120 @param inhibit true to inhibit reloads, false to allow them
121 */
122 bool inhibitDefaultReload( bool inhibit );
123 bool defaultReloadInhibited() const;
124
125 /**
126 Return whether the resource cache has been reloaded since startup.
127 */
128 bool reloaded() const;
129
130 /**
131 Set save policy. This controls when the cache is refreshed.
132
133 SaveNever never save
134 SaveOnExit save when resource is exited
135 SaveInterval save regularly after given interval
136 SaveDelayed save on every change, after small delay
137 SaveAlways save on every change
138 */
139 void setSavePolicy( int policy );
140 /**
141 Return save policy.
142
143 @see setsavePolicy()
144 */
145 int savePolicy() const;
146
147 /**
148 Set save interval in minutes which is used when save policy is
149 SaveInterval.
150 */
151 void setSaveInterval( int minutes );
152
153 /**
154 Return save interval in minutes.
155 */
156 int saveInterval() const;
157
158 /**
159 Return time of last load.
160 */
161 KDateTime lastLoad() const;
162
163 /**
164 Return time of last save.
165 */
166 KDateTime lastSave() const;
167
168 /**
169 Load resource data, specifying whether to refresh the cache file first.
170 For a non-cached resource, this method has the same effect as load().
171
172 @param action is the type of #CacheAction for this data loading.
173 */
174 bool load( CacheAction action );
175
176 /**
177 Load resource data.
178 */
179 virtual bool load();
180
181 /**
182 Save the resource data to cache, and optionally upload the cache file
183 afterwards. For a non-cached resource, this method has the same effect
184 as save().
185
186 @param action is the type of #CacheAction for this data saving.
187 @param incidence if given as 0, doSave(bool) is called to save all
188 incidences, else doSave(bool, incidence) is called to save only the
189 given one.
190 */
191 bool save( CacheAction action, Incidence *incidence = 0 );
192
193 /**
194 Save resource data.
195 */
196 virtual bool save( Incidence *incidence = 0 );
197
198 /**
199 Add event to calendar.
200
201 @param event is a pointer to the Event to insert.
202 */
203 bool addEvent( Event *event );
204
205 /**
206 Deletes an event from this calendar.
207 */
208 bool deleteEvent( Event *event );
209
210 /**
211 Removes all Events from this calendar.
212 */
213 void deleteAllEvents();
214
215 /**
216 Retrieves an event on the basis of the unique string ID.
217 */
218 Event *event( const QString &UniqueStr );
219
220 /**
221 Return filtered list of all events in calendar.
222 */
223 Event::List events();
224
225 /**
226 Return unfiltered list of all events in calendar.
227 */
228 Event::List rawEvents( EventSortField sortField = EventSortUnsorted,
229 SortDirection sortDirection = SortDirectionAscending );
230
231 /**
232 Builds and then returns a list of all events that match for the
233 date specified. useful for dayView, etc. etc.
234
235 @param date date for which to get the events
236 @param timeSpec the time specification of the date
237 @param sortField field used as the sort key for the result list
238 @param sortDirection direction of sorting according to @p sortField
239 */
240 Event::List rawEventsForDate( const QDate &date,
241 const KDateTime::Spec &timeSpec = KDateTime::Spec(),
242 EventSortField sortField = EventSortUnsorted,
243 SortDirection sortDirection = SortDirectionAscending );
244
245 /**
246 Get unfiltered events for date @p dt.
247 */
248 Event::List rawEventsForDate( const KDateTime &dt );
249
250 /**
251 Get unfiltered events in a range of dates. If inclusive is set to true,
252 only events are returned, which are completely included in the range.
253
254 @param start date at the begin of the searching range
255 @param end date at the end of the searching range
256 @param timeSpec timeSpec of the searching range
257 @param inclusive if @c true, only match events which are completely within
258 the specified range
259 */
260 Event::List rawEvents( const QDate &start, const QDate &end,
261 const KDateTime::Spec &timeSpec = KDateTime::Spec(),
262 bool inclusive = false );
263
264 /**
265 Add a todo to the todolist.
266
267 @param todo is a pointer to the Todo to insert.
268 */
269 bool addTodo( Todo *todo );
270
271 /**
272 Remove a todo from the todolist.
273 */
274 bool deleteTodo( Todo * );
275
276 /**
277 Removes all todos from this calendar.
278 */
279 void deleteAllTodos();
280
281 /**
282 Searches todolist for an event with this unique string identifier,
283 returns a pointer or null.
284 */
285 Todo *todo( const QString &uid );
286
287 /**
288 Return list of all todos.
289 */
290 Todo::List rawTodos( TodoSortField sortField = TodoSortUnsorted,
291 SortDirection sortDirection = SortDirectionAscending );
292
293 /**
294 Returns list of todos due on the specified date.
295 */
296 Todo::List rawTodosForDate( const QDate &date );
297
298 /**
299 Add a Journal entry to calendar
300
301 @param journal is a pointer to the Journal to insert.
302 */
303 virtual KCAL_DEPRECATED bool addJournal( Journal *journal );
304
305 /**
306 Remove a Journal from the calendar
307 */
308 virtual bool deleteJournal( Journal * );
309
310 /**
311 Removes all Journals from this calendar.
312 */
313 virtual void deleteAllJournals();
314
315 /**
316 Return Journal with given unique id.
317 */
318 virtual Journal *journal( const QString &uid );
319
320 /**
321 Return list of all journals.
322 */
323 Journal::List rawJournals( JournalSortField sortField = JournalSortUnsorted,
324 SortDirection sortDirection = SortDirectionAscending );
325
326 /**
327 Return list of journals for the given date.
328 */
329 Journal::List rawJournalsForDate( const QDate &date );
330
331 /**
332 Return all alarms, which occur in the given time interval.
333 */
334 Alarm::List alarms( const KDateTime &from, const KDateTime &to );
335
336 /**
337 Return all alarms, which occur before given date.
338 */
339 Alarm::List alarmsTo( const KDateTime &to );
340
341 /**
342 Set the time specification (time zone, etc.).
343
344 @param timeSpec the time specification to set
345 @see timeSpec()
346 */
347 void setTimeSpec( const KDateTime::Spec &timeSpec );
348
349 /**
350 Get the viewing time specification (time zone etc.) for the calendar.
351
352 @return time specification
353 */
354 KDateTime::Spec timeSpec() const;
355
356 /**
357 Set id of timezone, e.g. "Europe/Berlin"
358
359 @param timeZoneId the identifier for the timezone
360 @see timeZoneId()
361 */
362 void setTimeZoneId( const QString &timeZoneId );
363
364 /**
365 Returns the viewing time zone ID for the resource.
366
367 @return the string containing the time zone ID, or empty string if the
368 viewing time specification is not a time zone.
369 */
370 QString timeZoneId() const;
371
372 /**
373 @copydoc
374 ResourceCalendar::shiftTimes()
375 */
376 virtual void shiftTimes( const KDateTime::Spec &oldSpec, const KDateTime::Spec &newSpec );
377
378 /**
379 Return the owner of the calendar's full name.
380 */
381 Person owner() const;
382
383 /**
384 Set the owner of the calendar. Should be owner's full name.
385 @param owner the person who owns this calendar resource
386 */
387 void setOwner( const Person &owner );
388
389 void enableChangeNotification();
390 void disableChangeNotification();
391
392 void clearChange( Incidence *incidence );
393 void clearChange( const QString &uid );
394
395 void clearChanges();
396
397 bool hasChanges() const;
398
399 Incidence::List allChanges() const;
400
401 Incidence::List addedIncidences() const;
402 Incidence::List changedIncidences() const;
403 Incidence::List deletedIncidences() const;
404
405 /**
406 Load the resource from the cache.
407 @return true if the cache file exists, false if not
408 */
409 bool loadFromCache();
410
411 /**
412 Save the resource back to the cache.
413 */
414 void saveToCache();
415
416 /**
417 Clear cache.
418 */
419 void clearCache();
420
421 void cleanUpEventCache( const KCal::Event::List &eventList );
422 void cleanUpTodoCache( const KCal::Todo::List &todoList );
423
424 /**
425 Returns a reference to the id mapper.
426 */
427 KRES::IdMapper &idMapper();
428
429 using QObject::event; // prevent warning about hidden virtual method
430
431 protected:
432 CalendarLocal *calendar() const;
433
434 // From Calendar::CalendarObserver
435 void calendarIncidenceAdded( KCal::Incidence *incidence );
436 void calendarIncidenceChanged( KCal::Incidence *incidence );
437 void calendarIncidenceDeleted( KCal::Incidence *incidence );
438
439 /**
440 Virtual method from KRES::Resource, called when the last instace of the
441 resource is closed
442 */
443 virtual void doClose();
444
445 /**
446 Opens the resource. Dummy implementation, so child classes don't have to
447 reimplement this method. By default, this does not do anything, but can be
448 reimplemented in child classes
449 */
450 virtual bool doOpen();
451
452 /**
453 Do the actual loading of the resource data. Called by load(CacheAction).
454 */
455 virtual bool doLoad( bool syncCache ) = 0;
456
457 /**
458 Set the cache-reloaded status. Non-local resources must set this true once
459 the cache has been downloaded successfully.
460
461 @param done the new cache-reloaded status
462 */
463 void setReloaded( bool done );
464
465 /**
466 Do the actual saving of the resource data. Called by save(CacheAction).
467 Saves the resource data to the cache and optionally uploads (if a remote
468 resource).
469
470 @param syncCache if true, the cache will be uploaded to the remote
471 resource. If false, only the cache will be updated.
472 */
473 virtual bool doSave( bool syncCache ) = 0;
474
475 /**
476 Do the actual saving of the resource data. Called by save(CacheAction).
477 Save one Incidence. The default implementation calls doSave(bool) to
478 save everything.
479
480 @param syncCache if @c true, the cache will be uploaded to the remote
481 resource. If @c false, only the cache will be updated
482 @param incidence The incidence to be saved.
483 */
484 virtual bool doSave( bool syncCache, Incidence *incidence );
485
486 /**
487 Check if reload required according to reload policy.
488 */
489 bool checkForReload();
490
491 /**
492 Check if save required according to save policy.
493 */
494 bool checkForSave();
495
496 void checkForAutomaticSave();
497
498 void addInfoText( QString & ) const;
499
500 void setupSaveTimer();
501 void setupReloadTimer();
502
503 /**
504 This method is used by loadFromCache() and saveToCache(), reimplement
505 it to change the location of the cache.
506 */
507 virtual QString cacheFile() const;
508
509 /**
510 Functions for keeping the changes persistent.
511 */
512 virtual QString changesCacheFile( const QString &type ) const;
513 void loadChangesCache( QMap<Incidence *, bool> &map, const QString &type );
514 void loadChangesCache();
515 void saveChangesCache( const QMap<Incidence *, bool> &map, const QString &type );
516 void saveChangesCache();
517
518 protected Q_SLOTS:
519 void slotReload();
520 void slotSave();
521
522 void setIdMapperIdentifier();
523
524 private:
525 //@cond PRIVATE
526 Q_DISABLE_COPY( ResourceCached )
527 class Private;
528 Private *const d;
529 //@endcond
530};
531
532}
533
534#endif
535