diff --git a/akonadi/filteractionjob.cpp b/akonadi/filteractionjob.cpp index c01197221..8111cb417 100644 --- a/akonadi/filteractionjob.cpp +++ b/akonadi/filteractionjob.cpp @@ -1,149 +1,142 @@ /* Copyright (c) 2009 Constantin Berzan This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #include "filteractionjob.h" #include "collection.h" #include "itemfetchjob.h" #include "itemfetchscope.h" #include "job_p.h" #include using namespace Akonadi; class Akonadi::FilterActionJob::Private { public: Private( FilterActionJob *qq ) : q( qq ) , functor( 0 ) { } ~Private() { delete functor; } FilterActionJob *q; Collection collection; Item::List items; FilterAction *functor; ItemFetchScope fetchScope; // slots: void fetchResult( KJob *job ); void traverseItems(); }; void FilterActionJob::Private::fetchResult( KJob *job ) { if ( job->error() ) { // KCompositeJob takes care of errors. return; } ItemFetchJob *fjob = dynamic_cast( job ); Q_ASSERT( fjob ); Q_ASSERT( items.isEmpty() ); items = fjob->items(); traverseItems(); } void FilterActionJob::Private::traverseItems() { Q_ASSERT( functor ); kDebug() << "Traversing" << items.count() << "items."; foreach( const Item &item, items ) { if( functor->itemAccepted( item ) ) { q->addSubjob( functor->itemAction( item ) ); kDebug() << "Added subjob for item" << item.id(); } } if( q->subjobs().isEmpty() ) { kDebug() << "No subjobs; I am done."; q->emitResult(); } else { kDebug() << "Have subjobs; calling commit()."; q->commit(); } } FilterAction::~FilterAction() { } FilterActionJob::FilterActionJob( const Item &item, FilterAction *functor, QObject *parent ) : TransactionSequence( parent ) , d( new Private( this ) ) { d->functor = functor; d->items << item; } FilterActionJob::FilterActionJob( const Item::List &items, FilterAction *functor, QObject *parent ) : TransactionSequence( parent ) , d( new Private( this ) ) { d->functor = functor; d->items = items; } FilterActionJob::FilterActionJob( const Collection &collection, FilterAction *functor, QObject *parent ) : TransactionSequence( parent ) , d( new Private( this ) ) { d->functor = functor; Q_ASSERT( collection.isValid() ); d->collection = collection; } FilterActionJob::~FilterActionJob() { delete d; } -#if 0 -Item::List FilterActionJob::items() -{ - return d->items; -} -#endif - void FilterActionJob::doStart() { if( d->collection.isValid() ) { kDebug() << "Fetching collection" << d->collection.id(); ItemFetchJob *fjob = new ItemFetchJob( d->collection, this ); Q_ASSERT( d->functor ); d->fetchScope = d->functor->fetchScope(); fjob->setFetchScope( d->fetchScope ); connect( fjob, SIGNAL(result(KJob*)), this, SLOT(fetchResult(KJob*)) ); } else { d->traverseItems(); } } #include "filteractionjob.moc" diff --git a/akonadi/filteractionjob.h b/akonadi/filteractionjob.h index 26b643f5d..4a07ad7ac 100644 --- a/akonadi/filteractionjob.h +++ b/akonadi/filteractionjob.h @@ -1,96 +1,173 @@ /* Copyright (c) 2009 Constantin Berzan This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef AKONADI_FILTERACTIONJOB_H #define AKONADI_FILTERACTIONJOB_H #include "item.h" #include "transactionsequence.h" namespace Akonadi { class Collection; class ItemFetchScope; class Job; /** - Abstract functor for a FilterActionJob. Subclass it and implement the virtual - methods. - - // TODO docu - - // TODO example + @short Base class for a filter/action for FilterActionJob. + + Abstract class defining an interface for a filter and an action for + FilterActionJob. The virtual methods must be implemented in subclasses. + + @code + class ClearErrorAction : public Akonadi::FilterAction + { + public: + // reimpl + virtual Akonadi::ItemFetchScope fetchScope() const + { + ItemFetchScope scope; + scope.fetchFullPayload( false ); + scope.fetchAttribute(); + return scope; + } + + virtual bool itemAccepted( const Akonadi::Item &item ) const + { + return item.hasAttribute(); + } + + virtual Akonadi::Job *itemAction( const Akonadi::Item &item ) const + { + Item cp = item; + cp.removeAttribute(); + return new ItemModifyJob( cp ); + } + }; + @endcode + + @see FilterActionJob + + @author Constantin Berzan + @since 4.4 */ class AKONADI_EXPORT FilterAction { public: - /// only used if FilterActionJob created with collection constructor + /** + Destroys this FilterAction. + A FilterActionJob will delete its FilterAction automatically. + */ + virtual ~FilterAction(); + + /** + Returns an ItemFetchScope to use if the FilterActionJob needs to fetch + the items from a collection. + Note that the items are not fetched unless FilterActionJob is + constructed with a Collection parameter. + */ virtual Akonadi::ItemFetchScope fetchScope() const = 0; + + /** + Returns true if the @p item is accepted by the filter and should be + acted upon by the FilterActionJob. + */ virtual bool itemAccepted( const Akonadi::Item &item ) const = 0; + + /** + Returns a job to act on the @p item. + The FilterActionJob will finish when all such jobs are finished. + */ virtual Akonadi::Job *itemAction( const Akonadi::Item &item ) const = 0; - virtual ~FilterAction(); }; + /** - A job to filter and apply an action on a set of items. The filter and action - are provided by a functor derived from FilterAction. + @short Job to filter and apply an action on a set of items. + + This jobs filters through a set of items, and applies an action to the + items which are accepted by the filter. The filter and action + are provided by a functor class derived from FilterAction. + + For example, a MarkAsRead action/filter may be used to mark all messages + in a folder as read. + + @code + FilterActionJob *mjob = new FilterActionJob( LocalFolders::self()->outbox(), + new ClearErrorAction, this ); + connect( mjob, SIGNAL(result(KJob*)), this, SLOT(massModifyResult(KJob*)) ); + @endcode - // TODO docu + @see FilterAction - // TODO example + @author Constantin Berzan + @since 4.4 */ class AKONADI_EXPORT FilterActionJob : public TransactionSequence { Q_OBJECT public: + /** + Creates a FilterActionJob to act on a single item. + + @param item The item to act on. The item is not re-fetched. + @param functor The FilterAction to use. + */ FilterActionJob( const Item &item, FilterAction *functor, QObject *parent = 0 ); + + /** + Creates a FilterActionJob to act on a set of items. + + @param items The items to act on. The items are not re-fetched. + @param functor The FilterAction to use. + */ FilterActionJob( const Item::List &items, FilterAction *functor, QObject *parent = 0 ); - FilterActionJob( const Collection &collection, FilterAction *functor, QObject *parent = 0 ); - ~FilterActionJob(); - // TODO I would like to provide a list of modified items, but there is no - // easy way to get those, because FilterAction::itemAction() can return any - // kind of Job, not only an ItemModifyJob. - // Restrict it to modify jobs only? - // Re-fetch the accepted items after all jobs are done? - //Item::List items() const; + /** + Creates a FilterActionJob to act on items in a collection. - // TODO provide setFunctor? + @param items The items to act on. The items are fetched using functor->fetchScope(). + @param functor The FilterAction to use. + */ + FilterActionJob( const Collection &collection, FilterAction *functor, QObject *parent = 0 ); - // TODO provide forceFetch for the Item and Item::List constructors? + /** + Destroys this FilterActionJob. + This job autodeletes itself. + */ + ~FilterActionJob(); protected: + /* reimpl */ virtual void doStart(); private: //@cond PRIVATE class Private; Private *const d; Q_PRIVATE_SLOT( d, void fetchResult( KJob* ) ) //@endcond }; -} - - -#endif +} // namespace Akonadi +#endif // AKONADI_FILTERACTIONJOB_H