2009-03-04 03:32:22 +00:00
|
|
|
/*
|
|
|
|
* Copyright (C) 2008 The Android Open Source Project
|
|
|
|
*
|
|
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
|
|
* you may not use this file except in compliance with the License.
|
|
|
|
* You may obtain a copy of the License at
|
|
|
|
*
|
|
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
*
|
|
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
|
* See the License for the specific language governing permissions and
|
|
|
|
* limitations under the License.
|
|
|
|
*/
|
|
|
|
|
2011-02-10 02:47:43 +00:00
|
|
|
package com.android.emailcommon.mail;
|
2009-03-04 03:32:22 +00:00
|
|
|
|
|
|
|
|
|
|
|
public abstract class Folder {
|
|
|
|
public enum OpenMode {
|
|
|
|
READ_WRITE, READ_ONLY,
|
|
|
|
}
|
|
|
|
|
|
|
|
public enum FolderType {
|
|
|
|
HOLDS_FOLDERS, HOLDS_MESSAGES,
|
|
|
|
}
|
2009-04-15 19:58:19 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Identifiers of "special" folders.
|
|
|
|
*/
|
|
|
|
public enum FolderRole {
|
|
|
|
INBOX, // NOTE: The folder's name must be INBOX
|
|
|
|
TRASH,
|
|
|
|
SENT,
|
|
|
|
DRAFTS,
|
|
|
|
|
|
|
|
OUTBOX, // Local folders only - not used in remote Stores
|
|
|
|
OTHER, // this folder has no specific role
|
|
|
|
UNKNOWN // the role of this folder is unknown
|
|
|
|
}
|
2009-03-04 03:32:22 +00:00
|
|
|
|
2010-05-13 21:28:08 +00:00
|
|
|
/**
|
|
|
|
* Callback for each message retrieval.
|
|
|
|
*
|
|
|
|
* Not all {@link Folder} implementation won't call it.
|
|
|
|
* (Currently {@link com.android.email.mail.store.LocalStore.LocalFolder} won't.)
|
|
|
|
*/
|
|
|
|
public interface MessageRetrievalListener {
|
|
|
|
public void messageRetrieved(Message message);
|
2010-08-18 15:50:45 +00:00
|
|
|
public void loadAttachmentProgress(int progress);
|
2010-05-13 21:28:08 +00:00
|
|
|
}
|
|
|
|
|
2009-03-04 03:32:22 +00:00
|
|
|
/**
|
|
|
|
* Forces an open of the MailProvider. If the provider is already open this
|
|
|
|
* function returns without doing anything.
|
|
|
|
*
|
|
|
|
* @param mode READ_ONLY or READ_WRITE
|
AI 146134: Add persistence API for remote stores & folders to use while
syncing. This provides a key-value store, per folder, that
can be used by network Stores to record persistent data such
as sync status, server keys, etc.
Note that, by definition, this only applies to remote folders
(e.g. IMAP, POP3). You'll see everywhere that LocalFolder is
passed null, and this is correct - LocalFolder *is* persistent
storage and does not need external help.
Note to reviewers: The core changes are Folder.java,
LocalStore.java, and LocalStoreUnitTests.java, so please give
them the bulk of your reviewer attention. The other files
are just following along with minor API changes. Of those,
the one worth close examination is MessagingController.java,
which is the only place in the system where remote Folders
are bonded with Local Folders and thus where this new API
comes into play.
Note to jham: Can you please take a look at
LocalStore.LocalFolder.setPersistentString() and recommend
better SQL foo than my primitive test-then-update-or-insert
logic, which is not transactional or threadsafe.
BUG=1786939
Automated import of CL 146134
2009-04-14 17:15:07 +00:00
|
|
|
* @param callbacks Pointer to callbacks class. This may be used by the folder between this
|
|
|
|
* time and when close() is called. This is only used for remote stores - should be null
|
|
|
|
* for LocalStore.LocalFolder.
|
2009-03-04 03:32:22 +00:00
|
|
|
*/
|
AI 146134: Add persistence API for remote stores & folders to use while
syncing. This provides a key-value store, per folder, that
can be used by network Stores to record persistent data such
as sync status, server keys, etc.
Note that, by definition, this only applies to remote folders
(e.g. IMAP, POP3). You'll see everywhere that LocalFolder is
passed null, and this is correct - LocalFolder *is* persistent
storage and does not need external help.
Note to reviewers: The core changes are Folder.java,
LocalStore.java, and LocalStoreUnitTests.java, so please give
them the bulk of your reviewer attention. The other files
are just following along with minor API changes. Of those,
the one worth close examination is MessagingController.java,
which is the only place in the system where remote Folders
are bonded with Local Folders and thus where this new API
comes into play.
Note to jham: Can you please take a look at
LocalStore.LocalFolder.setPersistentString() and recommend
better SQL foo than my primitive test-then-update-or-insert
logic, which is not transactional or threadsafe.
BUG=1786939
Automated import of CL 146134
2009-04-14 17:15:07 +00:00
|
|
|
public abstract void open(OpenMode mode, PersistentDataCallbacks callbacks)
|
|
|
|
throws MessagingException;
|
2009-03-04 03:32:22 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Forces a close of the MailProvider. Any further access will attempt to
|
|
|
|
* reopen the MailProvider.
|
|
|
|
*
|
|
|
|
* @param expunge If true all deleted messages will be expunged.
|
|
|
|
*/
|
|
|
|
public abstract void close(boolean expunge) throws MessagingException;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @return True if further commands are not expected to have to open the
|
|
|
|
* connection.
|
|
|
|
*/
|
|
|
|
// TODO not used, get rid of this - it's a transport function
|
|
|
|
public abstract boolean isOpen();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Get the mode the folder was opened with. This may be different than the mode the open
|
|
|
|
* was requested with.
|
|
|
|
* @return
|
|
|
|
*/
|
|
|
|
public abstract OpenMode getMode() throws MessagingException;
|
|
|
|
|
2009-09-25 21:54:32 +00:00
|
|
|
/**
|
|
|
|
* Reports if the Store is able to create folders of the given type.
|
|
|
|
* Does not actually attempt to create a folder.
|
|
|
|
* @param type
|
|
|
|
* @return true if can create, false if cannot create
|
|
|
|
*/
|
|
|
|
public abstract boolean canCreate(FolderType type);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Attempt to create the given folder remotely using the given type.
|
|
|
|
* @param type
|
|
|
|
* @return true if created, false if cannot create (e.g. server side)
|
|
|
|
*/
|
2009-03-04 03:32:22 +00:00
|
|
|
public abstract boolean create(FolderType type) throws MessagingException;
|
|
|
|
|
|
|
|
public abstract boolean exists() throws MessagingException;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @return A count of the messages in the selected folder.
|
|
|
|
*/
|
|
|
|
public abstract int getMessageCount() throws MessagingException;
|
|
|
|
|
|
|
|
public abstract int getUnreadMessageCount() throws MessagingException;
|
|
|
|
|
|
|
|
public abstract Message getMessage(String uid) throws MessagingException;
|
|
|
|
|
|
|
|
public abstract Message[] getMessages(int start, int end, MessageRetrievalListener listener)
|
|
|
|
throws MessagingException;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Fetches the given list of messages. The specified listener is notified as
|
|
|
|
* each fetch completes. Messages are downloaded as (as) lightweight (as
|
|
|
|
* possible) objects to be filled in with later requests. In most cases this
|
|
|
|
* means that only the UID is downloaded.
|
|
|
|
*
|
|
|
|
* @param uids
|
|
|
|
* @param listener
|
|
|
|
*/
|
|
|
|
public abstract Message[] getMessages(MessageRetrievalListener listener)
|
|
|
|
throws MessagingException;
|
|
|
|
|
|
|
|
public abstract Message[] getMessages(String[] uids, MessageRetrievalListener listener)
|
|
|
|
throws MessagingException;
|
2009-04-22 20:49:57 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Return a set of messages based on the state of the flags.
|
|
|
|
* Note: Not typically implemented in remote stores, so not abstract.
|
|
|
|
*
|
|
|
|
* @param setFlags The flags that should be set for a message to be selected (can be null)
|
|
|
|
* @param clearFlags The flags that should be clear for a message to be selected (can be null)
|
|
|
|
* @param listener
|
|
|
|
* @return A list of messages matching the desired flag states.
|
|
|
|
* @throws MessagingException
|
|
|
|
*/
|
|
|
|
public Message[] getMessages(Flag[] setFlags, Flag[] clearFlags,
|
|
|
|
MessageRetrievalListener listener) throws MessagingException {
|
|
|
|
throw new MessagingException("Not implemented");
|
|
|
|
}
|
2009-03-04 03:32:22 +00:00
|
|
|
|
|
|
|
public abstract void appendMessages(Message[] messages) throws MessagingException;
|
|
|
|
|
2009-04-24 18:54:42 +00:00
|
|
|
public abstract void copyMessages(Message[] msgs, Folder folder,
|
|
|
|
MessageUpdateCallbacks callbacks) throws MessagingException;
|
2009-03-04 03:32:22 +00:00
|
|
|
|
|
|
|
public abstract void setFlags(Message[] messages, Flag[] flags, boolean value)
|
|
|
|
throws MessagingException;
|
|
|
|
|
|
|
|
public abstract Message[] expunge() throws MessagingException;
|
|
|
|
|
|
|
|
public abstract void fetch(Message[] messages, FetchProfile fp,
|
|
|
|
MessageRetrievalListener listener) throws MessagingException;
|
|
|
|
|
|
|
|
public abstract void delete(boolean recurse) throws MessagingException;
|
|
|
|
|
|
|
|
public abstract String getName();
|
|
|
|
|
|
|
|
public abstract Flag[] getPermanentFlags() throws MessagingException;
|
|
|
|
|
2009-04-15 19:58:19 +00:00
|
|
|
/**
|
|
|
|
* This method returns a string identifying the name of a "role" folder
|
|
|
|
* (such as inbox, draft, sent, or trash). Stores that do not implement this
|
|
|
|
* feature can be used - the account UI will provide default strings. To
|
|
|
|
* let the server identify specific folder roles, simply override this method.
|
|
|
|
*
|
|
|
|
* @return The server- or protocol- specific role for this folder. If some roles are known
|
|
|
|
* but this is not one of them, return FolderRole.OTHER. If roles are unsupported here,
|
|
|
|
* return FolderRole.UNKNOWN.
|
|
|
|
*/
|
|
|
|
public FolderRole getRole() {
|
|
|
|
return FolderRole.UNKNOWN;
|
|
|
|
}
|
2009-04-23 17:49:42 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* This function will be called after the messaging controller has called
|
|
|
|
* getPersonalNamespaces() and has created a matching LocalFolder object. This can
|
|
|
|
* be used as a trigger for the folder to write back any folder-specific persistent data using
|
|
|
|
* callbacks.
|
|
|
|
*
|
|
|
|
* This is not abstract because most folders do not require this functionality and do not
|
|
|
|
* need to implement it.
|
|
|
|
*/
|
|
|
|
@SuppressWarnings("unused")
|
|
|
|
public void localFolderSetupComplete(Folder localFolder) throws MessagingException {
|
|
|
|
// Do nothing - return immediately
|
|
|
|
}
|
2009-04-15 19:58:19 +00:00
|
|
|
|
2009-08-19 20:15:13 +00:00
|
|
|
/**
|
|
|
|
* Create an empty message of the appropriate type for the Folder.
|
|
|
|
*/
|
|
|
|
public abstract Message createMessage(String uid) throws MessagingException;
|
|
|
|
|
AI 146134: Add persistence API for remote stores & folders to use while
syncing. This provides a key-value store, per folder, that
can be used by network Stores to record persistent data such
as sync status, server keys, etc.
Note that, by definition, this only applies to remote folders
(e.g. IMAP, POP3). You'll see everywhere that LocalFolder is
passed null, and this is correct - LocalFolder *is* persistent
storage and does not need external help.
Note to reviewers: The core changes are Folder.java,
LocalStore.java, and LocalStoreUnitTests.java, so please give
them the bulk of your reviewer attention. The other files
are just following along with minor API changes. Of those,
the one worth close examination is MessagingController.java,
which is the only place in the system where remote Folders
are bonded with Local Folders and thus where this new API
comes into play.
Note to jham: Can you please take a look at
LocalStore.LocalFolder.setPersistentString() and recommend
better SQL foo than my primitive test-then-update-or-insert
logic, which is not transactional or threadsafe.
BUG=1786939
Automated import of CL 146134
2009-04-14 17:15:07 +00:00
|
|
|
/**
|
|
|
|
* Callback interface by which a Folder can read and write persistent data.
|
|
|
|
* TODO This needs to be made more generic & flexible
|
|
|
|
*/
|
|
|
|
public interface PersistentDataCallbacks {
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Provides keyed storage of strings. Should be used for per-folder data. Do not use for
|
|
|
|
* per-message data.
|
|
|
|
* @param key identifier for the data (e.g. "sync.key" or "folder.id")
|
|
|
|
* @param value Data to persist. All data must be encoded into a string,
|
|
|
|
* so use base64 or some other encoding if necessary.
|
|
|
|
*/
|
|
|
|
public void setPersistentString(String key, String value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @param key identifier for the data of interest
|
|
|
|
* @return the data saved by the Folder, or defaultValue if never set.
|
|
|
|
*/
|
|
|
|
public String getPersistentString(String key, String defaultValue);
|
2009-04-22 20:49:57 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* In a single transaction: Set a key/value pair for the folder, and bulk set or clear
|
|
|
|
* message flags. Typically used at the beginning or conclusion of a bulk sync operation.
|
|
|
|
*
|
|
|
|
* @param key if non-null, the transaction will set this folder persistent value
|
|
|
|
* @param value the value that will be stored for the key
|
|
|
|
* @param setFlags if non-null, flag(s) will be set for all messages in the folder
|
|
|
|
* @param clearFlags if non-null, flag(s) will be cleared for all messages in the folder
|
|
|
|
*/
|
|
|
|
public void setPersistentStringAndMessageFlags(String key, String value,
|
|
|
|
Flag[] setFlags, Flag[] clearFlags) throws MessagingException;
|
AI 146134: Add persistence API for remote stores & folders to use while
syncing. This provides a key-value store, per folder, that
can be used by network Stores to record persistent data such
as sync status, server keys, etc.
Note that, by definition, this only applies to remote folders
(e.g. IMAP, POP3). You'll see everywhere that LocalFolder is
passed null, and this is correct - LocalFolder *is* persistent
storage and does not need external help.
Note to reviewers: The core changes are Folder.java,
LocalStore.java, and LocalStoreUnitTests.java, so please give
them the bulk of your reviewer attention. The other files
are just following along with minor API changes. Of those,
the one worth close examination is MessagingController.java,
which is the only place in the system where remote Folders
are bonded with Local Folders and thus where this new API
comes into play.
Note to jham: Can you please take a look at
LocalStore.LocalFolder.setPersistentString() and recommend
better SQL foo than my primitive test-then-update-or-insert
logic, which is not transactional or threadsafe.
BUG=1786939
Automated import of CL 146134
2009-04-14 17:15:07 +00:00
|
|
|
}
|
2009-04-24 18:13:36 +00:00
|
|
|
|
2009-04-24 18:54:42 +00:00
|
|
|
/**
|
|
|
|
* Callback interface by which a folder can report UID changes caused by certain operations.
|
|
|
|
*/
|
|
|
|
public interface MessageUpdateCallbacks {
|
|
|
|
/**
|
|
|
|
* The operation caused the message's UID to change
|
|
|
|
* @param message The message for which the UID changed
|
|
|
|
* @param newUid The new UID for the message
|
|
|
|
*/
|
2009-05-05 23:36:31 +00:00
|
|
|
public void onMessageUidChange(Message message, String newUid) throws MessagingException;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* The operation could not be completed because the message doesn't exist
|
|
|
|
* (for example, it was already deleted from the server side.)
|
|
|
|
* @param message The message that does not exist
|
|
|
|
* @throws MessagingException
|
|
|
|
*/
|
|
|
|
public void onMessageNotFound(Message message) throws MessagingException;
|
2009-04-24 18:54:42 +00:00
|
|
|
}
|
|
|
|
|
2009-03-04 03:32:22 +00:00
|
|
|
@Override
|
|
|
|
public String toString() {
|
|
|
|
return getName();
|
|
|
|
}
|
|
|
|
}
|