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.Map;
21
22/**
23 * An interface for a cache keyed by a String with a byte array as data.
24 */
25public interface Cache {
26    /**
27     * Retrieves an entry from the cache.
28     * @param key Cache key
29     * @return An {@link Entry} or null in the event of a cache miss
30     */
31    public Entry get(String key);
32
33    /**
34     * Adds or replaces an entry to the cache.
35     * @param key Cache key
36     * @param entry Data to store and metadata for cache coherency, TTL, etc.
37     */
38    public void put(String key, Entry entry);
39
40    /**
41     * Performs any potentially long-running actions needed to initialize the cache;
42     * will be called from a worker thread.
43     */
44    public void initialize();
45
46    /**
47     * Invalidates an entry in the cache.
48     * @param key Cache key
49     * @param fullExpire True to fully expire the entry, false to soft expire
50     */
51    public void invalidate(String key, boolean fullExpire);
52
53    /**
54     * Removes an entry from the cache.
55     * @param key Cache key
56     */
57    public void remove(String key);
58
59    /**
60     * Empties the cache.
61     */
62    public void clear();
63
64    /**
65     * Data and metadata for an entry returned by the cache.
66     */
67    public static class Entry {
68        /** The data returned from cache. */
69        public byte[] data;
70
71        /** ETag for cache coherency. */
72        public String etag;
73
74        /** Date of this response as reported by the server. */
75        public long serverDate;
76
77        /** The last modified date for the requested object. */
78        public long lastModified;
79
80        /** TTL for this record. */
81        public long ttl;
82
83        /** Soft TTL for this record. */
84        public long softTtl;
85
86        /** Immutable response headers as received from server; must be non-null. */
87        public Map<String, String> responseHeaders = Collections.emptyMap();
88
89        /** True if the entry is expired. */
90        public boolean isExpired() {
91            return this.ttl < System.currentTimeMillis();
92        }
93
94        /** True if a refresh is needed from the original data source. */
95        public boolean refreshNeeded() {
96            return this.softTtl < System.currentTimeMillis();
97        }
98    }
99
100}
101