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