Home | History | Annotate | Download | only in mail 
      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 
     17 package com.android.emailcommon.mail;
     18 
     19 import com.android.emailcommon.service.SearchParams;
     20 import com.google.common.annotations.VisibleForTesting;
     21 
     22 
     23 public 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