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 import org.apache.hc.core5.concurrent.Cancellable; 35 import org.apache.hc.core5.concurrent.FutureCallback; 36 37 /** 38 * {@literal HttpAsyncCacheStorage} represents an abstract HTTP cache 39 * storage backend that can then be plugged into the asynchronous 40 * (non-blocking ) request execution 41 * pipeline. 42 * <p> 43 * Implementations of this interface are expected to be threading-safe. 44 * </p> 45 * 46 * @since 5.0 47 */ 48 @Contract(threading = ThreadingBehavior.SAFE) 49 public interface HttpAsyncCacheStorage { 50 51 /** 52 * Store a given cache entry under the given key. 53 * @param key where in the cache to store the entry 54 * @param entry cached response to store 55 * @param callback result callback 56 */ 57 Cancellable putEntry( 58 String key, HttpCacheEntry entry, FutureCallback<Boolean> callback); 59 60 /** 61 * Retrieves the cache entry stored under the given key 62 * or null if no entry exists under that key. 63 * @param key cache key 64 * @param callback result callback 65 * @return an {@link HttpCacheEntry} or {@code null} if no 66 * entry exists 67 */ 68 Cancellable getEntry( 69 String key, FutureCallback<HttpCacheEntry> callback); 70 71 /** 72 * Deletes/invalidates/removes any cache entries currently 73 * stored under the given key. 74 * @param key 75 * @param callback result callback 76 */ 77 Cancellable removeEntry( 78 String key, FutureCallback<Boolean> callback); 79 80 /** 81 * Atomically applies the given callback to processChallenge an existing cache 82 * entry under a given key. 83 * @param key indicates which entry to modify 84 * @param casOperation the CAS operation to perform. 85 * @param callback result callback 86 */ 87 Cancellable updateEntry( 88 String key, HttpCacheCASOperation casOperation, FutureCallback<Boolean> callback); 89 90 91 /** 92 * Retrieves multiple cache entries stored under the given keys. Some implementations 93 * may use a single bulk operation to do the retrieval. 94 * 95 * @param keys cache keys 96 * @param callback result callback 97 */ 98 Cancellable getEntries(Collection<String> keys, FutureCallback<Map<String, HttpCacheEntry>> callback); 99 100 }