This class is a storage backend for cache entries that uses the + * popular Ehcache cache implementation. + * In particular, this backend allows for spillover to disk, where the + * cache can be effectively larger than memory, and cached responses are + * paged into and out of memory from disk as needed.
+ * + *N.B. Since the Ehcache is configured ahead of time with a + * maximum number of cache entries, this effectively ignores the + * {@link CacheConfig#setMaxCacheEntries(int) maximum cache entries} + * specified by a provided {@link CacheConfig}.
+ * + *Please refer to the + * Ehcache documentation for details on how to configure the Ehcache + * itself.
+ * @since 4.1 + */ public class EhcacheHttpCacheStorage implements HttpCacheStorage { private final Ehcache cache; private final HttpCacheEntrySerializer serializer; private final int maxUpdateRetries; + /** + * Constructs a storage backend using the provided Ehcache + * with default configuration options. + * @param cache where to store cached origin responses + */ public EhcacheHttpCacheStorage(Ehcache cache) { this(cache, new CacheConfig(), new DefaultHttpCacheEntrySerializer()); } + /** + * Constructs a storage backend using the provided Ehcache + * with the given configuration options. + * @param cache where to store cached origin responses + * @param config cache storage configuration options - note that + * the setting for max object size will be ignored and + * should be configured in the Ehcache instead. + */ public EhcacheHttpCacheStorage(Ehcache cache, CacheConfig config){ this(cache, config, new DefaultHttpCacheEntrySerializer()); } + /** + * Constructs a storage backend using the provided Ehcache + * with the given configuration options, but using an alternative + * cache entry serialization strategy. + * @param cache where to store cached origin responses + * @param config cache storage configuration options - note that + * the setting for max object size will be ignored and + * should be configured in the Ehcache instead. + * @param serializer alternative serialization mechanism + */ public EhcacheHttpCacheStorage(Ehcache cache, CacheConfig config, HttpCacheEntrySerializer serializer){ this.cache = cache; this.maxUpdateRetries = config.getMaxUpdateRetries(); this.serializer = serializer; } - public synchronized void putEntry(String key, HttpCacheEntry entry) throws IOException { ByteArrayOutputStream bos = new ByteArrayOutputStream(); serializer.writeTo(entry, bos); diff --git a/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/package.html b/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/package.html new file mode 100644 index 000000000..2cdcbca7e --- /dev/null +++ b/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ehcache/package.html @@ -0,0 +1,40 @@ + + + + + + + ++This package contains a storage backend based on +Ehcache +that can be plugged into +a {@link org.apache.http.impl.client.cache.CachingHttpClient} and +used for storing cache entries. +
+ + diff --git a/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/MemcachedHttpCacheStorage.java b/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/MemcachedHttpCacheStorage.java index d6cd1a430..573c79622 100644 --- a/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/MemcachedHttpCacheStorage.java +++ b/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/MemcachedHttpCacheStorage.java @@ -45,20 +45,71 @@ import org.apache.http.client.cache.HttpCacheUpdateCallback; import org.apache.http.impl.client.cache.CacheConfig; import org.apache.http.impl.client.cache.DefaultHttpCacheEntrySerializer; +/** + *This class is a storage backend that uses an external memcached + * for storing cached origin responses. This storage option provides a + * couple of interesting advantages over the default in-memory storage + * backend: + *
Please refer to the + * memcached documentation and in particular to the documentation for + * the spymemcached + * documentation for details about how to set up and configure memcached + * and the Java client used here, respectively.
+ * + * @since 4.1 + */ public class MemcachedHttpCacheStorage implements HttpCacheStorage { private final MemcachedClientIF client; private final HttpCacheEntrySerializer serializer; private final int maxUpdateRetries; + /** + * Create a storage backend talking to a memcached instance + * listening on the specified host and port. This is useful if you + * just have a single local memcached instance running on the same + * machine as your application, for example. + * @param address where the memcached daemon is running + * @throws IOException + */ public MemcachedHttpCacheStorage(InetSocketAddress address) throws IOException { this(new MemcachedClient(address)); } + /** + * Create a storage backend using the pre-configured given + * memcached client. + * @param cache client to use for communicating with memcached + */ public MemcachedHttpCacheStorage(MemcachedClientIF cache) { this(cache, new CacheConfig(), new DefaultHttpCacheEntrySerializer()); } + /** + * Create a storage backend using the given memcached client and + * applying the given cache configuration and cache entry serialization + * mechanism. + * @param client how to talk to memcached + * @param config apply HTTP cache-related options + * @param serializer how to serialize the cache entries before writing + * them out to memcached. The provided {@link + * DefaultHttpCacheEntrySerializer} is a fine serialization mechanism + * to use here. + */ public MemcachedHttpCacheStorage(MemcachedClientIF client, CacheConfig config, HttpCacheEntrySerializer serializer) { this.client = client; diff --git a/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/package.html b/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/package.html new file mode 100644 index 000000000..a5fd731ca --- /dev/null +++ b/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/package.html @@ -0,0 +1,40 @@ + + + + + + + ++This package contains a storage backend based on +memcached +that can be plugged into +a {@link org.apache.http.impl.client.cache.CachingHttpClient} and +used for storing cache entries. +
+ +