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.client.cache;
28
29 import java.io.IOException;
30
31 /**
32 * New storage backends should implement this {@link HttpCacheStorage}
33 * interface. They can then be plugged into the existing
34 * {@link org.apache.http.impl.client.cache.CachingHttpClient}
35 * implementation.
36 *
37 * @since 4.1
38 */
39 public interface HttpCacheStorage {
40
41 /**
42 * Store a given cache entry under the given key.
43 * @param key where in the cache to store the entry
44 * @param entry cached response to store
45 * @throws IOException
46 */
47 void putEntry(String key, HttpCacheEntry entry) throws IOException;
48
49 /**
50 * Retrieves the cache entry stored under the given key
51 * or null if no entry exists under that key.
52 * @param key cache key
53 * @return an {@link HttpCacheEntry} or {@code null} if no
54 * entry exists
55 * @throws IOException
56 */
57 HttpCacheEntry getEntry(String key) throws IOException;
58
59 /**
60 * Deletes/invalidates/removes any cache entries currently
61 * stored under the given key.
62 * @param key
63 * @throws IOException
64 */
65 void removeEntry(String key) throws IOException;
66
67 /**
68 * Atomically applies the given callback to update an existing cache
69 * entry under a given key.
70 * @param key indicates which entry to modify
71 * @param callback performs the update; see
72 * {@link HttpCacheUpdateCallback} for details, but roughly the
73 * callback expects to be handed the current entry and will return
74 * the new value for the entry.
75 * @throws IOException
76 * @throws HttpCacheUpdateException
77 */
78 void updateEntry(
79 String key, HttpCacheUpdateCallback callback) throws IOException, HttpCacheUpdateException;
80
81 }