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