Store.java revision cd7e5664f9de81dbe3ba8e57941ca6aa6c1dc3d7 
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.email.mail;
18
19import com.android.email.Email;
20import com.android.email.R;
21
22import org.xmlpull.v1.XmlPullParserException;
23
24import android.content.Context;
25import android.content.res.XmlResourceParser;
26import android.util.Log;
27
28import java.io.IOException;
29
30/**
31 * Store is the access point for an email message store. It's location can be
32 * local or remote and no specific protocol is defined. Store is intended to
33 * loosely model in combination the JavaMail classes javax.mail.Store and
34 * javax.mail.Folder along with some additional functionality to improve
35 * performance on mobile devices. Implementations of this class should focus on
36 * making as few network connections as possible.
37 */
38public abstract class Store {
39
40    /**
41     * String constants for known store schemes.
42     */
43    public static final String STORE_SCHEME_IMAP = "imap";
44    public static final String STORE_SCHEME_POP3 = "pop3";
45    public static final String STORE_SCHEME_LOCAL = "local";
46
47    /**
48     * A global suggestion to Store implementors on how much of the body
49     * should be returned on FetchProfile.Item.BODY_SANE requests.
50     */
51    public static final int FETCH_BODY_SANE_SUGGESTED_SIZE = (50 * 1024);
52
53    private static java.util.HashMap<String, Store> mStores =
54        new java.util.HashMap<String, Store>();
55
56    /**
57     * Static named constructor.  It should be overrode by extending class.
58     * Because this method will be called through reflection, it can not be protected.
59     */
60    public static Store newInstance(String uri, Context context, PersistentDataCallbacks callbacks)
61            throws MessagingException {
62        throw new MessagingException("Store.newInstance: Unknown scheme in " + uri);
63    }
64
65    private static Store instantiateStore(String className, String uri, Context context,
66            PersistentDataCallbacks callbacks)
67        throws MessagingException {
68        Object o = null;
69        try {
70            Class<?> c = Class.forName(className);
71            // and invoke "newInstance" class method and instantiate store object.
72            java.lang.reflect.Method m =
73                c.getMethod("newInstance", String.class, Context.class,
74                        PersistentDataCallbacks.class);
75            o = m.invoke(null, uri, context, callbacks);
76        } catch (Exception e) {
77            Log.d(Email.LOG_TAG, String.format(
78                    "exception %s invoking %s.newInstance.(String, Context) method for %s",
79                    e.toString(), className, uri));
80            throw new MessagingException("can not instantiate Store object for " + uri);
81        }
82        if (!(o instanceof Store)) {
83            throw new MessagingException(
84                    uri + ": " + className + " create incompatible object");
85        }
86        return (Store) o;
87    }
88
89    /**
90     * Look up descriptive information about a particular type of store.
91     */
92    public static class StoreInfo {
93        public String mScheme;
94        public String mClassName;
95        public boolean mPushSupported = false;
96
97        public static StoreInfo getStoreInfo(String scheme, Context context) {
98            StoreInfo result = getStoreInfo(R.xml.stores_product, scheme, context);
99            if (result == null) {
100                result = getStoreInfo(R.xml.stores, scheme, context);
101            }
102            return result;
103        }
104
105        public static StoreInfo getStoreInfo(int resourceId, String scheme, Context context) {
106            try {
107                XmlResourceParser xml = context.getResources().getXml(resourceId);
108                int xmlEventType;
109                // walk through stores.xml file.
110                while ((xmlEventType = xml.next()) != XmlResourceParser.END_DOCUMENT) {
111                    if (xmlEventType == XmlResourceParser.START_TAG &&
112                            "store".equals(xml.getName())) {
113                        String xmlScheme = xml.getAttributeValue(null, "scheme");
114                        if (scheme.startsWith(xmlScheme)) {
115                            StoreInfo result = new StoreInfo();
116                            result.mScheme = scheme;
117                            result.mClassName = xml.getAttributeValue(null, "class");
118                            result.mPushSupported = xml.getAttributeBooleanValue(
119                                    null, "push", false);
120                            return result;
121                        }
122                    }
123                }
124            } catch (XmlPullParserException e) {
125                // ignore
126            } catch (IOException e) {
127                // ignore
128            }
129            return null;
130        }
131    }
132
133    /**
134     * Get an instance of a mail store. The URI is parsed as a standard URI and
135     * the scheme is used to determine which protocol will be used.
136     *
137     * Although the URI format is somewhat protocol-specific, we use the following
138     * guidelines wherever possible:
139     *
140     * scheme [+ security [+]] :// username : password @ host [ / resource ]
141     *
142     * Typical schemes include imap, pop3, local, eas.
143     * Typical security models include SSL or TLS.
144     * A + after the security identifier indicates "required".
145     *
146     * Username, password, and host are as expected.
147     * Resource is protocol specific.  For example, IMAP uses it as the path prefix.  EAS uses it
148     * as the domain.
149     *
150     * @param uri The URI of the store.
151     * @return an initialized store of the appropriate class
152     * @throws MessagingException
153     */
154    public synchronized static Store getInstance(String uri, Context context,
155            PersistentDataCallbacks callbacks)
156        throws MessagingException {
157        Store store = mStores.get(uri);
158        if (store == null) {
159            StoreInfo info = StoreInfo.getStoreInfo(uri, context);
160            if (info != null) {
161                store = instantiateStore(info.mClassName, uri, context, callbacks);
162            }
163
164            if (store != null) {
165                mStores.put(uri, store);
166            }
167        }
168
169        if (store == null) {
170            throw new MessagingException("Unable to locate an applicable Store for " + uri);
171        }
172
173        return store;
174    }
175
176    /**
177     * Get class of SettingActivity for this Store class.
178     * @return Activity class that has class method actionEditIncomingSettings().
179     */
180    public Class<? extends android.app.Activity> getSettingActivityClass() {
181        // default SettingActivity class
182        return com.android.email.activity.setup.AccountSetupIncoming.class;
183    }
184
185    public abstract Folder getFolder(String name) throws MessagingException;
186
187    public abstract Folder[] getPersonalNamespaces() throws MessagingException;
188
189    public abstract void checkSettings() throws MessagingException;
190
191    /**
192     * Enable or disable push mode delivery for a given Store.
193     *
194     * <p>For protocols that do not support push mode, be sure that push="true" is not
195     * set by the stores.xml definition file(s).  This function need not be implemented.
196     *
197     * <p>For protocols that do support push mode, this will be called at startup (boot) time
198     * so that the Store can launch its own underlying connection service.  It will also be called
199     * any time the user changes the settings for the account (because the user may switch back
200     * to polling mode (or disable checking completely).
201     *
202     * <p>This API will be called repeatedly, even after push mode has already been started or
203     * stopped.  Stores that support push mode should return quickly if the configuration has not
204     * changed.
205     *
206     * @param enablePushMode start or stop push mode delivery
207     */
208    public void enablePushModeDelivery(boolean enablePushMode) {
209        // does nothing for non-push protocols
210    }
211
212    /**
213     * Delete Store and its corresponding resources.
214     * @throws MessagingException
215     */
216    public void delete() throws MessagingException {
217    }
218
219    /**
220     * Callback interface by which a Store can read and write persistent data.
221     * TODO This needs to be made more generic & flexible
222     */
223    public interface PersistentDataCallbacks {
224
225        /**
226         * Provides a small place for Stores to store persistent data.
227         * @param storeData Data to persist.  All data must be encoded into a string,
228         * so use base64 or some other encoding if necessary.
229         */
230        public void setPersistentString(String storeData);
231
232        /**
233         * @return the data saved by the Store, or null if never set.
234         */
235        public String getPersistentString();
236    }
237}
238