1/*
2 * Copyright (C) 2006 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 android.webkit;
18
19import java.io.File;
20import java.io.IOException;
21import java.io.InputStream;
22import java.io.OutputStream;
23import java.util.Map;
24
25
26/**
27 * Manages the HTTP cache used by an application's {@link WebView} instances.
28 * @deprecated Access to the HTTP cache will be removed in a future release.
29 * @hide Since {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1}
30 */
31// The class CacheManager provides the persistent cache of content that is
32// received over the network. The component handles parsing of HTTP headers and
33// utilizes the relevant cache headers to determine if the content should be
34// stored and if so, how long it is valid for. Network requests are provided to
35// this component and if they can not be resolved by the cache, the HTTP headers
36// are attached, as appropriate, to the request for revalidation of content. The
37// class also manages the cache size.
38//
39// CacheManager may only be used if your activity contains a WebView.
40@Deprecated
41public final class CacheManager {
42    /**
43     * Represents a resource stored in the HTTP cache. Instances of this class
44     * can be obtained by calling
45     * {@link CacheManager#getCacheFile CacheManager.getCacheFile(String, Map<String, String>))}.
46     *
47     * @deprecated Access to the HTTP cache will be removed in a future release.
48     */
49    @Deprecated
50    public static class CacheResult {
51        // these fields are saved to the database
52        int httpStatusCode;
53        long contentLength;
54        long expires;
55        String expiresString;
56        String localPath;
57        String lastModified;
58        String etag;
59        String mimeType;
60        String location;
61        String encoding;
62        String contentdisposition;
63        String crossDomain;
64
65        // these fields are NOT saved to the database
66        InputStream inStream;
67        OutputStream outStream;
68        File outFile;
69
70        /**
71         * Gets the status code of this cache entry.
72         *
73         * @return the status code of this cache entry
74         */
75        public int getHttpStatusCode() {
76            return httpStatusCode;
77        }
78
79        /**
80         * Gets the content length of this cache entry.
81         *
82         * @return the content length of this cache entry
83         */
84        public long getContentLength() {
85            return contentLength;
86        }
87
88        /**
89         * Gets the path of the file used to store the content of this cache
90         * entry, relative to the base directory of the cache. See
91         * {@link CacheManager#getCacheFileBaseDir CacheManager.getCacheFileBaseDir()}.
92         *
93         * @return the path of the file used to store this cache entry
94         */
95        public String getLocalPath() {
96            return localPath;
97        }
98
99        /**
100         * Gets the expiry date of this cache entry, expressed in milliseconds
101         * since midnight, January 1, 1970 UTC.
102         *
103         * @return the expiry date of this cache entry
104         */
105        public long getExpires() {
106            return expires;
107        }
108
109        /**
110         * Gets the expiry date of this cache entry, expressed as a string.
111         *
112         * @return the expiry date of this cache entry
113         *
114         */
115        public String getExpiresString() {
116            return expiresString;
117        }
118
119        /**
120         * Gets the date at which this cache entry was last modified, expressed
121         * as a string.
122         *
123         * @return the date at which this cache entry was last modified
124         */
125        public String getLastModified() {
126            return lastModified;
127        }
128
129        /**
130         * Gets the entity tag of this cache entry.
131         *
132         * @return the entity tag of this cache entry
133         */
134        public String getETag() {
135            return etag;
136        }
137
138        /**
139         * Gets the MIME type of this cache entry.
140         *
141         * @return the MIME type of this cache entry
142         */
143        public String getMimeType() {
144            return mimeType;
145        }
146
147        /**
148         * Gets the value of the HTTP 'Location' header with which this cache
149         * entry was received.
150         *
151         * @return the HTTP 'Location' header for this cache entry
152         */
153        public String getLocation() {
154            return location;
155        }
156
157        /**
158         * Gets the encoding of this cache entry.
159         *
160         * @return the encoding of this cache entry
161         */
162        public String getEncoding() {
163            return encoding;
164        }
165
166        /**
167         * Gets the value of the HTTP 'Content-Disposition' header with which
168         * this cache entry was received.
169         *
170         * @return the HTTP 'Content-Disposition' header for this cache entry
171         *
172         */
173        public String getContentDisposition() {
174            return contentdisposition;
175        }
176
177        /**
178         * Gets the input stream to the content of this cache entry, to allow
179         * content to be read. See
180         * {@link CacheManager#getCacheFile CacheManager.getCacheFile(String, Map<String, String>)}.
181         *
182         * @return an input stream to the content of this cache entry
183         */
184        public InputStream getInputStream() {
185            return inStream;
186        }
187
188        /**
189         * Gets an output stream to the content of this cache entry, to allow
190         * content to be written. See
191         * {@link CacheManager#saveCacheFile CacheManager.saveCacheFile(String, CacheResult)}.
192         *
193         * @return an output stream to the content of this cache entry
194         */
195        // Note that this is always null for objects returned by getCacheFile()!
196        public OutputStream getOutputStream() {
197            return outStream;
198        }
199
200
201        /**
202         * Sets an input stream to the content of this cache entry.
203         *
204         * @param stream an input stream to the content of this cache entry
205         */
206        public void setInputStream(InputStream stream) {
207            this.inStream = stream;
208        }
209
210        /**
211         * Sets the encoding of this cache entry.
212         *
213         * @param encoding the encoding of this cache entry
214         */
215        public void setEncoding(String encoding) {
216            this.encoding = encoding;
217        }
218
219        /**
220         * @hide
221         */
222        public void setContentLength(long contentLength) {
223            this.contentLength = contentLength;
224        }
225    }
226
227    /**
228     * Gets the base directory in which the files used to store the contents of
229     * cache entries are placed. See
230     * {@link CacheManager.CacheResult#getLocalPath CacheManager.CacheResult.getLocalPath()}.
231     *
232     * @return the base directory of the cache
233     * @deprecated This method no longer has any effect and always returns null.
234     */
235    @Deprecated
236    public static File getCacheFileBaseDir() {
237        return null;
238    }
239
240    /**
241     * Gets whether the HTTP cache is disabled.
242     *
243     * @return true if the HTTP cache is disabled
244     * @deprecated This method no longer has any effect and always returns false.
245     */
246    @Deprecated
247    public static boolean cacheDisabled() {
248        return false;
249    }
250
251    /**
252     * Starts a cache transaction. Returns true if this is the only running
253     * transaction. Otherwise, this transaction is nested inside currently
254     * running transactions and false is returned.
255     *
256     * @return true if this is the only running transaction
257     * @deprecated This method no longer has any effect and always returns false.
258     */
259    @Deprecated
260    public static boolean startCacheTransaction() {
261        return false;
262    }
263
264    /**
265     * Ends the innermost cache transaction and returns whether this was the
266     * only running transaction.
267     *
268     * @return true if this was the only running transaction
269     * @deprecated This method no longer has any effect and always returns false.
270     */
271    @Deprecated
272    public static boolean endCacheTransaction() {
273        return false;
274    }
275
276    /**
277     * Gets the cache entry for the specified URL, or null if none is found.
278     * If a non-null value is provided for the HTTP headers map, and the cache
279     * entry needs validation, appropriate headers will be added to the map.
280     * The input stream of the CacheEntry object should be closed by the caller
281     * when access to the underlying file is no longer required.
282     *
283     * @param url the URL for which a cache entry is requested
284     * @param headers a map from HTTP header name to value, to be populated
285     *                for the returned cache entry
286     * @return the cache entry for the specified URL
287     * @deprecated This method no longer has any effect and always returns null.
288     */
289    @Deprecated
290    public static CacheResult getCacheFile(String url,
291            Map<String, String> headers) {
292        return null;
293    }
294
295    /**
296     * Adds a cache entry to the HTTP cache for the specicifed URL. Also closes
297     * the cache entry's output stream.
298     *
299     * @param url the URL for which the cache entry should be added
300     * @param cacheResult the cache entry to add
301     * @deprecated Access to the HTTP cache will be removed in a future release.
302     */
303    @Deprecated
304    public static void saveCacheFile(String url, CacheResult cacheResult) {
305        saveCacheFile(url, 0, cacheResult);
306    }
307
308    static void saveCacheFile(String url, long postIdentifier,
309            CacheResult cacheRet) {
310        try {
311            cacheRet.outStream.close();
312        } catch (IOException e) {
313            return;
314        }
315
316        // This method is exposed in the public API but the API provides no
317        // way to obtain a new CacheResult object with a non-null output
318        // stream ...
319        // - CacheResult objects returned by getCacheFile() have a null
320        //   output stream.
321        // - new CacheResult objects have a null output stream and no
322        //   setter is provided.
323        // Since this method throws a null pointer exception in this case,
324        // it is effectively useless from the point of view of the public
325        // API.
326        //
327        // With the Chromium HTTP stack we continue to throw the same
328        // exception for 'backwards compatibility' with the Android HTTP
329        // stack.
330        //
331        // This method is not used from within this package, and for public API
332        // use, we should already have thrown an exception above.
333        assert false;
334    }
335}
336