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