Store.java revision 2b0c619f1edd9fd89dc06bf35d99ece91f415f1e 
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)
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        throws MessagingException {
67        Object o = null;
68        try {
69            Class<?> c = Class.forName(className);
70            // and invoke "newInstance" class method and instantiate store object.
71            java.lang.reflect.Method m =
72                c.getMethod("newInstance", String.class, Context.class);
73            o = m.invoke(null, uri, context);
74        } catch (Exception e) {
75            Log.d(Email.LOG_TAG, String.format(
76                    "exception %s invoking %s.newInstance.(String, Context) method for %s",
77                    e.toString(), className, uri));
78            throw new MessagingException("can not instantiate Store object for " + uri);
79        }
80        if (!(o instanceof Store)) {
81            throw new MessagingException(
82                    uri + ": " + className + " create incompatible object");
83        }
84        return (Store) o;
85    }
86
87    /**
88     * Find Store implementation object consulting with stores.xml file.
89     */
90    private static Store findStore(int resourceId, String uri, Context context)
91            throws MessagingException {
92        Store store = null;
93        try {
94            XmlResourceParser xml = context.getResources().getXml(resourceId);
95            int xmlEventType;
96            // walk through stores.xml file.
97            while ((xmlEventType = xml.next()) != XmlResourceParser.END_DOCUMENT) {
98                if (xmlEventType == XmlResourceParser.START_TAG &&
99                    "store".equals(xml.getName())) {
100                    String scheme = xml.getAttributeValue(null, "scheme");
101                    if (uri.startsWith(scheme)) {
102                        // found store entry whose scheme is matched with uri.
103                        // then load store class.
104                        String className = xml.getAttributeValue(null, "class");
105                        store = instantiateStore(className, uri, context);
106                    }
107                }
108            }
109        } catch (XmlPullParserException e) {
110            // ignore
111        } catch (IOException e) {
112            // ignore
113        }
114        return store;
115    }
116
117    /**
118     * Get an instance of a mail store. The URI is parsed as a standard URI and
119     * the scheme is used to determine which protocol will be used.
120     *
121     * Although the URI format is somewhat protocol-specific, we use the following
122     * guidelines wherever possible:
123     *
124     * scheme [+ security [+]] :// username : password @ host [ / resource ]
125     *
126     * Typical schemes include imap, pop3, local, eas.
127     * Typical security models include SSL or TLS.
128     * A + after the security identifier indicates "required".
129     *
130     * Username, password, and host are as expected.
131     * Resource is protocol specific.  For example, IMAP uses it as the path prefix.  EAS uses it
132     * as the domain.
133     *
134     * @param uri The URI of the store.
135     * @return an initialized store of the appropriate class
136     * @throws MessagingException
137     */
138    public synchronized static Store getInstance(String uri, Context context)
139        throws MessagingException {
140        Store store = mStores.get(uri);
141        if (store == null) {
142            store = findStore(R.xml.stores_product, uri, context);
143            if (store == null) {
144                store = findStore(R.xml.stores, uri, context);
145            }
146
147            if (store != null) {
148                mStores.put(uri, store);
149            }
150        }
151
152        if (store == null) {
153            throw new MessagingException("Unable to locate an applicable Store for " + uri);
154        }
155
156        return store;
157    }
158
159    /**
160     * Get class of SettingActivity for this Store class.
161     * @return Activity class that has class method actionEditIncomingSettings().
162     */
163    public Class<? extends android.app.Activity> getSettingActivityClass() {
164        // default SettingActivity class
165        return com.android.email.activity.setup.AccountSetupIncoming.class;
166    }
167
168    public abstract Folder getFolder(String name) throws MessagingException;
169
170    public abstract Folder[] getPersonalNamespaces() throws MessagingException;
171
172    public abstract void checkSettings() throws MessagingException;
173
174    /**
175     * Delete Store and its corresponding resources.
176     * @throws MessagingException
177     */
178    public void delete() throws MessagingException {
179    }
180}
181