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.http.impl.client.cache;
28
29 import java.io.IOException;
30 import java.util.Date;
31 import java.util.Map;
32
33 import org.apache.http.HttpHost;
34 import org.apache.http.HttpRequest;
35 import org.apache.http.HttpResponse;
36 import org.apache.http.client.cache.HttpCacheEntry;
37 import org.apache.http.client.methods.CloseableHttpResponse;
38
39 /**
40 * @since 4.1
41 */
42 interface HttpCache {
43
44 /**
45 * Clear all matching {@link HttpCacheEntry}s.
46 * @param host
47 * @param request
48 * @throws IOException
49 */
50 void flushCacheEntriesFor(HttpHost host, HttpRequest request)
51 throws IOException;
52
53 /**
54 * Clear invalidated matching {@link HttpCacheEntry}s
55 * @param host
56 * @param request
57 * @throws IOException
58 */
59 void flushInvalidatedCacheEntriesFor(HttpHost host, HttpRequest request)
60 throws IOException;
61
62 /** Clear any entries that may be invalidated by the given response to
63 * a particular request.
64 * @param host
65 * @param request
66 * @param response
67 */
68 void flushInvalidatedCacheEntriesFor(HttpHost host, HttpRequest request,
69 HttpResponse response);
70
71 /**
72 * Retrieve matching {@link HttpCacheEntry} from the cache if it exists
73 * @param host
74 * @param request
75 * @return the matching {@link HttpCacheEntry} or {@code null}
76 * @throws IOException
77 */
78 HttpCacheEntry getCacheEntry(HttpHost host, HttpRequest request)
79 throws IOException;
80
81 /**
82 * Retrieve all variants from the cache, if there are no variants then an empty
83 * {@link Map} is returned
84 * @param host
85 * @param request
86 * @return a {@code Map} mapping Etags to variant cache entries
87 * @throws IOException
88 */
89 Map<String,Variant> getVariantCacheEntriesWithEtags(HttpHost host, HttpRequest request)
90 throws IOException;
91
92 /**
93 * Store a {@link HttpResponse} in the cache if possible, and return
94 * @param host
95 * @param request
96 * @param originResponse
97 * @param requestSent
98 * @param responseReceived
99 * @return the {@link HttpResponse}
100 * @throws IOException
101 */
102 HttpResponse cacheAndReturnResponse(
103 HttpHost host, HttpRequest request, HttpResponse originResponse,
104 Date requestSent, Date responseReceived)
105 throws IOException;
106
107 /**
108 * Store a {@link HttpResponse} in the cache if possible, and return
109 * @param host
110 * @param request
111 * @param originResponse
112 * @param requestSent
113 * @param responseReceived
114 * @return the {@link HttpResponse}
115 * @throws IOException
116 */
117 CloseableHttpResponse cacheAndReturnResponse(HttpHost host,
118 HttpRequest request, CloseableHttpResponse originResponse,
119 Date requestSent, Date responseReceived)
120 throws IOException;
121
122 /**
123 * Update a {@link HttpCacheEntry} using a 304 {@link HttpResponse}.
124 * @param target
125 * @param request
126 * @param stale
127 * @param originResponse
128 * @param requestSent
129 * @param responseReceived
130 * @return the updated {@link HttpCacheEntry}
131 * @throws IOException
132 */
133 HttpCacheEntry updateCacheEntry(
134 HttpHost target, HttpRequest request, HttpCacheEntry stale, HttpResponse originResponse,
135 Date requestSent, Date responseReceived)
136 throws IOException;
137
138 /**
139 * Update a specific {@link HttpCacheEntry} representing a cached variant
140 * using a 304 {@link HttpResponse}.
141 * @param target host for client request
142 * @param request actual request from upstream client
143 * @param stale current variant cache entry
144 * @param originResponse 304 response received from origin
145 * @param requestSent when the validating request was sent
146 * @param responseReceived when the validating response was received
147 * @param cacheKey where in the cache this entry is currently stored
148 * @return the updated {@link HttpCacheEntry}
149 * @throws IOException
150 */
151 HttpCacheEntry updateVariantCacheEntry(HttpHost target, HttpRequest request,
152 HttpCacheEntry stale, HttpResponse originResponse, Date requestSent,
153 Date responseReceived, String cacheKey)
154 throws IOException;
155
156 /**
157 * Specifies cache should reuse the given cached variant to satisfy
158 * requests whose varying headers match those of the given client request.
159 * @param target host of the upstream client request
160 * @param req request sent by upstream client
161 * @param variant variant cache entry to reuse
162 * @throws IOException may be thrown during cache update
163 */
164 void reuseVariantEntryFor(HttpHost target, final HttpRequest req,
165 final Variant variant) throws IOException;
166 }