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.impl.cache;
28
29 import java.time.Instant;
30 import java.util.Map;
31
32 import org.apache.hc.client5.http.cache.HttpCacheEntry;
33 import org.apache.hc.core5.concurrent.Cancellable;
34 import org.apache.hc.core5.concurrent.FutureCallback;
35 import org.apache.hc.core5.http.HttpHost;
36 import org.apache.hc.core5.http.HttpRequest;
37 import org.apache.hc.core5.http.HttpResponse;
38 import org.apache.hc.core5.util.ByteArrayBuffer;
39
40 interface HttpAsyncCache {
41
42 String generateKey (HttpHost host, HttpRequest request, HttpCacheEntry cacheEntry);
43
44 /**
45 * Clear all matching {@link HttpCacheEntry}s.
46 */
47 Cancellable flushCacheEntriesFor(
48 HttpHost host, HttpRequest request, FutureCallback<Boolean> callback);
49
50 /**
51 * Flush {@link HttpCacheEntry}s invalidated by the given request
52 */
53 Cancellable flushCacheEntriesInvalidatedByRequest(
54 HttpHost host, HttpRequest request, FutureCallback<Boolean> callback);
55
56 /**
57 * Flush {@link HttpCacheEntry}s invalidated by the given message exchange.
58 */
59 Cancellable flushCacheEntriesInvalidatedByExchange(
60 HttpHost host, HttpRequest request, HttpResponse response, FutureCallback<Boolean> callback);
61
62 /**
63 * Retrieve matching {@link HttpCacheEntry} from the cache if it exists
64 */
65 Cancellable getCacheEntry(
66 HttpHost host, HttpRequest request, FutureCallback<HttpCacheEntry> callback);
67
68 /**
69 * Retrieve all variants from the cache, if there are no variants then an empty
70 */
71 Cancellable getVariantCacheEntriesWithEtags(
72 HttpHost host, HttpRequest request, FutureCallback<Map<String,Variant>> callback);
73
74 /**
75 * Store a {@link HttpResponse} in the cache if possible, and return
76 */
77 Cancellable createCacheEntry(
78 HttpHost host,
79 HttpRequest request,
80 HttpResponse originResponse,
81 ByteArrayBuffer content,
82 Instant requestSent,
83 Instant responseReceived,
84 FutureCallback<HttpCacheEntry> callback);
85
86 /**
87 * Update a {@link HttpCacheEntry} using a 304 {@link HttpResponse}.
88 */
89 Cancellable updateCacheEntry(
90 HttpHost host,
91 HttpRequest request,
92 HttpCacheEntry stale,
93 HttpResponse originResponse,
94 Instant requestSent,
95 Instant responseReceived,
96 FutureCallback<HttpCacheEntry> callback);
97
98 /**
99 * Update a specific {@link HttpCacheEntry} representing a cached variant
100 * using a 304 {@link HttpResponse}.
101 */
102 Cancellable updateVariantCacheEntry(
103 HttpHost host,
104 HttpRequest request,
105 HttpResponse originResponse,
106 Variant variant,
107 Instant requestSent,
108 Instant responseReceived,
109 FutureCallback<HttpCacheEntry> callback);
110
111 /**
112 * Specifies cache should reuse the given cached variant to satisfy
113 * requests whose varying headers match those of the given client request.
114 */
115 Cancellable reuseVariantEntryFor(
116 HttpHost host,
117 HttpRequest req,
118 Variant variant,
119 FutureCallback<Boolean> callback);
120 }