1/*
2 * Copyright (C) 2011 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.volley;
18
19import java.util.Collections;
20import java.util.List;
21import java.util.Map;
22
23/**
24 * An interface for a cache keyed by a String with a byte array as data.
25 */
26public interface Cache {
27    /**
28     * Retrieves an entry from the cache.
29     * @param key Cache key
30     * @return An {@link Entry} or null in the event of a cache miss
31     */
32    Entry get(String key);
33
34    /**
35     * Adds or replaces an entry to the cache.
36     * @param key Cache key
37     * @param entry Data to store and metadata for cache coherency, TTL, etc.
38     */
39    void put(String key, Entry entry);
40
41    /**
42     * Performs any potentially long-running actions needed to initialize the cache;
43     * will be called from a worker thread.
44     */
45    void initialize();
46
47    /**
48     * Invalidates an entry in the cache.
49     * @param key Cache key
50     * @param fullExpire True to fully expire the entry, false to soft expire
51     */
52    void invalidate(String key, boolean fullExpire);
53
54    /**
55     * Removes an entry from the cache.
56     * @param key Cache key
57     */
58    void remove(String key);
59
60    /**
61     * Empties the cache.
62     */
63    void clear();
64
65    /**
66     * Data and metadata for an entry returned by the cache.
67     */
68    class Entry {
69        /** The data returned from cache. */
70        public byte[] data;
71
72        /** ETag for cache coherency. */
73        public String etag;
74
75        /** Date of this response as reported by the server. */
76        public long serverDate;
77
78        /** The last modified date for the requested object. */
79        public long lastModified;
80
81        /** TTL for this record. */
82        public long ttl;
83
84        /** Soft TTL for this record. */
85        public long softTtl;
86
87        /**
88         * Response headers as received from server; must be non-null. Should not be mutated
89         * directly.
90         *
91         * <p>Note that if the server returns two headers with the same (case-insensitive) name,
92         * this map will only contain the one of them. {@link #allResponseHeaders} may contain all
93         * headers if the {@link Cache} implementation supports it.
94         */
95        public Map<String, String> responseHeaders = Collections.emptyMap();
96
97        /**
98         * All response headers. May be null depending on the {@link Cache} implementation. Should
99         * not be mutated directly.
100         */
101        public List<Header> allResponseHeaders;
102
103        /** True if the entry is expired. */
104        public boolean isExpired() {
105            return this.ttl < System.currentTimeMillis();
106        }
107
108        /** True if a refresh is needed from the original data source. */
109        public boolean refreshNeeded() {
110            return this.softTtl < System.currentTimeMillis();
111        }
112    }
113
114}
115