1/*
2 Copyright (c) 2009 Constantin Berzan <exit3219@gmail.com>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef MAILTRANSPORT_FILTERACTIONJOB_P_H
21#define MAILTRANSPORT_FILTERACTIONJOB_P_H
22
23#include <mailtransport/mailtransport_export.h>
24
25#include <akonadi/item.h>
26#include <akonadi/transactionsequence.h>
27
28namespace Akonadi {
29
30class Collection;
31class ItemFetchScope;
32class Job;
33
34class FilterActionJob;
35
36/**
37 * @short Base class for a filter/action for FilterActionJob.
38 *
39 * Abstract class defining an interface for a filter and an action for
40 * FilterActionJob. The virtual methods must be implemented in subclasses.
41 *
42 * @code
43 * class ClearErrorAction : public Akonadi::FilterAction
44 * {
45 * public:
46 * // reimpl
47 * virtual Akonadi::ItemFetchScope fetchScope() const
48 * {
49 * ItemFetchScope scope;
50 * scope.fetchFullPayload( false );
51 * scope.fetchAttribute<ErrorAttribute>();
52 * return scope;
53 * }
54 *
55 * virtual bool itemAccepted( const Akonadi::Item &item ) const
56 * {
57 * return item.hasAttribute<ErrorAttribute>();
58 * }
59 *
60 * virtual Akonadi::Job *itemAction( const Akonadi::Item &item,
61 * Akonadi::FilterActionJob *parent ) const
62 * {
63 * Item cp = item;
64 * cp.removeAttribute<ErrorAttribute>();
65 * return new ItemModifyJob( cp, parent );
66 * }
67 * };
68 * @endcode
69 *
70 * @see FilterActionJob
71 *
72 * @author Constantin Berzan <exit3219@gmail.com>
73 * @since 4.4
74 */
75class MAILTRANSPORT_EXPORT FilterAction
76{
77 public:
78 /**
79 * Destroys this filter action.
80 *
81 * A FilterActionJob will delete its FilterAction automatically.
82 */
83 virtual ~FilterAction();
84
85 /**
86 * Returns an ItemFetchScope to use if the FilterActionJob needs
87 * to fetch the items from a collection.
88 *
89 * @note The items are not fetched unless FilterActionJob is
90 * constructed with a Collection parameter.
91 */
92 virtual Akonadi::ItemFetchScope fetchScope() const = 0;
93
94 /**
95 * Returns @c true if the @p item is accepted by the filter and should be
96 * acted upon by the FilterActionJob.
97 */
98 virtual bool itemAccepted( const Akonadi::Item &item ) const = 0;
99
100 /**
101 * Returns a job to act on the @p item.
102 * The FilterActionJob will finish when all such jobs are finished.
103 * @param item the item to work on
104 * @param parent the parent job
105 */
106 virtual Akonadi::Job *itemAction( const Akonadi::Item &item,
107 Akonadi::FilterActionJob *parent ) const = 0;
108};
109
110/**
111 * @short Job to filter and apply an action on a set of items.
112 *
113 * This jobs filters through a set of items, and applies an action to the
114 * items which are accepted by the filter. The filter and action
115 * are provided by a functor class derived from FilterAction.
116 *
117 * For example, a MarkAsRead action/filter may be used to mark all messages
118 * in a folder as read.
119 *
120 * @code
121 * FilterActionJob *mjob = new FilterActionJob( LocalFolders::self()->outbox(),
122 * new ClearErrorAction, this );
123 * connect( mjob, SIGNAL( result( KJob* ) ), this, SLOT( massModifyResult( KJob* ) ) );
124 * @endcode
125 *
126 * @see FilterAction
127 *
128 * @author Constantin Berzan <exit3219@gmail.com>
129 * @since 4.4
130 */
131class MAILTRANSPORT_EXPORT FilterActionJob : public TransactionSequence
132{
133 Q_OBJECT
134
135 public:
136 /**
137 * Creates a filter action job to act on a single item.
138 *
139 * @param item The item to act on. The item is not re-fetched.
140 * @param functor The FilterAction to use.
141 * @param parent The parent object.
142 */
143 FilterActionJob( const Item &item, FilterAction *functor, QObject *parent = 0 );
144
145 /**
146 * Creates a filter action job to act on a set of items.
147 *
148 * @param items The items to act on. The items are not re-fetched.
149 * @param functor The FilterAction to use.
150 * @param parent The parent object.
151 */
152 FilterActionJob( const Item::List &items, FilterAction *functor, QObject *parent = 0 );
153
154 /**
155 * Creates a filter action job to act on items in a collection.
156 *
157 * @param collection The collection to act on.
158 * The items of the collection are fetched using functor->fetchScope().
159 * @param functor The FilterAction to use.
160 * @param parent The parent object.
161 */
162 FilterActionJob( const Collection &collection, FilterAction *functor, QObject *parent = 0 );
163
164 /**
165 * Destroys the filter action job.
166 */
167 ~FilterActionJob();
168
169 protected:
170 /* reimpl */
171 virtual void doStart();
172
173 private:
174 //@cond PRIVATE
175 class Private;
176 Private *const d;
177
178 Q_PRIVATE_SLOT( d, void fetchResult( KJob* ) )
179 //@endcond
180};
181
182} // namespace Akonadi
183
184#endif // AKONADI_FILTERACTIONJOB_H
185