Diffstat (limited to 'libopie2/opiepim/backend/opimaccessbackend.h') (more/less context) (show whitespace changes)
-rw-r--r-- | libopie2/opiepim/backend/opimaccessbackend.h | 361 |
1 files changed, 294 insertions, 67 deletions
diff --git a/libopie2/opiepim/backend/opimaccessbackend.h b/libopie2/opiepim/backend/opimaccessbackend.h index 26af762..0d112c9 100644 --- a/libopie2/opiepim/backend/opimaccessbackend.h +++ b/libopie2/opiepim/backend/opimaccessbackend.h | |||
@@ -31,115 +31,85 @@ | |||
31 | 31 | ||
32 | #include <qarray.h> | 32 | #include <qarray.h> |
33 | #include <qdatetime.h> | 33 | #include <qdatetime.h> |
34 | 34 | ||
35 | #include <opie2/opimtemplatebase.h> | 35 | #include <opie2/opimtemplatebase.h> |
36 | #include <opie2/opimrecord.h> | 36 | #include <opie2/opimrecord.h> |
37 | 37 | #include <opie2/opimbackendoccurrence.h> | |
38 | 38 | ||
39 | namespace Opie { | 39 | namespace Opie { |
40 | class OPimAccessBackendPrivate; | 40 | class OPimAccessBackendPrivate; |
41 | |||
41 | /** | 42 | /** |
42 | * OPimAccessBackend is the base class | 43 | * OPimAccessBackend is the Backend Interface to be used |
43 | * for all private backends | 44 | * by OTemplateBase based Frontends. |
44 | * it operates on OPimRecord as the base class | 45 | * For efficency reasons and to support delayed loading |
45 | * and it's responsible for fast manipulating | 46 | * most of the Frontend functions can be implemented |
46 | * the resource the implementation takes care | 47 | * by this backend. |
47 | * of | 48 | * This allows to utilise the best method on each backend. |
49 | * For example we can use SQL queries instead of self made | ||
50 | * query which is first more efficent and also uses less memory. | ||
48 | */ | 51 | */ |
49 | template <class T = OPimRecord> | 52 | template <class T = OPimRecord> |
50 | class OPimAccessBackend { | 53 | class OPimAccessBackend { |
51 | public: | 54 | public: |
52 | typedef OTemplateBase<T> Frontend; | 55 | typedef OTemplateBase<T> Frontend; |
53 | 56 | ||
54 | /** The access hint from the frontend */ | 57 | //@{ |
55 | OPimAccessBackend(int access = 0); | 58 | OPimAccessBackend(int access = 0); |
56 | virtual ~OPimAccessBackend(); | 59 | virtual ~OPimAccessBackend(); |
60 | //@} | ||
57 | 61 | ||
58 | /** | 62 | //@{ |
59 | * load the resource | ||
60 | */ | ||
61 | virtual bool load() = 0; | 63 | virtual bool load() = 0; |
62 | |||
63 | /** | ||
64 | * reload the resource | ||
65 | */ | ||
66 | virtual bool reload() = 0; | 64 | virtual bool reload() = 0; |
67 | |||
68 | /** | ||
69 | * save the resource and | ||
70 | * all it's changes | ||
71 | */ | ||
72 | virtual bool save() = 0; | 65 | virtual bool save() = 0; |
66 | virtual void clear() = 0; | ||
67 | //@} | ||
73 | 68 | ||
74 | /** | ||
75 | * return an array of | ||
76 | * all available uids | ||
77 | */ | ||
78 | virtual QArray<int> allRecords()const = 0; | ||
79 | |||
80 | /** | ||
81 | * return a List of records | ||
82 | * that match the regex | ||
83 | */ | ||
84 | virtual QArray<int> matchRegexp(const QRegExp &r) const = 0; | ||
85 | 69 | ||
86 | /** | 70 | //@{ |
87 | * queryByExample for T with the given Settings | 71 | virtual UIDArray allRecords()const = 0; |
88 | * | 72 | virtual UIDArray matchRegexp(const QRegExp &r) const; |
89 | */ | 73 | virtual UIDArray queryByExample( const T& t, int settings, const QDateTime& d = QDateTime() )const = 0; |
90 | virtual QArray<int> queryByExample( const T& t, int settings, const QDateTime& d = QDateTime() ) = 0; | 74 | virtual UIDArray queryByExample( const OPimRecord* rec, int, const QDateTime& d = QDateTime() )const; |
75 | virtual UIDArray sorted( const UIDArray&, bool asc, int sortOrder, int sortFilter, const QArray<int>& cats )const; | ||
76 | virtual UIDArray sorted( bool asc, int sortOrder, int sortFilter, const QArray<int>& cats )const; | ||
77 | virtual OPimBackendOccurrence::List occurrences( const QDate& start, const QDate& end)const; | ||
78 | virtual OPimBackendOccurrence::List occurrences( const QDateTime& dt )const; | ||
79 | //@} | ||
91 | 80 | ||
92 | /** | ||
93 | * find the OPimRecord with uid @param uid | ||
94 | * returns T and T.isEmpty() if nothing was found | ||
95 | */ | ||
96 | virtual T find( int uid )const = 0; | ||
97 | 81 | ||
98 | virtual T find( int uid, const QArray<int>& items, | 82 | //@{ |
83 | virtual T find(UID uid )const = 0; | ||
84 | virtual T find(UID uid, const QArray<UID>& items, | ||
99 | uint current, typename Frontend::CacheDirection ) const; | 85 | uint current, typename Frontend::CacheDirection ) const; |
100 | /** | 86 | //@} |
101 | * clear the back end | ||
102 | */ | ||
103 | virtual void clear() = 0; | ||
104 | 87 | ||
105 | /** | 88 | |
106 | * add T | 89 | //@{ |
107 | */ | ||
108 | virtual bool add( const T& t ) = 0; | 90 | virtual bool add( const T& t ) = 0; |
91 | virtual bool remove( UID uid ) = 0; | ||
92 | virtual bool replace( const T& t ) = 0; | ||
93 | //@} | ||
109 | 94 | ||
110 | /** | ||
111 | * remove | ||
112 | */ | ||
113 | virtual bool remove( int uid ) = 0; | ||
114 | 95 | ||
115 | /** | ||
116 | * replace a record with T.uid() | ||
117 | */ | ||
118 | virtual bool replace( const T& t ) = 0; | ||
119 | 96 | ||
120 | /* | ||
121 | * setTheFrontEnd!!! | ||
122 | */ | ||
123 | void setFrontend( Frontend* front ); | 97 | void setFrontend( Frontend* front ); |
124 | 98 | ||
125 | /** | 99 | /** |
126 | * set the read ahead count | 100 | * set the read ahead count |
127 | */ | 101 | */ |
128 | void setReadAhead( uint count ); | 102 | void setReadAhead( uint count ); |
129 | protected: | 103 | protected: |
104 | //@{ | ||
130 | int access()const; | 105 | int access()const; |
131 | |||
132 | void cache( const T& t )const; | 106 | void cache( const T& t )const; |
133 | |||
134 | /** | ||
135 | * use a prime number here! | ||
136 | */ | ||
137 | void setSaneCacheSize( int ); | 107 | void setSaneCacheSize( int ); |
138 | |||
139 | uint readAhead()const; | 108 | uint readAhead()const; |
109 | //@} | ||
140 | 110 | ||
141 | private: | 111 | private: |
142 | OPimAccessBackendPrivate *d; | 112 | OPimAccessBackendPrivate *d; |
143 | Frontend* m_front; | 113 | Frontend* m_front; |
144 | uint m_read; | 114 | uint m_read; |
145 | int m_acc; | 115 | int m_acc; |
@@ -153,23 +123,80 @@ OPimAccessBackend<T>::OPimAccessBackend(int acc) | |||
153 | m_front = 0l; | 123 | m_front = 0l; |
154 | } | 124 | } |
155 | template <class T> | 125 | template <class T> |
156 | OPimAccessBackend<T>::~OPimAccessBackend() { | 126 | OPimAccessBackend<T>::~OPimAccessBackend() { |
157 | 127 | ||
158 | } | 128 | } |
129 | |||
130 | /* | ||
131 | * Slow but default matchRegexp Implementation | ||
132 | * Create a Big Enough QArray and then iterate | ||
133 | * over all Records and matchRegexp them. | ||
134 | * At the end we will resize the array to the actual | ||
135 | * number of items | ||
136 | */ | ||
137 | template <class T> | ||
138 | UIDArray OPimAccessBackend<T>::matchRegexp( const QRegExp& reg )const { | ||
139 | UIDArray all_rec = allRecords(); | ||
140 | UIDArray result( all_rec.count() ); | ||
141 | uint used_records = 0, all_rec_count = all_rec.count(); | ||
142 | |||
143 | for ( uint i = 0; i < all_rec_count; ++i ) | ||
144 | if (find( all_rec[i], all_rec, i, Frontend::Forward ).match( reg ) ) | ||
145 | result[used_records++] = all_rec[i]; | ||
146 | |||
147 | /* shrink to fit */ | ||
148 | result.resize( used_records ); | ||
149 | return result; | ||
150 | } | ||
151 | |||
152 | template <class T> | ||
153 | UIDArray OPimAccessBackend<T>::queryByExample( const OPimRecord* rec, int settings, | ||
154 | const QDateTime& datetime )const { | ||
155 | T* tmp_rec = T::safeCast( rec ); | ||
156 | UIDArray ar; | ||
157 | if ( tmp_rec ) | ||
158 | ar = queryByExample( *tmp_rec, settings, datetime ); | ||
159 | |||
160 | return ar; | ||
161 | } | ||
162 | |||
163 | template <class T> | ||
164 | UIDArray OPimAccessBackend<T>::sorted( const UIDArray& ids, bool, | ||
165 | int, int, const QArray<int>& ) const { | ||
166 | return ids; | ||
167 | } | ||
168 | |||
169 | template <class T> | ||
170 | UIDArray OPimAccessBackend<T>::sorted( bool asc, int order, int filter, | ||
171 | const QArray<int>& cats )const { | ||
172 | return sorted( allRecords(), asc, order, filter, cats ); | ||
173 | } | ||
174 | |||
175 | template<class T> | ||
176 | OPimBackendOccurrence::List OPimAccessBackend<T>::occurrences( const QDate&, | ||
177 | const QDate& )const { | ||
178 | return OPimBackendOccurrence::List(); | ||
179 | } | ||
180 | |||
181 | template<class T> | ||
182 | OPimBackendOccurrence::List OPimAccessBackend<T>::occurrences( const QDateTime& dt )const { | ||
183 | QDate date = dt.date(); | ||
184 | return occurrences( date, date ); | ||
185 | } | ||
186 | |||
159 | template <class T> | 187 | template <class T> |
160 | void OPimAccessBackend<T>::setFrontend( Frontend* fr ) { | 188 | void OPimAccessBackend<T>::setFrontend( Frontend* fr ) { |
161 | m_front = fr; | 189 | m_front = fr; |
162 | } | 190 | } |
163 | template <class T> | 191 | template <class T> |
164 | void OPimAccessBackend<T>::cache( const T& t )const { | 192 | void OPimAccessBackend<T>::cache( const T& t )const { |
165 | if ( m_front ) | 193 | if ( m_front ) |
166 | m_front->cache( t ); | 194 | m_front->cache( t ); |
167 | } | 195 | } |
168 | 196 | ||
169 | |||
170 | template <class T> | 197 | template <class T> |
171 | void OPimAccessBackend<T>::setSaneCacheSize( int size) { | 198 | void OPimAccessBackend<T>::setSaneCacheSize( int size) { |
172 | if ( m_front ) | 199 | if ( m_front ) |
173 | m_front->setSaneCacheSize( size ); | 200 | m_front->setSaneCacheSize( size ); |
174 | } | 201 | } |
175 | template <class T> | 202 | template <class T> |
@@ -190,7 +217,207 @@ template <class T> | |||
190 | int OPimAccessBackend<T>::access()const { | 217 | int OPimAccessBackend<T>::access()const { |
191 | return m_acc; | 218 | return m_acc; |
192 | } | 219 | } |
193 | 220 | ||
194 | } | 221 | } |
195 | 222 | ||
223 | /** | ||
224 | * \fn template <class T> OPimAccessBackend<T>::OPimAccessBackend(int hint ) | ||
225 | * @param hint The access hint from the frontend | ||
226 | */ | ||
227 | |||
228 | /** | ||
229 | * \fn template <class T> bool OPimAccessBackend<T>::load() | ||
230 | * Opens the DataBase and does necessary | ||
231 | * initialisation of internal structures. | ||
232 | * | ||
233 | * @return true If the DataBase could be opened and | ||
234 | * Information was successfully loaded | ||
235 | */ | ||
236 | |||
237 | /** | ||
238 | * \fn template <class T> bool OPimAccessBackend<T>::reload() | ||
239 | * Reinitialise the DataBase and merges the external changes | ||
240 | * with your local changes. | ||
241 | * | ||
242 | * @return True if the DataBase was reloaded. | ||
243 | * | ||
244 | */ | ||
245 | |||
246 | /** | ||
247 | * \fn template <class T> bool OPimAccessBackend<T>::save() | ||
248 | * | ||
249 | * Save the changes to storage. In case of memory or | ||
250 | * disk shortage, return false. | ||
251 | * | ||
252 | * | ||
253 | * @return True if the DataBase could be saved to storage. | ||
254 | */ | ||
255 | |||
256 | /** | ||
257 | * \fn template <class T> bool OPimAccessBackend<T>::clear() | ||
258 | * Until a \sa save() changes shouldn't be comitted | ||
259 | * | ||
260 | * | ||
261 | * @return True if the DataBase could be cleared | ||
262 | * @todo Introduce a 'Commit' | ||
263 | */ | ||
264 | |||
265 | /** | ||
266 | * \fn template <class T> QArray<UID> OPimAccessBackend<T>::allRecords()const | ||
267 | * Return an array of all available uids in the loaded | ||
268 | * DataBase. | ||
269 | * @see load | ||
270 | */ | ||
271 | |||
272 | /** | ||
273 | * \fn template <class T> QArray<UID> OPimAccessBackend<T>::matchRegexp(const QRegExp& r)const | ||
274 | * Return a List of records that match the regex \par r. | ||
275 | * | ||
276 | * @param r The QRegExp to match. | ||
277 | */ | ||
278 | |||
279 | /** | ||
280 | * \fn template <class T> QArray<UID> OPimAccessBackend<T>::queryByExample(const T& t, int settings, const QDateTime& d = QDateTime() ) | ||
281 | * | ||
282 | * Implement QueryByExample. An Example record is filled and with the | ||
283 | * settings and QDateTime it is determined how the query should be executed. | ||
284 | * Return a list of UIDs that match the Example | ||
285 | * | ||
286 | * @param t The Example record | ||
287 | * @param settings Gives | ||
288 | * | ||
289 | */ | ||
290 | |||
291 | /** | ||
292 | * \fn template<class T> QArray<UID> OPimAccessBackend<T>::sorted(const QArray<UID>& ids, bool asc, int sortOrder, int sortFilter, int cat) | ||
293 | * \brief Sort the List of records according to the preference | ||
294 | * | ||
295 | * Implement sorting in your backend. The default implementation is | ||
296 | * to return the list as it was passed. | ||
297 | * The default Backend Implementation should do unaccelerated filtering | ||
298 | * | ||
299 | * | ||
300 | * @param ids The Records to sort | ||
301 | * @param asc Sort ascending or descending | ||
302 | * @param sortOrder | ||
303 | * @param sortFilter Sort filter | ||
304 | * @param cat The Category to include | ||
305 | */ | ||
306 | |||
307 | /** | ||
308 | * \fn template <class T> T OPimAccessBackend<T>::find(UID uid)const | ||
309 | * \brief Find the Record with the UID | ||
310 | * | ||
311 | * Find the UID in the database and return the record. | ||
312 | * @param uid The uid to be searched for | ||
313 | * @return The record or an empty record (T.isEmpty()) | ||
314 | * | ||
315 | */ | ||
316 | |||
317 | /** | ||
318 | * \fn template <class T> T OPimAccessBackend<T>::find( UID uid, const QArray<UID>& items, uint current, typename Frontend::CacheDirection d)const | ||
319 | * \brief find a Record and do a read ahead or read behind | ||
320 | * | ||
321 | * @param uid The UID to search for | ||
322 | * @param items The list of items from where your search | ||
323 | * @param current The index of \param uid | ||
324 | * @param d The direction to search for | ||
325 | * | ||
326 | * @see find | ||
327 | */ | ||
328 | |||
329 | |||
330 | /** | ||
331 | * \fn template<class T> bool OPimAccessBackend<T>::add(const T& t) | ||
332 | * | ||
333 | * \brief Add the record to the internal database | ||
334 | * | ||
335 | * If an record with the same t.uid() is already present internally | ||
336 | * the behaviour is undefined but the state of the database | ||
337 | * needs to be stable. | ||
338 | * For modifying a record use \sa replace. | ||
339 | * | ||
340 | * | ||
341 | * @return true if the record could be added or false if not | ||
342 | * @todo Eilers your opinion on readd/replace | ||
343 | */ | ||
344 | |||
345 | /** | ||
346 | * \fn template<class T> bool OPimAccessBackend<T>::remove(UID uid) | ||
347 | * \brief Remove a record by its UID | ||
348 | * | ||
349 | * Remove the records with UID from the internal Database. | ||
350 | * | ||
351 | * @return True if the record could be removed. | ||
352 | * | ||
353 | */ | ||
354 | |||
355 | /** | ||
356 | * \fn template<class T> bool OPimAccessBackend<T>::replace(const T& t) | ||
357 | * \brief Take this Record and replace the old version. | ||
358 | * | ||
359 | * Take \param t as the new record for t.uid(). It is not described | ||
360 | * what happens if the record is not present in the database. | ||
361 | * Normally the record is determined by the UID. | ||
362 | * | ||
363 | * @param t The record to use internally. | ||
364 | */ | ||
365 | |||
366 | /** | ||
367 | * \fn template<class T> void OPimAccessBackend<T>::setFrontend( Frontend* fron) | ||
368 | * \@aram fron The Frontend that uses this backend | ||
369 | * | ||
370 | * This function is called by the frontend and is used | ||
371 | */ | ||
372 | |||
373 | /** | ||
374 | * \fn template<class T> void OPimAccessBackend<T>::setReadAhead(uint count) | ||
375 | * \brief Set the number of items to Read-Ahead/Read-Behind | ||
376 | * | ||
377 | * @param count The number of records to read ahead | ||
378 | */ | ||
379 | |||
380 | /** | ||
381 | * \fn template<class T> void OPimAccessBackend<T>::cache( const T& t)const | ||
382 | * \brief Add the Record to the PIM Cache | ||
383 | * | ||
384 | * This will add the Record to the PIM cache, which is owned | ||
385 | * by the FrontEnd. If no FrontEnd is available the item will | ||
386 | * not be cached. | ||
387 | * | ||
388 | * | ||
389 | * @param t The Item to be added to the Cache | ||
390 | */ | ||
391 | |||
392 | /** | ||
393 | * \fn template<class T> void OPimAccessBackend<T>::setSaneCacheSize(int items) | ||
394 | * \brief Give a hint on the number of too cached items | ||
395 | * | ||
396 | * Give the Frontend a hint on the number of items to be cached. Use | ||
397 | * a prime number for best performance. | ||
398 | * | ||
399 | * @param items The number of items to be cached | ||
400 | */ | ||
401 | |||
402 | /** | ||
403 | * \fn template<class T> uint OPimAccessBackend<T>::readAhead()const | ||
404 | * \brief Return the number of Items to be ReadAhead | ||
405 | * | ||
406 | * @return The number of Items to read ahead/read behind | ||
407 | */ | ||
408 | |||
409 | /** | ||
410 | * \fn template<class T> QArray<OPimBackendOccurence> OPimAccessBackend<T>::occurrences(const QDateTime& start,const QDateTime& end) | ||
411 | * \brief Get a List of Occurrences for a period of time | ||
412 | * | ||
413 | * Return an Array of OPimBackendOccurence for a period of time. If start == end date | ||
414 | * return only occurrences for the start date. If end is smaller the start date | ||
415 | * the result is not defined. You could switch dates or return an empty list. | ||
416 | * | ||
417 | * @return Return an array of OPimBackendOccurence for the period specified by the parameters | ||
418 | * @param start The start of the period. | ||
419 | * @param end The end of the period. | ||
420 | * | ||
421 | */ | ||
422 | |||
196 | #endif | 423 | #endif |