Folder.java revision 90660b081cb9eafd333c31ef58bd85f86d485152 
1/*
2 * Copyright (C) 2008 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package com.android.emailcommon.mail;
18
19import com.android.emailcommon.service.SearchParams;
20import com.google.common.annotations.VisibleForTesting;
21
22
23public abstract class Folder {
24    public enum OpenMode {
25        READ_WRITE, READ_ONLY,
26    }
27
28    public enum FolderType {
29        HOLDS_FOLDERS, HOLDS_MESSAGES,
30    }
31
32    /**
33     * Identifiers of "special" folders.
34     */
35    public enum FolderRole {
36        INBOX,      // NOTE:  The folder's name must be INBOX
37        TRASH,
38        SENT,
39        DRAFTS,
40
41        OUTBOX,     // Local folders only - not used in remote Stores
42        OTHER,      // this folder has no specific role
43        UNKNOWN     // the role of this folder is unknown
44    }
45
46    /**
47     * Callback for each message retrieval.
48     *
49     * Not all {@link Folder} implementations may invoke it.
50     */
51    public interface MessageRetrievalListener {
52        public void messageRetrieved(Message message);
53        public void loadAttachmentProgress(int progress);
54    }
55
56    /**
57     * Forces an open of the MailProvider. If the provider is already open this
58     * function returns without doing anything.
59     *
60     * @param mode READ_ONLY or READ_WRITE
61     * @param callbacks Pointer to callbacks class.  This may be used by the folder between this
62     * time and when close() is called.  This is only used for remote stores - should be null
63     * for LocalStore.LocalFolder.
64     */
65    public abstract void open(OpenMode mode)
66            throws MessagingException;
67
68    /**
69     * Forces a close of the MailProvider. Any further access will attempt to
70     * reopen the MailProvider.
71     *
72     * @param expunge If true all deleted messages will be expunged.
73     */
74    public abstract void close(boolean expunge);
75
76    /**
77     * @return True if further commands are not expected to have to open the
78     *         connection.
79     */
80    @VisibleForTesting
81    public abstract boolean isOpen();
82
83    /**
84     * Returns the mode the folder was opened with. This may be different than the mode the open
85     * was requested with.
86     */
87    public abstract OpenMode getMode() throws MessagingException;
88
89    /**
90     * Reports if the Store is able to create folders of the given type.
91     * Does not actually attempt to create a folder.
92     * @param type
93     * @return true if can create, false if cannot create
94     */
95    public abstract boolean canCreate(FolderType type);
96
97    /**
98     * Attempt to create the given folder remotely using the given type.
99     * @return true if created, false if cannot create (e.g. server side)
100     */
101    public abstract boolean create(FolderType type) throws MessagingException;
102
103    public abstract boolean exists() throws MessagingException;
104
105    /**
106     * Returns the number of messages in the selected folder.
107     */
108    public abstract int getMessageCount() throws MessagingException;
109
110    public abstract int getUnreadMessageCount() throws MessagingException;
111
112    public abstract Message getMessage(String uid) throws MessagingException;
113
114    /**
115     * Fetches the given list of messages. The specified listener is notified as
116     * each fetch completes. Messages are downloaded as (as) lightweight (as
117     * possible) objects to be filled in with later requests. In most cases this
118     * means that only the UID is downloaded.
119     */
120    public abstract Message[] getMessages(int start, int end, MessageRetrievalListener listener)
121            throws MessagingException;
122
123    public abstract Message[] getMessages(long startDate, long endDate, MessageRetrievalListener listener)
124            throws MessagingException;
125
126    public abstract Message[] getMessages(SearchParams params,MessageRetrievalListener listener)
127            throws MessagingException;
128
129    public abstract Message[] getMessages(String[] uids, MessageRetrievalListener listener)
130            throws MessagingException;
131
132    /**
133     * Return a set of messages based on the state of the flags.
134     * Note: Not typically implemented in remote stores, so not abstract.
135     *
136     * @param setFlags The flags that should be set for a message to be selected (can be null)
137     * @param clearFlags The flags that should be clear for a message to be selected (can be null)
138     * @param listener
139     * @return A list of messages matching the desired flag states.
140     * @throws MessagingException
141     */
142    public Message[] getMessages(Flag[] setFlags, Flag[] clearFlags,
143            MessageRetrievalListener listener) throws MessagingException {
144        throw new MessagingException("Not implemented");
145    }
146
147    public abstract void appendMessages(Message[] messages) throws MessagingException;
148
149    /**
150     * Copies the given messages to the destination folder.
151     */
152    public abstract void copyMessages(Message[] msgs, Folder folder,
153            MessageUpdateCallbacks callbacks) throws MessagingException;
154
155    public abstract void setFlags(Message[] messages, Flag[] flags, boolean value)
156            throws MessagingException;
157
158    public abstract Message[] expunge() throws MessagingException;
159
160    public abstract void fetch(Message[] messages, FetchProfile fp,
161            MessageRetrievalListener listener) throws MessagingException;
162
163    public abstract void delete(boolean recurse) throws MessagingException;
164
165    public abstract String getName();
166
167    public abstract Flag[] getPermanentFlags() throws MessagingException;
168
169    /**
170     * This method returns a string identifying the name of a "role" folder
171     * (such as inbox, draft, sent, or trash).  Stores that do not implement this
172     * feature can be used - the account UI will provide default strings.  To
173     * let the server identify specific folder roles, simply override this method.
174     *
175     * @return The server- or protocol- specific role for this folder.  If some roles are known
176     * but this is not one of them, return FolderRole.OTHER.  If roles are unsupported here,
177     * return FolderRole.UNKNOWN.
178     */
179    public FolderRole getRole() {
180        return FolderRole.UNKNOWN;
181    }
182
183    /**
184     * Create an empty message of the appropriate type for the Folder.
185     */
186    public abstract Message createMessage(String uid) throws MessagingException;
187
188    /**
189     * Callback interface by which a folder can report UID changes caused by certain operations.
190     */
191    public interface MessageUpdateCallbacks {
192        /**
193         * The operation caused the message's UID to change
194         * @param message The message for which the UID changed
195         * @param newUid The new UID for the message
196         */
197        public void onMessageUidChange(Message message, String newUid) throws MessagingException;
198
199        /**
200         * The operation could not be completed because the message doesn't exist
201         * (for example, it was already deleted from the server side.)
202         * @param message The message that does not exist
203         * @throws MessagingException
204         */
205        public void onMessageNotFound(Message message) throws MessagingException;
206    }
207
208    @Override
209    public String toString() {
210        return getName();
211    }
212}
213