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