1 /* 2 * ==================================================================== 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * ==================================================================== 20 * 21 * This software consists of voluntary contributions made by many 22 * individuals on behalf of the Apache Software Foundation. For more 23 * information on the Apache Software Foundation, please see 24 * <http://www.apache.org/>. 25 * 26 */ 27 package org.apache.hc.client5.http.cache; 28 29 import java.util.Collection; 30 import java.util.Map; 31 32 import org.apache.hc.core5.annotation.Contract; 33 import org.apache.hc.core5.annotation.ThreadingBehavior; 34 35 /** 36 * {@literal HttpCacheStorage} represents an abstract HTTP cache 37 * storage backend that can then be plugged into the classic 38 * (blocking) request execution pipeline. 39 * <p> 40 * Implementations of this interface are expected to be threading-safe. 41 * </p> 42 * 43 * @since 4.1 44 */ 45 @Contract(threading = ThreadingBehavior.SAFE) 46 public interface HttpCacheStorage { 47 48 /** 49 * Store a given cache entry under the given key. 50 * @param key where in the cache to store the entry 51 * @param entry cached response to store 52 * @throws ResourceIOException 53 */ 54 void putEntry(String key, HttpCacheEntry entry) throws ResourceIOException; 55 56 /** 57 * Retrieves the cache entry stored under the given key 58 * or null if no entry exists under that key. 59 * @param key cache key 60 * @return an {@link HttpCacheEntry} or {@code null} if no 61 * entry exists 62 * @throws ResourceIOException 63 */ 64 HttpCacheEntry getEntry(String key) throws ResourceIOException; 65 66 /** 67 * Deletes/invalidates/removes any cache entries currently 68 * stored under the given key. 69 * @param key 70 * @throws ResourceIOException 71 */ 72 void removeEntry(String key) throws ResourceIOException; 73 74 /** 75 * Atomically applies the given callback to processChallenge an existing cache 76 * entry under a given key. 77 * @param key indicates which entry to modify 78 * @param casOperation the CAS operation to perform. 79 * @throws ResourceIOException 80 * @throws HttpCacheUpdateException 81 */ 82 void updateEntry( 83 String key, HttpCacheCASOperation casOperation) throws ResourceIOException, HttpCacheUpdateException; 84 85 86 /** 87 * Retrieves multiple cache entries stored under the given keys. Some implementations 88 * may use a single bulk operation to do the retrieval. 89 * 90 * @param keys cache keys 91 * @return an map of {@link HttpCacheEntry}s. 92 * 93 * @since 5.0 94 */ 95 Map<String, HttpCacheEntry> getEntries(Collection<String> keys) throws ResourceIOException; 96 97 }