1/*
2 * Copyright (C) 2009 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.email.mail;
18
19import com.android.email.MessagingListener;
20import com.android.email.provider.EmailContent;
21import com.android.email.GroupMessagingListener;
22
23import android.content.Context;
24
25/**
26 * This interface allows a store to define a completely different synchronizer algorithm,
27 * as necessary.
28 */
29public interface StoreSynchronizer {
30
31    /**
32     * An object of this class is returned by SynchronizeMessagesSynchronous to report
33     * the results of the sync run.
34     */
35    public static class SyncResults {
36        /**
37         * The total # of messages in the folder
38         */
39        public int mTotalMessages;
40        /**
41         * The # of new messages in the folder
42         */
43        public int mNewMessages;
44
45        public SyncResults(int totalMessages, int newMessages) {
46            mTotalMessages = totalMessages;
47            mNewMessages = newMessages;
48        }
49    }
50
51    /**
52     * The job of this method is to synchronize messages between a remote folder and the
53     * corresponding local folder.
54     *
55     * The following callbacks should be called during this operation:
56     *  {@link MessagingListener#synchronizeMailboxNewMessage(Account, String, Message)}
57     *  {@link MessagingListener#synchronizeMailboxRemovedMessage(Account, String, Message)}
58     *
59     * Callbacks (through listeners) *must* be synchronized on the listeners object, e.g.
60     *   synchronized (listeners) {
61     *       for(MessagingListener listener : listeners) {
62     *           listener.synchronizeMailboxNewMessage(account, folder, message);
63     *       }
64     *   }
65     *
66     * @param account The account to synchronize
67     * @param folder The folder to synchronize
68     * @param listeners callbacks to make during sync operation
69     * @param context if needed for making system calls
70     * @return an object describing the sync results
71     */
72    public SyncResults SynchronizeMessagesSynchronous(
73            EmailContent.Account account, EmailContent.Mailbox folder,
74            GroupMessagingListener listeners, Context context) throws MessagingException;
75
76}
77